fix(payments): V6-RECOVER #387/#389/#390 — durable invalid + root-cause source-state reconstruction

[vrogojin]

Closes #387, closes #389, closes #390.

This PR grew from a single-issue fix for #387 into a 3-issue V6-RECOVER hardening bundle. The original #387 work made the permanent-invalid verdict survive restart; the #389 follow-up tightened ledger discipline; and #390 finally fixed the root cause — the malformed source-token reconstruction that was producing the spurious "Recipient address mismatch" verdicts in the first place. Bundling keeps the chain of fixes deployable as a unit (each builds on the previous).

Commits

SHA	Issue	Summary
a9e6242	#387	Durable V6-RECOVER 'invalid' status across reload; balance excludes ledger; soak gate.
bc28737	#389	PR #388 review follow-up — V6-RECOVER ledger discipline + decimal-aware soak gate.
e47da61	#390	Manual repro (manual-test-simple-send.sh) — deterministically reproduces the root-cause failure in ~30 s.
2f9a690	#390	Root-cause fix — recoverStrandedReceivedTokens rebuilds source-token state from lastTxJson.data.sourceState (was: kept top-level recipient-predicate state).
b8b526d	release	Version bump to 0.0.a1 for downstream testing.

---

#387 — Durable V6-RECOVER invalid status (original PR scope)

Summary

• v6RecoverPermanent ledger is now authoritative for balance + recovery (was: silently lost on TXF round-trip).
• aggregateTokens, addToken, loadFromStorageData, restoreV6RecoverPermanent, and the V6-RECOVER stamping site all consult / re-apply the ledger via a canonical-id-first lookup helper.
• 16 unit tests + 4 integration tests, both files fail without the fix.
• Soak script gains assert_no_unconfirmed_after_finalize gate + confirmed-only balance diff. Testnet soak: ALL GREEN, 779 s.

Why the bug existed

txfToToken → determineTokenStatus re-derives Token.status from the TXF transactions array only — 'invalid' is never encoded. The in-memory 'invalid' write that finalizeStrandedReceivedToken makes after a V6-RECOVER permanent-fail was silently downgraded back to 'pending' on the next loadFromStorageData. aggregateTokens then included the unspendable token in unconfirmed UCT.

The v6RecoverPermanent ledger added in #378 was the right defense-in-depth, but it was only consulted by recoverStrandedReceivedTokens and the drain predicate — never by balance aggregation or the Nostr at-least-once re-ingest path. So the verdict survived restart on disk but the polluted balance kept resurfacing.

What the fix does

1. New helper applyV6RecoverPermanentInvalidStatus() patches in-memory tokens to 'invalid' based on the ledger.
2. Called at end of loadFromStorageData — survives initial load AND every sync() reload.
3. Called at end of restoreV6RecoverPermanent — handles cold-start ordering (ledger arrives after tokens).
4. aggregateTokens belt-and-braces filter — balance NEVER includes a ledgered token.
5. addToken ledger-aware ingest — Nostr at-least-once replay persists incoming token as 'invalid' (still returns true so cursor advances; rejecting would cause perpetual replay).
6. Canonical-id-first lookup — new isV6RecoverPermanentToken(token, mapKey?) extracts canonical genesis tokenId from sdkData with map-key fallback (handles UUID-keyed addToken entries).
7. finalizeStrandedReceivedToken keys the ledger by canonical genesis tokenId (was: map key — ambiguous post-replay) and awaits the save (was: fire-and-forget).

---

#389 — PR #388 review follow-up: ledger discipline + decimal-aware soak gate

Bundled hardening from the review of the #387 commit:

• Tighter ledger guards on the V6-RECOVER stamping site (no fire-and-forget on the persist).
• Decimal-aware unconfirmed-residue gate in manual-test-full-recovery.sh so any non-zero fractional UCT residue post-finalize fails the soak — previously the gate's integer-only regex passed 0.0000001 silently.

---

#390 — Root cause: source-token state-reconstruction bug

Symptom

