From 4a8980110d4901b4747e9e12ef777e28d2069168 Mon Sep 17 00:00:00 2001 From: Andraxion Date: Sat, 25 Jul 2026 19:21:23 -0400 Subject: [PATCH] Document Release 1 adapter compatibility --- README.md | 6 ++++++ docs/CONTRACT.md | 9 +++++++-- docs/INCREMENTAL_INDEXING.md | 16 +++++++++++++++- docs/USER_MANUAL.md | 10 ++++++++++ 4 files changed, 38 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index c72ec15..b753c65 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,12 @@ DocForge 1.0.0 is the first stable product release. It combines the project-scop MCP query surfaces, reviewable hash-approved changesets, generic and project-owned adapters, declared rendering, and the complete Nodes/Flow/Web visualization model in one supported release. +The post-1.0 incremental compiler is a backward-compatible, optional enhancement. Existing Release +1 adapters that implement only `load_projection()` continue to use the original complete-projection +path without modification. Adapters gain incremental performance only when they additionally +implement the source manifest and extraction methods. Incremental adapters must retain +`load_projection()` as their clean-rebuild fallback and equivalence oracle. + ## Graph views The browser presents the same indexed graph through three complementary views: diff --git a/docs/CONTRACT.md b/docs/CONTRACT.md index 6ebb037..48a9e9a 100644 --- a/docs/CONTRACT.md +++ b/docs/CONTRACT.md @@ -1,4 +1,4 @@ -# DocForge 1.1 development contract +# DocForge post-1.0 development contract ## Authority boundary @@ -19,7 +19,7 @@ commit when Git is available; it cannot change repository state. - Result envelope: `schemas/result.schema.json`, version 1. - Changeset schema: `schemas/changeset.schema.json`, version 1. - Index schema: version 1, disposable and reproducible. -- Core, CLI, and MCP server: version 1.1.0.dev0 on `Dev-Rewrite`. +- Core, CLI, and MCP server: version 1.1.0.dev0. - Incremental extraction cache: version 1, disposable and reproducible. Schema files describe the generic interchange contract. Runtime validation remains responsible for @@ -214,6 +214,11 @@ Cached and refreshed facts are always assembled into a complete projection and p validation before publication. The full projection loader remains the fallback and equivalence oracle. +The Release 1 `AdapterLoader` contract remains valid. A loader that supplies only +`load_projection()` stays on the complete-projection path. Incremental capability detection is +additive and cannot make the new methods mandatory for an existing adapter. An incremental loader +must also implement `load_projection()` so a clean rebuild and equivalence check remain possible. + Logic projections are not primary graph nodes. They remain source-scoped, function-owned, independently cached control-flow data so ordinary search, Nodes, Flow, and Web do not become statement graphs. diff --git a/docs/INCREMENTAL_INDEXING.md b/docs/INCREMENTAL_INDEXING.md index bfeca43..c93df35 100644 --- a/docs/INCREMENTAL_INDEXING.md +++ b/docs/INCREMENTAL_INDEXING.md @@ -1,9 +1,23 @@ # Incremental Adapter Indexing DocForge Release 1 adapters return one complete immutable projection. That contract remains -supported. The `Dev-Rewrite` compiler adds an opt-in source-scoped contract that avoids reparsing +supported. The incremental compiler adds an opt-in source-scoped contract that avoids reparsing unchanged files while preserving the same validated, atomically published graph. +## Release 1 compatibility + +The incremental interface is additive: + +- An existing adapter implementing only `load_projection()` continues to work unchanged. +- Existing generic projects, descriptors, canonical sources, changesets, and indexes require no + migration. +- Only adapters implementing both `load_manifest()` and `extract_source()` use the incremental + path. +- Incremental adapters must still implement `load_projection()` for clean rebuilds and equivalence + testing. +- Existing adapters receive identical correctness behavior but no incremental speedup until they + opt in. + ## Safety model Incremental indexing is an extraction optimization. It does not weaken publication: diff --git a/docs/USER_MANUAL.md b/docs/USER_MANUAL.md index 6ead37a..a47c0d4 100644 --- a/docs/USER_MANUAL.md +++ b/docs/USER_MANUAL.md @@ -9,6 +9,12 @@ DocForge 1.0.0 is the first stable product release. It includes the project-scop CLI and MCP query surfaces, hash-approved proposal application, generic and project-owned adapters, declared rendering, and the Nodes/Flow/Web visualization model documented below. +Later incremental-compiler capabilities are additive. A Release 1 adapter with only +`load_projection()` remains valid and follows the same complete-rebuild path. No existing project +descriptor, canonical document, changeset, or adapter must be rewritten. Source-scoped caching and +lazy logic projections activate only for adapters that explicitly implement the optional +incremental methods while retaining the full loader as a fallback. + ## Features - Project-bound Markdown and TOML documentation graphs with stable node IDs. @@ -505,6 +511,10 @@ implement the optional source-scoped manifest and extraction contract. DocForge sources, reuses unchanged facts, reparses changed sources and their reverse dependents, validates a complete candidate graph, and publishes the index atomically. +DocForge detects this capability structurally. An adapter without both `load_manifest()` and +`extract_source()` remains on the Release 1 path. Its behavior and query results are unchanged, but +it does not receive incremental performance until it opts in. + Build results report cache hits, reparsed sources, invalidated sources, deleted sources, and total sources. A full projection remains the fallback and equivalence oracle.