Day-1 foundation for item B (async Stripe Connect reversal worker).
No worker code, no runtime enforcement yet — just the authoritative
state machine that day 2's code will route through. Before writing
the worker we want a single place where the legal transitions are
defined and tested, so the worker's behavior can be argued against
the matrix rather than implicitly codified across call sites.
transfer_transitions.go:
* SellerTransferStatus constants (Pending, Completed, Failed,
ReversalPending [new], Reversed [new], PermanentlyFailed).
* AllowedTransferTransitions map: pending → {completed, failed};
completed → {reversal_pending}; failed → {completed,
permanently_failed}; reversal_pending → {reversed,
permanently_failed}; reversed and permanently_failed as dead ends.
* CanTransitionTransferStatus(from, to) — same-state always OK
(idempotent bumps of retry_count / next_retry_at); unknown from
fails conservatively (typos in call sites become visible).
transfer_transitions_test.go:
* TestTransferStateTransitions iterates the full 6×6 matrix (36
pairs) and asserts every pair against the expected outcome.
* TestTransferStateTransitions_TerminalStatesHaveNoOutgoing
double-locks Reversed + PermanentlyFailed as dead ends at the
map level (not just at the caller level).
* TestTransferStateTransitions_MatrixKeysAreAccountedFor keeps the
canonical status list in sync with the map; a new status added
to one but not the other fails the test.
* TestCanTransitionTransferStatus_UnknownFromIsConservative
documents the "unknown from → always false" policy so a future
reader sees the intent.
Migration 982 adds a partial composite index on (status,
next_retry_at) WHERE status='reversal_pending', sibling to the
existing idx_seller_transfers_retry (scoped to failed). Two parallel
partial indexes cost less than widening the existing one (which
would need a table-level lock) and keep the worker query planner-
friendly.
Day 2 routes processSellerTransfers, TransferRetryWorker,
reverseSellerAccounting, admin_transfer_handler through
CanTransitionTransferStatus at every Status mutation, and writes
StripeReversalWorker. Day 3 exercises the end-to-end flow
(refund → reversal_pending → worker → reversed) in a smoke probe.
Checkpoint: ping user at end of day 1 before day 2 per discipline
agreed upfront.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
