docs: clarify reachable roots and detached-write evidence

[flyingrobots]

Closes #754.

WorldlineState::state_root() was described as a full-state hash, although the version-1 Merkle law covers only state reachable from the lane root. The API and operation/WAL documentation now state that detached create-if-absent cells can leave this root unchanged. Patch and commit identities retain those writes; duplicate evidence still needs the target-value digest. Hash bytes and runtime behavior are unchanged.

A focused witness creates two detached cells, verifies their presence and unchanged root, then holds root, parents, and policy fixed while proving their patch and commit identities differ.

Validation in the reused guarded Docker worker: the focused witness passed; all 11 worldline_state::tests passed; workspace rustfmt check, docs-lint link checks, and whitespace checks passed. Docs-lint skipped prettier/markdownlint because npx is absent; those checks are not claimed. Concrete API text before/after evidence is retained.

Canonical owners reviewed: docs/spec/merkle-commit.md, docs/architecture/application-contract-hosting.md, docs/topics/WAL.md, and the README route. Their reachable-state law stays unchanged. No provider package, footprint, WAL schema, or application-specific behavior changes.

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 42 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: flyingrobots/echo/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: c0b630e3-6d75-4153-b96f-49089d0a97b1

📥 Commits

Reviewing files that changed from the base of the PR and between a93e9d8 and f246f07.

📒 Files selected for processing (4)

• CHANGELOG.md
• crates/warp-core/src/worldline_state.rs
• docs/architecture/application-contract-hosting.md
• docs/topics/WAL.md

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

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

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-07T11:17:31.154388Z	f246f07	PR opened

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[flyingrobots]

Code Lawyer activity summary at f246f0711623617e7dd4f61d95642576bde44d0b.

Item	Finding / evidence	Result
Root contract	The old API said full-state. The canonical Merkle specification and actual hashing traversal cover reachable state. The API and operation/WAL text now agree.	Addressed
Detached-write witness	Two distinct node/attachment patches preserve the reachable root. Both cells exist. With equal root, parents and policy, patch digests and computed commit identities differ.	Passed in Docker
Caller evidence	Runner duplicate checks retain both roots and typed target-value digests. WAL recovery also binds patches, receipts, basis and Action decisions. Root equality alone is explicitly insufficient.	Inspected
Compatibility	No hashing code, operation footprint, provider package, persisted schema or callback path changes.	Preserved

Inspected the clean checkout, normal origin fetch, whole diff, canonical documentation, changed symbol callers, and all paginated PR review data. No actionable self-finding remains. The exact committed files match the guarded candidate manifest.

Executed in the reused guarded Docker worker: focused detached-create witness, all 11 worldline_state tests, workspace rustfmt check, and docs-lint link checks. Whitespace checks passed. Docs-lint skipped prettier/markdownlint because npx is absent; those local checks remain unrun. The witness is a unit contract test; original benchmark measurements were not reproduced.

Current-head hosted checks are green. Independent agy approval is still pending, and the user-requested solution-feedback reconciliation remains a merge prerequisite. No merge is claimed. @codex

[chatgpt-codex-connector]

Review Outcome

• No actionable code or documentation finding remains. The existing commit already documents that state roots cover reachable state and that detached writes remain bound by patch and commit evidence. docs/topics/WAL.mdL248-L248
• The application-contract documentation also explains why equal roots alone do not prove equal stores or the absence of detached writes. docs/architecture/application-contract-hosting.mdL166-L166
• The shipped-behavior clarification is recorded in the changelog. CHANGELOG.mdL6-L10
• The working tree was clean at f246f0711623617e7dd4f61d95642576bde44d0b. No new changes were necessary, so no additional commit or follow-up pull request was created. Independent approval and solution-feedback reconciliation remain external merge prerequisites.

Checks

• ✅ git status --short --branch
• ✅ git diff --check
• ✅ git show --stat --oneline --decorate HEAD
• ✅ git diff-tree --no-commit-id --name-only -r HEAD

View task →

[flyingrobots]

Adversarial Independent Review: PR #762 (flyingrobots/echo)

