feat(core): expose retained evidence posture on readings

[flyingrobots]

Summary

• expose generic retained-evidence posture on app-safe reading surfaces
• inventory outstanding Echo work items and adopt the sequencing filter
• add WAL/WSC, WSC causal-history, retained-evidence durability, JS/WASM/browser, and publish/versioning backlog cards
• mark the jedit retained-ref and replay witness checkpoint slices complete

Validation

• git diff --check
• pnpm exec markdownlint-cli2 on touched docs
• cargo xtask lint-dead-refs on touched docs
• pre-push hook: cargo fmt/check/test slices for echo-wasm-abi, warp-core observation tests, installed contract pipeline tests, warp-wasm lib tests, and prettier check

Cross-repo note

Paired with the jedit branch stack/jedit-echo-production-cutover-plan, which consumes adapter-projected retained reading evidence in the product witness path.

Summary by CodeRabbit

• New Features

  • Observation artifacts now include retained-evidence posture information for contract-based queries, enabling better tracking and transparency of evidence in the system.

• Improvements

  • Enhanced infrastructure with improved contract evidence handling and query identity support, strengthening system observability and query result integrity.

• Documentation

  • Updated design and implementation documentation to reflect new retained-evidence capabilities and storage architecture.

[coderabbitai]

Warning

Review limit reached

@flyingrobots, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 17 minutes and 57 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: dffe087b-a292-4162-a550-38553084aa7f

📥 Commits

Reviewing files that changed from the base of the PR and between 9e3495a and 2641c53.

📒 Files selected for processing (3)

• crates/echo-wesley-gen/tests/generation.rs
• crates/warp-core/src/observation.rs
• crates/warp-core/src/retained_evidence.rs

📝 Walkthrough

Walkthrough

Observation artifacts now encode retained-evidence posture: a generic semantic marker indicating whether reading coordinate or payload bytes are locally available or missing retention. ABI version 11→12, observation artifact version v3→v4. ReadingEnvelope carries retained_evidence vector; computation emits postures only when both contract evidence and query identity exist. Core retained-evidence type refactors missing states into two explicit variants carrying semantic input and obstruction. ABI pipeline converts postures to kernel port shape. Tests verify round-trip CBOR encoding and contract query identity participation in v4 artifact identity.

Changes

Retained Evidence in Observation Artifacts

