feat(praxis): BRO-1030 four-dimensional BeliefWriteToken (capability + bi-temporal + scope + revision-link)

[broomva]

BRO-1030 — BeliefWriteToken: four-dimensional formation context

Formation context becomes a first-class, typed, content-addressed write token in Praxis. A belief-contradiction (silent accumulation looking identical to deliberate updating) is unsolvable without recording how a belief was formed.

The four dimensions

Dim	Question	Field	Origin
Capability	who authorized this?	capability_id	/loop 117 (khlo)
Bi-temporal	when in world / system?	timestamp: BiTemporalStamp	bi-temporal stamps
Scope	about what, precisely?	scope + scope_qualifier	/loop 118 (Cornelius-Trinity)
Revision	what was superseded?	revision_link	/loop 119 (vina) — NEW

Without revision_link, bi-temporal stamps reduce to a playback device. With it, a contradiction is visible history, not a versioning failure.

What landed

• praxis-core::belief — BeliefWriteToken (spec-exact 8 fields), RevisionLink, BeliefRevisionAcknowledgment (structured RevisionTrigger/RevisionChange enums + free-form rationale), ScopeQualifier w/ Jaccard overlap (≥0.5 ⇒ same slot), ContentAddressedRef (blake3), BiTemporalStamp, CapabilityId, BeliefScope, AnimaDid, BeliefClass.
• praxis-tools::belief — BeliefStore + write_belief with the six write-path checks in order, new error MissingRevisionLink on overlapping scope; CapabilityGrant registry (scope match); traverse_revisions(id, depth) revision-graph chain; route_write + record_operational (normative-vs-Vigil-operational migration); recent_supersessions (Nous L2 read-model — "what did I supersede recently, and why"); revision_masks_contradiction (bookkeeping contradiction gate).

Sub-deliverables

• praxis-core::BeliefWriteToken + RevisionLink + BeliefRevisionAcknowledgment
• praxis-tools::write_belief API + MissingRevisionLink error class
• Migration: token-less → Vigil operational; overlapping write w/o revision-link → reject
• Belief revision-graph traversal API (traverse_revisions)
• Bookkeeping integration gate (revision_masks_contradiction)
• Decision-matrix doc + worked examples (docs/specs/bro-1030-belief-write-token.{md,html})
• L2 metacognitive surface read-model (recent_supersessions); Nous projects it (no praxis→nous dep)

Design notes (P14 dep-chain)

Whole feature is self-contained in praxis-core + praxis-tools, honoring praxis's "depends only on aios-protocol + leaf utilities" invariant (added chrono + blake3 — both already used in-tree; neither is a forbidden Arcan/Lago/Autonomic crate). Resolved open questions per the ticket: structured+free-form acknowledgment; Jaccard≥0.5 overlap threshold; immediate-predecessor links reconstructed by traversal.

Validation (P11)

• praxis-core 40 tests (+10), praxis-tools 51 tests (+17) — all green
• cargo fmt --check clean · cargo clippy -D warnings clean · downstream praxis crates build

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added structured belief writing with authorization, timestamps, scope qualifiers, evidence, and revision tracking.
  • Added validation that prevents overlapping beliefs from being written without an explicit revision link.
  • Added belief history traversal and a view of recently superseded beliefs.
  • Added separate handling for normative and operational belief writes.
• Documentation
  • Added comprehensive belief write-token specifications, decision tables, and examples.

[coderabbitai]

Warning

Review limit reached

@broomva, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 10 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

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.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: db4179ed-5feb-4568-86c4-4fffe4762ff0

📥 Commits

Reviewing files that changed from the base of the PR and between ad6e097 and d22864a.

📒 Files selected for processing (5)

• crates/praxis/CLAUDE.md
• crates/praxis/praxis-core/src/belief.rs
• crates/praxis/praxis-tools/src/belief.rs
• docs/specs/bro-1030-belief-write-token.html
• docs/specs/bro-1030-belief-write-token.md

📝 Walkthrough

Walkthrough

