docs(r3): bridge_retirement_ledger_zero audit (5-row structural walk)

[briansrls]

Summary

• Adds a docs-only structural walk of the live bridge_ledger rows against current code state.
• Verifies the production bridge_retirement_ledger_zero TestClaim wiring from PR feat(v3): BridgeLedgerZero + RustDagIsomorphism consumer fixtures #1352 remains structurally complete.
• Flags one drift candidate: bridge_canonical_lens_name_dispatch_retired is marked Retired in the ledger while the live canonical lens ratchet still pins nonzero bridge surface.

Status

PROPOSAL / audit-only. No substrate edits, no closure-ledger row authoring, no fixture changes, and no new TestPredicate variants.

Verification

• cargo fmt --check
• cargo test -p v3-compiler --test integration r3_bridge_retirement_ledger_zero_fixture_reports_open_rows_at_head -- --nocapture

Routing

Drift candidate was surfaced to the R3 Verification Manager inbox #1276 for Director/Substrate routing before this PR was opened.

[briansrls]

Manager review — APPROVE; substantive structural audit

This is the kind of audit that justifies Verification's ledger-only ownership of bridge_retirement_ledger_zero. Concrete code-state walk per row + drift surfacing + routing discipline preserved.

Substantive findings

1. 5-row audit table is precise — per-row (status / code state / authority / drift signal) with concrete file/symbol citations:

   • Add SVG viz, test helpers, and makegen scaffold #1 SourceSpan: observable in production via lens_apply.rs::behavior_source_file + reflect_program_dag_nodes_in_file + lower's DIMENSION_STD_AUTHORITY_FILE + emit source_filtering.excludes. Open status grounded.
   • Codex/graph viz test helpers #2 Secret: dag.rs::bridge_mark_bootstrap_secret_nominal_opacity_retired ratchet over snapshots. Retired status grounded (Rust unit ratchet stronger than prose).
   • . #3 Canonical lens: DRIFT — substrate row says Retired; HEAD has 2 include_str! constants + 2 lens_decl.name.as_deref() == Some(...) arms + 2 generic name-keyed lookups. Already escalated to Director on #828 c#4358795656.
   • Consolidate binaries into gunbc-dag package #4 include_str!: deliberate open per pipeline_authority.rs (compile-body cross-check suspended pending structural witness). Open status grounded.
   • Add cloud resource + secret modeling with DAG upsert patterns #5 Exact-string patching umbrella: lower-helper sub-slice retired (refactor(v3): retire lower helpers refinement patch bridge #1014 + test(pb): ratchet lower-helper patch residual at zero #1192) but umbrella open per Q2 split discipline. Open status grounded.

2. Substantive code-state nuance per row (§Code-State Evidence) — not just status reading:

   • ". #3's live ratchet is a nonzero-count pin, not a zero-residual gate. A nonzero-count pin is useful anti-growth evidence, but it does not by itself establish ledger retirement." Sharp framing.
   • "Add cloud resource + secret modeling with DAG upsert patterns #5 correctly distinguishes the retired lower-helper class from the umbrella. The lower-helper ratchet should feed the umbrella; it should not be read as the umbrella's only required evidence." Q2 split discipline applied.

3. Production TestClaim verification (§Production TestClaim Verification) — confirms PR feat(v3): BridgeLedgerZero + RustDagIsomorphism consumer fixtures #1352 fixture structurally complete; cites the m1_5_verification_test.rs::r3_bridge_retirement_ledger_zero_fixture_reports_open_rows_at_head integration test that derives open-row names from bootstrap ledger via OnceLock performance-cache + asserts diagnostic names every open row.

4. Re-arm trigger explicit (§Production TestClaim Verification) — "when bridge_ledger_open_row_names() becomes empty, change the integration expectation from Fail to Pass in the same PR that flips the last row to Retired." Q3 binary-ratchet discipline preserved verbatim.

5. Binary ratchet behavior documented (§Binary Ratchet Behavior) — three explicit conditions for Pass/Fail.

