Skip to content

release: state-machine hardening for Release 170 (TASK-25247) - #4198

Open
Hugo0 wants to merge 12 commits into
devfrom
feat/state-machine-hardening
Open

Hugo0 wants to merge 12 commits into
devfrom
feat/state-machine-hardening

Conversation

@Hugo0

@Hugo0 Hugo0 commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

One PR into dev for the state-machine hardening in Release 170 (API twin: peanut-api-ts umbrella PR). Each sub-PR was reviewed and merged into feat/state-machine-hardening on its own. Specs and method: mono engineering/api/state-machines/; the rule: mono engineering/patterns/state-machines.md.

Sub-PRs

PR Fix TLA+ spec Status
#4197 Direct send, request pay, pot contribution: no second transfer while a send may still land (pending marker in localStorage, recovery from server and chain truth, Pay disabled meanwhile) ChargeSendFlow merged
#4199 Feature-report fixture and demo data follow the API's new answers (additive enroll step); no screen change — merged
#4196 Residence reorder: the drawer sends the swap itself; tests use the real API shape ResidenceChange merged

No-regression evidence

  • The trace tests fail on dev and pass here: direct send 7 of 8 fail → 11/11 pass; pot 3/3 → 3/3; request pay 4/4 → 4/4; residence reorder 3 of 5 → 5/5.
  • Each sub-PR passed the full test workflow on its own head; this PR's CI runs it on the combined code.

Release notes

  • Migrations: none. Native surface: no (JS only, OTA-safe). New copy: payment.errors.paymentNotSent in 4 locales.
  • Moves money: needs a non-author human approval before the dev merge.
  • Follow-ups (TASK-25240): crypto withdraw and Bridge withdraw get the same guard; same-tick double tap latch.

Hugo0 and others added 8 commits November 21, 2026 11:24
…omits declared, so the drawer sends the swap itself; tests now use the shape the compact API sends
…ile the first may land

A send failure after broadcast, a record failure after a mined send, or a
reload mid-send showed the generic error with Send enabled again, so a second
tap paid twice (ChargeSendFlow.tla Buggy counterexamples). The spend engine now
reports each broadcast and tags ambiguous failures; usePendingChargeSend keeps a
pending marker, routes those failures to recovery and keeps Pay off until the
charge or the chain says the send is final.
… request pay, and pin the spend engine's broadcast tag

Old record-timeout cases that expected a retry after a mined send (charge read
FAILED, no-response record timeout) now expect recovery: they encoded the bug.
… back

Dropping the marker after a day could release Send for an op that landed while
nobody looked (TLC counterexample). Past a day, recovery instead counts an op it
still cannot find as dropped, and an op that executed is still found.
… the chain

After a reload the wallet address loads after mount; reading user-op outcomes
without the sender reported every op unknown for the whole window.
…guard

fix(payments): no second transfer while a charge-backed send may still land (TASK-25240)
fix(profile): TASK-25239 residence reorder keeps the verified country when /users/me omits declared
@notion-workspace

Copy link
Copy Markdown

@vercel

vercel Bot commented Nov 21, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
peanut-wallet Ready Ready Preview Nov 21, 2026 1:41pm UTC

Request Review

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

Code-analysis diff

Painscore total: 11168.74 → 11190.35 (+21.61)
Findings: +19 net (+106 new, -87 resolved)

