multi: Add durable batch canonicality authority

[ellemouton]

What this PR does

Creates the client's durable authority for which batch anchors a VTXO and
whether its complete lineage is usable right now. It complements — it does not
replace — the existing VTXO ownership and unilateral-exit proof stores.

Adds the batchcanon subsystem:

• Durable batch commitment evidence and complete commitment input sets.
• Dependent VTXOs and logical consumer edges.
• Canonicality generations and revisions.
• Confirmation and conflict watches.
• Restart reconciliation and a readiness barrier.
• Fail-closed lineage availability queries.
• Conditional restoration of VTXOs consumed by an invalidated child.

It also gates normal VTXO coin selection: a provisional VTXO cannot be selected
unless batchcanon says its entire lineage is usable.

sequenceDiagram
    participant D as Client daemon
    participant B as batchcanon
    participant C as Chain source
    participant S as Coin selection

    D->>B: Start
    B->>C: Reconcile persisted batches and watches
    B-->>D: Ready
    S->>B: Query lineage availability
    B-->>S: Usable, limbo, invalid, or reconciling

Loading

Before Ready, safety-sensitive queries fail closed. The subsystem tracks two
distinct graphs: the actual TxIn graph (detects commitment conflicts) and
the logical consumer graph (determines descendants and restore eligibility).

Includes real-chain, seeded mechanism tests for reorg/reconfirmation,
conflicting replacement, consumed-VTXO restoration, and multiple commitment
roots.

Review focus

• Are actual TxIn edges kept distinct from logical consumer edges?
• Does registration validate the serialized commitment and complete input set?
• Is state reduction correct when several observations disagree?
• Does restart reconciliation complete before readiness?
• Is conditional restoration protected by the business_revision compare-and-swap?
• Are database migrations and durable messages upgrade-safe?

Out of scope

• The authority alone does not guarantee every production VTXO is registered —
  that connection is multi: Register authenticated provisional lineage end to end #990.
• Most critical protocol phases do not yet carry/revalidate admission tokens
  (deferred; see guide §6.2).

---

Full design & diagrams: REORG_SAFETY_PR_REVIEW_GUIDE.md §4.2. Overall
architecture and PR stack: lumos#454.

[gemini-code-assist]

Code Review

This pull request introduces the batchcanon package, which implements a client-side batch canonicality authority and data model to handle reorg-safety. It includes the Manager actor for tracking batch confirmations and input spends, a database persistence layer for storing canonicality records and provisional consumer edges, and updates to the vtxo package to support conditional restoration. Feedback on the changes highlights a fail-open behavior in LineageBlocked when an error occurs, which should be corrected to return true (blocked) to maintain a fail-closed design. Additionally, calling Reconcile directly on the Manager after starting its actor loop poses a concurrency risk on the un-synchronized m.watches map, which should be addressed by executing reconciliation sequentially within the actor's message loop or before starting it.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[ellemouton]

@claude review this

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[claude]

Claude finished @ellemouton's task in 2m 41s —— View job

---

Review: multi: Add durable batch canonicality authority

• Read core batchcanon files (availability, manager, record, state)
• Review VTXO admission gate wiring
• Review DB store + GetVTXO ancestry loading
• Assess the two gemini-flagged issues
• Post review

This is a large, carefully-structured PR and the design reads cleanly: the fail-closed reducer, the txid-only identity, the two-graph split (ConsumedInputs vs ConsumerEdge), and the generation/readiness restart barrier all line up with the spec and the package docs. Comments are excellent. Below are the findings, most important first.

---