• Pull Request: #762 docs: clarify reachable roots and detached-write evidence
• Branch: fix/study-state-root-contract
• Head Commit: f246f0711623617e7dd4f61d95642576bde44d0b
• Base Commit: a93e9d82e89455ed1fa0b63447c88de544b9da26 (target: main)
• Reviewer Role: Adversarial Independent Reviewer (read-only; no file modifications, commits, pushes, comments, merges, or host/Docker test executions)

---

Executive Summary & Review Scope

PR #762 resolves Feedback Item 1 from [supplied sources: FEEDBACK-echo.md] (tracking issue #754). Detached cells created via anchored-node-attachment-create-if-absent/v1 do not add a skeleton edge from the lane root, leaving WorldlineState::state_root() unchanged while the doc comment historically claimed a "canonical full-state root hash". The underlying BLAKE3 Merkle implementation deliberately and normatively commits only to reachable WARP state.

This PR:

1. Corrects the WorldlineState::state_root() doc comment to define its reachability boundary and explain that equal roots do not prove equal stores.
2. Updates canonical operation and WAL documentation (docs/architecture/application-contract-hosting.md and docs/topics/WAL.md) to reflect that detached writes remain bound by the tick patch digest and commit identity, and that root equality alone is insufficient for recovery or no-mutation witnesses.
3. Records the API documentation correction in CHANGELOG.md.
4. Adds a synthetic unit witness detached_creates_preserve_state_root_but_change_patch_and_commit_identity proving that two detached writes preserve the reachable root while differing in patch digests and commit hash v2 identities.
5. Preserves all hash bytes, operation footprints, schemas, and runtime execution paths unchanged.

---

Findings (P0–P5)

No functional defects, regressions, unhandled error transitions, or documentation inconsistencies were found in the PR diff or candidate tree at head f246f0711623617e7dd4f61d95642576bde44d0b.

Review Coverage Limitations & Non-Defect Observations

1. Linter Execution Gap (Inspected from Docker Logs; Skipped in Runner):
   • Evidence: [retained evidence: s01-green.log:40-41] records:

     markdown-fix: npx not found, skipping prettier
     markdown-fix: npx not found, skipping markdownlint
     

   • Status: Neither prettier nor markdownlint executed in the Docker validation runner due to the absent npx binary in echo-read-runtime:red. git diff --check and xtask docs-lint link checks executed and passed. This review inspected Markdown formatting manually (confirming single-physical-line paragraphs and clean link targets).
2. Synthetic Unit Witness vs. Benchmark Scope (Declared & Accurately Scoped):
   • Evidence: PR description and crates/warp-core/src/worldline_state.rs:488-540.
   • Status: The added test is a synthetic unit witness of the causal Merkle law and commit identity binding, not a live scheduler benchmark or reproduction of the 5,000-fact study run from [FEEDBACK-echo.md:14-15]. The PR body and commit message truthfully scope this claim.
3. Separate Roadmap PR docs: record the study audit and experimental Keep roadmap #758 Unmerged:
   • Status: PR docs: record the study audit and experimental Keep roadmap #758 (audit/study-feedback) is separate and has not merged into main. The current review confirmed no dependency on PR docs: record the study audit and experimental Keep roadmap #758 and evaluated PR docs: clarify reachable roots and detached-write evidence #762 strictly against main base a93e9d82e89455ed1fa0b63447c88de544b9da26.

---

Mandatory Verification Checklist

1. Code Paths Traced

• Path 1: WorldlineState::state_root() Evaluation Boundary
  • Trace: crates/warp-core/src/worldline_state.rs:252-255 $\rightarrow$ crates/warp-core/src/snapshot.rs:157-159 $\rightarrow$ crates/warp-core/src/snapshot.rs:81-153.
  • Production Behavior: compute_state_root executes BFS traversal collect_reachable_graph(state, root) (snapshot.rs:83, 161-200). Nodes and edges are filtered by reachability (snapshot.rs:113, 126). Unconnected nodes created in the store are omitted from the hash by design. The updated doc comment accurately reflects this invariant.