sphere payments send <amount> UCT @<recipient> on two freshly-created testnet wallets produced a token whose recipient predicate appeared not to bind to the recipient's HD signers. Bob's payments receive --finalize hit VerificationError: Recipient address mismatch and #387 stamped the durable permanent-invalid verdict. End-to-end: alice -10 UCT confirmed, bob +0 UCT — funds effectively lost. The PR #388 soak (manual-test-full-recovery.sh) passed end-to-end because §D exercises the invoice-payment path; the direct-send path (sphere payments send) was broken on every fresh send.

Root cause (NOT what the issue body hypothesised)

The send path was correct — alice resolved @bob to bob's published directAddress and minted a transfer commitment targeting it. The bug was in bob's V6-RECOVER recovery path, specifically in recoverStrandedReceivedTokens (~line 9626 pre-fix):

const sourceTokenJsonObj = {
  ...parsed,
  transactions: txs.slice(0, -1),     // strip the last unfinalized tx
};

This rebuilt the source-at-state-N-1 by spreading the persisted parsed JSON and stripping the last transaction. But it kept the top-level state field unchanged. For instant-mode receives, the ingestion path (saveCommitmentOnlyToken and the UXF receive at line 2807) writes state.predicate = recipient_predicate so the on-disk shape advertises bob as owner once finalize completes. The source token used by Token.update → transaction.verify → verifyRecipient therefore exposed state.predicate.publicKey = bob while genesis.data.recipient = alice's directAddress — the SDK unconditionally returned 'Recipient address mismatch'.

#387/#388/#389 only stamped the durable verdict — they did NOT fix this construction. #390 is the actual root cause.

Fix

Replace state with lastTxJson.data.sourceState (= alice's mint state, the sender's predicate at state N-1):

const sourceTokenJsonObj = {
  ...parsed,
  state: (lastTxJson.data as { sourceState?: unknown }).sourceState,  // ← #390
  transactions: txs.slice(0, -1),
};

Mirrors the correct pattern already in tryLocalFinalizeUnconfirmed (~line 10249) and the UXF assembly path (~line 16284).

Regression coverage

• Unit: PaymentsModule.proof-polling-persistence.test.ts — "recoverStrandedReceivedTokens rewrites sourceTokenJson.state to the transfer sourceState (fresh alice→bob direct send: recipient predicate doesn't bind to recipient HD signers (root cause behind #387/#388/#389) #390)" — pins the invariant by inserting distinct markers in the top-level state vs the last-tx sourceState and asserting the registered proof-polling job's sourceTokenJson carries the SENDER's marker. Fails without the fix.
• E2E: manual-test-simple-send.sh (committed in e47da61, ~30 s against testnet). Pre-fix reliably ASSERT FAIL (bob-confirmed-rise-10-UCT); post-fix all 4 ASSERT OK.

---

Test plan

• npx vitest run tests/unit/modules/ → 1804 pass (0 fail; pre-existing flake on AccountingModule invoice-payment-attribution reproduced once across two runs, unrelated to this PR)
• npx vitest run tests/unit/modules/PaymentsModule.proof-polling-persistence.test.ts → 29 pass (includes new fresh alice→bob direct send: recipient predicate doesn't bind to recipient HD signers (root cause behind #387/#388/#389) #390 regression test)
• npx vitest run tests/unit/modules/PaymentsModule.v6-recover-invalid-status-387.test.ts → 23 pass
• npx vitest run tests/unit/modules/PaymentsModule.v6-recover-permanent-378.test.ts → 5 pass
• Manual repro (manual-test-simple-send.sh) → ALL GREEN — alice -10 UCT, bob +10 UCT, both CONFIRMED, no residue
• manual-test-full-recovery.sh soak — ALL GREEN at 513 s, 14 ASSERT OK (per PR #388 review follow-up: V6-RECOVER ledger consult gaps + soak gate regex misses decimals #389 verification)

Acceptance criteria (#390)

• A fresh alice → fresh bob sphere payments send 10 UCT @bob followed by sphere payments receive --finalize on bob's side leaves bob with +10 UCT CONFIRMED and 0 unconfirmed, NO V6-RECOVER permanent-verdict fires.
• Alice's CONFIRMED balance drops by exactly 10 UCT (smallest-unit integer comparison — no float coercion).
• Manual reproduction (manual-test-simple-send.sh) gates an end-to-end clean run.
• Regression unit test pinning the source-state reconstruction invariant.