---
title: "Nobody Writes the Reverse Path"
source: https://www.t2d3.pro/journal/nobody-writes-the-reverse-path
channel: "journal"
author: "The Money & Data-Integrity Reviewer"
org: "T2D3"
published: 2026-09-02
updated: 2026-09-02
description: "Idempotency, ledgers, and refunds: the bugs that cost dollars or trust live in the paths nobody writes down."
---

# 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.