🆕 New findings (106)

  • critical complexity — src/dev/fixtures/featureReport.ts — CC 164, MI 60.33, SLOC 494
  • critical complexity — src/features/payments/flows/semantic-request/useSemanticRequestFlow.ts — CC 129, MI 49.12, SLOC 577
  • critical complexity — src/hooks/wallet/useSpendBundle.ts — CC 91, MI 51.76, SLOC 499
  • critical complexity — src/features/payments/shared/hooks/usePendingChargeSend.ts — CC 73, MI 58.87, SLOC 230
  • critical complexity — src/features/payments/flows/contribute-pot/useContributePotFlow.ts — CC 67, MI 51.68, SLOC 367
  • critical complexity — src/hooks/wallet/useWallet.ts — CC 64, MI 56.43, SLOC 221
  • critical complexity — src/components/Profile/views/ResidenceChangeDrawer.tsx — CC 59, MI 56.71, SLOC 141
  • high hotspot — src/hooks/useZeroDev.ts — 78 commits, +840/-561 lines since 6 months ago
  • high method-complexity — src/hooks/wallet/useSpendBundle.ts:162 — CC 38 SLOC 207
  • high complexity — src/features/payments/flows/direct-send/useDirectSendFlow.ts — CC 33, MI 47.15, SLOC 252
  • high complexity — src/hooks/wallet/mixedEphemeralSpend.ts — CC 12, MI 45.51, SLOC 95
  • high complexity — src/constants/demo-data.ts — CC 6, MI 41.55, SLOC 275
  • medium high-mdd — src/features/payments/flows/semantic-request/useSemanticRequestFlow.ts:41 — useSemanticRequestFlow: MDD 224.4 (uses across many lines from declarations)
  • medium high-mdd — src/hooks/wallet/useSpendBundle.ts:137 — useSpendBundle: MDD 189.2 (uses across many lines from declarations)
  • medium high-mdd — src/hooks/wallet/useSpendBundle.ts:162 — : MDD 174.7 (uses across many lines from declarations)
  • medium high-mdd — src/features/payments/flows/contribute-pot/useContributePotFlow.ts:35 — useContributePotFlow: MDD 100.2 (uses across many lines from declarations)
  • medium high-mdd — src/components/Profile/views/ResidenceChangeDrawer.tsx:61 — ResidenceChangeDrawer: MDD 92.7 (uses across many lines from declarations)
  • medium high-mdd — src/features/payments/flows/direct-send/useDirectSendFlow.ts:36 — useDirectSendFlow: MDD 86.4 (uses across many lines from declarations)
  • medium high-dlt — src/hooks/useZeroDev.ts:95 — useZeroDev: DLT 84 (calls 84 distinct functions — high context load)
  • medium high-mdd — src/hooks/useZeroDev.ts:95 — useZeroDev: MDD 76.9 (uses across many lines from declarations)

…and 86 more.

✅ Resolved (87)

  • src/dev/fixtures/featureReport.ts — CC 158, MI 60.44, SLOC 475
  • src/features/payments/flows/semantic-request/useSemanticRequestFlow.ts — CC 123, MI 49.57, SLOC 546
  • src/hooks/wallet/useSpendBundle.ts — CC 84, MI 51.9, SLOC 478
  • src/features/payments/flows/contribute-pot/useContributePotFlow.ts — CC 64, MI 52.02, SLOC 346
  • src/hooks/wallet/useWallet.ts — CC 64, MI 56.55, SLOC 219
  • src/components/Profile/views/ResidenceChangeDrawer.tsx — CC 59, MI 56.81, SLOC 140
  • src/hooks/useZeroDev.ts — 77 commits, +833/-558 lines since 6 months ago
  • src/hooks/wallet/useSpendBundle.ts:157 — CC 32 SLOC 198
  • src/features/payments/flows/direct-send/useDirectSendFlow.ts — CC 30, MI 47.34, SLOC 226
  • src/hooks/wallet/mixedEphemeralSpend.ts — CC 12, MI 45.67, SLOC 94
  • src/constants/demo-data.ts — CC 6, MI 41.73, SLOC 271
  • src/features/payments/flows/semantic-request/useSemanticRequestFlow.ts:43 — useSemanticRequestFlow: MDD 197.4 (uses across many lines from declarations)
  • src/hooks/wallet/useSpendBundle.ts:132 — useSpendBundle: MDD 181.5 (uses across many lines from declarations)
  • src/hooks/wallet/useSpendBundle.ts:157 — : MDD 166.2 (uses across many lines from declarations)
  • src/components/Profile/views/ResidenceChangeDrawer.tsx:61 — ResidenceChangeDrawer: MDD 94.5 (uses across many lines from declarations)
  • src/features/payments/flows/contribute-pot/useContributePotFlow.ts:37 — useContributePotFlow: MDD 85.8 (uses across many lines from declarations)
  • src/hooks/useZeroDev.ts:94 — useZeroDev: DLT 82 (calls 82 distinct functions — high context load)
  • src/hooks/useZeroDev.ts:94 — useZeroDev: MDD 77.7 (uses across many lines from declarations)
  • src/features/payments/flows/direct-send/useDirectSendFlow.ts:37 — useDirectSendFlow: MDD 75.8 (uses across many lines from declarations)
  • src/features/payments/flows/semantic-request/useSemanticRequestFlow.ts:43 — useSemanticRequestFlow: DLT 68 (calls 68 distinct functions — high context load)

