One append-only entry in a tenant's credit ledger, in micro-dollars.

kind says what happened and amount is the signed delta it applied to the balance (grant positive; settle, debit and expire negative or zero; hold and release zero, moving held_delta instead). balance_after and held_after snapshot the row after the entry, so the log alone reproduces every balance.

balance_after, held_after and promotional_after snapshot the row after the entry, so the log alone reproduces every figure.

reference is the caller's idempotency key: unique per kind, so a retried grant is returned instead of credited twice and a retried hold or debit is refused. A hold carries status (:pending, :settled, :released) and, once settled, settled_amount; a promotional grant may carry expires_at and gets expired_at when AuroraMeter.Credits.expire_due/1 consumes it.

category names where a grant's money came from (:paid, :promotional, :adjustment) and, on a reversal, marks :reversal, which is a refund or chargeback taking a paid grant back. A reversal never consumes promotional credit and is reported against grants rather than as spend.

A reversal is kind: :reverse from schema version 9 on, and was kind: :debit, category: :reversal before it. Both shapes are permanent, because the log is append only. Ask reversal?/1 rather than matching on either.

seq is the order. It is a Postgres identity column, assigned in commit order, and it is what every query that reconstructs what happened first sorts by. inserted_at is a wall-clock stamp and is not monotonic, so it orders nothing (findings L20, X213). hold_transaction_id names the hold a settle or release row closes, and updated_at is stamped by the database the first time the row is updated in place.