87 lines
4.1 KiB
Markdown
87 lines
4.1 KiB
Markdown
|
# 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.
|