Last updated 2026-05-18

Reservations

Reservations are for actions where cost is estimated before work starts, such as LLM token generation or long-running export jobs.

Reserve

Reserve consumes reserve_cost immediately and stores a reservation record containing the exact Redis keys touched.

Finalize

FinalizeReservation records actual cost. If actual cost is lower than reserved cost, refundable impacts are refunded. If actual cost is higher, overage is recorded but the original operation is not failed retroactively.

Increment

IncrementReservation adjusts an active reservation for streaming and long-running workloads. Positive deltas re-check the stored impacted limits atomically and deny without mutation if any limit would be exceeded. Negative deltas reduce reserved cost and release refundable impacts.

Release

ReleaseReservation is used when the operation definitely did not happen. Active refundable impacts are released idempotently.

Important invariant

Increment, finalization, release, and expiry use ReservationImpact.redis_key. They must not recompute the current window key from wall-clock time.

Expiry

Expiry is processed by an internal Redis-backed sweeper. A REFUND_FULL policy refunds the stored reserved cost even when the impact is not otherwise refundable; CHARGE_FULL keeps the debit in place and marks the reservation expired.