Preserve catalog source lineage for guarded snapshot retention
Catalog projection discarded the exact query and retained observation bindings needed for a later saved-source handoff. Preserve those original server-produced bytes in an internal envelope and add a default-off retention step after fenced assistant persistence. Rendered schema-v1, SSE/text output and UIMessage parts remain unchanged.
The step validates actor/chat/message scope, source revision 1, exact lineage and source/surface digests, then requires an exact RPC receipt. Conflicts, denied writes and ambiguous acknowledgements fail without retry or fallback. No client proof field or new public route is introduced.
Validation: 85 focused tests across eight files, full lint, scoped strict TypeScript, formatting and the compiled synthetic workflow fixture (14 cases, zero network attempts). Enabled retention success/failure is covered by synthetic workflow unit tests; compiled coverage uses the disabled step. Existing wire goldens remain unchanged.
This is an incomplete, guarded source increment for review: the companion Database proposal has no grants and an always-deny authorizer. No SQL execution, migration, enrollment, environment activation, deployment or working-surface save/reopen. Current authorization/withdrawal adapters, PostgreSQL concurrency qualification and read/history/export enforcement remain prerequisites. Failure after assistant persistence may leave a message without a source receipt. Coordinator owns integration and release.
Summary by cubic
Preserves the exact query and observation bindings a catalog snapshot was built from so a later saved-source handoff can reference the original server bytes, without changing any rendered output.
prepareCatalogSurfacenow returns an internalsourceEnvelope(actor, message ID, canonical input, surface digest) that never reaches the client or UIMessage parts.- A default-off
retainCatalogSnapshotStepruns after required assistant persistence and before the fenced writer is released. - The step validates scope, source revision 1, exact lineage and byte digests, then requires an exact RPC receipt; conflicts, denials, and ambiguous acknowledgements fail without retry or fallback.
Guard rails
- Enabled only when
CATALOG_SURFACE_RETENTION_ENABLED=trueandNODE_ENV=development; production is refused. - The companion SQL proposal has no grants and an always-deny authorizer; no migration or deployment is included.
- A failure after persistence may leave a message without a source receipt.
- No new public route, request field, or working-surface save/reopen is introduced.