Bind Echo and Keep content identities explicitly

[flyingrobots]

Problem

Echo and Keep both use 32-byte BLAKE3 outputs, but they do not name content with the same identity law. Treating their digests as interchangeable would make the experimental backend unsound.

Approach

• define the exact Echo and Keep v1 identity preimages in Echo's canonical physical-content boundary
• decide that Echo retains its current BlobHash in WAL/WSC while the adapter retains a witnessed Echo-to-Keep binding
• require exact bytes or a previously admitted binding; no digest cast or implicit conversion
• add an executable same-source witness over empty, text, and byte-ramp vectors

Invariant

The same exact byte stream deterministically establishes both identities under their respective pinned contracts. Neither identity is reinterpreted as the other.

Validation

• cargo fmt --all -- --check
• cargo test -p echo-cas
• cargo clippy -p echo-cas --all-targets -- -D warnings
• bash tests/docs/test_documentation_model.sh
• npx --no-install markdownlint-cli2 docs/architecture/echo-keep-physical-content-boundary.md
• git diff --check

Compatibility and limitations

This changes no shipped Echo storage behavior, durable format, WAL identity, or WSC identity, so no changelog entry is warranted. The witness deliberately does not execute Keep or prove reconstruction through an independent adapter path; those remain later gates in #722.

Advances #722.

Summary by CodeRabbit

• Documentation

  • Clarified the identity formats and digest requirements for Echo and Keep.
  • Documented length handling, incompatibility behavior, retained identities, and reconstruction constraints.
  • Updated references to the authenticated reconstruction invariants.

• Tests

  • Added coverage for identity digests across empty input, fixed text, and all byte values.
  • Verified expected digest vectors and confirmed Echo and Keep identities remain distinct.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 569342a8-1ca4-4dd7-bdc3-8279b5d4a8c7

📥 Commits

Reviewing files that changed from the base of the PR and between 490134c and db3e5df.

📒 Files selected for processing (2)

• crates/echo-cas/tests/keep_identity_bridge.rs
• docs/architecture/echo-keep-physical-content-boundary.md

---

📝 Walkthrough

Walkthrough

The PR defines distinct Echo and Keep identity formats, documents their reconstruction and compatibility rules, and adds integration coverage for pinned digest vectors across representative byte payloads.

Changes

Identity bridge contract and validation

Layer / File(s)	Summary
Define the identity contract docs/architecture/echo-keep-physical-content-boundary.md	The architecture document specifies distinct Echo and Keep identities, exact digest preimages, retained contract versions, incompatibility behavior, and identity-witness limitations.
Validate pinned digest vectors crates/echo-cas/tests/keep_identity_bridge.rs	The integration test computes Echo and Keep digests for empty input, text, and all byte values. It checks pinned hexadecimal vectors and confirms the digests differ.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to db3e5

This PR adds explicit Echo and Keep content-identity binding documentation and tests without changing shipped storage or runtime behavior; no actionable merge-blocking risk remains beyond normal checks and review.

Possibly related PRs

• flyingrobots/echo#721: Extends the same architecture document and identity-witness coverage.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: explicitly binding Echo and Keep content identities.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/echo-keep-identity-bridge

---

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.}