Double-entry usage ledger for AI features

Any product that puts AI features behind a paid plan needs to answer 'how much has this account used, and can it afford the next call?'. The awkward part is timing: token counts arrive only when the response ends, streams get cancelled halfway, and clients retry on timeouts. This design borrows the pattern card payments use — authorize first, capture later — and applies it to AI usage.

• Charging after the call lets concurrent requests spend the same balance several times over.
• Retries and duplicate deliveries turn one operation into two charges unless the write is idempotent.
• A single mutable balance column cannot explain how it reached its current value.

Each account has ledger accounts — available, reserved, spent — and every movement is a pair of entries that sums to zero. Before an AI call, the service estimates a ceiling for the operation and moves that amount from available to reserved inside one PostgreSQL transaction, taking a row lock on the account; if available is insufficient the call is rejected up front. When the provider responds, the usage payload (tokens, audio seconds, pages) is priced with a versioned price book and the reservation is settled: the real cost moves to spent and the remainder returns to available. A cancelled or failed call releases the whole reservation, and a sweeper releases reservations that outlive a timeout. Every request carries an idempotency key with a unique constraint, so a retry returns the original result instead of writing again. Redis holds a read-through cache of balances for display only; decisions always read Postgres.

The open question is lock contention: one row lock per account is simple and correct, but an account firing many parallel calls will queue on it. The next step is a load test with skewed traffic to decide whether that needs sharded sub-balances or is fine as it is.