• Path 2: Commit ID v2 Delta Binding
  • Trace: crates/warp-core/src/snapshot.rs:257-277 invoked by production settlement in crates/warp-core/src/settlement.rs:1374 and crates/warp-core/src/engine_impl.rs:2242.
  • Production Behavior: compute_commit_hash_v2(state_root, parents, patch_digest, policy_id) commits directly to patch_digest. When state_root, parents, and policy_id remain identical across detached writes, distinct patches produce distinct commit hashes.
• Path 3: Detached Operation Emission in Production
  • Trace: crates/warp-core/src/echo_operation.rs:4665-4682.
  • Production Behavior: AnchoredNodeOperationModeV1::CreateIfAbsent emits WarpOp::UpsertNode and WarpOp::SetAttachment for the target node/slot without inserting an edge from state.root(). The node exists in store.nodes and store.node_attachments, but has no edge from the root.
• Path 4: Runner Duplicate and Recovery Witnesses
  • Trace: xtask/src/run_edict_operation.rs:437-442 and xtask/src/run_edict_operation.rs:618-644.
  • Production Behavior: state_recovered checks both current_state(&recovered)?.state_root() == committed_state_root AND node_value(...) == input.replacement. duplicate_report compares both application_state_root_before == application_state_root_after AND target_value_before == target_value_after, retaining target_value_digest_before and target_value_digest_after. Callers do not rely solely on state root equality.
• Path 5: Unit Contract Witness
  • Trace: crates/warp-core/src/worldline_state.rs:488-540.
  • Test Behavior: Builds empty state, captures initial root root. Sequentially applies detached-a and detached-b patches containing UpsertNode and SetAttachment. Verifies state.state_root() == root, asserts presence in store.node() and store.node_attachment(), and asserts patch_digests[0] != patch_digests[1] and commit_ids[0] != commit_ids[1] under identical root, parents (&[]), and policy (0).

2. Merges Audited

• PR Commit History: Exactly 1 commit:
  • f246f0711623617e7dd4f61d95642576bde44d0b (docs: state reachable root coverage and bind detached-write evidence).
• Merge Commit Check: Zero merge commits exist in PR docs: clarify reachable roots and detached-write evidence #762. The branch is a clean linear diff atop origin/main (a93e9d82e89455ed1fa0b63447c88de544b9da26).
• Semantic Integration Invariants: git diff --check passes with zero whitespace or conflict markers. The working tree is clean and mergeStateStatus is CLEAN.

3. Verification of Claims (No Trusted Claims)

• Claim A: Old API doc claimed full-state root.
  • Verification: Verified at base commit a93e9d82; line 250 read /// Returns the canonical full-state root hash for this worldline.. Replaced with reachability boundary specification ([s01-contract-before-after.json]).
• Claim B: Merkle spec mandates reachable WARP state.
  • Verification: docs/spec/merkle-commit.md:26-28 states: Decision 1: state_root commits to reachable WARP state. The state root is BLAKE3 over canonical encoding of reachable WARP state from a root NodeKey. Reachability follows outbound skeleton edges and descended attachment portals....
• Claim C: Hash bytes and runtime code are unchanged.
  • Verification: git diff a93e9d82..f246f071 modifies zero lines in compute_state_root or compute_commit_hash_v2 in crates/warp-core/src/snapshot.rs.
• Claim D: Duplicate evidence retains target-value digest.
  • Verification: Line-by-line check in xtask/src/run_edict_operation.rs:626-642 confirms target_value_before == target_value_after and target_value_digest_before/target_value_digest_after are recorded in the report.

4. Constants & Evidence Verification

• Candidate Manifest Verification:
  • Evaluated [retained evidence: s01-green.manifest.json] against candidate checkout at f246f0711623617e7dd4f61d95642576bde44d0b.
  • Exactly 964 files evaluated. SHA256 mismatches: 0.
  • Candidate files SHA256 verified:
    • CHANGELOG.md: e2d35aab52e62a26c9b754d737808236f471d2f6a570370a8046645dacf23f13
    • crates/warp-core/src/worldline_state.rs: 68db8484040e8a9e9be66f1da8de8d52d689a8645f2865fc85b227cfce596029
    • docs/architecture/application-contract-hosting.md: 6c1e05d6ad05bac13296dc2d363893776f45a4effa4ee7b2f15964749c7a0872
    • docs/topics/WAL.md: 345d4cddea8f223f1580e140e0a807f8861825d4ce6c62d489ee8152d2674742