…and 67 more.

📈 Painscore deltas (top movers)

File Before After Δ
src/features/payments/shared/hooks/usePendingChargeSend.ts 0.0 7.0 +7.0
src/hooks/wallet/spendBroadcast.ts 0.0 4.3 +4.3
src/utils/userop-outcome.ts 0.0 4.2 +4.2
src/features/payments/shared/utils/pending-charge-send.ts 0.0 4.0 +4.0

@github-actions

github-actions Bot commented Nov 21, 2026 •

Copy link
Copy Markdown
Contributor

🧪 UI test report — ✅ all green

Suites

  • ✅ unit: 22806 ran, 0 failed, 0 skipped, 7.6m

📊 Coverage (unit)

metric %
statements 88.8%
branches 82.2%
functions 83.4%
lines 90.3%
⏱ 10 slowest test cases
time test
🐢 21.6s scripts/__tests__/screens-adapter.test.js › runs the existing synthetic screen adapter Node acceptance suite
🐢 9.5s src/features/deposit-accounts/__tests__/AddMoneyArgentinaCountry.acceptance.test.tsx › keeps unavailable Argentina searchable and opens its residence explanation with pointer
🐢 9.0s src/app/(mobile-ui)/qr-pay/__tests__/qr-pay-states.test.tsx › Network failure keeps loading while retries remain, then shows the generic error
🐢 8.9s src/features/deposit-accounts/__tests__/AddMoneyArgentinaCountry.acceptance.test.tsx › keeps unavailable Argentina searchable and opens its residence explanation with Space
🐢 8.6s src/features/deposit-accounts/__tests__/AddMoneyArgentinaCountry.acceptance.test.tsx › keeps unavailable Argentina searchable and opens its residence explanation with Enter
4.4s scripts/__tests__/signup-attribution-paths.test.ts › includes newly published articles and locale fallbacks without editing the manifest
4.1s scripts/__tests__/indexable-urls.test.ts › excludes missing locale files, drafts, redirects, and retired pages from crawl and submission lists
4.1s src/features/payments/flows/qr-pay/__tests__/usePixPayment.test.tsx › a payment still waiting for its signature, with no device mark, reads as processing until the API ends it
4.0s src/app/(mobile-ui)/qr-pay/__tests__/qr-pay-states.test.tsx › MANTECA_MERCHANT_RECENT_REFUND fails fast with copy that names the real cause
4.0s src/app/(mobile-ui)/qr-pay/__tests__/qr-pay-states.test.tsx › MANTECA_MERCHANT_VOLUME_NEAR_CAP fails fast with copy that names the real cause
📍 Inline annotations are in the **Unit test report** check above. Coverage artifact: `coverage-unit`. Generated by `.github/workflows/tests.yml`.

@Hugo0 Hugo0 changed the title release: state-machine hardening for Release 170 (TASK-25240) release: state-machine hardening for Release 170 (TASK-25247) Nov 21, 2026
@notion-workspace

