Add bounded generation transition receipts

docs/COMPATIBILITY.md

@@ -79,6 +79,12 @@ Milestone 0 preserves:
   Context and changeset MCP reads accept optional limits and opaque generation-bound cursors.
   Direct Python changeset methods and the ordinary CLI context command retain full legacy results
   when pagination is not requested.
+- Latest-generation-diff receipt schema version 1. The additive `generation-diff` CLI command and
+  `docforge_get_generation_diff` MCP read accept only optional pagination fields. They record one
+  primary-graph transition and do not create a history store or expose Logic details.
+- Latest-generation-diff page schema version 1. Pages use one top-level pagination object and a
+  nested `receipt_header`. `stored_receipt_hash` names the complete stored receipt. Opaque cursors
+  may be restarted after a server or receipt change and are not durable public identifiers.
 
 Indexes, attestations, extraction caches, previews, and rendered artifacts are disposable. A schema
 change may rebuild them. Canonical project content and stored proposals may not be silently
@@ -99,6 +105,10 @@ must retain `load_projection()` as their independent clean-build and equivalence
 Project adapters remain explicitly composed. Generic DocForge does not discover arbitrary adapter
 modules or choose a project globally.
 
+The supported generation-diff Python boundary is `ProjectIndex.generation_diff()`. Helpers in the
+`docforge.generation_diff` module implement the disposable publication contract and are internal;
+they are not frozen as adapter-authoring imports.
+
 ## Preserved no-AST binding
 
 `docforge-mcp --project-root /project --no-ast` is a stable shorthand for the

docs/CONTRACT.md

@@ -20,6 +20,8 @@ commit when Git is available; it cannot change repository state.
 - Changeset schema: `schemas/changeset.schema.json`, version 1.
 - Effective policy: `schemas/policy.schema.json`, version 1.
 - Task context capsule: `schemas/context-capsule.schema.json`, version 1.
+- Latest generation diff: `schemas/generation-diff.schema.json`, version 1.
+- Latest generation-diff page: `schemas/generation-diff-page.schema.json`, version 1.
 - Index schema: version 3, disposable and reproducible.
 - Index attestation: schema version 1, disposable and reproducible.
 - Core, CLI, and MCP server: version 1.3.0.dev0.
@@ -57,6 +59,22 @@ SQLite integrity verification. A fresh process may use that receipt to verify an
 without reconstructing all graph rows. A missing, malformed, or mismatched receipt falls back to
 complete verification and is repaired only after that verification succeeds.
 
+Index replacement is the derived publication commit point. Attestation, cheap source-generation,
+and latest-generation-diff receipts are independent post-commit evidence. Their failure produces
+bounded degraded success and never falsely reports that a committed index mutation failed.
+
+Before replacement, a build accepts a predecessor only when its exact main-file inode has a
+matching whole-file attestation, has no WAL, journal, or shared-memory sidecar, and passes the
+published SQLite identity, row, hash, FTS, integrity, and policy checks. It uses an immutable
+main-file read and never repairs predecessor evidence. The build then revalidates the new source
+snapshot including exact node and edge equality and rejects a stable source identity that produces
+different graph content as `generation_collision`.
+
+The version-1 generation-diff receipt stores one bounded latest primary-graph transition. It is
+not history and contains no Logic details or source text. Public pages carry one
+`receipt_header`; its `stored_receipt_hash` identifies the complete persisted receipt rather than
+the header alone. One top-level pagination object carries the only continuation cursor.
+
 ## Isolated proposal model
 
 Create, update, move, and delete are ordered node operations inside an isolated changeset. Every

docs/MCP_CONTRACT.md

@@ -48,6 +48,7 @@ schema version 1 and does not silently acquire machine-specific process policy.
 - `docforge_visualize`
 - `docforge_stop_visualization`
 - `docforge_visualization_status`
+- `docforge_get_generation_diff`
 
 Each response states that document text is project content, not higher-priority instructions. Each
 response includes project identity, revision, source hash, adapter version, and staleness state.
@@ -108,6 +109,37 @@ the effective policy and task request. One evidence item that cannot fit advance
 a hash-identified `response_limit` omission. A changed generation, policy, plan, or collection
 fails as `stale_cursor`.
 
