ENG-701: change refills the card's covering ladder, ladder-aware coin selection, and an offline refusal log

[islandbitcoin]

Problem

A charge with change gives the change back in the fewest powers of two (splitPow2). A card that pays 3 from an 8 is left holding 4 + 1, which pays only 1, 4 and 5 exactly offline. Every later small bill then needs change, and change needs the mint (CHANGE_NEEDS_MINT). Coin selection made this worse: for an exact bill it took the DP's first witness, so a card holding [1,1,2,2] paid 4 with 1+1+2 and was left [2], which cannot pay 1. Nobody could see how often cards were refused offline.

Change

• The canonical card shape (src/utils/denominations.ts). targetPieces is transcribed from flash-mobile's ENG-700 cashu-card-shape.ts: the ladder, then the spares [1,2,4,8], then the rest as the fewest powers of two, with the same slot-limited degradation. __tests__/fixtures/card-shape-vectors.json is flash-mobile's file from 1a7023ab4 (ENG-700, PR #773, still open), copied verbatim apart from an added source field. Every vector is asserted here.
• Change refills the ladder. splitChangeForLadder(changeSat, keep, maxPieces) fills the gaps between the card's target shape and the pieces it keeps. It returns at most popcount(change) + 3 pieces, never more than the free slots and openings, and never a split that scores worse than splitPow2 (decision 3). With no room it falls back silently to splitPow2.
• The split is chosen once, before anything burns, and travels on the plan. selectFittingPlan(plans, freeSlots, unspent) keeps its walk order and its fit test (pow2PieceCount), so the set of plans it accepts does not change (ENG-630/642/645). It returns the plan with changePieces. readAndPlan cuts owed change by changePieces.length. executeCharge passes the pieces to spendAll, which writes exactly those pieces with SPEND_ALL_CHANGE. A list that is not powers of two summing to changeSat is refused before any APDU. The stage animates the same list (changePieces(changeSat, planned)).
• Coin selection. Change is still the first sort key. Among plans with equal change, the one that leaves the card closest to its ladder wins (ladderScore), and fewer slots break any remaining tie. The exact subset is now the best-shaped one (bestExactSubset), capped at 4096 count vectors; past the cap the DP witness is kept.
• Kill switch (decision 5). Set FLASH_LADDER_CHANGE=false (@env-optional) to get today's splitPow2 change and today's coin selection exactly. It is on when the variable is absent.
• Refusal log (src/services/refusalLog.ts). Each offline CHANGE_NEEDS_MINT and ONLINE_ONLY refusal records {kind, amountSat, cardPieces, at} in AsyncStorage, one entry per tap. The log keeps the last 200 entries. Counts are stored separately and never go down. Writes run one at a time. A corrupt blob is reset. The call is never awaited, so it cannot delay or mask the refusal. The Card refusals row in Settings and the RefusalLog route are in production builds, not behind __DEV__ (decision 4).

How it was tested

• yarn lint --max-warnings 99999: 0 errors. The 1 warning is pre-existing, in useSatPrice.tsx.
• yarn typecheck: clean.
• yarn test --runInBand: 74 suites passed, 1 skipped. 1690 tests passed, 9 skipped (the cardsim suite).
• CARD_E2E_CARDSIM=… CARD_E2E_MINT=… yarn jest __tests__/integration/cardsimMint.test.ts --selectProjects ios --ci --runInBand, run locally against cardsim built at the CI pin (bced1c4) and Nutshell 0.20.3 on FakeWallet: 9/9 passed. The real applet and mint accept ladder change with repeated amounts. A 16 that pays 10 beside a 4 leaves the card [1,1,2,2,4] (it was [2,4,4]).
• APDU cost, logged by that test: 16 pays 10 beside a 4: SPEND_ALL_CHANGE 4 + LOAD 4 (power-of-two change: 2 + 2).
• Every existing assertion that encoded pow2 change is now derived from splitChangeForLadder instead of a hand-edited number (decision 6). That covers 19 tests in cashuCharge.test.ts, 4 in cardsimMint.test.ts, and the 5 Maestro flows. The Maestro EXPECTs are checked against the function by a new test in e2eLib.test.ts. For example, charge-with-change now asserts [2,1,1,1] after 8 pays 3.
• Mutation check (decision 8): the new tests were run against origin/main's src.
  • Fail on base: the denominations.test vectors and properties (100/101), the refusalLog and RefusalLog suites (module missing), the 3 kill-switch tests in featureFlags, 5 in cashuSpend, the 30 ENG-701 and re-derived tests in cashuCharge, 2 in money, 2 in Settings, 2 in Profile, and 7 in e2eLib.
  • Pass on base, by design. These tests guard behaviour that must not change:
    • change with the kill switch off;
    • spendAll called with no pieces named;
    • lower change still beating a better shape;
    • a charge that is not refused logs nothing;
    • a log that fails to write never masks the refusal;
    • changePieces with no split falling back to the fewest pieces;
    • the Settings row absent when no handler is wired;
    • the fixture source field.

Follow-ups

• ENG-700 drift. If flash-mobile #773 changes the vectors before it merges, copy the new file here and re-run.
• More pieces mean more APDUs for each tap with change. Change of 5 goes from 2 pieces to 4, and change of 6 goes from 2 to 4. That widens the burn-to-written window (ENG-642/645 lost-LOAD exposure). On tight cards, more owed change waits for a later tap. The flag turns this off.
• The refusal counts measure taps, not bills. A retried bill is logged again, and the stored amount lets retries be grouped later.
• yarn e2e:flashcard was not run locally. It needs the iOS simulator and the TEST merchant login. The E2E Flashcard workflow runs it on this PR, and it is part of the merge gate.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WxkKbrg2Xohf3mQj7BLrs6

[linear]

ENG-701