Credit Ledger Parity Checks: Catching Drift Early

The credit system has one invariant that must hold forever: a balance equals the sum of its ledger entries. Every reservation, settlement, release, top-up, and fee is a ledger row; the balance is just their running total. If those two ever disagree, money is wrong somewhere — and the worst version is the kind that drifts slowly and surfaces in a customer complaint. So we don't wait for the complaint. We check parity continuously. This post is how, and why drift detection matters as much as drift prevention.

The invariant, restated

balance(org)  ==  Σ ledger_entries(org)

This isn't an accounting nicety — it's the definition of correctness for the reserve-and-settle system. The ledger is the source of truth; the balance is a materialized total kept in lockstep via atomic writes (balance change and ledger row commit together, always). When they match, the books are right. When they don't, something wrote one without the other.

How parity drifts

In a correct system it shouldn't drift at all. But the whole point of a parity check is to catch the cases where a bug, a crash, or an edge path broke the atomicity:

The leaked reservation is the most common and the most insidious: the customer's available balance silently shrinks for calls that never cost anything, and nothing errors. Only a parity check notices.

Continuous checking, not month-end reconciliation

The check is simple to state — for each org, does balance == Σ ledger? — and the value is in running it continuously as a background scanner rather than discovering a mismatch at month-end close. A scanner that surfaces "org X is off by $0.40" the hour it happens turns a forensic investigation into a quick fix while the cause is still in recent deploys. Discovering the same $0.40 three weeks later means spelunking through logs to reconstruct what happened.

This is one of a family of seam scanners that watch for drift between what the system claims and what the data shows — leaked reservations, orphaned virtual keys, Stripe ledger lag, RLS gaps. Each compares two things that should agree and alerts when they don't.

What a finding triggers

A parity mismatch is high-severity by default — it's money. The response is to (a) freeze the assumption that the balance is right, (b) reconstruct the correct balance from the ledger (the source of truth), and (c) find the write path that broke atomicity so it can't recur. Because the ledger is authoritative, recovery is well-defined: the balance is always re-derivable by summing entries. The check tells you there's a problem; the ledger tells you the right answer.

Testing the check itself

A drift detector that never fires might be perfect — or might be broken. So the parity check is itself tested: deliberately introduce a mismatch in a test fixture and assert the scanner flags it. A monitor you haven't seen catch a planted bug is a monitor you can't trust to catch a real one. (Same discipline as testing a fallback chain by forcing the failure.)

The takeaway

The credit system's correctness is one equation — balance equals ledger sum — and the difference between a robust system and a fragile one is whether you verify that equation continuously or just assume it. Atomic writes prevent drift; a continuous parity scanner detects what slips through, surfaces it while the cause is fresh, and recovery is always well-defined because the ledger is the source of truth. Prevent, then check — and test the check.