feat(core)!: two-phase broadcast status + reconcile grace window

[whoabuddy]

Closes #25.

Summary

• Introduces LedgerEntry.status (pending_broadcast | broadcast_sent | broadcast_failed) with explicit lifecycle helpers — beginPendingBroadcast / resolveBroadcast — backed by a transition matrix enforced at the schema layer (LedgerTransitionError on invalid moves).
• Adds justBroadcastGraceSeconds (default 30) to reconcile(); ledger entries absent from the mempool but broadcast within the grace window are surfaced as inFlightPendingIndex instead of dropped. reconcile() also auto-promotes pending_broadcast → broadcast_sent on mempool confirmation.
• decideBroadcast gains an await_pending_broadcast variant that short-circuits any other decision while a ledger entry is unresolved — hard invariant against silent double-broadcast.

Design notes

• OccupantClassification stays closed. Grace-window ambiguity needs ledger + clock context that classifyOccupant has neither of by design; forcing it in would make every caller grace-aware for a concern only reconcile can answer. inFlightPendingIndex is additive on ReconcileResult where that context lives.
• Timestamps stay ISO. broadcastAt remains IsoDateTimeSchema; grace math parses to epoch ms internally. No parallel unix-ms field.
• Lifecycle helpers over README conventions. A two-phase write "pattern" documented only in prose drifts. beginPendingBroadcast / resolveBroadcast enforce the transition matrix at the type boundary and throw on misuse.

Breaking change

SponsorLedgerEntry.status is required. Entries persisted under 0.8.0 lack it and will fail schema parse. Consumers must backfill status: "broadcast_sent" on migration. Targets 0.9.0.

Test plan

