Nobody Writes the Reverse Path

I read T2D3 OS the way I read any system that touches money: not by following a purchase, but by asking what happens when it is undone. The forward path is the part somebody demoed. The reverse path is the part somebody wrote later, at speed, by reading the forward path and inverting it in their head.

The good news first, because it is real and it sets up the rest.

The forward path here is careful

The Stripe webhook is the best-built code in this repository. It claims the event id, reclaims stale claims with a compare-and-swap, anchors each branch on its own unique index, and — the detail I care about most — grants after the anchor, so a crash lands on the under-credit side and screams into Sentry rather than quietly minting a second balance. Elsewhere a purchase freezes its price into checkout metadata so the webhook never recomputes it, and one send path claims work with a CAS specifically, per its own comment, so a reviewer's click and a cron can never both transmit.

That is a team with the instinct; somebody here has been burned before and wrote it down. Which is why the failures are interesting: not ignorance, asymmetry.

Debits are audited. Credits are trusted.

The shape, as a class: a product sells a balance. Buying it is protected by an idempotency anchor, so a retried webhook cannot mint that balance twice. Refunding it returns the customer's money, updates a refund status, and sends a confirmation email. It does not touch the balance. The idempotency machinery everybody is proud of prevents double-granting. There is no inverse — nobody was worried about giving a customer too little.

So the reversal returns the cash and leaves the goods. The loss per cycle is the price plus the vendor cost of whatever the retained balance buys — real compute and real human work, off real invoices.

"They forgot to write the refund" is not the lesson. They did write the refund. It refunded the wrong ledger — the one made of dollars, not the one made of entitlements. When a purchase moves value in two systems, the reversal has to move it back in two, and the second system is always the one the author does not think of as money.

Debit and credit disagreeing about the account

The sharper version showed up in credits.

The spend function is well written: a SECURITY DEFINER routine that resolves which pool to charge — if the org has a parent agency, the agency's pool pays. That resolution lives inside the function, where no caller can get it wrong.

The refund function updates the balance row for the org id it was handed. No parent lookup. Every route passes the same subject org to both and assumes symmetry.

So the charge lands on the agency and the refund goes looking for a client-org balance row that, by the code's own comment, usually does not exist. The UPDATE matches zero rows. Postgres does not consider that an error. The function returns success, the helper above it reports the full amount refunded without checking rows-affected, and the customer gets an email saying the credits have been refunded. Then the refund-once ledger row commits, so the honest retry hits the unique index and is swallowed as "already refunded."

Every individual line is defensible. The composite takes money, fails to give it back, tells the customer it did, and locks the door behind itself. Four routes inherit the same helper, and the ones carrying the most money are not the one it was found in.

A ledger is only a ledger if the debit and the credit agree on which account they mean. That agreement is not a property of a function; it is a property of a pair of functions, visible only when you read them side by side.

The ledger that cannot be summed

I also looked for the balance history and found a transactions table whose balance_after column is hardcoded to zero, annotated "informational." Five tables each remember one kind of credit event; none remembers all of them; the authoritative balances live in mutable rows nobody snapshots.

An idempotency key proves an event happened once. A ledger tells you what the balance was. You can have perfect keys and still be unable to answer "why is my balance 340?" — and you will be answering that to a customer who is already unhappy.

Guards that live in the UI

Two money routes gate on bare organization membership — any role. The billing page above them renders, to every non-owner, "View only — only the owner of this org can change the plan or manage payment methods." True about the button, false about the API, and the API is the authority. A newer sibling route gets it right and excludes delegated operators explicitly. Same feature, three postures on who may spend.

A disabled button is a suggestion. Authorization is a property of the route.

The same misplaced trust runs through the destructive side, where confirmation friction is applied in inverse proportion to irreversibility: the recoverable action asks "are you sure," the one that moves cash out does not.

The send path with no compliance check

One finding is not about dollars. I will state it plainly anyway, because in this category the regulator is the counterparty.

There are three ways a contact gets messaged. Two route through a gate that checks consent and deliverability. The third — the one a human clicks from a list — performs no compliance check on any status. It calls the channel dispatcher directly, including the SMS branch, whose own header says it is invoked after the compliance gate re-passes. It never enters that gate.

Meanwhile an opt-out reply writes a withdrawal into the consent store and completes the sequence, but never touches already-pending work. The withdrawn contact's queued message keeps rendering with a live Send button beside it. The consent function would say no. That path never asks.

On email that is a GDPR exposure. On the SMS branch it is the TCPA version, where statutory damages are per message. Consent is a global fact about a person; here it lives in two drifting stores and is read by only some of the paths that act on it.

What the refuter took away from me

The bench ran an adversarial pass over every finding, and roughly half of what the seats filed as top severity did not survive contact with the code. Two of mine died.

I filed a credit-minting RLS hole: a balances table whose UPDATE policy had no WITH CHECK, letting an authenticated user write their own balance. The policy defect is real and still live. The impact is not. The table is retired — a hardening sweep had already moved live spend to sibling tables, the consume functions were revoked from anon and authenticated, and nothing reads it on any entitlement or billing path. Minted balances buy nothing. Orphan-table hygiene, filed by me as theft.

I also filed duplicate journal entries into the accounting integration — no external idempotency key, the synced flag written after the POST with its error unchecked, and a cleanup tool that deletes only by recorded entity id, so the duplicate is invisible to the thing built to reverse it. Mechanism confirmed, severity cut: writes are off by default and the money at risk is our own books. Worth fixing, not worth my alarm.

Both refutations carry the same moral as the findings that held. Severity is a property of the reachable path, and the only way to know a path is reachable is to follow it to a reader. I skipped that step twice; the refuter didn't.

The transferable part

For every write that moves value, ask three questions, and do not accept a comment as an answer:

1. Who writes the inverse? Name the function. If the answer is "the status flip and the email," you have a receipt, not a reversal.
2. Do forward and reverse resolve the same account? Symmetry is a property of the pair, so review them as a pair.
3. What does zero rows mean here? A guarded UPDATE matching nothing is not an error in Postgres, and "success" plus a confirmation email is how a silent loss becomes a lie you told the customer.

Then the fourth: who reconciles? Customer-facing copy in this repo says "we are reconciling it — no action is needed from you," written inside a catch block. I went looking for the reconciler. No cron, no admin route, and the polling path early-returns on exactly the rows that need it. "Parked for reconciliation" is a status, not a process.

Reconciliation is a feature. It takes a sprint, ships nothing visible, and is the only mechanism that will ever tell you two individually-true numbers disagree. Nobody writes a test for the refund they hope never happens. That is exactly why the refund is where the money goes.