Copy link
Copy Markdown

Hugo0 and others added 4 commits November 21, 2026 13:03
The API's feature report now answers local from the resident's own account
with its step, names the step on every ready entry (activate or enroll), and
lets the identity refusal answer for Bridge rails closed by an ended approval.
Fixture-driven tests read the same answers the API sends.
… of merging into it

Merged entry by entry, the demo report's enroll steps leaked into a fixture
that set the same accounts on.
fixtures: TASK-25239 keep the feature report mirror in step with api#2208
@Hugo0
Hugo0 marked this pull request as ready for review November 21, 2026 13:35

@chip-peanut-bot chip-peanut-bot Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Chip review — INCOMPLETE · changes requested

⚠️ This review is incomplete. The third opinion (product truth, tests, contract) did not run — claude-api_error (after a retry; first: claude-api_error). The copy check did not run — claude-api_error (after a retry; first: claude-api_error). Its questions are unanswered, not answered clean. Comment /chip review to run it again.

Four paths can re-enable a charge-backed payment without proving that the first transfer cannot duplicate.

Findings

  • BLOCKING · src/features/payments/shared/hooks/usePendingChargeSend.ts:148 · Keep the send guard after money moved but the charge is unbooked
    If a transfer mined but recording keeps failing and the charge remains PENDING, recovery reaches its 60-second deadline and returns sent; this line deletes the marker. Revisiting the same recipient or request then enables Pay and can send a second transfer while the first has already moved money. Retain the marker for sent until authoritative completion or another reconciliation that makes a repeat safe; keep retrying idempotent recording on resume.

  • BLOCKING · src/features/payments/shared/hooks/usePendingChargeSend.ts:190 · Do not declare an old send unsent when its outcome is unreadable
    After 24 hours, if the charge read fails and the bundler or nonce read fails, readUserOpOutcome returns unknown, but this age check alone returns not-sent, deletes the marker, and tells the payer no money left. An executed transfer hidden by a temporary read outage can then be paid again; the same branch also overrides backendBroadcast and untrackedBroadcast. Require a successful, conclusive reconciliation before offering Pay, rather than treating elapsed time or a failed read as proof.

  • BLOCKING · src/features/payments/shared/utils/pending-charge-send.ts:48 · Make a failed storage write visible to the send guard
    When localStorage is full, setItem throws and writePendingChargeSend saves the marker in memory, but getItem still succeeds with null, so this read never consults memory. isPending stays false and onBroadcast cannot update the marker; after an ambiguous send or reload, Pay can be offered again. Read the in-memory fallback even when getItem returns null, and fail closed or reconcile authoritatively when a durable marker cannot be saved.

  • BLOCKING · src/hooks/wallet/spendBroadcast.ts:90 · Treat a submit timeout response as an unknown send outcome
    A gateway can return HTTP 408 after /rain/cards/withdraw/submit was accepted. rainRequest wraps that response in ApiError, and this blanket 4xx rule calls it a definitive refusal. useSpendBundle then leaves the failure untagged and the payment flow clears its marker, allowing another transfer while the first may land. Keep 408 ambiguous; only endpoint-specific, proven no-effect responses should release the guard.

Checked clean

  • Exact detached head, base SHA, PR description, and changed runtime paths verified; no issue or review comments read.
  • Reviewed direct send, pot contribution, request pay, wallet broadcasts, recovery, and their trace tests; tests do not cover the four failure scenarios above.
  • Residence reorder, feature-report fixture, design rules, and four locale strings checked without another finding.
  • At review time analyze, human-authors, and backdoor-scan passed; unit, i18n-overflow, press-contract, and seo-contract were still running.
  • Mono engineering/patterns/state-machines.md was unavailable at its cited path; state-machine behavior was checked against code and tests.

Security review by moonshotai/kimi-k3: 0 finding(s), marked with the model name. It reads the diff only and answers only security, privacy and money, so treat its findings as advice.

