Finish braid historical membership and replay goalpost

[flyingrobots]

Summary

Completes Goalpost 3 of the braids/strands hardening roadmap: historical membership and replay.

This PR adds:

• BraidMembershipCursor, Braid::current_membership_cursor(), and Braid::membership_at(...) for historical membership views over accepted MemberWoven events.
• BraidMembershipDiff and Braid::diff_membership(...) for deterministic added/ended projection facts, with revealed/concealed slots reserved until explicit disclosure evidence exists.
• audit_braid_shell(...) and BraidShellAudit for retained shell replay/audit facts: member verdicts, support/frontier digests, posture floor, proof binding, and self-witness posture.
• Braid Flight Recorder and Causal X-Ray lower-mode output shape in the Goalpost 3 design packet.

The implementation keeps event-log membership cursors distinct from BraidCoordinate, which remains shell identity. Audit facts validate the same retained shell and lineage constraints as replay_braid_shell(...) and do not reopen member strand histories.

Validation

Local witnesses and hooks run before opening this PR:

• RED witnesses first for GP3-S2, GP3-S3, and GP3-S4 missing APIs.
• cargo test -p warp-core --test braid_public_api_tests
• cargo test -p warp-core braid::tests
• cargo test -p warp-core braid_shell::tests
• cargo test -p warp-core --lib via pre-push hook
• cargo clippy -p warp-core --lib -- -D warnings
• cargo clippy -p warp-core --test braid_public_api_tests -- -D warnings
• cargo fmt --all -- --check
• pnpm exec markdownlint-cli2 CHANGELOG.md docs/design/braids-and-strands-roadmap.md docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md
• scripts/check_spdx.sh
• git diff --check
• pre-commit hooks on all four commits
• pre-push hook on branch push

Summary by CodeRabbit

• New Features
  • Historical membership projection: Query membership using event-sequence cursors
  • Membership diff computation: Report deterministic membership additions/ends between two cursors
  • Braid shell audit: Generate audit records with member verdicts, support/frontier digests, witness posture, and proof-binding status
• Documentation
  • Marked historical membership and replay milestones as implemented and clarified projection/diff semantics
  • Documented “Braid Flight Recorder” and “Causal X-Ray” output targets, including example audit/recorder fixtures

[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

Run ID: 77883a03-4d1c-4345-ac06-f92ce2bb353f

📥 Commits

Reviewing files that changed from the base of the PR and between f74d3e8 and b84bfc3.

📒 Files selected for processing (1)

• docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md

---

📝 Walkthrough

Walkthrough

Adds historical braid membership projection via BraidMembershipCursor-based membership_at and diff_membership APIs on Braid, and a shell audit surface via audit_braid_shell returning BraidShellAudit with per-member verdicts, proof binding, and witness posture. New types are re-exported from the crate root. Tests and design docs define cursor semantics, Flight Recorder pipeline, and Causal X-Ray output target.

Changes

Historical Braid Membership Projection

Layer / File(s)	Summary
Membership cursor/diff types and module exports crates/warp-core/src/braid.rs, crates/warp-core/src/lib.rs	Adds BTreeMap import; defines BraidMembershipCursor (half-open sequence interval), BraidMembershipDisclosureChange, and BraidMembershipDiff with is_empty; re-exports all three from crate root alongside reformatted braid_shell re-exports.
Braid projection methods, API tests, and design docs crates/warp-core/src/braid.rs, crates/warp-core/tests/braid_public_api_tests.rs, docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md, docs/design/braids-and-strands-roadmap.md	Implements current_membership_cursor, membership_at (filters MemberWoven by sequence number), diff_membership (set comparison over projected entries), and private membership_index helper. External tests validate membership projections before/after weave events and diff semantics in both directions. Design docs mark GP3-S1 implemented, define event-sequence cursor semantics with reserved disclosure slots and no implicit inference, update roadmap status and parameter naming (from_cursor/to_cursor).

Braid Shell Audit Surface

Layer / File(s)	Summary
Shell audit data model crates/warp-core/src/braid_shell.rs	Defines BraidProofBinding (absent vs. matched with proof kind/digests/public inputs), BraidWitnessPosture (SelfWitnessIntegrityOnly), BraidShellMemberAuditFact (per-member verdict/frontier digest/support proof status), and BraidShellAudit (posture floor, settlement frontier, members, proof binding, witness posture).
audit_braid_shell implementation, tests, and design docs crates/warp-core/src/braid_shell.rs, CHANGELOG.md, docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md	Implements audit_braid_shell via shared validated_shell_for_replay, computing posture_floor as least-revealed posture, deriving proof_binding from optional proof envelope, and building per-member BraidShellMemberAuditFact entries. Fixes validated_shell_for_replay to return Ok(shell) after lineage validation. Unit test constructs proof-bearing shell and asserts audit fields. Design docs expand Flight Recorder pipeline to consume fact APIs and specify Causal X-Ray lower-mode JSON output target with concrete fixture example (membership projection/diff, shell details, member digests, proof binding, witness posture, warnings). Changelog records all three feature additions. Non-goals explicitly exclude Causal X-Ray CLI command.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• flyingrobots/echo#550: Introduces the BraidMembershipEntry concept that the cursor/diff APIs in this PR operate over.

Suggested labels

tooling

Poem

Cursors now slice through the braid's tangled past,
Half-open windows hold each member fast.
The shell audit speaks: proof bound or bare,
Posture and witness laid open to air.
X-Ray the causal, replay what was cast —
The flight recorder rolls, anchored at last. 🛩️

🚥 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 directly summarizes the main objective: completing Goalpost 3 (historical membership and replay) for braids. It aligns with the core changes across documentation, membership API, shell audit, and public exports.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 hardening/braid-membership-coordinate-views

---

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]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md (1)

