Token metering
Token metering means estimating, reserving, and reconciling LLM token usage against its real dollar cost, so a crossed spend cap blocks the next call rather than the wallet drifting unchecked. Caisson's @caisson/ai-meter module reserves integer credits against a conservative pre-call estimate, then trues the charge to the provider's actual reported usage: refunding over-reservations, billing shortfalls, never touching floats.
In code
const delta = settledCredits - core.reservedCredits;
let refundedCredits = 0;
let chargedCredits = 0;
if (billable && delta > 0) {
const res = await debit(tx, {
accountId: core.accountId,
amount: asCredits(delta),
eventType: "feature_debit",
feature: INFERENCE_FEATURE,
idempotencyKey: `${core.callId}:reconcile`,
rounding: actual.roundingCredits,
});
chargedCredits = delta;
} else if (billable && delta < 0) {
const res = await grant(tx, {
accountId: core.accountId,
amount: asCredits(-delta),
eventType: "feature_grant",
feature: INFERENCE_FEATURE,
idempotencyKey: `${core.callId}:reconcile`,
rounding: actual.roundingCredits,
});
refundedCredits = -delta;
}
// delta === 0 (or a BYOK lane): no credit row moves — the wallet stays put.How it holds
Estimate before spend
A cheap chars/4 heuristic sizes the reservation before the provider answers: conservative (rounds up, assumes a full output budget), so most calls over-reserve; reconcile() trues any residual shortfall afterward.
Reconcile to actual
After the call, reconcile() computes the real cost from provider-reported tokens and trues the delta: a feature_debit for a shortfall, a feature_grant for an over-reservation, nothing at all when the delta is zero.
Idempotent settlement
The append-only usage_event (account_id, call_id) UNIQUE constraint is the reconcile anchor: a retried settlement runs exactly once, so a network retry can never double-charge or double-refund.
Fail-closed pricing
resolvePriceEntry throws on an unknown provider/model rather than metering at zero, and every cost computation is integer-only (BigInt, ceiling division per token leg) so a charge is reproducible to the unit.