• 217 tests pass (npm test)
• npm run typecheck clean
• npm run build clean
• New coverage: every state transition (valid + invalid), await_pending_broadcast precedence over RBF, grace window inside/outside (10s/60s) and custom override (45s × {30, 60}), reconcile pending-promotion, crash-recovery scenario
• Relay integration smoke (out of scope here — tracked in Consume tx-schemas sponsor wallet helpers; fix nonce conflict handling x402-sponsor-relay#338)

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR hardens the sponsor wallet state machine by introducing a two-phase broadcast lifecycle for ledger entries and adding a reconcile grace window to reduce false “dropped” classifications during mempool/indexer propagation lag.

Changes:

• Add required SponsorLedgerEntry.status (pending_broadcast | broadcast_sent | broadcast_failed) and new lifecycle helpers beginPendingBroadcast / resolveBroadcast with LedgerTransitionError.
• Update decideBroadcast to return await_pending_broadcast when a nonce is unresolved, preventing accidental double-broadcast.
• Extend reconcile() with justBroadcastGraceSeconds and a new inFlightPendingIndex result bucket; also auto-promote pending_broadcast → broadcast_sent on mempool confirmation.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
src/core/sponsor-ledger.ts	Adds required status field + status enum schema for ledger entries.
src/core/sponsor-wallet-machine.ts	Implements two-phase lifecycle helpers, await_pending_broadcast decision, and reconcile grace-window + in-flight classification.
tests/sponsor-wallet-machine.test.ts	Updates existing tests for required status and adds coverage for two-phase lifecycle + grace-window behaviors.
README.md	Documents the two-phase broadcast write pattern and reconcile grace-window semantics.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[arc0btc]

Two-phase broadcast lifecycle + reconcile grace window — closes the crash-window gap that's been an open reliability concern for the relay.

What works well:

• The transition matrix is airtight: PENDING_PREDECESSORS set clearly models which states are valid predecessors, and LedgerTransitionError gives callers a typed error to catch rather than a silent wrong-state write.
• decideBroadcast guarding at the top — returning await_pending_broadcast before any other logic — is the right precedence call. It keeps the invariant clean regardless of occupant classification.
• The two-pass structure in reconcile() is well-commented and the separation of concerns is sound: Pass 1 handles mempool hits (adopt + promote), Pass 2 handles absences (grace vs. dropped). The second commit's fix making txId-drift unconditionally dropped is exactly right — drift is not lag.
• Test coverage is thorough. The crash-recovery scenario (entry broadcast 120s ago, never resolved, not in mempool → dropped) and the grace-window boundary tests (10s inside / 60s outside / custom override) give me confidence the edge cases are understood.

[question] Grace window applies to broadcast_sent entries too (src/core/sponsor-wallet-machine.ts, Pass 2)

Pass 2 computes ageMs from entry.broadcastAt for all entries when observed is null — regardless of whether the entry is pending_broadcast or broadcast_sent. A broadcast_sent entry that temporarily disappears from the Hiro mempool (say, due to rapid confirmation or transient indexer lag) within 30s of its broadcastAt timestamp would land in inFlightPendingIndex rather than dropped. Is this intentional? Operationally, a broadcast_sent entry going absent is a different signal than a pending_broadcast one — the former means the node confirmed receipt, the latter means we haven't heard back yet. If the intent is grace-for-pending-only, the condition could be:

    const ageMs = nowMs - Date.parse(entry.broadcastAt);
    if (entry.status === "pending_broadcast" && ageMs >= 0 && ageMs < graceMs) {
      inFlightPendingIndex.push(entry.nonce);
    } else {

If the current behavior is intentional (grace for any recent absence), a brief comment explaining why would help future readers.

[question] justBroadcastGraceSeconds default vs. stated propagation timing (src/core/sponsor-wallet-machine.ts:507)

The comment says the grace window "Covers node→indexer propagation lag (~6-10 Nakamoto blocks + Hiro indexing)". If those are streaming Stacks blocks at ~1-2s each, 30s is comfortably generous. If they're longer, 30s could be tight. The x402 relay can override this via ReconcileOptions, but for consumers who don't override, it's worth confirming the 30s default is calibrated to real Hiro indexing latency. We've seen Hiro 400 delays operationally, though those are different failure modes.

[nit] Variable shadowing in README example (README.md)

let ledger = beginPendingBroadcast(ledger, {

This shadows the outer ledger binding. JS evaluates the RHS correctly so the code works, but the pattern is confusing to read — looks like a circular assignment at a glance. let pendingLedger = beginPendingBroadcast(ledger, ...) or a reassignment (ledger = beginPendingBroadcast(ledger, ...)) would read more naturally.

Code quality notes:

The rbfAttempts defaulting chain in beginPendingBroadcast (input.rbfAttempts ?? existing?.rbfAttempts ?? 0) is correct but callers doing RBF need to remember to pass the incremented count explicitly — there's no auto-increment. The README covers the first-broadcast case but not the RBF flow. A brief README addition showing the RBF call (rbfAttempts: existingEntry.rbfAttempts + 1) would prevent a subtle foot-gun for consumers integrating this pattern.

Operational context:

We run this code path nightly for Zest sBTC supply operations. The nonce-serialization fix we shipped last week (shared nonce coordinator) prevents concurrent double-submissions at the application layer, but there was still a theoretical crash window between write and node confirmation. This closes it cleanly at the state machine layer. The await_pending_broadcast guard is the piece we'd want most — if the process dies mid-broadcast, crash recovery via reconcile picks it up without a second broadcast firing.

The two questions above are worth a quick check before merge, but neither is blocking. The core logic is sound and the test coverage gives me confidence in the critical paths.

[whoabuddy]

Thanks for the thorough read, @arc0btc — all four points addressed in a909bbc.

[question 1] Grace window leaking to broadcast_sent — fixed.
Sharp catch. You're right that broadcast_sent and pending_broadcast carry different operational meaning when they vanish from the mempool. Pass 2 now branches explicitly:

• pending_broadcast + absent → grace window applies (could still be propagation lag)
• broadcast_sent + absent → dropped immediately (node confirmed receipt; absence means mined or evicted, caller disambiguates via tx status lookup)
• any tx_id mismatch → dropped immediately (drift, not lag)

Added a test does NOT grace-window broadcast_sent entries that pins this: 5s-old broadcast_sent entry, mempool null → dropped, not inFlightPendingIndex. Comment on ReconcileOptions.justBroadcastGraceSeconds now spells out the scope.

[question 2] 30s default — keeping it, but documented honestly.
Stayed at 30s to match the issue spec, but expanded the comment to acknowledge it's calibrated to the tight end of the Nakamoto-block + Hiro-indexer envelope (3-5s × 6-10 blocks ≈ 30-50s). Operators seeing routine Hiro slowness should override upward; the grace only delays a dropped classification, never changes a true outcome. If we hit operational pain on this default, we can revisit in a 0.10.x.

[nit 3] README shadowing — fixed.
Dropped the let ledger = ... rebind in favor of straight reassignment. Reads as the iterative state update it actually is.

[code quality] RBF flow example — added.
Good foot-gun call. README now has a second snippet showing the explicit rbfAttempts: existing.rbfAttempts + 1 pass on retry, with a note that beginPendingBroadcast doesn't auto-increment because the same helper covers first broadcasts and retries.

Operationally: the Zest sBTC nightly path is exactly the consumer this is meant to harden. The shared nonce coordinator catches concurrent submissions; this catches the in-process crash window. Together that's the gap closed end-to-end. 219 tests green, build clean — ready for merge when you are.