46-48: ⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Remove stale GP3-S1-only scope text to avoid design contradiction.

Line 46-48 conflicts with Line 6 (Status: implemented.) and the implemented cursor/diff/audit sections below. Keep this section consistent with the current implemented scope to prevent stale design guidance.

As per coding guidelines, “Documentation accuracy matters — especially anything touching determinism guarantees, hash stability, or canonical ordering.”

🤖 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/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md`
around lines 46 - 48, The text describing GP3-S1 in lines 46-48 contradicts the
"Status: implemented" statement on line 6 and the implemented cursor/diff/audit
sections that follow. Remove or update the GP3-S1 scope description that states
it does not implement cursor, diff, replay, or recorder surfaces, and instead
align it with the current implemented status and the detailed implemented
sections below to maintain consistency throughout the document.

Source: Coding guidelines

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

Outside diff comments:
In
`@docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md`:
- Around line 46-48: The text describing GP3-S1 in lines 46-48 contradicts the
"Status: implemented" statement on line 6 and the implemented cursor/diff/audit
sections that follow. Remove or update the GP3-S1 scope description that states
it does not implement cursor, diff, replay, or recorder surfaces, and instead
align it with the current implemented status and the detailed implemented
sections below to maintain consistency throughout the document.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: fc6fc5e1-0ef8-42c4-a936-2d894466056b

📥 Commits

Reviewing files that changed from the base of the PR and between e55f6bf and f74d3e8.

📒 Files selected for processing (7)

• CHANGELOG.md
• crates/warp-core/src/braid.rs
• crates/warp-core/src/braid_shell.rs
• crates/warp-core/src/lib.rs
• crates/warp-core/tests/braid_public_api_tests.rs
• docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md
• docs/design/braids-and-strands-roadmap.md

[flyingrobots]

Self-Code Review Findings

@codex please sanity-check these review notes.

I reviewed hardening/braid-membership-coordinate-views against origin/main for PR #551. No P0-P4 behavior, determinism, race, API-safety, or Rust quality issues found. The remaining findings are documentation consistency nits.

Severity	File	Lines	Infraction	Evidence	Recommended mitigation
P5 Nit	docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md	L46-L47	Stale implementation-design wording after the goalpost was marked implemented.	The file now says Status: implemented., but the implementation design still says GP3-S1 establishes... without implementing the later coordinate, diff, replay, or recorder surfaces. The same PR implements/checks off those later surfaces.	Rewrite this paragraph to make the sequence explicit: GP3-S1 established the source of truth, while GP3-S2 through GP3-S5 now add historical views, diffs, audit facts, and recorder output shape.
P5 Nit	docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md	L202-L206	Inconsistent Markdown list punctuation.	The non-goals list uses semicolon-delimited bullets, but plurality law registry execution. now has a period even though another bullet follows.	Normalize the list punctuation: use semicolons for non-final bullets and a period only on the final bullet.

Verification performed:

• git status --porcelain clean before review.
• git fetch origin --prune completed.
• git diff --check origin/main...HEAD clean.
• GitHub checks are green, including CodeRabbit.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🚀

Reviewed commit: f74d3e82d0

ℹ️ 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]

Resolved both self-review findings in b84bfc3 (docs-only): updated the GP3 implementation-design wording and normalized the non-goals punctuation.

[flyingrobots]

Code Lawyer Activity Summary

Lockdown and review pass completed on current head b84bfc30.

#	Source	Severity	File	Lines	Issue	Commit	Outcome
1	PR / CodeRabbit	P5	docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md	L46-L48	Stale GP3-S1-only wording contradicted implemented status.	b84bfc30	Resolved before this pass; verified current text is aligned.
2	Self	P5	docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md	L202-L206	Non-goals list punctuation was inconsistent after adding a final bullet.	b84bfc30	Resolved before this pass; verified punctuation is normalized.
3	Self	None	full origin/main...HEAD diff	n/a	Fresh deep audit found no new logic, race, edge-case, determinism, duplication, SoC, style, typing, or docs issues.	n/a	No action needed.

Review-thread state:

• GraphQL review threads: 0 total, 0 unresolved.
• Changes Requested reviews: 0.
• Approvals: 0.
• CodeRabbit status: SUCCESS.

Verification:

• git status --porcelain: clean.
• git fetch origin --prune: completed.
• git diff --check origin/main...HEAD: passed.
• scripts/check_spdx.sh: passed.
• cargo fmt --all -- --check: passed.
• pnpm exec markdownlint-cli2 CHANGELOG.md docs/design/braids-and-strands-roadmap.md docs/design/braids-and-strands-hardening/goalpost-03-historical-membership-and-replay.md: passed.
• cargo test -p warp-core --test braid_public_api_tests: 7 passed.
• cargo test -p warp-core --lib braid::tests: 8 passed.
• cargo test -p warp-core --lib braid_shell::tests: 26 passed.
• cargo test -p warp-core --lib: 562 passed.
• cargo clippy -p warp-core --test braid_public_api_tests -- -D warnings: passed.
• cargo clippy -p warp-core --lib -- -D warnings: passed.
• gh pr checks 551: all checks passing.

Merge gate: locked by review policy only (0 approvals; required >=2).

[flyingrobots]

@coderabbitai review

[flyingrobots]

@codex review please

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Hooray!

Reviewed commit: b84bfc30c0

ℹ️ 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".