Repository navigation
Files Changed: add bounded receipt, assessment, and evidence storage #1076
Description
Files Changed: add bounded receipt, assessment, and evidence storage
Important
Problem - Session diffs and external preimages are split across ephemeral metadata, snapshots, and host-local artifacts. There is no bounded durable representation for operation groups, immutable receipt facts, current assessments, or root-owned evidence.
Approach - Add compact root-owned operation, receipt, and assessment storage to the session database, with a separate bounded host-local evidence store. Adapt existing external-diff state through this storage boundary without widening legacy output.
Scope - in: storage schema, migration, quotas, pagination, retention, compaction, evidence references, and existing external-diff compatibility. out: mutation-route adoption and UI replacement.
Assumptions - The typed lineage root from the preceding slice is available.
Acceptance Criteria
- One operation group can atomically publish immutable receipts for all declared resources.
- Immutable receipt facts are separate from append-only or derived assessments.
- Assessments represent observation confidence, net state, evidence availability, revision, and expiry without rewriting receipt history.
- Receipt metadata, row count, and evidence bytes are bounded per root with paged retrieval and documented retention.
- A known local mutation that would exceed the active root budget is refused before filesystem work begins.
- Evidence resides outside the session database and can hold bounded patches, preimages, or structured metadata without entering legacy session output.
- Existing external-diff data can be read through a compatibility adapter without granting old sessions full-provenance status.
- Root deletion removes receipt data and evidence according to retention policy; orphan cleanup is idempotent.
Testing Decisions
- Add migration, restart, retention, quota, pagination, root deletion, and orphan-cleanup integration coverage.
- Extend external-diff lifecycle tests through the compatibility adapter.
Key Decisions
- Database rows store compact provenance facts; potentially large evidence remains a separate private sidecar.
- Capacity exhaustion is a visible gate, not a reason to silently stop accounting.
Constraints & Invariants
- Ledger infrastructure never emits its own session-visible receipts.
- Legacy diff consumers remain wire-compatible.
Prior Art
- Parent Files Changed: full session-lineage mutation ledger #972
- Existing external baseline and assessed-diff persistence
Deliberation Resolution
- An operation group advances through
prepared,evidence_ready, andcommitted. Evidence is written atomically before the database transaction references it; an orphaned evidence artifact is swept, while a committed receipt with missing evidence receives anunavailableassessment and never renders a patch. - The injected root budget exposes four deterministic units:
max_receipts,max_metadata_bytes,max_evidence_bytes, andretention_ms. Preparation reserves declared receipt and metadata capacity; evidence above its byte limit becomes metadata-only without losing the receipt. - Pagination is by immutable receipt creation sequence within a root. Retention begins when the root is deleted or reaches its configured terminal age; compaction may remove expired evidence and assessments but preserves a compact receipt tombstone until root retention ends.
- A v1 external baseline maps to a
legacy_externalcompatibility record with no operation group, no lineage ownership, and no full-provenance display claim.
Activity