money-path-safety

Money path safety: money and value — a special class of code

Distilled from live billing sessions. Apply to ANY path where you deduct/credit/pay/limit.

1. Money: iron rules

1. MONEY PATH IS SACRED — lock/transaction + idempotency + a log for every event + a test for double-submit. Check: pressed «pay» twice → balance +X, not +2X.
2. IDEMPOTENCY BY DEFAULT — operation key (invoice_id, event_id) + credited flag + early return. Check: run the handler 2 times — second is a no-op.
3. SEPARATE BUCKETS — trial/promo/purchase/subscription = different entities, not one balance field. Explicit deduction order: free → bonus → paid.
4. HARD GATE BEFORE EXPENSIVE WORK — check entitlement/limit/money BEFORE the external call (CPU/API/LLM). With a zero balance the API is not called.
5. CHARGE AFTER SUCCESS — success → debit; error → no debit (+ log). Inject a provider error → balance unchanged.
6. LOG EVERY MUTATION — one line per credit/debit/grant/refund: charge uid=%s seconds=%.3f from_free=%.3f from_bonus=%.3f from_paid=%.3f. grep by user_id reconstructs the history.
7. NO SILENT EXCEPT ON SIDE EFFECTS — except: pass is acceptable on cleanup, NOT acceptable on money/auth/data-loss. Money path: log + fallback or fail loud.
8. READ-MODIFY-WRITE UNDER LOCK — «read→compute→write» without locking = lost update. Mutex/transaction over the whole RMW.
9. ONE SOURCE OF TRUTH — UI/cache/log are derivatives. Truth is the storage. An incident starts with reading storage, not with a theory.

2. Atomicity in SQL (without races)

• Atomic check-and-increment: UPDATE ... SET used = used + 1 WHERE used < max — one query, rowcount 0 = limit exhausted. NOT SELECT → IF → UPDATE.
• Compound PK as idempotency: PRIMARY KEY (code, user_id) — a repeat is blocked at the DB level, without SELECT before INSERT.
• SQLite: connect(timeout=30.0) + PRAGMA busy_timeout=30000 + journal_mode=WAL — three settings together.
• Metric upsert: INSERT ... ON CONFLICT DO UPDATE SET value=value+excluded.value — without SELECT+UPDATE race.