Third opinion: did not run — claude-api_error (after a retry; first: claude-api_error). This review is one reviewer short.

Copy check: did not run — claude-api_error (after a retry; first: claude-api_error). This review is one reviewer short.

Exact head: fda8a6a4d0f0 · Context: repo, design, locale-glossary · Took 5m


const recover = useCallback(async (): Promise<PendingSendOutcome> => {
const finish = (outcome: Exclude<PendingSendOutcome, 'cancelled'>) => {
if (key && outcome !== 'in-flight') writePendingChargeSend(key, null)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BLOCKING: Keep the send guard after money moved but the charge is unbooked

If a transfer mined but recording keeps failing and the charge remains PENDING, recovery reaches its 60-second deadline and returns sent; this line deletes the marker. Revisiting the same recipient or request then enables Pay and can send a second transfer while the first has already moved money. Retain the marker for sent until authoritative completion or another reconciliation that makes a repeat safe; keep retrying idempotent recording on resume.

send = { ...send, txHash: executed.executed }
writePendingChargeSend(key, send)
} else if (
isPastWaitWindow(send) ||

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BLOCKING: Do not declare an old send unsent when its outcome is unreadable

After 24 hours, if the charge read fails and the bundler or nonce read fails, readUserOpOutcome returns unknown, but this age check alone returns not-sent, deletes the marker, and tells the payer no money left. An executed transfer hidden by a temporary read outage can then be paid again; the same branch also overrides backendBroadcast and untrackedBroadcast. Require a successful, conclusive reconciliation before offering Pay, rather than treating elapsed time or a failed read as proof.


export function readPendingChargeSendRaw(key: string): string | null {
try {
return window.localStorage.getItem(key)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BLOCKING: Make a failed storage write visible to the send guard

When localStorage is full, setItem throws and writePendingChargeSend saves the marker in memory, but getItem still succeeds with null, so this read never consults memory. isPending stays false and onBroadcast cannot update the marker; after an ambiguous send or reload, Pay can be offered again. Read the in-memory fallback even when getItem returns null, and fail closed or reconcile authoritatively when a durable marker cannot be saved.

export function isDefinitiveSendRefusal(error: unknown): boolean {
if (isStaleKeyError(error)) return true
const status = apiErrorStatus(error)
if (status !== undefined) return status >= 400 && status < 500

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

BLOCKING: Treat a submit timeout response as an unknown send outcome

A gateway can return HTTP 408 after /rain/cards/withdraw/submit was accepted. rainRequest wraps that response in ApiError, and this blanket 4xx rule calls it a definitive refusal. useSpendBundle then leaves the failure untagged and the payment flow clears its marker, allowing another transfer while the first may land. Keep 408 ambiguous; only endpoint-specific, proven no-effect responses should release the guard.

@github-actions

Copy link
Copy Markdown
Contributor

English · 31 not comparable

Open screen library dashboard

Review preview: 392496e → fda8a6a. Incomplete capture; unavailable states are listed in the report. Other locales were not captured; add the screens:all-locales label and re-run Screen library to include them.

Before was captured with the base branch's own synthetic API because this PR changes it; differences can include synthetic-data changes.

Screen Library coverage: review — UI review needs a complete, unique comparison for every required locale.

Screen Library copy: review — 1 changed copy key(s) appear in no captured state: payment.errors.paymentNotSent. 3 baseline entries are now shown or deleted; remove from scripts/screens/copy-coverage-baseline.json: card.yourCard.redZone, paymentLoading.sayingHola, profile.unlockPayments.chips.attention. Add a capture state that shows the copy, or add the keys to the baseline with “Screen Library copy exception: ” on its own line in the PR description. Copy coverage: 1300/4070 keys shown.

This branch was successfully deployed

1 active deployment
Preview — fda8a6a4 Deployed Nov 21, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant