offrouter-core 0.2.0 → 0.2.2

package/src/usage.ts

@@ -1,859 +0,0 @@
-/**
- * Usage, quota, and provider-health store for OffRouter V1.
- *
- * Distinguishes subscription quota from API-key spend so doctor/status/route
- * explain can say why paid fallback was or was not used.
- *
- * Provider health uses a small sliding-window error budget plus cooldown:
- * - healthy: enough budget remaining, no active cooldown
- * - degraded: elevated errors but still usable
- * - dead: cooldown active after budget exhaustion / hard failures
- *
- * In-memory only for this task; SQLite is deferred until the interface stabilizes.
- */
-import {
-  InMemoryAuditStore,
-  type AuditStore,
-  type InMemoryAuditStoreOptions,
-} from "./audit.js";
-import type {
-  AuthTier,
-  ProviderHealth,
-  SubscriptionStatus,
-} from "./types.js";
-
-/** Canonical event classes that drive health / quota / spend counters. */
-export type UsageEventKind =
-  | "request_success"
-  | "request_error"
-  | "rate_limited"
-  | "quota_exhausted"
-  | "timeout"
-  | "cancelled"
-  | "auth_failure"
-  | "subscription_quota_set"
-  | "subscription_usage"
-  | "api_key_spend";
-
-export interface SlidingWindowOptions {
-  /** Error-window length in ms. Default 60_000. */
-  windowMs?: number;
-  /** Errors inside the window that keep the provider healthy. Default 2. */
-  healthyMaxErrors?: number;
-  /** Errors inside the window before dead (above = dead). Default 5. */
-  deadMinErrors?: number;
-  /** Cooldown after death / hard failure before resurrectable. Default 30_000. */
-  cooldownMs?: number;
-}
-
-export interface ProviderUsageSnapshot {
-  providerId: string;
-  modelId?: string;
-  health: ProviderHealth;
-  /** Why health is at this level (short, audit-safe). */
-  healthReason?: string;
-  /** Errors counted in the sliding window. */
-  recentErrorCount: number;
-  /** Epoch ms when cooldown ends, if any. */
-  cooldownUntil?: number;
-  /** Configured / observed subscription unit quota (opaque units). */
-  subscriptionQuotaLimit?: number;
-  /** Subscription units consumed (opaque units). */
-  subscriptionQuotaUsed: number;
-  /** Remaining subscription units when limit known. */
-  subscriptionQuotaRemaining?: number;
-  subscriptionStatus?: SubscriptionStatus;
-  /** Cumulative paid API-key spend in USD (estimated). */
-  apiKeySpendUsd: number;
-  /** Total successful request count. */
-  successCount: number;
-  /** Total error count (all time in this process). */
-  errorCount: number;
-  lastErrorAt?: string;
-  lastErrorKind?: UsageEventKind;
-  lastSuccessAt?: string;
-  updatedAt: string;
-}
-
-export interface UsageEvent {
-  providerId: string;
-  modelId?: string;
-  authTier: AuthTier;
-  kind: UsageEventKind;
-  /**
-   * For subscription_usage / subscription_quota_set: opaque quota units.
-   * For api_key_spend: USD amount.
-   */
-  amount?: number;
-  /** Optional hard set of subscription limit when kind is subscription_quota_set. */
-  quotaLimit?: number;
-  subscriptionStatus?: SubscriptionStatus;
-  /** Override clock for tests. */
-  at?: Date;
-  /** Human-safe detail (already redacted by caller). */
-  detail?: string;
-}
-
-export interface RecordUsageResult {
-  snapshot: ProviderUsageSnapshot;
-  /**
-   * True when this event moved health from a usable state into dead/degraded,
-   * or when subscription became exhausted.
-   */
-  healthChanged: boolean;
-  previousHealth: ProviderHealth;
-}
-
-export const DEFAULT_NEAR_LIMIT_THRESHOLD = 0.2;
-
-/**
- * Snapshot of usage for a specific account within a provider.
- */
-export interface AccountUsageSnapshot {
-  providerId: string;
-  accountId: string;
-  used: number;
-  limit?: number;
-  remaining?: number;
-  percentRemaining?: number;
-  nearLimit: boolean;
-  subscriptionStatus: SubscriptionStatus;
-  /**
-   * Derived account health from quota usage: "dead" when exhausted,
-   * "degraded" when near-limit, otherwise "healthy". Useful for
-   * persisted stores that need a stable, restorable health signal.
-   */
-  health?: ProviderHealth;
-  updatedAt: string;
-}
-
-/**
- * Minimal persisted document for a single account's quota usage.
- * Shared between the in-memory and file-backed usage stores so snapshot
- * math stays in one place.
- */
-export interface AccountUsageDoc {
-  providerId: string;
-  accountId: string;
-  used: number;
-  limit?: number;
-  updatedAt: string;
-}
-
-/**
- * Why paid API-key capacity was or was not selected given current usage state.
- * Consumed by doctor / status / route explain surfaces.
- */
-export interface PaidFallbackExplanation {
-  providerId: string;
-  recommendation:
-    | "prefer_subscription"
-    | "allow_api_key_fallback"
-    | "api_key_only"
-    | "no_capacity";
-  reason: string;
-  subscriptionStatus?: SubscriptionStatus;
-  subscriptionQuotaRemaining?: number;
-  subscriptionHealth?: ProviderHealth;
-  apiKeySpendUsd: number;
-  usedPaidFallback: boolean;
-}
-
-export interface UsageStore {
-  /** Atomically apply a usage event and recompute health. */
-  record(event: UsageEvent): Promise<RecordUsageResult>;
-
-  getProvider(providerId: string): Promise<ProviderUsageSnapshot | undefined>;
-
-  listProviders(): Promise<ProviderUsageSnapshot[]>;
-
-  /**
-   * Set subscription quota limit/used for a provider without incrementing spend.
-   * Useful when adapters discover limit snapshots out of band.
-   */
-  setSubscriptionQuota(
-    providerId: string,
-    input: {
-      limit?: number;
-      used?: number;
-      status?: SubscriptionStatus;
-      modelId?: string;
-      at?: Date;
-    },
-  ): Promise<ProviderUsageSnapshot>;
-
-  /**
-   * Explain whether subscription capacity remains or paid fallback is justified.
-   */
-  explainPaidFallback(
-    providerId: string,
-    options?: { hasApiKeyCandidate?: boolean },
-  ): Promise<PaidFallbackExplanation>;
-
-  /**
-   * Record usage for a specific account within a provider.
-   */
-  recordUsage(
-    providerId: string,
-    accountId: string,
-    input: { used?: number; limit?: number; at?: Date },
-  ): Promise<AccountUsageSnapshot>;
-
-  /**
-   * Check whether a specific account is near its quota limit.
-   */
-  isNearLimit(providerId: string, accountId: string, threshold?: number): Promise<boolean>;
-
-  /**
-   * Get all accounts whose usage is near their quota limit.
-   */
-  getNearLimitAccounts(threshold?: number): Promise<AccountUsageSnapshot[]>;
-
-  /**
-   * Get the usage snapshot for a specific account.
-   */
-  getAccountUsage(providerId: string, accountId: string): Promise<AccountUsageSnapshot | undefined>;
-
-  /**
-   * List all account usage snapshots.
-   */
-  listAccountUsage(): Promise<AccountUsageSnapshot[]>;
-
-  /**
-   * JSON-safe diagnostic view. No secrets.
-   */
-  toJSON(): Record<string, unknown>;
-}
-
-export interface InMemoryUsageStoreOptions extends SlidingWindowOptions {
-  now?: () => Date;
-}
-
-interface InternalProviderState {
-  providerId: string;
-  modelId?: string;
-  /** Epoch-ms timestamps of recent errors inside the sliding window. */
-  errorTimestamps: number[];
-  cooldownUntil?: number;
-  health: ProviderHealth;
-  healthReason?: string;
-  subscriptionQuotaLimit?: number;
-  subscriptionQuotaUsed: number;
-  subscriptionStatus?: SubscriptionStatus;
-  apiKeySpendUsd: number;
-  successCount: number;
-  errorCount: number;
-  lastErrorAt?: string;
-  lastErrorKind?: UsageEventKind;
-  lastSuccessAt?: string;
-  updatedAt: string;
-}
-
-interface AccountQuotaState {
-  providerId: string;
-  accountId: string;
-  used: number;
-  limit?: number;
-  updatedAt: string;
-}
-
-const DEFAULT_WINDOW_MS = 60_000;
-const DEFAULT_HEALTHY_MAX_ERRORS = 2;
-const DEFAULT_DEAD_MIN_ERRORS = 5;
-const DEFAULT_COOLDOWN_MS = 30_000;
-
-const HARD_ERROR_KINDS: ReadonlySet<UsageEventKind> = new Set([
-  "auth_failure",
-  "quota_exhausted",
-]);
-
-/**
- * In-memory usage/health store.
- * Mutations are serialized so concurrent updates never lose counters.
- */
-export class InMemoryUsageStore implements UsageStore {
-  readonly #providers = new Map<string, InternalProviderState>();
-  readonly #accounts = new Map<string, AccountQuotaState>();
-  readonly #windowMs: number;
-  readonly #healthyMaxErrors: number;
-  readonly #deadMinErrors: number;
-  readonly #cooldownMs: number;
-  readonly #now: () => Date;
-  #chain: Promise<unknown> = Promise.resolve();
-
-  constructor(options: InMemoryUsageStoreOptions = {}) {
-    this.#windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
-    this.#healthyMaxErrors =
-      options.healthyMaxErrors ?? DEFAULT_HEALTHY_MAX_ERRORS;
-    this.#deadMinErrors = options.deadMinErrors ?? DEFAULT_DEAD_MIN_ERRORS;
-    this.#cooldownMs = options.cooldownMs ?? DEFAULT_COOLDOWN_MS;
-    this.#now = options.now ?? (() => new Date());
-
-    if (
-      this.#healthyMaxErrors < 0 ||
-      this.#deadMinErrors <= this.#healthyMaxErrors
-    ) {
-      throw new RangeError(
-        "healthyMaxErrors must be >= 0 and deadMinErrors must be > healthyMaxErrors",
-      );
-    }
-  }
-
-  #exclusive<T>(fn: () => T | Promise<T>): Promise<T> {
-    const run = this.#chain.then(fn, fn);
-    this.#chain = run.then(
-      () => undefined,
-      () => undefined,
-    );
-    return run;
-  }
-
-  async record(event: UsageEvent): Promise<RecordUsageResult> {
-    return this.#exclusive(() => {
-      const at = event.at ?? this.#now();
-      const state = this.#ensure(event.providerId, event.modelId, at);
-      const previousHealth = state.health;
-
-      if (event.modelId) state.modelId = event.modelId;
-
-      switch (event.kind) {
-        case "request_success":
-          state.successCount += 1;
-          state.lastSuccessAt = at.toISOString();
-          this.#pruneErrors(state, at.getTime());
-          break;
-
-        case "request_error":
-        case "rate_limited":
-        case "timeout":
-        case "auth_failure":
-        case "quota_exhausted":
-          state.errorCount += 1;
-          state.errorTimestamps.push(at.getTime());
-          state.lastErrorAt = at.toISOString();
-          state.lastErrorKind = event.kind;
-          if (event.kind === "rate_limited") {
-            state.subscriptionStatus =
-              state.subscriptionStatus === "exhausted"
-                ? "exhausted"
-                : "rate-limited";
-          }
-          if (event.kind === "quota_exhausted") {
-            if (event.authTier === "subscription") {
-              state.subscriptionStatus = "exhausted";
-              if (
-                state.subscriptionQuotaLimit !== undefined &&
-                state.subscriptionQuotaUsed < state.subscriptionQuotaLimit
-              ) {
-                state.subscriptionQuotaUsed = state.subscriptionQuotaLimit;
-              }
-            }
-          }
-          if (HARD_ERROR_KINDS.has(event.kind)) {
-            state.cooldownUntil = at.getTime() + this.#cooldownMs;
-          }
-          break;
-
-        case "cancelled":
-          // Cancellation is not a provider-health error by default.
-          break;
-
-        case "subscription_quota_set":
-          if (event.quotaLimit !== undefined) {
-            state.subscriptionQuotaLimit = event.quotaLimit;
-          }
-          if (event.amount !== undefined) {
-            state.subscriptionQuotaUsed = event.amount;
-          }
-          if (event.subscriptionStatus) {
-            state.subscriptionStatus = event.subscriptionStatus;
-          }
-          break;
-
-        case "subscription_usage": {
-          const units = event.amount ?? 1;
-          state.subscriptionQuotaUsed += units;
-          state.successCount += 1;
-          state.lastSuccessAt = at.toISOString();
-          if (
-            state.subscriptionQuotaLimit !== undefined &&
-            state.subscriptionQuotaUsed >= state.subscriptionQuotaLimit
-          ) {
-            state.subscriptionStatus = "exhausted";
-          } else if (
-            !state.subscriptionStatus ||
-            state.subscriptionStatus === "unknown"
-          ) {
-            state.subscriptionStatus = "active";
-          }
-          break;
-        }
-
-        case "api_key_spend": {
-          const usd = event.amount ?? 0;
-          if (usd < 0) {
-            throw new RangeError("api_key_spend amount must be >= 0");
-          }
-          state.apiKeySpendUsd += usd;
-          state.successCount += 1;
-          state.lastSuccessAt = at.toISOString();
-          break;
-        }
-
-        default: {
-          const _exhaustive: never = event.kind;
-          throw new Error(`Unhandled usage event kind: ${String(_exhaustive)}`);
-        }
-      }
-
-      if (event.subscriptionStatus) {
-        state.subscriptionStatus = event.subscriptionStatus;
-      }
-
-      this.#recomputeHealth(state, at.getTime(), event);
-      state.updatedAt = at.toISOString();
-
-      return {
-        snapshot: toSnapshot(state),
-        healthChanged: previousHealth !== state.health,
-        previousHealth,
-      };
-    });
-  }
-
-  async getProvider(
-    providerId: string,
-  ): Promise<ProviderUsageSnapshot | undefined> {
-    const state = this.#providers.get(providerId);
-    if (!state) return undefined;
-    const now = this.#now();
-    this.#recomputeHealth(state, now.getTime());
-    state.updatedAt = now.toISOString();
-    return toSnapshot(state);
-  }
-
-  async listProviders(): Promise<ProviderUsageSnapshot[]> {
-    const now = this.#now();
-    const out: ProviderUsageSnapshot[] = [];
-    for (const state of this.#providers.values()) {
-      this.#recomputeHealth(state, now.getTime());
-      state.updatedAt = now.toISOString();
-      out.push(toSnapshot(state));
-    }
-    return out.sort((a, b) => a.providerId.localeCompare(b.providerId));
-  }
-
-  async setSubscriptionQuota(
-    providerId: string,
-    input: {
-      limit?: number;
-      used?: number;
-      status?: SubscriptionStatus;
-      modelId?: string;
-      at?: Date;
-    },
-  ): Promise<ProviderUsageSnapshot> {
-    const result = await this.record({
-      providerId,
-      modelId: input.modelId,
-      authTier: "subscription",
-      kind: "subscription_quota_set",
-      amount: input.used,
-      quotaLimit: input.limit,
-      subscriptionStatus: input.status,
-      at: input.at,
-    });
-    return result.snapshot;
-  }
-
-  async explainPaidFallback(
-    providerId: string,
-    options: { hasApiKeyCandidate?: boolean } = {},
-  ): Promise<PaidFallbackExplanation> {
-    const snap = await this.getProvider(providerId);
-    const hasApiKey = options.hasApiKeyCandidate === true;
-    const apiKeySpendUsd = snap?.apiKeySpendUsd ?? 0;
-
-    if (!snap) {
-      return {
-        providerId,
-        recommendation: hasApiKey ? "api_key_only" : "no_capacity",
-        reason: hasApiKey
-          ? "No subscription usage recorded for this provider; API-key candidate may be used if policy allows."
-          : "No usage recorded and no API-key candidate announced.",
-        apiKeySpendUsd: 0,
-        usedPaidFallback: false,
-      };
-    }
-
-    const subStatus = snap.subscriptionStatus;
-    const remaining = snap.subscriptionQuotaRemaining;
-    const health = snap.health;
-
-    const subscriptionUsable =
-      health !== "dead" &&
-      subStatus !== "exhausted" &&
-      subStatus !== "expired" &&
-      subStatus !== "unconfigured" &&
-      (remaining === undefined || remaining > 0);
-
-    if (subscriptionUsable) {
-      if (subStatus === "rate-limited" || health === "degraded") {
-        return {
-          providerId,
-          recommendation: hasApiKey
-            ? "allow_api_key_fallback"
-            : "prefer_subscription",
-          reason:
-            subStatus === "rate-limited"
-              ? "Subscription is rate-limited; API-key fallback is justified if policy allows."
-              : "Subscription capacity is degraded; API-key fallback is available if policy allows.",
-          subscriptionStatus: subStatus,
-          subscriptionQuotaRemaining: remaining,
-          subscriptionHealth: health,
-          apiKeySpendUsd,
-          usedPaidFallback: apiKeySpendUsd > 0,
-        };
-      }
-      return {
-        providerId,
-        recommendation: "prefer_subscription",
-        reason:
-          remaining === undefined
-            ? "Healthy subscription capacity is preferred over paid API-key routes."
-            : `Subscription still has ${remaining} quota units remaining; paid API-key fallback should not be used yet.`,
-        subscriptionStatus: subStatus ?? "active",
-        subscriptionQuotaRemaining: remaining,
-        subscriptionHealth: health,
-        apiKeySpendUsd,
-        usedPaidFallback: apiKeySpendUsd > 0,
-      };
-    }
-
-    if (hasApiKey) {
-      let reason: string;
-      if (
-        subStatus === "exhausted" ||
-        (remaining !== undefined && remaining <= 0)
-      ) {
-        reason =
-          "Subscription quota is exhausted; paid API-key fallback is justified if policy allows.";
-      } else if (subStatus === "expired") {
-        reason =
-          "Subscription is expired; paid API-key fallback is justified if policy allows.";
-      } else if (subStatus === "unconfigured") {
-        reason =
-          "Subscription is unconfigured; paid API-key fallback is justified if policy allows.";
-      } else if (health === "dead") {
-        reason = `Subscription provider is dead${
-          snap.cooldownUntil
-            ? ` until ${new Date(snap.cooldownUntil).toISOString()}`
-            : ""
-        }; paid API-key fallback is justified if policy allows.`;
-      } else {
-        reason =
-          "Subscription capacity is unavailable; paid API-key fallback is justified if policy allows.";
-      }
-      return {
-        providerId,
-        recommendation: "allow_api_key_fallback",
-        reason,
-        subscriptionStatus: subStatus,
-        subscriptionQuotaRemaining: remaining,
-        subscriptionHealth: health,
-        apiKeySpendUsd,
-        usedPaidFallback: apiKeySpendUsd > 0,
-      };
-    }
-
-    return {
-      providerId,
-      recommendation: "no_capacity",
-      reason:
-        "Subscription capacity is unavailable and no API-key candidate is available.",
-      subscriptionStatus: subStatus,
-      subscriptionQuotaRemaining: remaining,
-      subscriptionHealth: health,
-      apiKeySpendUsd,
-      usedPaidFallback: false,
-    };
-  }
-
-  async recordUsage(
-    providerId: string,
-    accountId: string,
-    input: { used?: number; limit?: number; at?: Date },
-  ): Promise<AccountUsageSnapshot> {
-    return this.#exclusive(() => {
-      const at = input.at ?? this.#now();
-      const key = `${providerId}:${accountId}`;
-      let state = this.#accounts.get(key);
-      if (!state) {
-        state = { providerId, accountId, used: 0, updatedAt: at.toISOString() };
-        this.#accounts.set(key, state);
-      }
-      if (input.used !== undefined) state.used = input.used;
-      if (input.limit !== undefined) state.limit = input.limit;
-      state.updatedAt = at.toISOString();
-      return computeAccountSnapshot(state);
-    });
-  }
-
-  async isNearLimit(
-    providerId: string,
-    accountId: string,
-    threshold?: number,
-  ): Promise<boolean> {
-    return this.#exclusive(() => {
-      const key = `${providerId}:${accountId}`;
-      const state = this.#accounts.get(key);
-      if (!state) return false;
-      return computeAccountSnapshot(state, threshold).nearLimit;
-    });
-  }
-
-  async getNearLimitAccounts(threshold?: number): Promise<AccountUsageSnapshot[]> {
-    return this.#exclusive(() => {
-      const out: AccountUsageSnapshot[] = [];
-      for (const state of this.#accounts.values()) {
-        const snap = computeAccountSnapshot(state, threshold);
-        if (snap.nearLimit) out.push(snap);
-      }
-      return out.sort((a, b) => {
-        if (a.providerId !== b.providerId) return a.providerId.localeCompare(b.providerId);
-        return a.accountId.localeCompare(b.accountId);
-      });
-    });
-  }
-
-  async getAccountUsage(
-    providerId: string,
-    accountId: string,
-  ): Promise<AccountUsageSnapshot | undefined> {
-    return this.#exclusive(() => {
-      const key = `${providerId}:${accountId}`;
-      const state = this.#accounts.get(key);
-      if (!state) return undefined;
-      return computeAccountSnapshot(state);
-    });
-  }
-
-  async listAccountUsage(): Promise<AccountUsageSnapshot[]> {
-    return this.#exclusive(() => {
-      const out: AccountUsageSnapshot[] = [];
-      for (const state of this.#accounts.values()) {
-        out.push(computeAccountSnapshot(state));
-      }
-      return out.sort((a, b) => {
-        if (a.providerId !== b.providerId) return a.providerId.localeCompare(b.providerId);
-        return a.accountId.localeCompare(b.accountId);
-      });
-    });
-  }
-
-  toJSON(): Record<string, unknown> {
-    const providers: Record<string, unknown> = {};
-    for (const [id, state] of this.#providers) {
-      providers[id] = {
-        health: state.health,
-        healthReason: state.healthReason,
-        subscriptionQuotaLimit: state.subscriptionQuotaLimit,
-        subscriptionQuotaUsed: state.subscriptionQuotaUsed,
-        subscriptionStatus: state.subscriptionStatus,
-        apiKeySpendUsd: state.apiKeySpendUsd,
-        successCount: state.successCount,
-        errorCount: state.errorCount,
-        cooldownUntil: state.cooldownUntil,
-      };
-    }
-    return {
-      kind: "in-memory-usage",
-      providers,
-      accounts: Object.fromEntries(this.#accounts),
-    };
-  }
-
-  #ensure(
-    providerId: string,
-    modelId: string | undefined,
-    at: Date,
-  ): InternalProviderState {
-    let state = this.#providers.get(providerId);
-    if (!state) {
-      state = {
-        providerId,
-        modelId,
-        errorTimestamps: [],
-        health: "healthy",
-        subscriptionQuotaUsed: 0,
-        apiKeySpendUsd: 0,
-        successCount: 0,
-        errorCount: 0,
-        updatedAt: at.toISOString(),
-      };
-      this.#providers.set(providerId, state);
-    }
-    return state;
-  }
-
-  #pruneErrors(state: InternalProviderState, nowMs: number): void {
-    const cutoff = nowMs - this.#windowMs;
-    state.errorTimestamps = state.errorTimestamps.filter((t) => t >= cutoff);
-  }
-
-  #recomputeHealth(
-    state: InternalProviderState,
-    nowMs: number,
-    event?: UsageEvent,
-  ): void {
-    this.#pruneErrors(state, nowMs);
-
-    if (state.cooldownUntil !== undefined && state.cooldownUntil <= nowMs) {
-      state.cooldownUntil = undefined;
-    }
-
-    const errors = state.errorTimestamps.length;
-    let health: ProviderHealth;
-    let reason: string;
-
-    if (state.cooldownUntil !== undefined && state.cooldownUntil > nowMs) {
-      health = "dead";
-      reason = `Cooldown active until ${new Date(state.cooldownUntil).toISOString()}`;
-    } else if (
-      state.subscriptionStatus === "exhausted" ||
-      (state.subscriptionQuotaLimit !== undefined &&
-        state.subscriptionQuotaUsed >= state.subscriptionQuotaLimit)
-    ) {
-      if (event?.kind === "quota_exhausted" && state.cooldownUntil) {
-        health = "dead";
-        reason = "Subscription quota exhausted; cooldown applied";
-      } else if (errors >= this.#deadMinErrors) {
-        health = "dead";
-        reason = `Error budget exhausted (${errors} errors in ${this.#windowMs}ms window) with subscription quota exhausted`;
-        state.cooldownUntil = nowMs + this.#cooldownMs;
-      } else {
-        health = "degraded";
-        reason = "Subscription quota exhausted";
-      }
-    } else if (errors >= this.#deadMinErrors) {
-      health = "dead";
-      reason = `Error budget exhausted (${errors} errors in ${this.#windowMs}ms window)`;
-      state.cooldownUntil = nowMs + this.#cooldownMs;
-    } else if (errors > this.#healthyMaxErrors) {
-      health = "degraded";
-      reason = `Elevated error rate (${errors} errors in ${this.#windowMs}ms window)`;
-    } else {
-      health = "healthy";
-      reason =
-        errors === 0
-          ? "No recent errors"
-          : `Within error budget (${errors}/${this.#healthyMaxErrors} allowed)`;
-    }
-
-    state.health = health;
-    state.healthReason = reason;
-  }
-}
-
-function toSnapshot(state: InternalProviderState): ProviderUsageSnapshot {
-  const limit = state.subscriptionQuotaLimit;
-  const used = state.subscriptionQuotaUsed;
-  const remaining =
-    limit === undefined ? undefined : Math.max(0, limit - used);
-
-  return {
-    providerId: state.providerId,
-    modelId: state.modelId,
-    health: state.health,
-    healthReason: state.healthReason,
-    recentErrorCount: state.errorTimestamps.length,
-    cooldownUntil: state.cooldownUntil,
-    subscriptionQuotaLimit: limit,
-    subscriptionQuotaUsed: used,
-    subscriptionQuotaRemaining: remaining,
-    subscriptionStatus: state.subscriptionStatus,
-    apiKeySpendUsd: state.apiKeySpendUsd,
-    successCount: state.successCount,
-    errorCount: state.errorCount,
-    lastErrorAt: state.lastErrorAt,
-    lastErrorKind: state.lastErrorKind,
-    lastSuccessAt: state.lastSuccessAt,
-    updatedAt: state.updatedAt,
-  };
-}
-
-export function computeAccountSnapshot(
-  doc: AccountUsageDoc,
-  threshold: number = DEFAULT_NEAR_LIMIT_THRESHOLD,
-): AccountUsageSnapshot {
-  const limit = doc.limit;
-  const used = doc.used;
-  const remaining =
-    limit === undefined ? undefined : Math.max(0, limit - used);
-  let status: SubscriptionStatus;
-  let nearLimit = false;
-  let health: ProviderHealth;
-  if (limit === undefined) {
-    status = "unknown";
-    health = "healthy";
-  } else if (used >= limit) {
-    status = "exhausted";
-    health = "dead";
-  } else if ((limit - used) / limit < threshold) {
-    status = "near-limit";
-    nearLimit = true;
-    health = "degraded";
-  } else {
-    status = "active";
-    health = "healthy";
-  }
-  const percentRemaining =
-    limit === undefined
-      ? undefined
-      : Math.round(((limit - used) / limit) * 100);
-  return {
-    providerId: doc.providerId,
-    accountId: doc.accountId,
-    used,
-    limit,
-    remaining,
-    percentRemaining,
-    nearLimit,
-    subscriptionStatus: status,
-    health,
-    updatedAt: doc.updatedAt,
-  };
-}
-
-/**
- * Composite facade for callers that want one injectable "state" handle.
- * Writes stay on the specialized stores; this is a thin convenience.
- */
-export interface StateStore {
-  audit: AuditStore;
-  usage: UsageStore;
-}
-
-export class InMemoryStateStore implements StateStore {
-  readonly audit: AuditStore;
-  readonly usage: UsageStore;
-
-  constructor(options?: {
-    audit?: AuditStore;
-    usage?: UsageStore;
-    auditOptions?: InMemoryAuditStoreOptions;
-    usageOptions?: InMemoryUsageStoreOptions;
-  }) {
-    this.audit = options?.audit ?? new InMemoryAuditStore(options?.auditOptions);
-    this.usage =
-      options?.usage ?? new InMemoryUsageStore(options?.usageOptions);
-  }
-
-  toJSON(): Record<string, unknown> {
-    return {
-      kind: "in-memory-state",
-      audit: this.audit.toJSON(),
-      usage: this.usage.toJSON(),
-    };
-  }
-}