Module budget 

LLM hard budgets (gateway L1).

L0 (crate::llm) meters token spend; L1 enforces a hard cap on it. A budget is a ceiling on tokens (or cost) over a fixed window, enforced fail-closed and atomically across replicas so a fleet behind a load balancer can’t collectively overshoot — the failure mode that makes naive per-replica caps leak.

The enforcement model is reserve → reconcile (the same shape a payment hold uses):

1. reserve an estimate (prompt size + the request’s max_tokens) before forwarding. If it would exceed the budget, the request is denied 429 and never reaches the upstream — so the cap is a true ceiling, not a post-hoc overshoot.
2. reconcile to the upstream’s actual usage once known: release the over-reserved remainder, or charge the extra if the estimate was low. A request that never produced usage (error, client hangup) reconciles to zero — a full release.

Structure mirrors crate::limiter: a pure decision ([would_reserve]) split from the store ([Store::Memory] for a single replica / tests, [Store::Redis] running the same arithmetic as an atomic Lua script). The window is encoded in the key (…:{window_index}) so it resets at the boundary with no sweeper, and the key TTLs out after the window passes.

Honesty note (mirrors the limiter / ACME): the Redis backend is implemented and compiled but the live transport isn’t exercised by cargo test (no Redis in CI) — only the pure decision and the in-memory store are. The #[ignore]d redis_*_live tests prove it against a real server.

Structs

BudgetEngine

Enforces the configured LLM budgets over a [Store]. Built once per config (re)load and carried on the proxy Runtime.

Denial

A budget denial: which budget rejected the request, its scope (the block-counter label) and unit (so a cost cap can answer 402 while a token cap answers 429).

Dims

The request dimensions a budget keys on (which subset it uses depends on the budget’s scope).

Observation

One budget’s post-reserve consumption, surfaced so the caller can feed the near-limit gauge.

Reservation

A held reservation: the per-budget amounts charged at reserve time, to be reconciled (or released) once the actual usage is known. Opaque to the caller beyond passing it back, except for the Observations it exposes for metrics.

Spend

An estimate (or actual) spend, carrying both units so a budget can charge whichever it caps.

Enums

BudgetScope

Which dimension a budget is keyed by.

BudgetUnit

The unit a budget caps.

Reserved

The outcome of a reserve attempt.