• Docker Resource Contract Telemetry:
  • Reused worker: echo-read-runtime (echo-read-runtime:red). Reused cache: /lease-target.
  • Canonical locks: /Users/Shared/git-locks/workstation.git (host/heavy-work, host/docker/echo-read-runtime/, host/docker/echo-provider-builder/).
  • Limits: 20 GiB build ($21,474,836,480$ B), 4 GiB data ($4,294,967,296$ B), 128 MiB logs ($134,217,728$ B); 50 GiB host/VM free space floor ($53,687,091,200$ B); 4.0 CPUs, 6 GiB RAM, 1000s timeout.
  • S01 POST Telemetry ([s01-green.result.json]):
    • Build: $13,088,045,872$ B ($< 20$ GiB budget)
    • Data: $4,246,080,304$ B ($< 4$ GiB budget)
    • Logs: $13,373,417$ B ($< 128$ MiB budget)
    • Host free: $736,909,209,600$ B ($> 50$ GiB floor)
    • VM free: $700,456,304,640$ B ($> 50$ GiB floor)
    • Exit code: 0. Worker stopped.

5. Document Figures Checked

• 964 files: Matches s01-green.manifest.json count and candidate checkout verification.
• 11 unit tests: Matches s01-green.log line 18 (running 11 tests $\rightarrow$ 11 passed) and grep count for #[test] in crates/warp-core/src/worldline_state.rs.
• 82 markdown files: Matches s01-green.log line 38 (markdown-fix: 82 file(s) in docs) and file tree scan of docs/**/*.md.
• 4 files modified: Matches git show --stat (4 files changed, 64 insertions(+), 1 deletion(-)).

6. Repository Standards & AGENTS.md Conformance

• Git rules honored: standard commit, no amend, no rebase, no force-push.
• Documentation standards (docs/DOCUMENTATION_STANDARDS.md):
  • Canonical owners preserved: docs/architecture/application-contract-hosting.md, docs/topics/WAL.md, and CHANGELOG.md.
  • Single-physical-line paragraphs verified at application-contract-hosting.md:166, WAL.md:248, and CHANGELOG.md:10.
• Pure Rust, edition 2024, pinned toolchain 1.96.0.
• Test law naming: detached_creates_preserve_state_root_but_change_patch_and_commit_identity states a causal law.

---

Checks Executed, Inspected, Skipped, or Unavailable

• Executed in this review session:
  • Git commit tree, patch inspection, and history (git log -n 5, git status, git rev-parse HEAD, git diff).
  • Full candidate manifest SHA256 evaluation across all 964 files against [s01-green.manifest.json].
  • Code path inspection across worldline_state.rs, snapshot.rs, echo_operation.rs, run_edict_operation.rs, and merkle-commit.md.
  • git diff --check whitespace and formatting verification.
  • Review discussion and PR state audit via [pr762-current.json].
• Inspected from raw primary Docker evidence:
  • Focused test execution and worldline_state::tests suite passing ([s01-green.log:1-32]).
  • Formatting and docs-lint link validation ([s01-green.log:33-45]).
  • Process launch and post-run resource limits and telemetry ([s01-green.launch.json], [s01-green.result.json]).
• Skipped during primary validation:
  • prettier and markdownlint (skipped in container due to absent npx; manually verified).
• Unavailable:
  • Raw original benchmark harness and WAL stores from the author of FEEDBACK-echo.md (unreproduced; properly scoped).
  • Host and Docker test execution by reviewer (forbidden by read-only independent review role).

---

APPROVE

Primary source correction: the review’s incidental edition statement is inaccurate. crates/warp-core/Cargo.toml declares Rust edition 2021 and MSRV 1.96.0. The original report remains preserved. No code changes follow from this correction. The reviewer’s exact-head approval and runtime-path checklist are recorded above.