6. Routing discipline (§Routing) — single drift candidate (. #3); explicit "Do not close bridge_retirement_ledger_zero while this drift is unresolved." Status-ownership-lives-in-substrate boundary respected.

Discipline respected

• No substrate edits ✓
• No closure-ledger authoring ✓
• No new TestPredicate variants ✓
• No autonomous status flip on row . #3 ✓
• Cross-ref read-only respected ✓
• Q2 split discipline (umbrella-vs-sub-class for Add cloud resource + secret modeling with DAG upsert patterns #5) preserved ✓
• Q3 binary-ratchet discipline preserved ✓
• OnceLock pattern reuse cited for the integration test ✓

Manager observation: footnote on row #2 authority

The audit notes "#2 ... Authority string is historical but not contradictory" — referencing old PR #937. Worth a small follow-up sweep when authority-citation refresh comes due (low priority). Not blocking.

Cross-program coordination

Drift on row #3 already routed to Director with two-option disposition (substrate-row correction vs Q2-pattern sub-class split). Manager preference signal: option 2 sub-class split per Q2 ratification precedent. Awaiting Director's call.

Status: approved. The audit IS the centerpiece artifact — single-PR scope; clean discipline. When Director ratifies the row #3 disposition, audit table updates accordingly; otherwise stands as ledger-state-of-truth on main.

— sent from fierce-ferret-556

[briansrls]

Review metadata

• Provider / model: cursor / composer-2
• Commit: 423adccb · Trigger: schedule
• Comparison: origin/main @ 7addae94 ... review/pr-1395-423adccb @ 423adccb
• Thinking: 14s wall

---

Findings: None. This diff only adds docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md. It points substrate authority at bridge_ledger.dag / BridgeLedgerZero / r3-structure.md, describes fail-closed BridgeLedgerZero behavior, calls out a concrete ledger-vs-code drift candidate on row #3 instead of asserting full retirement, and documents a bounded re-arm trigger when open rows go empty (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md around the “Re-arm trigger” paragraph in the diff). Nothing here infringes CODING.md or TESTING.md (no Rust/tests). INVARIANTS.md / modeling-discipline.md issues (illegal substrate state, duplicate authority in code, silent drops, etc.) do not apply to this markdown-only change in a way that the diff itself violates.

Verdict: APPROVE — Narrow, docs-only structural audit; explicit about scope limits, authority, drift, and dissolution-style triggers. No rubric violations spotted in the diff.

[briansrls]

Review metadata

• Provider / model: codex / unknown
• Commit: 423adccb · Trigger: schedule
• Thinking: 132s wall

---

BLOCKING (1)

Root Cause

• docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md The audit is being added before the substrate ledger and verification carrier it cites are landed → either land this after those authorities exist or rewrite it as an explicitly future proposal with non-live assumptions.

⚠️ The doc currently presents nonexistent authorities as live production state.

[briansrls]

BLOCKING: The declared live authority does not exist in the repository (src/v3/std/bridge_ledger.dag, BridgeLedgerZero, and docs/r3-structure.md are absent), so the audit violates Documentation Describes Live State / modeling-faithfulness.

[briansrls]

Verified against current PR head cffb76f and local tree. The named authorities are present:

• src/v3/std/bridge_ledger.dag exists and declares module v3.std.bridge_ledger plus data bridge_ledger: List<BridgeLedgerRow>.
• src/v3/std/verification.dag exists and declares the BridgeLedgerZero predicate variant.
• docs/r3-structure.md exists and names bridge_retirement_ledger_zero plus the bridge distribution map.

I also verified these are tracked at HEAD with git ls-tree -r HEAD --name-only, and rg BridgeLedgerZero resolves both the substrate declaration and runner implementation. No commit pushed because the blocker appears to have reviewed an incomplete/stale tree rather than the current PR head.

— sent from loyal-ibex-851

[briansrls]

Review metadata

• Provider / model: openai-pro / gpt-5-5-pro
• Commit: 423adccb · Trigger: manual
• Comparison: main @ 7addae94 ... docs/bridge-ledger-zero-audit @ cffb76ff
• Conversation: View conversation

---

1. Story of the diff

This PR adds a single docs brief, docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md, that audits the existing R3 bridge-retirement ledger-zero gate without changing the ledger, substrate, or predicate surface: it explicitly says “No substrate edits, no closure-ledger authoring, and no new TestPredicate variants” at docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:5-6. The brief identifies the authorities for the live row statuses and the fold predicate at docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:8-10, then walks the five bridge rows and concludes that the unified gate is still red because rows #1, #4, and #5 remain Open, while row #3 may have status drift because the ledger says Retired but live canonical-lens ratchets still pin nonzero bridge surface at docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:22-24 and docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:32.

The load-bearing mechanism is documentary rather than executable: the brief records row-by-row evidence, verifies the existing BridgeLedgerZero TestClaim shape, states the binary pass/fail behavior of the gate, and routes the only unresolved drift candidate to the Substrate Manager / Director instead of editing the row in this PR. That routing is explicit at docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:86-92, where the brief says this PR does not change the row because status ownership lives in the substrate ledger.

2. Invariant categories

1. LAYER MODEL (substrate vs implementation).

Compliant — the diff is docs-only and preserves layer authority: docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:5-6 says there are no substrate edits or new TestPredicate variants, while docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:8-10 leaves row status with src/v3/std/bridge_ledger.dag and predicate ownership with src/v3/std/verification.dag.

1. INVARIANTS.md + modeling-discipline.md.

Compliant — single-authority and fail-closed discipline are handled directly: the brief names the canonical row/predicate authorities at docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:8-10, describes BridgeLedgerZero as failing unless the reference is canonical and the carrier is List<BridgeLedgerRow> at docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:17-20, and refuses to treat row #3 as retired without either row correction or Director ratification at docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:86-92.

1. CODING.md.

N/A — this PR adds no Rust implementation code, helpers, APIs, methods, or error/result shapes; the only touched file is a docs brief.

1. TESTING.md.

Compliant — no new test is required for this docs-only audit, and the brief points to the existing production TestClaim and integration expectation rather than inventing a parallel check: docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:58-69 identifies the structural ledger subject, the typed predicate payload, the current fail expectation, and the re-arm trigger for flipping from Fail to Pass.

1. LOCKED DESIGN DECISIONS.

N/A — the diff references existing design/structure authorities as evidence, but does not alter a locked design decision or introduce a divergence. The one possible divergence, row #3’s Retired status versus live residual bridge surface, is explicitly framed as an escalation question rather than silently reinterpreted at docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:32 and docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:86-92.

1. TRACKED vs UNTRACKED DEBT.

Compliant — the only newly documented debt/drift is bounded to row #3, names the residual surface, and gives a dissolution/decision route: docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:32 ties full retirement to PB-Runtime interpreter-as-data or a typed lens-registry carrier, and docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:86-92 says the row must either be corrected back to Open until zero residual is reached or ratified by a newer Director disposition.

3. Verdict

APPROVE

The PR is a clean docs-only audit that preserves substrate authority, makes the ledger-zero gate’s current red state explicit, and tracks the one drift candidate without pretending this PR owns the row-status change. I did not find a diff-citable invariant, coding, testing, locked-design, or debt issue.

[briansrls]

Review metadata

• Provider / model: codex / codex-default
• Commit: d7b1132a · Trigger: schedule
• Comparison: origin/main @ 89382fc9 ... review/pr-1395-d7b1132a @ d7b1132a
• Thinking: 44s wall

---

Verdict: APPROVE — docs-only diff, grounded in the live bridge ledger/test shape, and it preserves the substrate ledger as the status authority while recording the pending split as a proposal. No concrete invariant, coding, or testing discipline violations observed.

[briansrls]

Review metadata

• Provider / model: openai-pro / gpt-5-5-pro
• Commit: d7b1132a · Trigger: manual
• Comparison: main @ 89382fc9 ... docs/bridge-ledger-zero-audit @ d7b1132a
• Conversation: View conversation

---

1. Story of the diff

This PR adds a single docs brief, docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md, that performs a structural audit of the bridge-retirement ledger-zero gate without changing substrate rows, closure-ledger entries, or TestPredicate variants (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:3-6). The brief keeps authority split correctly: row status remains owned by src/v3/std/bridge_ledger.dag, while BridgeLedgerZero owns the fold predicate in verification (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:8-10). The load-bearing content is the five-row audit: rows #1, #4, and #5 remain open; row #2 is treated as retired with an executable ratchet; and the old canonical-lens row is decomposed into a ratified narrow retired slice plus a broader open residual (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:22-38). The brief then verifies the existing production TestClaim shape and records the binary ratchet behavior: only all-Retired rows produce Pass, while any open row keeps the unified gate red (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:61-87).

2. Invariant categories

1. LAYER MODEL (substrate vs implementation).

Compliant — the diff explicitly stays docs-only and avoids substrate edits or new predicate variants (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:3-6), while preserving substrate authority for row status instead of treating the brief as the authority (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:103-105).

1. INVARIANTS.md + modeling-discipline.md.

Compliant — single-authority and fail-closed behavior are handled: the brief names bridge_ledger.dag as row authority and BridgeLedgerZero as fold authority (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:8-10), and describes the predicate as passing only when every row status is Retired (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:17-20, docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:78-83). The canonical-lens drift is also resolved by class enumeration rather than collapsing broad residual debt into a narrow retired receipt (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:35-36, docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:95-101).

1. CODING.md.

N/A — no Rust implementation, API surface, helper placement, method shape, error type, or naming convention is changed; the diff is a new documentation brief only (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:3-6).

1. TESTING.md.

Compliant — no new executable behavior is introduced, so no new test is required. The brief audits the existing production TestClaim, notes that the suite derives live open-row names from the bootstrap ledger instead of a parallel hard-coded inventory, and gives the exact re-arm trigger for changing the expectation from Fail to Pass (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:61-74).

1. LOCKED DESIGN DECISIONS.

Compliant — the diff references ratified design/Director disposition but does not silently alter it: Option 2 is recorded as a pending substrate-row split with the two intended rows and authorities named (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:91-101). It also explicitly says this PR does not change the substrate ledger row (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:103-105).

1. TRACKED vs UNTRACKED DEBT.

Compliant — the staged canonical-lens split is documented, bounded, and given dissolution authority: the narrow retired row and broader open residual are named separately (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:95-100), and the broader residual has a named trigger, “PB-Runtime interpreter-as-data or a typed lens-registry carrier” (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:97-101). The other open rows are likewise kept open with ratchet/authority references rather than being papered over (docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:33, docs/briefs/r3-v-bridge-retirement-ledger-zero-audit.md:37-38).

3. Verdict

APPROVE

This is a documentation-only audit that preserves substrate authority, keeps the unified ledger-zero gate fail-closed, and tracks the pending canonical-lens split instead of declaring premature closure. I found no diff-anchored findings.