fix(wallet): preserve root across interrupted WAB faucet registration

[BraydenLangley]

Program and scope

• Issue: interrupted WAB faucet registration can generate a new wallet root on retry and redeem the same faucet output twice, invalidating the later transaction chain.
• The fix persists an encrypted unpublished UMP token before funding, restores the original root after restart, reconciles an already redeemed payment using wallet transaction evidence, and refuses a pending-account retry without its original checkpoint.
• Latest update: 36 additional regression cases (34 unit/boundary cases and two SQLite restart integration cases); test-only commit 2ee36d368f43d84ea7a9396cf516131da826fdf2.
• Out of scope: faucet amount changes, account deletion, storage sync, live wallet recovery, release/publication and deployment.
• Exact head reviewed: 2ee36d368f43d84ea7a9396cf516131da826fdf2.

Impact

• Public package source or manifest changed; affected packages are listed below
• Public API, exports, types, runtime targets, or browser/mobile behavior changed
• Security-sensitive boundary changed
• Documentation or examples changed

Affected source: @bsv/wallet-toolbox; desktop integration also consumes the pending-registration checkpoint API. The latest commit changes only three test files, with no production, dependency, workflow, threshold, or release metadata changes. The previously prepared wallet/client/mobile 2.15.0 release metadata is not included in this PR head; that original release coordination remains pending and must be resolved before publication.

Verification

Fresh local baseline/candidate comparison (2026-10-12)

Isolated Docker WAB/MySQL services, demo authentication, synthetic 2,000,000-sat faucet output, real SQLite wallet signing/storage and reopen, interrupted UMP publication, and a simulated chain that rejects a second distinct redemption:

Result	Public main baseline (6493d5f)	Candidate (b175384, production bytes unchanged by latest tests)
Initial spendable balance	1,999,980 sats	1,999,980 sats
Same wallet root after restart	No	Yes
Redemption broadcasts	2	1
Spendable balance after retry	0 sats	1,999,980 sats
Registration status	Pending; retry failed	Active; retry succeeded
Desired-state assertion	Failed as expected	Passed

Both runs reached terminal process exits. Test-owned containers/network/volume were removed. No real phone, account, funds, or external chain broadcast was used. This reproduces the failure mechanism locally; it does not establish Bob's production history or live-chain consensus behavior.

Repeatable regression coverage on latest test bytes

• 154/154 tests pass across seven focused suites, including CWI checkpoint validation, WAB transport, continuity/phone-number compatibility, actual SQLite funding, and faucet evidence boundaries.
• New offline integration cases interrupt after broadcast/internalization and during UMP publication, close/reopen the SQLite wallet, refuse a retry without the checkpoint, then verify the original root/outpoint, one redemption, no second signing, one recovery-key save, and 1,999,980 spendable sats after successful retry.
• New negative cases cover malformed/oversized checkpoint bytes, token shape/root validation, authentication-state restrictions, malformed pagination, unspendable/mismatched outputs, missing/oversized BEEF, and changed evidence between reads. Invalid evidence must not construct, sign, or internalize another redemption.
• Local and exact-head hosted changed-line/branch coverage: 97.38% (223/229), up from prior hosted 88.21% (202/229); required target remains 90%. No suppression, exclusion, baseline or threshold change.
• pnpm build, pnpm health:check, pnpm lint, pnpm format:check, pnpm typecheck, pnpm audit:security, changed-test Prettier/oxlint and git diff --check: pass.
• Hosted four wallet shards: 3,217 passing tests, with four existing registered skipped cases; the new restart integration suite passed in shard4. All dependent, packed consumer, browser/mobile and HTTP-sync lanes passed.
• Full exact-head hosted qualification: CI run 38289740697, plus Conformance and CodeQL; terminal success, including the repository merge gate.
• Earlier source qualification included client 22/22 and mobile 46/46, core/client/mobile builds and packed consumers. These are historical evidence; new exact-head hosted checks remain required.
• I self-reviewed the complete source/test diff for correctness, security, compatibility, public API, artifacts, dependencies, docs, and operations
• All applicable checks are terminal and successful on the exact head; any scope-based skip is expected and validated by the merge gate

Security and dependencies

• No dependency or lockfile change in this PR
• No new override, advisory dismissal, quality suppression, or skipped test
• Exact-head CodeQL has no new alert
• Exact-head repository quality gate reports zero new Sonar findings and zero unreviewed hotspots
• Complete repository merge gate is successful

Release and operations

The testing update is complete. This PR remains draft because the original coordinated release-metadata batch is not pushed; that pending work is separate from this test-only update.

• No npm publication, live faucet use, or deployment was performed
• Required package version, release-note, migration, and changelog entries are pushed and reviewed (original coordinated release metadata remains pending)
• Exact-head CI is terminal and successful; no open review conversations (maintainer approval on preceding source head; latest update is test-only)

Desktop companion: metanet-client-desktop#69. Publication and deployment are separate actions.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[codecov]

Codecov Report

❌ Patch coverage is 94.87179% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...wallet/wallet-toolbox/src/CWIStyleWalletManager.ts	92.20%	2 Missing and 4 partials ⚠️

📢 Thoughts on this report? Let us know!