administrator/DocForge2
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions Pages

Document Release 1 adapter compatibility

Browse source
This commit is contained in:
Andraxion 2026-07-25 19:21:23 -04:00
parent 696b62f9f8
commit 4a8980110d
4 changed files with 38 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

9
docs/CONTRACT.md
View file

@ -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.

16
docs/INCREMENTAL_INDEXING.md
View file

@ -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:

10
docs/USER_MANUAL.md
View file

@ -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.