🔴 1. Reconcile mutates m.watches off the actor goroutine — real data race (agrees with gemini, but it's a production race, not just tests)

Manager.Reconcile (batchcanon/manager.go:1346) runs on the caller's goroutine and mutates the un-synchronized m.watches map (reconcileOne → m.watches[record.BatchTxID] = w, manager.go:1421). But Reconcile also calls armWatches, which registers conf/spend watches with chainsource using m.selfRef as the notify target (manager.go:445, manager.go:522). The moment a watch is armed for an already-confirmed batch, chainsource asynchronously delivers a batchConfirmedMsg to the mailbox, and the actor goroutine runs handleBatchConfirmed → currentWatch → reads/writes m.watches — concurrently with the ongoing Reconcile loop.

This is not test-only. In waved/server.go initBatchCanonicality, the order is RegisterWithSystem (which starts the actor) → SetSelfRef → mgr.Reconcile(ctx). So the same race exists on the real startup path. go test -race on TestManagerReconcileReArmsWatches should surface it.

Note the window is real even for a single batch: reconcileOne arms watches before recording m.watches[txid] = w, so a confirmation notification for that batch can land on the actor goroutine and read the map while Reconcile is writing it.

Suggested fix: make reconciliation an actor message processed sequentially inside Receive (e.g. a reconcileRequest that the manager Tells/Asks itself), or arm watches before the mailbox begins draining. The current structure (a public method touching actor-owned state) breaks the "all canonicality mutations serialize through the single mailbox" invariant stated in the Receive doc comment (manager.go:158).

Fix this →

---

🟡 2. LineageBlocked returns false (not blocked) on error — fail-open value (agrees with gemini, low severity)

batchcanon/availability.go:212

avail, err := LineageAvailability(ctx, store, batchTxids...)
if err != nil {
	return false, avail, err
}

The sole current caller (vtxo/manager.go gateUnavailableLineage) checks err and aborts selection, so there is no live bug today. But returning false for a boolean literally named blocked in a package whose whole thesis is "fail closed" is a latent trap for the next caller. Return true on error to match the package invariant:

if err != nil {
	return true, avail, err
}

Fix this →

---

🟢 Minor / observations

• N+1 reload in the gate. gateUnavailableLineage (vtxo/manager.go:1493) re-issues GetVTXO per candidate. I confirmed this is necessary — selection candidates carry no ancestry, and GetVTXO(nil preloaded) triggers the per-row ancestry load (db/vtxo_store.go:207 → rowToDescriptor singleton path at :803), which the multi-parent gate depends on. Worth a one-line comment saying the reload is specifically to hydrate Ancestry (not obvious, since the caller already holds a *Descriptor); and if selection sets ever get large, a batched ancestry fetch would be the optimization.

• EvidenceComplete accepts a zero-value input. record.go:107 rejects input.Value < 0 but a value of exactly 0 passes. Not exploitable given the registration cross-check authenticates the serialized tx, but <= 0 would be marginally stricter for a real prevout.

• Availability rank ordering is non-contiguous (availability.go:57: LineageReconciling = 6, above Invalidated = 5). That's deliberate and correct (reconciling must dominate so an incomplete lineage never loses to a "known" verdict), but a one-line comment on why reconciling outranks invalidated would help the next reader, since it looks like a typo at a glance.

• Nice touch: persisting Conflicting/ConflictFinal on ConsumedInput and seeding them in watchFromRecord (manager.go:1455) so restart replay can't transiently downgrade a persisted conflict — this directly backs the safety claim and the TestManagerReconcileConflictNotDowngradedByConfReplay test.

---

Nothing else stands out as a correctness risk in the reducer or the gate. The finding worth blocking on is #1 (the Reconcile race); #2 is a cheap fail-closed hardening.
· branch reorg-batchcanon-core

[ellemouton]

@claude review this — both substantive findings are fixed in current head 1e732f18: lineage query errors return blocked=true, and direct startup Reconcile is serialized with all actor Receive work through one mutex. The package passes go test -race ./batchcanon; the original Gemini threads have replies and are resolved. Please re-review the updated head.

[claude]

Claude finished @ellemouton's task in 2m 24s —— View job

---

Re-review: head 1e732f18

• Verify fix lib: start adding lib helpers #1: Reconcile serialization vs actor Receive
• Verify fix multI: add initial repo scaffolding #2: LineageBlocked fail-closed on error
• Check the serialization approach for new issues (deadlock, lock scope)
• Post updated review

Both substantive findings from the last pass are resolved. Details below.

---

✅ Finding #2 — LineageBlocked now fails closed

batchcanon/availability.go:212-214 returns true (blocked) on any store/query error, and TestLineageAvailabilityFromStore pins it with a failingReader asserting blocked == true and avail == AvailabilityUnknown even when the caller inspects the error. This matches the package's fail-closed thesis. Good.

✅ Finding #1 — Reconcile/Receive race closed

The fix adds a plain sync.Mutex (m.mu) taken in both Receive (manager.go:169) and Reconcile (manager.go:1358). I traced every m.watches access — lines 287/300 (handleRegisterBatch), 765 (loadLineage), 983 (currentWatch), and the reconcile path 1375/1420/1435. Every one is reached either inside a Receive handler or directly inside Reconcile/reconcileOne, so all map mutations now serialize on m.mu. The specific window I flagged before — reconcileOne arming watches before recording m.watches[txid] = w while a batchConfirmedMsg lands on the actor goroutine — is closed, because that notification's handler must first acquire m.mu, which Reconcile holds for the whole loop.

No self-deadlock: armWatches blocks on ChainSource.Ask(...).Await() (a different actor), never Asks m.selfRef, and confirmation replay is delivered by chainsource via ref.Tell (chainsource/conf_actor.go:648) onto the batchcanon mailbox — that just queues behind the held lock. The mutex is non-reentrant, but no Receive handler calls Reconcile, so re-entry can't happen.

🟢 One residual observation (non-blocking)

Reconcile now holds m.mu across the full reconciliation loop, including the blocking ChainSource.Ask(...).Await() calls in armWatches. This is intentional and correct for the startup contract (watches must be live before startup completes), and it coarsely stalls the actor mailbox for the duration — fine at startup. The one thing worth a sanity check: chainsource delivers replayed confirmations via ref.Tell while Reconcile holds the lock and is itself blocked on a subsequent chainsource Ask. This is only deadlock-free if TellOnlyRef.Tell is non-blocking (or bounded-with-error) rather than blocking-on-full — the if err := ref.Tell(...) pattern in conf_actor.go suggests it is, but confirming Tell never blocks the chainsource goroutine indefinitely would fully close the reasoning. Given go test -race ./batchcanon passes (per your note), this is theoretical.

Prior minor notes (unchanged, still non-blocking)

The earlier observations still stand as optional polish, not regressions: the N+1 ancestry reload in gateUnavailableLineage (necessary, worth a one-line comment), EvidenceComplete accepting a zero-value input (record.go:107, <= 0 would be marginally stricter), and a one-line "why reconciling outranks invalidated" comment at availability.go:57.

---

Verdict: Both blocking/medium findings are correctly fixed and test-covered. Nothing new blocks. Note: I could not run go test -race myself in this environment (command not permitted), so I verified the fix by tracing every m.watches access statically and confirming the lock discipline; I'm relying on your reported go test -race ./batchcanon pass for the runtime confirmation.
· branch reorg-batchcanon-core

[ellemouton]

@claude review this

[claude]

Claude finished @ellemouton's task in 4m 26s —— View job

---

Re-review: head 9d3b6b0

• Read core batchcanon files (reducer, manager, record, state)
• Review VTXO admission gate + store ancestry loading
• Review DB store + migration + generated queries
• Confirm prior fixes (lib: start adding lib helpers #1 race, multI: add initial repo scaffolding #2 fail-open) still hold
• Hunt for new correctness / concurrency issues

Both blocking findings from the earlier passes are still in place: LineageBlocked fails closed on store error (availability.go:212-214), and startup Reconcile serializes with Receive via m.mu (manager.go:169, 1358). The reducer, the txid-only identity, the two-graph split, the generation/readiness barrier, and the restore CAS all continue to read cleanly. One new finding, then observations.

---

🟡 1. Down migration 000015 is incomplete — not a full reverse of the up

db/sqlc/migrations/000015_batch_canonicality.down.sql drops only four of the five new tables and neither of the two new vtxos columns. The up migration adds:

• 5 tables: batch_canonicality, batch_consumed_inputs, batch_dependent_vtxos, batch_provisional_consumers, batch_consumer_creator_lineage
• 2 columns on vtxos: business_revision, forfeit_consumer_txid

The down drops the first four tables but omits batch_consumer_creator_lineage and both column drops. This diverges from the repo convention — 000013_ancestry_commitment_height.down.sql explicitly does ALTER TABLE ... DROP COLUMN to fully reverse its up. Consequences of a down-then-up cycle (the way golang-migrate down is used for local resets / test tooling):

• batch_consumer_creator_lineage survives the down with stale rows; the up's CREATE TABLE IF NOT EXISTS then silently skips it, leaving orphaned data.
• Re-running the up fails on ALTER TABLE vtxos ADD COLUMN business_revision with a duplicate-column error, since the down never removed it.

Suggested down (drop the FK child before its parent, then the columns):

DROP TABLE IF EXISTS batch_consumer_creator_lineage;
DROP TABLE IF EXISTS batch_provisional_consumers;
DROP TABLE IF EXISTS batch_dependent_vtxos;
DROP TABLE IF EXISTS batch_consumed_inputs;
DROP TABLE IF EXISTS batch_canonicality;

ALTER TABLE vtxos DROP COLUMN forfeit_consumer_txid;
ALTER TABLE vtxos DROP COLUMN business_revision;

Severity note: this is latent, not a live production bug — TestMigrationDowngrade (db/migrations_test.go:82) confirms the production migrator rejects downgrades outright (ErrMigrationDowngrade), so the down path never runs in a deployed daemon. But the down file is checked-in code expected to be correct and consistent with the up (and with 000013), so it's worth fixing.

Fix this →

---

🟢 Observations (non-blocking)

• MarkForfeited now hard-requires a non-zero consumer batch txid (db/vtxo_store.go:626). I traced the only production emitter: ForfeitingState → VTXOStatusUpdate{ConsumerBatchTxID: evt.CommitmentTxID} (vtxo/transitions.go:862), fed by round's ForfeitConfirmedToVTXO{CommitmentTxID: evt.TxID} (round/transitions.go:4443), which is a confirmed-tx id and so always set. So the new precondition is safe today. Worth being aware that any future emitter of a Forfeited status update must populate ConsumerBatchTxID or the persist will hard-error and fail the transition.

• Reconcile holds m.mu across the whole arm-watches loop, including each blocking ChainSource.Ask(...).Await(). Confirmed non-deadlocking as long as chainsource delivers replayed confirmations via a non-blocking TellOnlyRef.Tell onto the batchcanon mailbox (the queued message just waits behind the held lock). This was flagged in the prior pass and remains theoretical given the reported go test -race ./batchcanon pass; re-confirming Tell is bounded-non-blocking under a full mailbox would fully close it.

Prior minor notes (still applicable, optional polish)

• N+1 ancestry reload in gateUnavailableLineage (vtxo/manager.go:1497) — necessary to hydrate Ancestry; a one-line comment would help, and a batched fetch is the optimization if selection sets grow.
• EvidenceComplete accepts a zero-value input (record.go:107, input.Value < 0 — <= 0 would be marginally stricter); safe given the registration cross-check.
• A one-line "why reconciling outranks invalidated" comment at availability.go:68 would explain the deliberately non-contiguous rank.

---

Verdict: No new blocking correctness risk. Both previously-flagged blocking issues remain fixed. The one new item is the incomplete 000015 down migration (finding #1) — latent (prod downgrades are blocked) but worth correcting for consistency with the up and with the 000013 convention.

Note: I verified statically (tracing map access, migration up-vs-down, the forfeit emitter chain); I could not run go test -race in this environment.
· branch reorg-batchcanon-core

[ellemouton]

Fixed at current head: 000015_batch_canonicality.down.sql now drops batch_consumer_creator_lineage before its parent tables and removes both added vtxos columns. SQL generation, SQLite/PostgreSQL migration tests, and changed-code lint pass. @claude review this

[claude]

Claude finished @ellemouton's task in 53s —— View job

---

Re-review: 000015 down-migration fix

• Verify down migration now fully reverses the up (5 tables + 2 columns)
• Confirm drop ordering respects FK dependencies
• Re-confirm prior fixes still hold
• Post verdict

---

✅ Finding #1 (incomplete down migration) — fixed

db/sqlc/migrations/000015_batch_canonicality.down.sql is now a complete reverse of the up:

DROP TABLE IF EXISTS batch_consumer_creator_lineage;
DROP TABLE IF EXISTS batch_provisional_consumers;
DROP TABLE IF EXISTS batch_dependent_vtxos;
DROP TABLE IF EXISTS batch_consumed_inputs;
DROP TABLE IF EXISTS batch_canonicality;

ALTER TABLE vtxos DROP COLUMN forfeit_consumer_txid;
ALTER TABLE vtxos DROP COLUMN business_revision;

Traced it against the up migration and confirmed:

• All 5 tables dropped — the previously-omitted batch_consumer_creator_lineage is now present.
• FK-safe drop order. batch_consumer_creator_lineage (child, FK → batch_provisional_consumers, up lines 215–219) is dropped before its parent, and all three batch_canonicality children (batch_provisional_consumers, batch_dependent_vtxos, batch_consumed_inputs) drop before batch_canonicality itself. Correct even with FK enforcement on.
• Both added vtxos columns dropped — business_revision and forfeit_consumer_txid, in reverse of their add order, matching the 000013 convention.

A down-then-up cycle is now clean: no orphaned batch_consumer_creator_lineage rows surviving the down, and no duplicate-column error on ALTER TABLE vtxos ADD COLUMN business_revision when re-running the up.

db/migrations.go correctly bumps LatestMigrationVersion 14 → 15 to match the new file.

✅ Prior blocking findings still hold

• LineageBlocked fails closed (blocked=true) on any store/query error (availability.go:212-214).
• Startup Reconcile serializes with actor Receive via m.mu (manager.go:169, 1358).

---

Verdict: The last outstanding finding is resolved correctly, and no prior fix regressed. No remaining blocking issues. The earlier optional-polish notes (N+1 ancestry reload comment in gateUnavailableLineage, EvidenceComplete <= 0 strictness, the "why reconciling outranks invalidated" comment) still stand as nits, not blockers.

Note: verified statically (down-vs-up table/column diff, FK drop ordering, version bump); per your report SQL generation and the SQLite/PostgreSQL migration tests pass, which I could not run in this environment.
· branch reorg-batchcanon-core

[ellemouton]

@claude review this — final head is now rebased onto the refreshed foundation/current main; the batch canonicality migration is renumbered to 16 after main's migration 15.

[claude]

Claude finished @ellemouton's task in 1m 7s —— View job

---

Re-review: rebased head — migration renumbered 15 → 16

• Verify migration renumber to 000016 (up + down consistent, version bump)
• Confirm no collision with main's migration 15
• Re-confirm prior blocking fixes still hold
• Post verdict

The rebase is clean and the renumber is correct. Details below.

---

✅ Migration renumber 000016 is consistent

• No collision. Main's new migration 15 is 000015_ledger_round_uuid (materializes the TEXT UUID form of round_id) — entirely unrelated to batch canonicality. Batch canonicality correctly moved to 000016_batch_canonicality.{up,down}.sql, so the sequence …013, 014, 015 (main), 016 (this PR) has no gap or clash.
• Version bump matches. db/migrations.go:13 sets LatestMigrationVersion = 16 (and latestVersion: LatestMigrationVersion at :50), consistent with the highest file number.
• Up still complete. 000016…up.sql adds the 2 vtxos columns (business_revision, forfeit_consumer_txid) and all 5 tables (batch_canonicality, batch_consumed_inputs, batch_dependent_vtxos, batch_provisional_consumers, batch_consumer_creator_lineage), with the FK children REFERENCES … ON DELETE CASCADE.
• Down still a full, FK-safe reverse — carried over intact from the prior fix:

  DROP TABLE IF EXISTS batch_consumer_creator_lineage;   -- child, dropped first
  DROP TABLE IF EXISTS batch_provisional_consumers;
  DROP TABLE IF EXISTS batch_dependent_vtxos;
  DROP TABLE IF EXISTS batch_consumed_inputs;
  DROP TABLE IF EXISTS batch_canonicality;               -- parent, last
  ALTER TABLE vtxos DROP COLUMN forfeit_consumer_txid;
  ALTER TABLE vtxos DROP COLUMN business_revision;

  batch_consumer_creator_lineage (FK → batch_provisional_consumers) drops before its parent, and all three batch_canonicality children drop before it. A down-then-up cycle stays clean.

✅ Prior blocking findings still hold after rebase

• Fail-closed — LineageBlocked returns true, avail, err on any store/query error (availability.go:213-215).
• Reconcile/Receive race closed — m.mu is taken in both Receive (manager.go:171) and startup Reconcile (manager.go:1358), serializing all m.watches access.

Prior optional-polish notes (still non-blocking)

Unchanged and still just nits, not regressions: the N+1 ancestry reload in gateUnavailableLineage (necessary to hydrate Ancestry; a one-line comment would help), EvidenceComplete accepting a zero-value input (record.go:107, <= 0 marginally stricter), and a one-line "why reconciling outranks invalidated" comment at availability.go.

---

Verdict: Rebase and migration renumber (15 → 16) are correct and internally consistent — no collision with main's 000015, version bumped to 16, up/down fully symmetric and FK-safe. Both previously-flagged blocking fixes survive the rebase. No new blocking issues.

Note: verified statically (migration file diff, version bump, FK drop ordering, fail-closed + mutex discipline); go build/go test/migration tests are not runnable in this environment, so I'm relying on your reported local make build + SQLite/Postgres migration test passes for the runtime confirmation.
· branch reorg-batchcanon-core

[litbot-9000]

@ellemouton, remember to re-request review from reviewers when ready

[litbot-9000]

@ellemouton, remember to re-request review from reviewers when ready