Preserve catalog source lineage for guarded snapshot retention

Draft
SI
2d ago
+554-7

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.

  • prepareCatalogSurface now returns an internal sourceEnvelope (actor, message ID, canonical input, surface digest) that never reaches the client or UIMessage parts.
  • A default-off retainCatalogSnapshotStep runs 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=true and NODE_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.