Define the Echo–Keep boundary and semantic decision model - #721
Merged
Conversation
Contributor
📝 WalkthroughWalkthroughThe PR establishes documentation standards, converts numbered ADRs into a historical archive, adds documentation-model validation, and records the experimental Echo–Keep physical-content boundary and adoption requirements. ChangesDocumentation governance
Echo–Keep physical-content architecture
Estimated code review effort: 3 (Moderate) | ~25 minutes Possibly related issues
Suggested labels: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches 💡 1📝 Generate docstrings 💡
🧪 Generate unit tests (beta)
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. Comment |
flyingrobots
marked this pull request as ready for review
August 10, 2026 03:45
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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 `@docs/architecture/echo-keep-physical-content-boundary.md`:
- Around line 156-164: The complete-view absence witness is underspecified
across both documents. In
docs/architecture/echo-keep-physical-content-boundary.md:156-164, define the
receipt evidence, completeness predicate, and retained-closure proof required to
establish target non-membership in the pinned view; in
docs/plans/echo-keep-physical-cas-interop-plan.md:153-166, update the
conformance cases to exercise and verify that same evidence and rule.
- Around line 111-129: Define a single output-visibility contract and apply it
consistently: in
docs/architecture/echo-keep-physical-content-boundary.md:111-129, either specify
implementable transactional promotion semantics or revise the no-visible-bytes
guarantee; align the sink-failure witness in
docs/plans/echo-keep-physical-cas-interop-plan.md:139-146 with that choice; and
update the durable operation’s prefix rule in
docs/plans/echo-keep-physical-cas-interop-plan.md:190-198 to match the
architecture contract.
In `@docs/plans/echo-keep-physical-cas-interop-plan.md`:
- Around line 12-13: Update the “Keep contract” reference in the plan so it is
reproducible: link to the external flyingrobots/keep document at a specific
pinned revision, or explicitly identify the path as external and record the
revision used by the plan. Preserve the referenced document path while making
the cross-reference navigable and revision-specific.
🪄 Autofix
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 Plus
Run ID: c8c7fedb-49f9-429c-8a17-00641da1ac32
📒 Files selected for processing (3)
docs/README.mddocs/architecture/echo-keep-physical-content-boundary.mddocs/plans/echo-keep-physical-cas-interop-plan.md
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 60956c55e8
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
flyingrobots
marked this pull request as draft
August 10, 2026 04:05
flyingrobots
changed the title
flyingrobots
marked this pull request as ready for review
August 11, 2026 01:39
Contributor
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 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 `@docs/adr/0012-repository-knowledge-model.md`:
- Around line 24-29: Add a historical-retention note immediately before the
five-home list in the repository knowledge model section, stating that the list
records the July 2026 model and no longer governs current ownership. Preserve
the original decision text and distinguish it from the current Documentation
Standards policy.
In `@docs/architecture/echo-keep-physical-content-boundary.md`:
- Around line 134-137: Update the success-receipt verification described in the
staging artifact promotion flow to require the requested target identity, pinned
view identity, Keep identity, and exact logical length before atomic commit.
Ensure an artifact with a receipt for another same-length object cannot be
promoted, and preserve observation emission only after successful commit.
- Around line 293-298: Clarify the publication sequence around the Echo
request-and-claim contract: define the pre-publication claim as a
non-authoritative operation-intent or WAL record, explicitly not a content
reference or observation. State that Echo creates the authoritative reference
only after Keep’s publication is durably reconciled, while preserving the
existing settlement-before-resumption ordering.
🪄 Autofix
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 Plus
Run ID: 5162e8f3-88d5-46a1-b74e-ce598ac20e44
📒 Files selected for processing (13)
.github/workflows/ci.ymlAGENTS.mddocs/DOCUMENTATION_STANDARDS.mddocs/README.mddocs/adr/0012-repository-knowledge-model.mddocs/adr/README.mddocs/architecture/echo-keep-physical-content-boundary.mddocs/invariants/FIXED-TIMESTEP.mddocs/plans/echo-keep-physical-cas-interop-plan.mddocs/topics/README.mdtests/docs/test_adr_namespace.shtests/docs/test_documentation_model.shtests/docs/test_knowledge_model.sh
💤 Files with no reviewable changes (1)
- tests/docs/test_adr_namespace.sh
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b1f095ae47
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
echo-casremains in place.Invariants
Scope
This PR changes no Echo runtime API, WSC identity, durable format, or production backend. Keep is accepted only for experimental conformance, not as Echo sole durable content authority.
Evidence
tests/docs/test_documentation_model.shpreserves the closed ADR archive and prevents current documentation from restoring numbered allocation.01ac62a53.Compatibility and recovery
The architecture preserves current
echo-casbehavior and requires explicit migration, rollback, fallback removal, retention, and cross-store crash evidence before production adoption. Issue #722 owns that implementation and cutover work.Links
docs/architecture/echo-keep-physical-content-boundary.mddocs/DOCUMENTATION_STANDARDS.mdChecklist
Summary by CodeRabbit
Documentation
Tests