Module quota_keeper

Expand description

G6 — quota keeper: pure scheduler state machine, private persisted state and singleton/attempt locking.

The keeper watches each kept account’s weekly window (identified by its provider-reported duration — never by the name primary) and tracks the provider-reported reset instant as the authoritative reset generation. When a generation’s reset has passed and fresh usage still shows no newer window, the account is due for activation. In read-only mode (the default) the keeper only records and alerts. Only for accounts the operator explicitly opted in, the runner performs one bounded, tool-free request per generation; the keeper never declares the window active until a fresh usage read shows a strictly later reset.

§Invariants

No I/O, no clock, no network in the state machine: every function takes now_ms. Persistence and locking are separate helpers.
State is keyed by broker source + provider seat identity. For an opted-in account the identity is a strong seat fingerprint (digest of the full provider account id carried by the credential itself), so the key is canonical across aliases: two labels for one seat share one attempt ledger and a sequential alias switch cannot spend twice. A read-only account may carry only a weak metadata preview (label-scoped key). A metadata prefix is not an identity: activation is refused without a strong fingerprint, and the runner re-verifies the seat from the freshly vended token immediately before the request. Re-login of the same alias with a different seat never inherits a ticket.
An attempt is recorded and must be persisted before the request is sent (begin_attempt); ambiguous outcomes (timeout, crash between begin and finish, 5xx) consume the per-generation budget of exactly one. Only a definitive not sent (typed pre-flight stage) or a whitelisted pre-inference 4xx is refunded, and those are bounded separately with backoff. A second attempt for the same generation requires an explicit operator rearm.
A newly observed window is labelled verified; correlation with a keeper attempt is recorded, but never claimed as causal.
Natural rollover is never assumed: with no evidence the phase is Unknown/AwaitingActivation, never Active.
Proven capacity before any inference. An activation attempt is authorized only when the latest poll succeeded, is fresh, carries no overall limit_reached assertion, and every window applicable to the activation model (5h, weekly, model-scoped) shows headroom. A passed reset while the provider still asserts 100 % / limit_reached is Exhausted (reset passed), never due.

Structs§

AccountIdentity: Namespace of one kept account. Every field is non-secret display text.
AccountState
AttemptRecord: One activation attempt, for the operator record.
AttemptTicket: Ticket for one attempt. The caller MUST persist the state between begin_attempt and the request, so a crash leaves a pending record.
BankedResets: Banked reset inventory (Codex rate_limit_reset_credits). Alert-only.
KeeperConfig
KeeperLock: Exclusive advisory flock held for the process lifetime (released on drop or process death). Used for the state-dir singleton and for one lock per kept account in the canonical keeper dir, so a second keeper with a different --state-dir still cannot act on the same account.
KeeperState
StateStore: Private, atomic JSON state (dir 0700, file 0600, tmp+rename).
UsageObservation: What one usage poll returned. Produced by the runner’s usage adapter.

Enums§

ActivationDecision: Runner-facing decision after a poll.
AttemptOutcome: Terminal classification of one activation attempt, as reported by the runner. Only a typed NotSent and a whitelisted Rejected status are definitive “no inference” outcomes; everything else may have spent quota.
Attribution: How a verified window relates to keeper activity. Correlation is recorded; causation is never claimed (an external request or a provider-side reset could equally have anchored the window).
KeeperError
KeeperEvent: Operator-visible outcome of a state-machine step. Secret-free.
NotSentStage: Where a request definitively stopped before leaving the process or before reaching the provider. Only these stages may be reported as NotSent; anything after the request was written to the socket is Ambiguous.
ObservationOutcome
Phase

Constants§

ACCOUNT_LOCK_DIR: Sub-directory (of the canonical keeper dir) holding per-account locks.
DEFAULT_ATTEMPT_TIMEOUT_MS
DEFAULT_BANKED_EXPIRY_ALERT_MS
DEFAULT_MAX_ATTEMPTS: Attempts per reset generation. Fixed at one: a second attempt for the same generation only ever happens through an explicit operator rearm, never automatically.
DEFAULT_MAX_BACKOFF_MS
DEFAULT_POLL_INTERVAL_MS
DEFAULT_RESET_GRACE_MS: Poll shortly after the reported reset instead of waiting a full interval.
DEFAULT_STALE_AFTER_MS
DEFAULT_USAGE_TIMEOUT_MS
DEFAULT_VERIFY_POLL_MS: Re-poll cadence while an attempt awaits verification.
DEFAULT_VERIFY_WINDOW_MS: How long an attempt may stay pending before it is labelled unverified.
MAX_ATTEMPT_TIMEOUT_MS
MAX_HISTORY: Attempt history retained per account.
MAX_MAX_ATTEMPTS
MAX_MAX_BACKOFF_MS
MAX_NOT_SENT_PER_GENERATION: Definitive not-sent/rejected outcomes tolerated per generation.
MAX_POLL_INTERVAL_MS
MAX_RESET_GRACE_MS
MAX_STALE_AFTER_MS
MAX_VERIFY_WINDOW_MS
MIN_ATTEMPT_TIMEOUT_MS
MIN_POLL_INTERVAL_MS
MIN_STALE_AFTER_MS
REFUNDABLE_REJECT_STATUSES: HTTP statuses that prove the provider rejected the request before any inference (malformed request, auth, missing route, payload shape). Everything else — notably 429, 402, 408, 409 — is not refunded.
SEAT_FP_PREFIX: Prefix of a strong seat fingerprint (see AccountIdentity::seat_fingerprint).
SINGLETON_LOCK_NAME: File name of the singleton lock inside the state dir.
STATE_FILE_NAME: File name of the persisted state inside the state dir.
STATE_VERSION

Functions§

account_lock_name: File-name-safe form of a storage key for per-account locks.
activation_decision: Whether the runner may start an activation attempt now.
begin_attempt: Record an attempt as started. Consumes one unit of the generation budget.
capacity_view: Capacity view of the last successful poll, for quota_policy.
finish_attempt: Record the outcome of an attempt. Refundable outcomes return the budget unit and apply backoff; all others stay pending until verified/expired.
observe: Feed one fresh usage observation for key into the state machine.
rearm: Explicit operator re-arm: allow exactly one more attempt for the generation currently in Unverified. Never automatic. Returns Ok(None) when the account is not unverified (nothing to re-arm).
recover_after_restart: Housekeeping on startup: a pending attempt with no recorded outcome means the previous process died between begin and finish — mark it ambiguous.
windows_with_overall_flag: Fold a provider-asserted overall limit_reached: true into the account-wide windows so every policy consumer honours it. With no account-wide window present a synthetic overall window is added.