Core concepts
The ledger
Append-only, and why that is not negotiable.
Every movement of money writes a ledger_entry. Entries are never updated and never deleted, a database trigger refuses both, so the guarantee survives a migration, a psql session, and a future role misconfiguration.
Entry types
| Type | Means |
|---|---|
topup | The end user paid and their wallet was credited |
grant | Credit issued without a payment, a trial, a support gesture |
usage_debit | Inference consumed, at raw upstream cost |
refund | Money returned |
reversal | A top-up undone, a chargeback, or a duplicate |
adjustment | A correction, including credit from an orphaned hold |
Idempotency is a unique index, never application logic. A check-then-insert has a race window; a constraint does not.