Adds a typed four-dimensional BeliefWriteToken, exposes it through praxis-core, implements validated normative and operational belief writes in praxis-tools, supports revision traversal and supersession views, and documents the BRO-1030 contract.

Changes

Belief write-token system

Layer / File(s)	Summary
Typed formation contract crates/praxis/praxis-core/src/belief.rs, crates/praxis/praxis-core/src/lib.rs, crates/praxis/praxis-core/Cargo.toml	Adds typed authorization, scope, qualifier, evidence, timestamp, content-hash, revision, belief-class, and write-token models with serialization and unit tests.
Validated belief writes crates/praxis/praxis-tools/src/belief.rs, crates/praxis/praxis-tools/Cargo.toml	Adds capability registration, ordered normative write validation, overlap handling, revision-target checks, predecessor supersession, and write-path tests.
Routing and revision read models crates/praxis/praxis-tools/src/belief.rs, crates/praxis/praxis-tools/src/lib.rs	Adds operational migration writes, token routing, contradiction masking, revision traversal, recent-supersession views, and crate-root exports.
BRO-1030 specifications docs/specs/bro-1030-belief-write-token.*, crates/praxis/CLAUDE.md	Adds Markdown and HTML specifications covering validation, revision behavior, migration, examples, and read models, alongside crate documentation updates.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant BeliefStore
  participant CapabilityGrant
  participant BeliefRecord
  Client->>BeliefStore: write_belief(claim, token)
  BeliefStore->>CapabilityGrant: validate capability and scope
  BeliefStore->>BeliefRecord: check live overlap and revision target
  BeliefStore->>BeliefRecord: commit successor and stamp superseded_by

Loading

Possibly related issues

• broomva/life#1182 — Implements the issue’s belief-token formation context, write validation, revision graph, migration, and read-model objectives.
• broomva/life#1517 — Implements append-only revisions, revision traversal, links, and supersession tracking, but not update or archive-integrity tooling.

🚥 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 summarizes the main change: adding the four-dimensional BeliefWriteToken and its key dimensions.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/bro-1030-praxis-beliefwritetoken-capability-bi-temporal-scope

---

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