+`docforge_get_generation_diff` accepts only optional `limit` and `cursor` fields. It reads the one
+latest version-1 primary-graph transition receipt; it does not accept arbitrary generations,
+paths, or history selectors. Exact summary counts and the full item-collection hash cover the
+complete transition. Pagination covers only the deterministically ordered retained details and
+states separately when the fixed 1,000-item or 1 MiB publication limit permanently omitted
+details.
+
+The receipt binds project, root, adapter, index schema, from/to source identity, node and edge
+hashes and counts, the committed index file identity, retained and full collection hashes, and its
+own canonical hash. Node changes compare every core `Node` field. Edge identity is the exact
+`(source_id, relation, target_id)` triple. Logic is excluded from public diff details.
+
+Current pages use `page_schema_version = 1`. The nested `receipt_header` contains every stored
+receipt field except `items`; its `stored_receipt_hash` is the hash of the complete stored receipt,
+not of the header. Page items and hash-identified response-limit omissions are siblings of that
+header. The only pagination object is at the top level, and its `next_cursor` is the only cursor
+copy. The page hash covers the complete header, page items, omissions, receipt state, and
+pagination receipt.
+
+Receipt states are fail-closed: `current` is proven against cheap source identity and exact index
+and receipt inodes; `stale` is a proven generation mismatch; `missing` means no receipt;
+`unsafe` means confinement or file-type checks failed; `unverified` covers corrupt, foreign,
+oversized, or concurrently changed evidence; and `unknown` means the project cannot provide a
+cheap generation identity. Only `current` returns a page.
+
+This status boundary is non-repairing. It never opens SQLite, loads or extracts an adapter
+projection, parses source, synchronizes, builds, or writes a receipt. Cheap source identity and
+stable receipt/index file identities can establish `current`; legacy projects without cheap
+identity report `unknown`. Invalid or unavailable disposable evidence remains an explicit status
+instead of triggering hidden recovery.
+
 The legacy `docforge_get_context` tool and its custom three-argument provider contract remain
 unchanged. A server with a custom context provider does not silently inherit the core task planner;
 version 1 exposes no custom task-planner extension point. `docforge_get_task_context` returns

docs/USER_MANUAL.md

@@ -478,8 +478,15 @@ backlinks NODE_ID [--relation RELATION] [--limit N]
 dependencies NODE_ID [--depth N] [--limit N]
 impact NODE_ID [--depth N] [--limit N]
 context PROFILE [--budget N] [--limit N] [--cursor OPAQUE]
+generation-diff [--limit N] [--cursor OPAQUE]
 ```
 
+`generation-diff` returns the latest verified primary-graph transition. It is not a history query.
+Current results carry a version-1 page, a `receipt_header` bound to the complete stored receipt by
+`stored_receipt_hash`, and one top-level pagination cursor. Missing, unsafe, stale, corrupt, or
+unprovable disposable evidence is reported as a non-repairing receipt status. The command never
+builds or repairs the index.
+
 ### Render and proposal commands
 
 ```text
@@ -588,6 +595,7 @@ Example MCP client configuration:
 - `docforge_visualize`
 - `docforge_visualization_status`
 - `docforge_stop_visualization`
+- `docforge_get_generation_diff`
 
 ### Proposal tools
 
@@ -644,6 +652,24 @@ Task context never exceeds 1,000 evidence items, 100,000 examined candidate edge
 query characters, even when a project configures broader general limits. An edge-work or
 unclassified-relation ceiling appears as an explicit omission rather than an unbounded response.
 
+Use `docforge_get_generation_diff` after synchronization or a completed implementation slice to
+inspect the one latest verified primary-graph transition. The version-1 receipt reports exact
+added, removed, and changed node counts plus added and removed edge counts. Retained node details
+identify changed fields and before/after hashes and source paths. Edge details retain the exact raw
+relation triple. The receipt stores no source text, rendered content, Logic identities, or
+historical sequence.
+
+The first successful publication is an explicit baseline and does not claim every current node was
+added. A corrupt, foreign, unsafe, or unavailable predecessor produces an unavailable comparison
+rather than fabricated removals. A same-generation reindex preserves the latest meaningful
+transition. Each later real transition atomically replaces the single disposable receipt.
+
+Generation-diff reads use only the bounded receipt, stable file identities, and an adapter's cheap
+source-generation proof. They do not open SQLite, load a complete adapter projection, parse source,
+synchronize, build, or repair. Legacy adapters without cheap identity report `unknown`. Missing,
+corrupt, foreign, oversized, or concurrently changed receipts report an explicit receipt state and
+do not trigger hidden recovery.
+
 Recommended release-candidate sequence:
 
 1. Call `docforge_bootstrap`. It synchronizes derived state and reports the exact fixed binding.
@@ -711,6 +737,11 @@ followed by capsule omissions. Keep the semantic task arguments unchanged while
 may change. Every page retains the same plan, collection, and capsule hashes. A `stale_cursor`
 means that the generation, policy, plan, or collection changed; discard earlier pages and restart.
 
+`docforge_get_generation_diff` paginates only the details retained in the latest bounded receipt.
+Its summary counts and full collection hash still cover permanently truncated details. The cursor
+binds the exact receipt, target generation, retained and full collection hashes, receipt state, and
+effective policy. A replacement receipt returns `stale_cursor`; restart from its first page.
+
 Canonical application records its terminal receipt immediately after the project-owned serializer
 verifies the new canonical state. A later index or render refresh failure is reported as degraded
 derived state with remediation, not as permission to apply the same canonical change again.