From 059f26539b86ce02c6a0e3af541bcdaad194c6a4 Mon Sep 17 00:00:00 2001 From: James Ross Date: Wed, 8 Jul 2026 23:00:13 -0700 Subject: [PATCH] docs: define retained evidence boundary posture --- ...ained-evidence-boundary-posture-runtime.md | 40 ++++ docs/README.md | 1 + ...ned-evidence-refs-and-missing-retention.md | 192 +++++++++++++++--- 3 files changed, 203 insertions(+), 30 deletions(-) create mode 100644 backlog/bad-code/RE-033-retained-evidence-boundary-posture-runtime.md diff --git a/backlog/bad-code/RE-033-retained-evidence-boundary-posture-runtime.md b/backlog/bad-code/RE-033-retained-evidence-boundary-posture-runtime.md new file mode 100644 index 00000000..3ee7fed3 --- /dev/null +++ b/backlog/bad-code/RE-033-retained-evidence-boundary-posture-runtime.md @@ -0,0 +1,40 @@ + + + +# RE-033: Project Retained Evidence Boundary Posture + +## Problem + +`warp-core` has local retained evidence coordinates, refs, and missing-retention +posture, but observer-facing projection still lacks the full boundary posture +needed to distinguish native support, translated support, fixture support, +redaction, authority blockage, unsupported evidence kinds, stale basis, corrupt +content, and proof-backed compaction. + +## Why It Matters + +A raw retained ref or content hash can cite bytes but cannot answer whether an +observer may reveal those bytes, whether the evidence is native, whether the +proof is strong enough for the current purpose, or whether missing raw material +is actually proof-backed cold evidence. Collapsing those cases would create +false availability and false missing-retention reports. + +## Desired Shape + +- Project retained evidence through semantic coordinate, witness-ladder layer, + origin, proof strength, access, and completeness posture. +- Keep citation authority, reveal authority, and admission authority distinct. +- Preserve `MissingRetention` for true local byte-retention absence while + refining observer-facing obstruction for redaction, unsupported evidence, + stale basis, authority blockage, corruption, fixture-only support, and + translated evidence. +- Keep WAL, CAS, checkpoint, and scheduler internals behind the boundary + posture surface. + +## Acceptance Tests + +- `native_and_fixture_retained_evidence_do_not_alias` +- `redacted_retained_evidence_is_not_missing_content` +- `unsupported_evidence_kind_obstructs_not_missing_retention` +- `retained_content_hash_does_not_identify_semantic_evidence` +- `available_retained_evidence_ref_does_not_grant_reveal` diff --git a/docs/README.md b/docs/README.md index accb7cd2..c7fe858e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -62,6 +62,7 @@ Echo's live documentation centers on the runtime carrier, the retained witnesses - ABI golden vectors: [/spec/abi-golden-vectors](/spec/abi-golden-vectors) - WARP view protocol: [/spec/warp-view-protocol](/spec/warp-view-protocol) - WSC, Verkle, IPA, and retained readings: [/architecture/wsc-verkle-ipa-retained-readings](/architecture/wsc-verkle-ipa-retained-readings) +- Retained evidence refs and missing-retention posture: [/design/retained-evidence-refs-and-missing-retention](/design/retained-evidence-refs-and-missing-retention) ## Determinism Evidence diff --git a/docs/design/retained-evidence-refs-and-missing-retention.md b/docs/design/retained-evidence-refs-and-missing-retention.md index 760d79b4..f5575264 100644 --- a/docs/design/retained-evidence-refs-and-missing-retention.md +++ b/docs/design/retained-evidence-refs-and-missing-retention.md @@ -3,53 +3,185 @@ # Retained Evidence Refs And Missing-Retention Posture -Status: accepted and implemented local boundary. +Status: design boundary for retained evidence projection. Existing local +`RetainedEvidenceCoordinate`, `RetainedEvidenceRef`, and +`RetainedEvidencePosture` primitives remain accepted; the broader +Observer-Geometry/Continuum posture model below governs future runtime and ABI +projection work. ## Claim -Echo now has first-class retained evidence references in `warp-core`. A retained -evidence reference binds: +Echo retained evidence refs are boundary evidence posture objects. They cite +semantic retained support across receipt, reading, witness, and artifact +surfaces without collapsing evidence origin, proof strength, access rights, +completeness, or witness-ladder layer into raw content availability. -- installed contract evidence identity; -- retained evidence role; -- semantic digest; -- content-only hash; -- byte length. +A retained evidence ref may bind retained bytes, but the public claim is not +"CAS hash exists." The public claim is: -Missing retained material returns typed `MissingRetention` obstruction posture. -It does not become empty success, a cache hit, a stale query identity, or a -generic runtime fault. +```text +observer / optic surface ++ basis and aperture ++ semantic retained coordinate ++ witness-ladder layer ++ evidence origin, proof strength, access, and completeness posture +-> justified retained evidence posture +``` -## Boundary +This prevents missing retained material from becoming empty success, a cache +hit, stale query identity, fixture/native evidence aliasing, or a generic +runtime fault. -`RetainedEvidenceCoordinate` names the semantic coordinate for retained -contract material. `RetainedEvidenceRef` then binds that coordinate to retained -bytes by content hash and byte length. `RetainedEvidencePosture` reports either -available evidence or a `ContractObstructionKind::MissingRetention` obstruction. +## Existing Local Boundary -This is the core/product-facing reference layer above local byte retention. It -does not change `echo-cas`: CAS still names bytes only, and `RetainedBlobIndex` -still owns local semantic byte lookup. +Echo already has the local reference layer needed for byte-backed retained +evidence: + +- `RetainedEvidenceCoordinate` names contract evidence identity, retained role, + and semantic digest. +- `RetainedEvidenceRef` binds that coordinate to content hash and byte length. +- `RetainedEvidencePosture` reports available evidence, missing coordinate, or + missing content with `ContractObstructionKind::MissingRetention`. +- `RetainedBlobIndex` in `echo-cas` remains the local semantic byte index above + content-only CAS. + +Those primitives intentionally keep CAS byte identity separate from semantic +evidence identity. Equal bytes under different semantic coordinates produce +different evidence reference ids, and reading payload refs do not alias reading +envelope refs. + +## Observer Boundary + +Retained evidence crosses an observer or optic boundary only as posture. A +runtime may retain bytes, proofs, receipts, or shells locally, but the boundary +answer must be phrased in terms of the caller's lawful reading frame: + +- observer plan or optic surface; +- causal basis and bounded aperture; +- semantic coordinate or read identity; +- retained support obligation; +- rights, budget, residual, and obstruction posture; +- evidence origin, proof strength, access, and completeness. + +This follows the Echo rule that observation is revelation, not authorship. A +reading may cite retained evidence without mutating history, and citation is +not the same authority as byte revelation. + +## Witness Ladder + +Continuum-style boundary evidence has three non-collapsible layers: + +| Layer | Echo role | Examples | +| ------------------ | ------------------------------------------ | ------------------------------------------------------------------------------------ | +| Reintegration core | Locates the claim in causal history | coordinates, parent hashes, lane boundaries, read identity, basis/frontier | +| Witness core | Proves admission or observation lawfulness | signatures, replay certificates, Merkle openings, ZK proofs, transport-square proofs | +| Receipt shell | Carries operational explanation | routing, debug metadata, correlation ids, human-facing explanation | + +`RetainedEvidenceRole` names what the retained material is for. The witness +ladder names which boundary layer the material occupies. The two dimensions are +orthogonal: a receipt may cite witness-core material, and a reading envelope may +carry reintegration facts plus receipt-shell posture. + +These layers may reference one another by digest, but they must not collapse +into one blob. Redacting receipt-shell metadata must not invalidate witness-core +proofs, and witness-core availability must not imply receipt-shell reveal +permission. + +## Boundary Posture Axes + +Future ABI and product-facing projection should treat retained evidence posture +as a small lattice over four axes: + +| Axis | Question | Example values | +| -------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------- | +| Origin | Where did this evidence come from? | native, translated, fixture, derived, opaque | +| Proof strength | What justifies it? | digest-only, signature, replay certificate, Merkle opening, ZK proof, composite proof | +| Access | What may this observer do? | revealable, citation-only, redacted, authority-blocked, key-unavailable, unsupported | +| Completeness | Is the obligated support present? | complete, partial, declared-lost, stale, missing-coordinate, missing-content, corrupt, obstructed | + +The current `RetainedEvidencePosture` covers the local completeness cases that +exist today. It must not be read as the complete boundary posture lattice. + +## Obstruction Rules + +The public retained-evidence boundary must preserve these distinctions: + +- Missing coordinate is not missing content. +- Missing content is not redaction. +- Redaction is not successful availability. +- Authority-blocked evidence is not missing retention. +- Unsupported evidence kind is an obstruction, not a cache miss. +- Fixture evidence is not native evidence. +- Translated/substrate evidence is not native Echo witnesshood. +- Corrupt content is not unavailable content. +- Stale basis is not absent retention. +- Available citation is not byte revelation. + +The low-level `MissingRetention` obstruction remains valid for the local byte +reference path, but observer-facing APIs should refine it when the failure is +actually capability denial, unsupported proof kind, redaction, stale basis, +corruption, fixture-only support, translated support, or budget exhaustion. + +## Implementation Shape + +The next runtime slice should not add a hash lookup helper such as +`retained_ref_for_hash(hash)`. That would erase the semantic coordinate, +observer purpose, evidence layer, rights posture, and retained support +obligation. + +Instead, project retained evidence through a structure shaped like: + +```text +RetainedEvidenceBoundaryPosture { + coordinate, + role, + layer, + origin, + proof_strength, + access, + completeness, + obstruction, +} +``` + +The exact Rust type can be smaller than this sketch, but it must preserve the +axes. When the runtime lacks an axis today, it should report a conservative +unknown, opaque, blocked, or unsupported posture instead of claiming native +available evidence. ## Invariants - CAS byte identity is not semantic evidence identity. -- Equal bytes under different semantic coordinates produce different evidence - reference ids. -- Reading payload refs and reading-envelope refs are distinct roles. -- A query or reading identity does not imply payload retention. -- Missing semantic coordinates and missing retained bytes surface as - `MissingRetention`. -- Missing-retention obstructions carry the installed contract evidence identity - when available. +- Query identity and reading identity do not imply payload retention. +- Payload and envelope evidence are different roles. +- Native, translated, fixture, redacted, and obstructed evidence never alias. +- Retained proof availability does not imply retained plaintext availability. +- Citation authority, reveal authority, and admission authority are separate. +- Missing support that is declared should downgrade posture; it becomes witness + debt only if Echo reports stronger support than the ledger justifies. +- Hot, warm, and cold compaction tiers may all preserve evidence differently; + absence of raw bytes is not automatically absence of proof-backed evidence. ## Non-Goals -- Do not add distributed retention, settlement shells, or replica import. -- Do not add disk persistence or garbage-collection policy. -- Do not treat retained reading refs as query identities. +- Do not implement distributed retention, settlement shells, replica import, or + suffix transport here. +- Do not add disk persistence or garbage-collection policy here. +- Do not expose WAL, checkpoint, CAS path, or scheduler implementation details + as boundary evidence posture. - Do not make content hashes stand in for semantic coordinates. +- Do not make a successful retained ref imply permission to reveal bytes. ## Witnesses +Existing local tests: + - `cargo test -p warp-core --test retained_evidence_ref_tests` + +Target tests for the next implementation slice: + +- native and fixture retained evidence do not produce the same boundary posture; +- redacted evidence returns citation or redaction posture, not missing content; +- unsupported proof kind returns obstruction, not missing retention; +- content hash alone cannot identify semantic retained evidence; +- available retained evidence citation does not imply reveal permission.