Add bounded generation transition receipts

DEVELOPMENT_NOTES.md

@@ -445,3 +445,81 @@ adapters.
 The complete repository gate passes with 158 tests and 101 subtests, zero Pyright diagnostics,
 warning-strict execution, package builds, public-contract validation, and the maintained Milestone
 0 and Milestone 1 smoke benchmarks. Gitleaks 8.30.1 reports no secret findings in the working tree.
+
+### Latest-generation diff receipt
+
+Three read-only audits reconciled the index publication, public transport, compatibility, and
+no-AST boundaries before implementation. The selected design stores one disposable
+`generation-diff.json` receipt. It does not add a history database, arbitrary generation
+selectors, source text, rendered content, or Logic details.
+
+Before a build loads current source, it accepts an existing index only when its exact main-file
+inode has a matching stable whole-file attestation and no WAL, journal, or shared-memory sidecar.
+It then captures that predecessor through an immutable main-file transaction. The capture validates
+the SQLite application and schema IDs, project/root/adapter binding, integrity, complete node and
+edge rows, Logic aggregate identity, FTS count, metadata hashes and counts, and final file
+signature. It never calls normal check or synchronization and never repairs predecessor evidence.
+
+The final source revalidation now compares exact nodes and edges in addition to source hash,
+revision, and Logic. A verified predecessor that maps the same source identity to different graph
+content fails before publication as `generation_collision`. This closes a pre-existing adapter
+determinism gap found during the generation-diff audit.
+
+SQLite replacement is now the explicit derived mutation commit point. Whole-file attestation,
+cheap source-generation, and generation-diff receipts publish independently afterward. Any
+post-commit receipt failure returns `status = ok`, `index = published`, a bounded degraded
+publication record, and receipt-stage names. It never rolls back the new index or reports a false failed
+mutation. Attestation hashing checks the exact index signature before, during, and immediately
+before receipt publication.
+
+Version-1 diff semantics compare every core `Node` field by stable node ID and exact edge triples.
+Node renames are removal plus addition. Edge changes are removal plus addition. Exact summary
+counts and a full ordered item-hash collection cover every change. Retained details are
+deterministically ordered and independently capped at 1,000 items and 1 MiB with explicit item- or
+byte-limit evidence. A first build or untrusted predecessor is a baseline with no fabricated
+all-added result. A same-generation reindex republishes the existing meaningful transition against
+the new index file identity instead of erasing it with an empty diff.
+
+The additive public surfaces are:
+
+- CLI `generation-diff [--limit N] [--cursor OPAQUE]`.
+- MCP `docforge_get_generation_diff(limit=None, cursor=None)`.
+- Telemetry operations `cli.generation-diff` and `mcp.generation_diff`.
+
+Public reads do not open SQLite, call `project.load()`, extract an adapter projection, parse source,
+check, synchronize, build, or repair. They strictly validate the bounded receipt, compare stable
+receipt and index file identities, require two matching cheap source-generation checks, and report
+unknown for legacy adapters without that capability. Missing, corrupt, foreign, oversized,
+symlinked, stale, or concurrently changed evidence remains a read-only status outcome.
+
+Generation-diff pagination binds the complete stored receipt hash and effective policy. That hash
+already covers project, generation, graph, collection, and committed-index identity. Page size may
+change. A replaced receipt returns `stale_cursor`. One top-level pagination object owns the only
+cursor. The nested version-1 page uses `receipt_header.stored_receipt_hash` so it never
+misrepresents the complete receipt hash as the hash of a partial header. The summary distinguishes
+additional retained pages from details permanently omitted by the fixed publication limits.
+
+Adversarial coverage now includes strict runtime/schema rejection, predecessor attestation and
+generation identity, live and synthetic SQLite sidecars, cache-root symlink substitution,
+source/sidecar changes during diff preparation, independent receipt failures, and degraded
+post-commit identity and durability failures. Focused verification passes the direct, CLI, MCP,
+schema, pagination, legacy, incremental no-AST, and zero-work suites. The complete repository gate
+passes with 176 tests and 113 subtests, zero Pyright diagnostics, package builds, web checks, and
+the maintained Milestone 0 and Milestone 1 smoke benchmarks. Final independent re-audit is in
+progress before this slice is committed.
+
+The final dense benchmark uses a 1,000-node transition with 1,000 changed details. Its receipt is
+775,663 bytes. Direct status is 37.659 ms median and 39.108 ms p95. A maximum-size MCP request
+returns 307 items in 199,754 bytes at 54.037 ms median and 56.617 ms p95. Four pages reconstruct
+all 1,000 retained details in 652,798 bytes at 201.55 ms median. Peak RSS is 79,096 KiB.
+Every hidden-work counter remains zero; the read performs exactly two cheap source-generation
+checks.
+
+Measurement found and removed two avoidable costs before commit. Receipt loading had repeated the
+complete 1,000-item validator solely to check project identity; it now validates once and compares
+the three binding fields directly. Page fitting had encoded every growing prefix; it now uses an
+exact logarithmic search and retains the hash-only oversized-item omission path. The maximum page
+fell from 272.06 ms p95 to 56.617 ms p95, while full traversal fell from roughly 859 ms to
+203.55 ms p95. Regression tests require one receipt validation and at most 15 response encodes for
+1,000 page candidates. Final independent publication, contract, and performance audits approve
+the slice for commit.