Layer / File(s)	Summary
ABI retained evidence types and ReadingEnvelope extension crates/echo-wasm-abi/src/kernel_port.rs	New public types for retained evidence (RetainedEvidenceRole, RetainedEvidenceCoordinate, RetainedEvidenceRef, RetainedEvidencePosture with Available/MissingRetention variants). ReadingEnvelope extended with retained_evidence vector field, serde default. ABI_VERSION bumped 11→12.
Core retained evidence type refinement crates/warp-core/src/retained_evidence.rs	RetainedEvidencePosture refactored: MissingRetention variant replaced with MissingCoordinate and MissingContent, each carrying semantic input (coordinate/ref) and typed obstruction. Constructors and obstruction() accessor updated for both variants.
Observation artifact version bump to v4 crates/warp-core/src/observation.rs	OBSERVATION_VERSION and artifact domain constants bumped v3→v4. ReadingEnvelope extended with retained_evidence field. Test expectations updated to verify v4 artifact identity hash domain.
Retained evidence computation in ObservationService crates/warp-core/src/observation.rs	ObservationService::reading_envelope builder computes retained_evidence postures when both contract evidence and query reading identity exist; otherwise emits empty vector. New retained_evidence_postures() helper returns MissingCoordinate and conditional MissingContent postures. Direct (non-contract) observer readings omit retained evidence.
ABI conversion pipeline for retained evidence crates/warp-core/src/observation.rs	ReadingEnvelope::to_abi maps retained_evidence through conversion helpers. New retained_evidence_*_to_abi functions convert roles, coordinates, refs, and postures to ABI shapes. Retention_id derived from ContractObstruction when obstruction is retention-based. Content hash computed from QueryBytes.
ABI version constant and retained evidence round-trip tests crates/echo-wasm-abi/src/lib.rs, crates/echo-wasm-abi/src/kernel_port.rs	ABI version constant test updated to expect 12. OpticReadingEnvelope fixture includes retained_evidence empty vector. Legacy CBOR decoding logic filters retained_evidence field; assertion verifies decoded legacy reading has retained_evidence as empty Vec. New test_retained_evidence_posture_round_trip verifies Available and MissingRetention variants CBOR round-trip with equality.
Core test fixtures and integration test updates crates/warp-core/src/optic/tests.rs, crates/warp-core/tests/installed_contract_intent_pipeline_tests.rs	reading_envelope() fixture includes retained_evidence empty vector. installed_contract_intent_pipeline_tests enhanced: computes query payload BLAKE3 hash, asserts retained_evidence contains two missing-retention variants with second matching hash/length, verifies to_abi() preserves count. Import list reflowed.
WASM test stub kernel updated crates/warp-wasm/src/lib.rs	StubKernel::observe test implementation includes retained_evidence field initialized to empty Vec in returned ReadingEnvelope.
Changelog, design, backlog, and specification documentation CHANGELOG.md, docs/BEARING.md, docs/spec/SPEC-0009-wasm-abi.md, docs/design/*, docs/method/backlog/v0.1.0/*, docs/WorkItems.md, crates/warp-wasm/README.md	CHANGELOG documents observation artifact v4 and ABI v12 with retained-evidence-posture semantics. BEARING.md refreshed with WAL/WSC design doc references and assertion that app-safe observation/WASM surfaces carry generic retained-evidence posture. SPEC-0009 version bumped to 12 with observation metadata including contract/query identity and retained-evidence posture. New work-item-sequencing-and-prioritization.md design document defines execution gravity and release-proof sequence for v0.1.0. New backlog specifications for retained-evidence durability boundary, WAL/WSC storage relationship, WSC causal-history storage, JS/WASM/Browser client release surface. causal-wal-end-to-end.md extended with WAL projection and WSC doctrine. v0.1.0-jedit-next-ten-slices.md progress bar and implementation notes for slices 3–5. warp-wasm README updated with ABI_VERSION 12 exports. WorkItems.md populated with comprehensive inventory, audit metadata, and backlog categorization.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• flyingrobots/echo#371: Added contract/query_identity fields to ReadingEnvelope ABI; this PR extends the same envelope further with retained_evidence and bumps to next ABI/artifact versions (11→12, v3→v4).

Poem

Evidence retained yet locally sparse—
query identity hashed into artifact;
missing bytes marked with obstruction's face,
v4 knows what v3 couldn't track. 🔒

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 51.85% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the primary change: exposing retained evidence posture on reading surfaces across the codebase.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch stack/wasm-retained-evidence-refs

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/warp-core/src/observation.rs`:
- Around line 975-1021: The MissingContent branch recomputes the coordinate_id
(heavy BLAKE3) multiple times; fix by computing coordinate_id once (let coord_id
= reference.coordinate.coordinate_id().to_vec()), then build the ABI values
reusing that id: construct an abi::RetainedEvidenceCoordinate with coord_id and
use it for the coordinate field, and construct an abi::RetainedEvidenceRef that
uses the same coord_id for its coordinate and for evidence_ref_id, instead of
calling retained_evidence_coordinate_to_abi or evidence_ref_id() which trigger
another hash; update retained_evidence_posture_to_abi (MissingContent arm) to
assemble these ABI structs directly from the precomputed coord_id and call
retained_obstruction_id(obstruction) as before.

In `@docs/WorkItems.md`:
- Line 296: Update the platform name capitalization in the WorkItems table row
referencing issue [`#285`]: change "Github" to the official "GitHub" in the table
cell text that currently reads ".github/workflows/det-gates.yml computes..." so
the row becomes consistent with platform naming (identify the row by the issue
link "[`#285`]" and the quoted file names `det-gates.yml` / `det-policy.yaml` for
locating it).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: bf9abbb2-7124-4579-995a-ab336c7c2129

📥 Commits

Reviewing files that changed from the base of the PR and between 6f01f06 and 9e3495a.

📒 Files selected for processing (20)

• CHANGELOG.md
• crates/echo-wasm-abi/src/kernel_port.rs
• crates/echo-wasm-abi/src/lib.rs
• crates/warp-core/src/observation.rs
• crates/warp-core/src/optic/tests.rs
• crates/warp-core/src/retained_evidence.rs
• crates/warp-core/tests/installed_contract_intent_pipeline_tests.rs
• crates/warp-wasm/README.md
• crates/warp-wasm/src/lib.rs
• docs/BEARING.md
• docs/WorkItems.md
• docs/design/causal-wal-end-to-end.md
• docs/design/v0.1.0-jedit-next-ten-slices.md
• docs/design/work-item-sequencing-and-prioritization.md
• docs/method/backlog/v0.1.0/PLATFORM_js-wasm-browser-client-release-surface.md
• docs/method/backlog/v0.1.0/PLATFORM_retained-evidence-durability-boundary.md
• docs/method/backlog/v0.1.0/PLATFORM_wal-wsc-storage-relationship.md
• docs/method/backlog/v0.1.0/PLATFORM_wsc-causal-history-storage.md
• docs/method/backlog/v0.1.0/RELEASE_package-publish-and-versioning.md
• docs/spec/SPEC-0009-wasm-abi.md

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Use official capitalization for GitHub.

Use GitHub (capital H) in this table row to avoid platform-name inconsistency in release evidence docs.

As per coding guidelines, documentation accuracy matters and factual errors should be flagged.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~296-~296: The official name of this software platform is spelled with a capital “H”.
Context: ...85) | Closed as completed. | .github/workflows/det-gates.yml computes `DETE...

(GITHUB)

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/WorkItems.md` at line 296, Update the platform name capitalization in
the WorkItems table row referencing issue [`#285`]: change "Github" to the
official "GitHub" in the table cell text that currently reads
".github/workflows/det-gates.yml computes..." so the row becomes consistent with
platform naming (identify the row by the issue link "[`#285`]" and the quoted file
names `det-gates.yml` / `det-policy.yaml` for locating it).

[flyingrobots]

@codex self-review pass for PR #380.

Severity	File / lines	Issue	Evidence	Recommended mitigation prompt
P5 nit / perf	crates/warp-core/src/observation.rs:1010-1018	MissingContent ABI conversion recomputes retained-evidence coordinate identity while converting both the coordinate and ref.	retained_evidence_coordinate_to_abi(&reference.coordinate) computes coordinate_id(), then retained_evidence_ref_to_abi(reference) computes it again indirectly through evidence_ref_id(). RetainedEvidenceRef::evidence_ref_id() is intentionally a distinct domain hash over coordinate id, content hash, and byte length (crates/warp-core/src/retained_evidence.rs:120-128).	Refactor the ABI conversion helpers so the MissingContent path can compute the coordinate id once and pass it through to coordinate/ref conversion, but preserve the distinct RetainedEvidenceRef id domain. Do not reuse coordinate_id as evidence_ref_id; add a helper such as evidence_ref_id_from_coordinate_id(reference, coordinate_id) if this is worth optimizing.

False positive checked:

Source	File / line	Finding	Disposition
CodeRabbit	docs/WorkItems.md:296	Change "Github" to "GitHub" in the #285 row.	False positive. The row contains the path .github/workflows/det-gates.yml, where lowercase .github is correct path text. Other prose instances already use GitHub.

No P0-P3 correctness issues found in this review pass. git diff --check origin/main...HEAD is clean.

[chatgpt-codex-connector]

Summary

• Added RetainedEvidenceRef::evidence_ref_id_from_coordinate_id so the retained ref ID can be derived from a precomputed coordinate ID while preserving the existing RETAINED_EVIDENCE_REF_ID_DOMAIN hash semantics. evidence_ref_id() now delegates to that helper, so behavior remains consistent while enabling reuse. crates/warp-core/src/retained_evidence.rsL120-L135
• Refactored retained_evidence_ref_to_abi to compute coordinate_id once and reuse it for both ABI coordinate serialization and evidence_ref_id, removing redundant hashing work in the MissingContent conversion path without collapsing coordinate and ref ID domains. crates/warp-core/src/observation.rsL986-L1000
• Left the .github/GitHub docs suggestion untouched (as requested in trigger context) because the referenced table cell is a filesystem path literal where lowercase .github is correct. crates/warp-core/src/observation.rsL1018-L1024

Testing

• ✅ cargo check -p warp-core

View task →

[flyingrobots]

@codex resolution update for the self-review thread:

Severity	Issue	Resolution	Commit
P5	MissingContent retained-evidence ABI conversion recomputed the coordinate id while building coordinate/ref ABI values.	Added a crate-internal evidence_ref_id_with_coordinate_id helper and reused the precomputed coordinate id in the ABI conversion path while preserving the distinct retained-ref hash domain.	aae4c56
False positive	docs/WorkItems.md .github/workflows/det-gates.yml capitalization.	No code change. .github is a literal path and must remain lowercase.	N/A

Validation:

• cargo fmt --all
• cargo test -p warp-core retained_evidence
• cargo check -p warp-core
• pre-push: cargo fmt --all -- --check
• pre-push: cargo test -p warp-core --lib observation::tests
• pre-push: cargo check -p warp-core --quiet

[chatgpt-codex-connector]

Summary

• Reviewed the PR trigger/context and verified the requested self-review resolutions are already reflected in head_ref (aae4c56ad251e0cff742af5f5fe0586e9a5944ed) from <PR_INFO>, so no additional repository edits were needed.
• Reverted an unrelated local working-tree modification in pnpm-lock.yaml to keep the branch clean (no net code changes).

Testing / Checks

• ✅ rg --files -g 'AGENTS.md'
• ⚠️ sed -n '1,120p' docs/BEARING.md && sed -n '1,120p' METHOD.md && rg --files backlog/asap && git log -n 5 --oneline && git status --short (warning: backlog/asap path does not exist in this repo layout; backlog is under docs/method/backlog/asap)
• ✅ rg --files docs/method/backlog/asap && git log -n 5 --oneline && git status --short
• ✅ git diff -- pnpm-lock.yaml | sed -n '1,120p'
• ✅ git checkout -- pnpm-lock.yaml && git status --short

No commit was created, and make_pr was not called, because there were no code changes to submit.

View task →

[flyingrobots]

@codex CI follow-up:

Issue	Resolution	Commit
Tests (workspace sans warp-core) failed in test_toy_contract_generated_output_compiles_in_consumer_crate because the consumer smoke fixture constructed ReadingEnvelope without the new ABI v12 retained_evidence field.	Added retained_evidence: Vec::new() to the generated consumer smoke fixture.	2641c53

Validation:

• cargo test -p echo-wesley-gen --test generation test_toy_contract_generated_output_compiles_in_consumer_crate
• cargo fmt --all
• git diff --check
• pre-commit: cargo clippy -p echo-wesley-gen --lib --tests
• pre-commit: cargo check -p echo-wesley-gen
• pre-push: cargo test -p echo-wesley-gen --test generation

[chatgpt-codex-connector]

Summary

• I verified the trigger’s CI follow-up is already present on this branch in commit 2641c53 (the fixture now includes retained_evidence: Vec::new()). crates/echo-wesley-gen/tests/generation.rsL334
• I did not make additional code changes, so there was nothing to commit and no PR to create via make_pr.
• I also restored a clean working tree by discarding an unrelated local modification to pnpm-lock.yaml.

Testing

• ✅ rg --files -g 'AGENTS.md' && git status --short && git log -n 5 --oneline
• ✅ rg -n "retained_evidence" crates/echo-wesley-gen/tests/generation.rs && git show --name-only --oneline 2641c53
• ✅ git checkout -- pnpm-lock.yaml && git status --short
• ⚠️ cargo test -p echo-wesley-gen --test generation test_toy_contract_generated_output_compiles_in_consumer_crate (fails in this environment due to crates.io network access: CONNECT tunnel failed, response 403, not due to code regression)

View task →