Module quota_policy 

G5 — pure capacity-selection policy for multi-account OAuth providers.

This module has no I/O, no clock and no network. Every decision is a deterministic function of now_ms and the caller-supplied per-account capacity views (AccountCapacity), so it is trivially testable with a synthetic clock and can be shared by the broker (AccountSelector::Auto), the Codex stream failover and the quota keeper.

Invariants

• Fail closed. Stale, unknown, malformed, unsupported or auth-errored quota is not capacity. An account is only advertised as ready when a fresh observation shows headroom on every applicable limit.
• All applicable limits count. Every window that applies to the requested model (account-wide windows plus model-scoped windows naming that model) must have headroom. A window with no usable evidence makes the account ineligible.
• Exclusions are absolute. Cooling-down, exhausted, excluded and auth-errored accounts are never selected.
• Explicit never falls back. When a specific account is requested only that account is considered; it is selected or the request fails.
• Deterministic preference. Ties are broken by the operator’s preference order, then by storage key, so equal inputs always yield the same seat.
• One bounded failover. failover permits a single switch to a different eligible seat, only on a recognized pre-output quota failure, never after any output or tool activity and never on an ordinary 429.
• Perishable capacity first. Strategy::SoonestReset ranks eligible seats by tier — urgent anchored, then unanchored (first use starts the clock), then far anchored, then no reset evidence — soonest budget reset first, so capacity about to expire is burned before it is lost. Stickiness keeps the currently pinned seat unless a candidate sits in a strictly higher tier (or, within tier 1, resets strictly sooner); an ineligible current seat is never kept and an excluded one never re-picked.

Modules

cred_serde

Serde shim: CredentialRef round-trips as its storage key ("openai-codex@astra2"), which is already validated text.

Structs

AccountCapacity

Per-account capacity view supplied by the caller.

AccountFailure

One account’s part in a failed selection.

Eligible

Eligible-account summary produced by evaluate.

FailureEvidence

Evidence about the failed attempt.

ModelAvailability

Provider-reported model availability for an account.

ObservationFailure

A failed observation: its kind plus the HTTP status and Retry-After the provider sent, when there were any. Never token material or body bytes.

Rejection

One rejected candidate.

SelectionFailure

A failed automatic selection: the top-level kind, every account’s part in it, and the earliest known reset among limited accounts.

SelectionRequest

A selection request. All times are epoch milliseconds.

WindowLimit

One provider-reported rate-limit window, normalized by the usage adapter.

Enums

AccountFailureKind

Why one account could not serve a request, as a stable snake_case kind: a failed observation (usage read, token refresh, credential store) or the policy verdict on a good one. Secret-free; safe for logs and users.

FailoverDecision

FailureKind

Classification of the failure that triggered a failover request.

ModelState

Tri-state model availability. Unknown is preserved as unknown — it is never coerced to “available”.

QuotaObservation

What the usage adapter learned about one account.

RejectReason

Why an account was not selected. Secret-free, display-ready.

Selection

Result of select.

SelectionFailureKind

The one kind that explains a failed automatic selection.

Strategy

Ordering strategy among eligible accounts. All are deterministic.

WindowVerdict

Fail-closed verdict for one window.

Constants

DEFAULT_EXHAUSTED_AT_PERCENT

Default utilization percentage at/above which a window is exhausted.

DEFAULT_URGENT_HORIZON_MS

Default SelectionRequest::urgent_horizon_ms: an anchored budget window resetting within this horizon is “urgent” — its unused capacity is about to be lost, so it ranks first under Strategy::SoonestReset.

MAX_FAILOVERS

Maximum number of account switches for one request.

MAX_FUTURE_OBSERVATION_SKEW_MS

Observation timestamps further in the future than this are malformed (a small allowance for clock skew between the provider and this host).

UNANCHORED_MAX_USED_PERCENT

Maximum used_percent (inclusive) for a window to count as “≈0 % used” in is_unanchored. A window with real consumption has, by definition, already been anchored by that first use.

UNANCHORED_TOLERANCE_MS

Tolerance for is_unanchored: a window whose reported reset is within this distance of observed_at + duration is sliding with the observation rather than fixed on the provider’s calendar. Absorbs poll latency and clock skew between the provider and this host.

WEEKLY_WINDOW_MAX_MS

Upper bound (inclusive) for the weekly classification.

WEEKLY_WINDOW_MIN_MS

Lower bound (inclusive) for classifying a window as “weekly” from its provider-reported duration. Six days leaves room for providers that report approximate durations; never infer weekliness from a name like primary.

Functions

budget_window

The budget window of a reading for model: the window whose reset decides when unused capacity is lost.

evaluate

Evaluate a single account against the request. Pure; ignores explicit_account and provider matching (the caller filters those).

failover

Decide whether the request may be retried on another seat.

is_unanchored

Whether window’s reset slides with the observation instead of being a fixed instant — the signature of a seat whose window has not been started by a first use (Codex anchors a window at first use after a reset; an idle seat therefore keeps reporting reset ≈ observed_at + duration).

model_matches

Whether a provider availability/window entry (sonnet, gpt-6-astra) names the requested model id (claude-sonnet-4-6). Exact (case-insensitive) match, or the entry equals one -/_///:/. separated token of the request — the same rule the usage adapter uses.

select

Pick the best eligible account for req among candidates.

valid_threshold

Whether an exhaustion threshold is usable (finite, 0..=100).

weekly_window

The account-wide weekly window of a reading, if the provider reports one.