Close Milestone 4 with adapter adoption evidence

docs/RECOVERY_AND_PERFORMANCE.md

@@ -0,0 +1,86 @@
+# 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](CORE_CONCEPTS_AND_AUTHORITY.md) and the
+[security model](SECURITY.md).
+
+## Recovery order
+
+Use the narrowest verified recovery:
+
+1. Run `docforge check` or the corresponding MCP status operation.
+2. Run `docforge sync` to repair a missing or stale disposable index when safe.
+3. Run `docforge reindex` for an explicit complete rebuild.
+4. Restart a long-running MCP or viewer binding after descriptor or adapter implementation drift.
+5. 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](MIGRATING_FROM_V1.md) 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](MILESTONE_4_BASELINE.md).
+
+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:
+
+```bash
+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.