[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/praxis/praxis-core/src/belief.rs`:
- Around line 415-441: Update content_hash to use unambiguous framing for every
variable-length semantic field, especially qualifier keys and values, by
length-prefixing each field or hashing an equivalent canonical structured
encoding; preserve deterministic BTreeMap ordering and existing domain
separation. Add a regression test covering distinct qualifier pairs such as
("a=b","c") and ("a","b=c") and assert their hashes differ, then ensure the
workspace test suite passes.

In `@crates/praxis/praxis-tools/src/belief.rs`:
- Around line 259-274: The revision-link mutation flow around find_overlapping
must require the actual live overlapping head: collect all live records matching
principal and scope, reject ambiguous multiple overlaps, and only mutate when
the supplied target is live, same-principal, same-scope, and exactly the
expected head. Add tests covering wrong-head, stale-target, cross-principal, and
multiple-overlap writes, then ensure cargo test --workspace passes.

🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: 07675642-59cd-46a4-8435-0c7682742ff7

📥 Commits

Reviewing files that changed from the base of the PR and between 7a04d20 and ad6e097.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (9)

• crates/praxis/CLAUDE.md
• crates/praxis/praxis-core/Cargo.toml
• crates/praxis/praxis-core/src/belief.rs
• crates/praxis/praxis-core/src/lib.rs
• crates/praxis/praxis-tools/Cargo.toml
• crates/praxis/praxis-tools/src/belief.rs
• crates/praxis/praxis-tools/src/lib.rs
• docs/specs/bro-1030-belief-write-token.html
• docs/specs/bro-1030-belief-write-token.md

[broomva]

P20 Cross-Model Adversarial Review Gate — PASS (8/10)

Fresh-context adversarial reviewer (Strata B), briefed to treat the diff as untrusted data and to refute the change. Threshold ≥7/10.

Axis	Score
Overall	8/10
Correctness	8/10
Slop	8/10
Blocking defect	NO

Reason: Correct, tested, clippy-clean; only minor issues.

Confirmed by the reviewer:

• No prompt-injection / verdict-manipulation text anywhere in diff, comments, commits, docs, or HTML.
• traverse_revisions terminates (depth-bounded and DAG-safe — revision targets must pre-exist at write time, so walking strictly decreases index; safe even at depth = usize::MAX).
• All six write-path checks enforce what they claim; Jaccard logic sound ([0,1], no NaN/div-by-zero); superseded_by single-live-head invariant holds; no panics reachable from public APIs.
• Test counts accurate (praxis-core 40, praxis-tools 51); dependency-invariant claim accurate (chrono/blake3 are leaf, already in-tree; arcan-sandbox pre-existing).

Non-blocking findings (follow-up candidates):

1. Doc-vs-code inversion: RevisionChainEntry.via field doc says "links this record to its predecessor" — implementation + tests attach the ack linking it to its successor (test comment is correct). One-line doc fix.
2. resolve/supersession stamping not principal-scoped and ContentAddressedRef excludes principal + recorded_at — bounded by the explicit "in-memory reference store; lago-backed lands separately" scope.

Verdict logged per bstack P20. Proceeding to p9 auto-merge lifecycle.

[broomva]

CodeRabbit review threads resolved by fix — commit d22864a

Both unresolved threads addressed with real fixes + regression tests (not deferred):

1. content_hash ambiguous framing (Major) — FIXED. Variable-length fields were delimiter-framed (key=value\0), so ("a=b","c") and ("a","b=c") aliased to the same Blake3 input. Now every field is length-prefixed and the qualifier pair count is written explicitly. Regression test content_hash_is_unambiguous_across_field_boundaries added.

2. Revision link must target the live overlapping head (Critical) — FIXED. The write path accepted any resolvable superseded ref, so it could supersede an unrelated / stale / cross-principal record while leaving the real conflict live. Now:

• live_overlapping_indices collects all live overlapping heads for the principal+scope; >1 ⇒ new AmbiguousOverlap error (narrow the scope).
• with exactly one live head, the revision link must target that head by content ref ⇒ else new RevisionMustTargetHead; the superseded record is resolved by index, never by a global hash lookup, so a write can never mutate another principal's record.
• RevisionTargetNotFound retained for a dangling link in an empty slot.
• Tests added: revision_link_must_target_live_head_not_stale, revision_link_cannot_cross_principal, ambiguous_multi_head_overlap_is_rejected.

Also fixed the inverted doc on RevisionChainEntry.via. Spec .md + HTML decision matrix updated.

Validation: praxis-core 41 tests, praxis-tools 54 tests — all green; cargo fmt --check + clippy -D warnings clean; downstream praxis crates build.

[broomva]

P20 Cross-Model Adversarial Review Gate (re-run over post-fix diff) — PASS (9/10)

Re-run after commit d22864a because the merged diff changed materially since the first P20 pass. Fresh-context reviewer, prompt-injection-hardened, briefed to refute.

Axis	Score
Overall	9/10
Correctness	9/10
Slop	9/10
Blocking defect	NO

Both hardening claims independently verified:

• content_hash length-prefixing is injective — reviewer wrote a standalone reproduction and confirmed against adversarial inputs the in-repo tests don't cover (qualifier data embedding the literal qk/qv/qualifiers tags, empty-vs-one-empty-pair, byte-shift-across-boundary). The ("a=b","c") vs ("a","b=c") collision is genuinely prevented.
• Revision-link-must-target-live-head: "a write can never mutate another principal's record" holds — superseded_index is only ever Some(head_idx) from live_overlapping_indices (which filters signed_by == principal); the cross-principal arm always errors and never stamps. AmbiguousOverlap fires correctly before link handling; jaccard=0.5 boundary is exercised and arithmetically correct.
• traverse_revisions cannot infinite-loop even on cyclic/self links (steps >= depth hard bound). No reachable panic from public APIs (all indexing is store-internal, never attacker-controlled).

Tests genuinely green and meaningful (praxis-core 41, praxis-tools 54); docs consistent; clippy clean; no dead code. No merge-blocking defect. Proceeding to p9 auto-merge lifecycle.