Recovery and performance

DocForge keeps canonical project evidence separate from disposable indexes, caches, receipts, and rendered projections. Recovery rebuilds derived state from current authority; it does not rewrite canonical content to make a cache look valid.

For the underlying boundaries, see core authority and the security model.

Recovery order

Use the narrowest verified recovery:

Run docforge check or the corresponding MCP status operation.
Run docforge sync to repair a missing or stale disposable index when safe.
Run docforge reindex for an explicit complete rebuild.
Restart a long-running MCP or viewer binding after descriptor or adapter implementation drift.
Regenerate a derived client fragment, command reference, preview, manual, or portable graph from current project evidence.

Never delete or rewrite canonical sources, active changesets, or reviewed hashes as cache cleanup.

Extraction-cache recovery

Incremental adapter contributions are stored in a version-1 disposable extraction cache. Reads are no-follow, regular-file-only, identity-checked, bounded to 64,000,000 bytes and 10,000 source records, and fail to a cache miss on malformed or incompatible data. Publication is atomic.

After a miss, current manifest sources are extracted again and the complete assembly is validated. The active SQLite generation remains authoritative for reads until a new verified index is published. An extraction cache may therefore be safely ahead of the last index; the two files do not pretend to be one transaction.

Index and receipt recovery

A validated SQLite index is a generation-pinned derived snapshot. Missing, corrupt, unattested, or stale indexes rebuild from the complete project or adapter oracle. Generation receipts and render receipts are post-publication evidence. Failure to write a receipt after a committed artifact is reported as degraded committed success, not as permission to repeat a mutation.

The live viewer pins one validated index identity. Index replacement makes the running snapshot stale and causes a later visualize request to start a fresh worker.

Proposal and application recovery

Hash or base conflicts are not cache failures. Retrieve the current changeset and diff, then review the new exact hash. Rebase is allowed only when every touched node, relationship, source, permission, and graph invariant still matches. A content conflict requires a new proposal.

If a canonical serializer fails its round-trip check, use its reported rollback state. Do not reapply a changeset whose application may already have committed. See migrating from v1 for rollback planning.

Milestone 4 scale evidence

The maintained Python reference benchmark creates 334 Python source files and produces:

1,002 primary nodes and 1,001 primary edges.
334 Logic projections with 2,338 Logic nodes and 2,338 Logic edges.
Exact complete/incremental primary graph and Logic equality.
Exact output after corrupt extraction-cache recovery and corrupt-index recovery.
Zero ast.parse calls and zero extract_source calls during a warm build.

On the frozen Milestone 4 candidate, operation p95 values were 1.266 to 1.898 seconds. Per-operation traced peaks were about 61 to 67 MiB, and process high-water was 78,798,848 bytes. These are regression measurements from one machine, not universal latency promises. The machine-readable record is ../benchmarks/milestone4-2026-07-29.json; detailed method and hashes are in the Milestone 4 baseline.

The zero-parser claim is deliberately Python-only. Focused JavaScript and TypeScript tests prove their manifests avoid Tree-sitter. The C++ reference manifest currently uses Tree-sitter while discovering bounded quoted includes, so a warm C++ cache hit is not evidence of zero parser work.

Maintained gates

Run:

make gate
make adoption-m4
make benchmark-m4-full
make docs-check

The main gate includes smoke benchmarks. Full milestone evidence is recorded separately from a clean candidate so smoke or dirty-tree results cannot become release claims.

4.1 KiB Raw Blame History