@velum-labs/routekit-accounts 0.16.0 → 0.16.2

package/dist/account-set.d.ts

@@ -1,10 +1,10 @@
 import { type ModelReasoningCapabilities, ProviderFailureError } from "@velum-labs/routekit-contracts";
 import type { SubscriptionMode } from "@velum-labs/routekit-registry";
 import type { SubscriptionAccountSource } from "./account-source.js";
-import { type SubscriptionProvider } from "./provider.js";
 import { AccountActivityCoordinator } from "./activity.js";
-import type { AccountLimits, ResetCreditSnapshot, SubscriptionCredential, SubscriptionAccountSetSnapshot, SubscriptionSelectionStrategy } from "./types.js";
 import type { ConsumeResetCreditResult } from "./provider.js";
+import { type SubscriptionProvider } from "./provider.js";
+import type { AccountLimits, ResetCreditSnapshot, SubscriptionAccountSetSnapshot, SubscriptionCredential, SubscriptionSelectionStrategy } from "./types.js";
 export type SubscriptionAccountSetOptions = {
     mode: SubscriptionMode;
     activity?: AccountActivityCoordinator;
@@ -29,15 +29,22 @@ export type RedeemResetCreditResult = ConsumeResetCreditResult & {
     label: string;
     mode: SubscriptionMode;
 };
+type CooldownContext = {
+    model?: string;
+    windows?: string[];
+};
 export declare class RateLimitTracker {
     #private;
     constructor(statePath: string, mode?: SubscriptionMode);
     limits(memberId: string): AccountLimits | undefined;
     coolingUntil(memberId: string): number | undefined;
+    cooldownRevision(memberId: string): number;
+    cooldownContext(memberId: string): CooldownContext | undefined;
     update(memberId: string, limits: AccountLimits): void;
-    cool(memberId: string, until: number): void;
-    clearCooling(memberId: string): void;
-    resetAfterRefresh(memberId: string): void;
+    cool(memberId: string, until: number, context?: CooldownContext): number;
+    clearCooling(memberId: string, expectedRevision?: number): boolean;
+    reconcileSnapshot(memberId: string, limits: AccountLimits, expectedCooldownRevision: number, recovered: boolean): boolean;
+    resetAfterRefresh(memberId: string, expectedCooldownRevision: number): boolean;
     renameMember(sourceId: string, targetId: string): void;
 }
 export declare class SubscriptionAccountSetExhaustedError extends ProviderFailureError {
@@ -74,3 +81,4 @@ export declare class SubscriptionAccountSet {
     refreshUsage(maxAgeMs?: number, signal?: AbortSignal): Promise<void>;
     execute(model: string | undefined, operation: (credential: SubscriptionCredential) => Promise<Response>, signal?: AbortSignal, observer?: SubscriptionExecutionObserver): Promise<Response>;
 }
+export {};

package/dist/account-set.js

@@ -1,14 +1,14 @@
-import { existsSync, readFileSync } from "node:fs";
 import { createHmac, randomBytes, randomUUID } from "node:crypto";
-import { join } from "node:path";
-import { ProviderFailureError, isRetryableProviderFailure } from "@velum-labs/routekit-contracts";
+import { existsSync, readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { isRetryableProviderFailure, ProviderFailureError } from "@velum-labs/routekit-contracts";
 import { CapacityPool, SseDecoder, SseParseError } from "@velum-labs/routekit-gateway";
 import { writeFileAtomic } from "@velum-labs/routekit-runtime";
-import { hasUsableCredits, isOverSwitchThreshold, isPoolEligible, memberHeadroom } from "./admission.js";
 import { resolveSubscriptionAccounts } from "./account-source.js";
+import { AccountActivityCoordinator, subscriptionAccountIdentity } from "./activity.js";
+import { hasUsableCredits, isOverSwitchThreshold, isPoolEligible, memberHeadroom, poolReadiness, quotaAdmissionReasons } from "./admission.js";
 import { subscriptionCredentialLabel } from "./credentials.js";
 import { canonicalRateLimitWindowKey } from "./provider.js";
-import { AccountActivityCoordinator, subscriptionAccountIdentity } from "./activity.js";
 const DEFAULT_SWITCH_THRESHOLD = 0.9;
 const DEFAULT_REFRESH_SKEW_SECONDS = 300;
 const DEFAULT_FALLBACK_COOLDOWN_SECONDS = 300;
@@ -103,11 +103,35 @@ function parsedMemberState(value, mode, migration) {
     const coolingUntil = typeof value.coolingUntil === "number" && Number.isFinite(value.coolingUntil)
         ? value.coolingUntil
         : undefined;
-    if (limits === undefined && coolingUntil === undefined)
+    let cooldownRevision = typeof value.cooldownRevision === "number" &&
+        Number.isSafeInteger(value.cooldownRevision) &&
+        value.cooldownRevision >= 0
+        ? value.cooldownRevision
+        : 0;
+    if (coolingUntil !== undefined && cooldownRevision === 0) {
+        cooldownRevision = 1;
+        if (migration !== undefined)
+            migration.required = true;
+    }
+    let cooldownContext;
+    if (isRecord(value.cooldownContext)) {
+        const windows = Array.isArray(value.cooldownContext.windows)
+            ? value.cooldownContext.windows.filter((item) => typeof item === "string")
+            : undefined;
+        cooldownContext = {
+            ...(typeof value.cooldownContext.model === "string"
+                ? { model: value.cooldownContext.model }
+                : {}),
+            ...(windows !== undefined ? { windows } : {})
+        };
+    }
+    if (limits === undefined && coolingUntil === undefined && cooldownRevision === 0)
         return {};
     return {
         ...(limits !== undefined ? { limits } : {}),
-        ...(coolingUntil !== undefined ? { coolingUntil } : {})
+        ...(coolingUntil !== undefined ? { coolingUntil } : {}),
+        ...(cooldownRevision > 0 ? { cooldownRevision } : {}),
+        ...(cooldownContext !== undefined ? { cooldownContext } : {})
     };
 }
 function readTrackerState(path, mode) {
@@ -146,9 +170,7 @@ function readTrackerState(path, mode) {
 }
 function mergeLimits(previous, next, mode) {
     const windows = Object.create(null);
-    const sources = next.completeness === "snapshot"
-        ? [next.windows]
-        : [previous?.windows, next.windows];
+    const sources = next.completeness === "snapshot" ? [next.windows] : [previous?.windows, next.windows];
     for (const source of sources) {
         if (source === undefined)
             continue;
@@ -171,15 +193,64 @@ function mergeLimits(previous, next, mode) {
             source: next.source
         };
 }
+/**
+ * Trackers for one state file share mutable state process-wide. A daemon
+ * reload runs the candidate router before the previous one drains, so
+ * independent maps would let a candidate probe replace the whole file and
+ * silently discard a cooldown the draining generation just wrote.
+ */
+const sharedTrackerStates = new Map();
+function readStateFileText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
 export class RateLimitTracker {
     #statePath;
     #mode;
+    #shared;
     #state;
     constructor(statePath, mode) {
-        this.#statePath = statePath;
+        this.#statePath = resolve(statePath);
         this.#mode = mode;
-        const loaded = readTrackerState(statePath, mode);
+        const shared = sharedTrackerStates.get(this.#statePath);
+        if (shared !== undefined) {
+            if (shared.mode !== mode) {
+                throw new Error(`rate-limit tracker mode mismatch for ${this.#statePath}`);
+            }
+            this.#shared = shared;
+            this.#state = shared.members;
+            this.#adoptExternalState();
+            return;
+        }
+        const loaded = readTrackerState(this.#statePath, mode);
         this.#state = loaded.state;
+        this.#shared = {
+            mode,
+            members: this.#state,
+            lastPersisted: readStateFileText(this.#statePath)
+        };
+        sharedTrackerStates.set(this.#statePath, this.#shared);
+        if (loaded.migrated)
+            this.#persist();
+    }
+    /**
+     * Operators recover accounts by editing `.state.json` and reloading, so a
+     * new generation must honor a file this process did not write. Shared
+     * members are replaced in place to keep existing trackers consistent.
+     */
+    #adoptExternalState() {
+        const text = readStateFileText(this.#statePath);
+        if (text === this.#shared.lastPersisted)
+            return;
+        const loaded = readTrackerState(this.#statePath, this.#mode);
+        this.#state.clear();
+        for (const [id, member] of loaded.state)
+            this.#state.set(id, member);
+        this.#shared.lastPersisted = text;
         if (loaded.migrated)
             this.#persist();
     }
@@ -189,31 +260,70 @@ export class RateLimitTracker {
     coolingUntil(memberId) {
         return this.#state.get(memberId)?.coolingUntil;
     }
+    cooldownRevision(memberId) {
+        return this.#state.get(memberId)?.cooldownRevision ?? 0;
+    }
+    cooldownContext(memberId) {
+        return this.#state.get(memberId)?.cooldownContext;
+    }
     update(memberId, limits) {
         const member = this.#state.get(memberId) ?? {};
         member.limits = mergeLimits(member.limits, limits, this.#mode);
         this.#state.set(memberId, member);
         this.#persist();
     }
-    cool(memberId, until) {
+    cool(memberId, until, context) {
         const member = this.#state.get(memberId) ?? {};
+        member.cooldownRevision = (member.cooldownRevision ?? 0) + 1;
         member.coolingUntil = until;
+        if (context === undefined)
+            delete member.cooldownContext;
+        else
+            member.cooldownContext = context;
         this.#state.set(memberId, member);
         this.#persist();
+        return member.cooldownRevision;
     }
-    clearCooling(memberId) {
+    clearCooling(memberId, expectedRevision) {
         const member = this.#state.get(memberId);
-        if (member === undefined || member.coolingUntil === undefined)
-            return;
+        if (member === undefined ||
+            member.coolingUntil === undefined ||
+            (expectedRevision !== undefined && member.cooldownRevision !== expectedRevision))
+            return false;
+        member.cooldownRevision = (member.cooldownRevision ?? 0) + 1;
         delete member.coolingUntil;
+        delete member.cooldownContext;
         this.#persist();
+        return true;
     }
-    resetAfterRefresh(memberId) {
+    reconcileSnapshot(memberId, limits, expectedCooldownRevision, recovered) {
+        const member = this.#state.get(memberId) ?? {};
+        member.limits = mergeLimits(member.limits, limits, this.#mode);
+        const cleared = recovered &&
+            limits.completeness === "snapshot" &&
+            member.coolingUntil !== undefined &&
+            (member.cooldownRevision ?? 0) === expectedCooldownRevision;
+        if (cleared) {
+            member.cooldownRevision = (member.cooldownRevision ?? 0) + 1;
+            delete member.coolingUntil;
+            delete member.cooldownContext;
+        }
+        this.#state.set(memberId, member);
+        this.#persist();
+        return cleared;
+    }
+    resetAfterRefresh(memberId, expectedCooldownRevision) {
         const member = this.#state.get(memberId) ?? {};
         delete member.limits;
-        delete member.coolingUntil;
+        const cleared = (member.cooldownRevision ?? 0) === expectedCooldownRevision;
+        if (cleared) {
+            member.cooldownRevision = (member.cooldownRevision ?? 0) + 1;
+            delete member.coolingUntil;
+            delete member.cooldownContext;
+        }
         this.#state.set(memberId, member);
         this.#persist();
+        return cleared;
     }
     renameMember(sourceId, targetId) {
         const source = this.#state.get(sourceId);
@@ -228,7 +338,9 @@ export class RateLimitTracker {
         const file = {
             members: [...this.#state].map(([id, member]) => ({ id, ...member }))
         };
-        writeFileAtomic(this.#statePath, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+        const text = `${JSON.stringify(file, null, 2)}\n`;
+        writeFileAtomic(this.#statePath, text, { mode: 0o600 });
+        this.#shared.lastPersisted = text;
     }
 }
 export class SubscriptionAccountSetExhaustedError extends ProviderFailureError {
@@ -295,6 +407,7 @@ export class SubscriptionAccountSet {
                     ...(tracker.coolingUntil(id) !== undefined
                         ? { coolingUntil: tracker.coolingUntil(id) }
                         : {}),
+                    cooldownRevision: tracker.cooldownRevision(id),
                     lastUsed: 0,
                     inFlight: 0,
                     switchedAt: 0
@@ -334,14 +447,30 @@ export class SubscriptionAccountSet {
                     (member.credential.expiresAt === undefined ||
                         member.credential.expiresAt > Date.now() / 1000 ||
                         (member.credential.refreshToken?.length ?? 0) > 0);
-                const poolEligible = this.#eligible(member, undefined, now);
+                const readiness = poolReadiness({
+                    limits: this.#tracker.limits(member.id),
+                    switchThreshold: this.#options.switchThreshold,
+                    ...(member.coolingUntil !== undefined ? { coolingUntil: member.coolingUntil } : {}),
+                    ...(member.credential.expiresAt !== undefined
+                        ? { credentialExpiresAt: member.credential.expiresAt }
+                        : {}),
+                    hasRefreshToken: member.credential.refreshToken !== undefined,
+                    catalogReady: this.#catalogReady,
+                    models: [...member.models],
+                    now,
+                    isWindowRelevant: (key, limitName) => this.#windowRelevant(key, limitName, undefined)
+                });
+                const readinessReasons = credentialValid
+                    ? readiness.reasons
+                    : member.credential.expiresAt !== undefined && member.credential.expiresAt <= now
+                        ? readiness.reasons
+                        : [{ code: "credential_invalid" }, ...readiness.reasons];
                 return {
                     ...status,
                     credentialValid,
-                    poolEligible,
-                    relayReady: credentialValid &&
-                        poolEligible &&
-                        (member.coolingUntil === undefined || member.coolingUntil <= now)
+                    poolEligible: readiness.eligible,
+                    relayReady: credentialValid && readiness.eligible,
+                    readinessReasons
                 };
             })
         };
@@ -405,9 +534,14 @@ export class SubscriptionAccountSet {
     async probe(signal) {
         await Promise.allSettled(this.#members.map(async (member) => {
             await this.#ensureFresh(member, signal);
+            const cooldownRevision = member.cooldownRevision;
+            const cooldownContext = this.#tracker.cooldownContext(member.id);
             const limits = await this.#provider.fetchUsage(member.credential, signal);
             const withResets = await this.#attachResetCredits(member, limits, signal);
-            this.#tracker.update(member.id, withResets);
+            const recovered = this.#snapshotRecovered(withResets, cooldownContext);
+            this.#tracker.reconcileSnapshot(member.id, withResets, cooldownRevision, recovered);
+            member.coolingUntil = this.#tracker.coolingUntil(member.id);
+            member.cooldownRevision = this.#tracker.cooldownRevision(member.id);
         }));
     }
     /**
@@ -429,6 +563,7 @@ export class SubscriptionAccountSet {
         }
         const member = this.#requireMember(input.label);
         await this.#ensureFresh(member, signal);
+        const expectedCooldownRevision = this.#tracker.cooldownRevision(member.id);
         const redeemRequestId = input.redeemRequestId !== undefined && input.redeemRequestId.trim().length > 0
             ? input.redeemRequestId.trim()
             : randomUUID();
@@ -471,8 +606,13 @@ export class SubscriptionAccountSet {
             catch {
                 // Consume already succeeded; clear cooling even if refresh fails.
             }
-            delete member.coolingUntil;
-            this.#tracker.clearCooling(member.id);
+            if (this.#tracker.clearCooling(member.id, expectedCooldownRevision)) {
+                delete member.coolingUntil;
+            }
+            else {
+                member.coolingUntil = this.#tracker.coolingUntil(member.id);
+            }
+            member.cooldownRevision = this.#tracker.cooldownRevision(member.id);
         }
         return {
             ...result,
@@ -494,15 +634,13 @@ export class SubscriptionAccountSet {
         const now = Date.now();
         const allFresh = this.#members.every((member) => {
             const limits = this.#tracker.limits(member.id);
-            return (limits?.completeness === "snapshot" &&
-                now - limits.observedAt * 1000 < maxAgeMs);
+            return limits?.completeness === "snapshot" && now - limits.observedAt * 1000 < maxAgeMs;
         });
         if (allFresh)
             return;
         if (this.#usageProbe !== undefined)
             return await this.#usageProbe;
-        if (this.#lastUsageProbeAt !== undefined &&
-            now - this.#lastUsageProbeAt < maxAgeMs) {
+        if (this.#lastUsageProbeAt !== undefined && now - this.#lastUsageProbeAt < maxAgeMs) {
             return;
         }
         this.#lastUsageProbeAt = now;
@@ -594,9 +732,8 @@ export class SubscriptionAccountSet {
                 // Only an actual spent quota window rotates accounts. Authentication,
                 // context, and unknown failures were already returned above.
                 const until = failure.resetsAt ??
-                    Date.now() / 1000 +
-                        (failure.retryAfter ?? this.#options.fallbackCooldownSeconds);
-                this.#penalize(member, until);
+                    Date.now() / 1000 + (failure.retryAfter ?? this.#options.fallbackCooldownSeconds);
+                this.#penalize(member, until, model);
                 excluded.add(member.id);
             }
             finally {
@@ -662,8 +799,14 @@ export class SubscriptionAccountSet {
         const now = Date.now() / 1000;
         for (const member of this.#members) {
             if (member.coolingUntil !== undefined && member.coolingUntil <= now) {
-                delete member.coolingUntil;
-                this.#tracker.clearCooling(member.id);
+                if (this.#tracker.clearCooling(member.id, member.cooldownRevision)) {
+                    delete member.coolingUntil;
+                    member.cooldownRevision = this.#tracker.cooldownRevision(member.id);
+                }
+                else {
+                    member.coolingUntil = this.#tracker.coolingUntil(member.id);
+                    member.cooldownRevision = this.#tracker.cooldownRevision(member.id);
+                }
             }
         }
         const eligible = this.#members.filter((member) => !excluded.has(member.id) && this.#eligible(member, model, now));
@@ -768,12 +911,38 @@ export class SubscriptionAccountSet {
         }
         return resets.length > 0 ? Math.min(...resets) : undefined;
     }
-    #penalize(member, until) {
+    #penalize(member, until, model) {
         member.coolingUntil = until;
-        this.#tracker.cool(member.id, until);
+        const limits = this.#tracker.limits(member.id);
+        const windows = limits === undefined
+            ? undefined
+            : Object.entries(limits.windows)
+                .filter(([key, window]) => this.#windowRelevant(key, window.limitName, model))
+                .map(([key]) => key);
+        member.cooldownRevision = this.#tracker.cool(member.id, until, {
+            ...(model !== undefined ? { model } : {}),
+            ...(windows !== undefined && windows.length > 0 ? { windows } : {})
+        });
         if (this.#activeId === member.id)
             this.#activeId = undefined;
     }
+    #snapshotRecovered(limits, context) {
+        if (limits.completeness !== "snapshot")
+            return false;
+        const relevant = (key, limitName) => {
+            if (context?.windows !== undefined && context.windows.length > 0) {
+                return context.windows.includes(key);
+            }
+            if (context?.model === undefined)
+                return true;
+            return this.#windowRelevant(key, limitName, context.model);
+        };
+        return (quotaAdmissionReasons({
+            limits,
+            switchThreshold: this.#options.switchThreshold,
+            isWindowRelevant: relevant
+        }).length === 0);
+    }
     /**
      * A member keeps its previous catalog when discovery fails, because an empty
      * model set makes it pool-ineligible: a provider blip would otherwise take
@@ -813,10 +982,16 @@ export class SubscriptionAccountSet {
             return false;
         }
         member.forcedRefreshAt = now;
+        const expectedCooldownRevision = this.#tracker.cooldownRevision(member.id);
         const refresh = (async () => {
             member.credential = await this.#provider.refresh(member.credential, signal);
-            this.#tracker.resetAfterRefresh(member.id);
-            delete member.coolingUntil;
+            if (this.#tracker.resetAfterRefresh(member.id, expectedCooldownRevision)) {
+                delete member.coolingUntil;
+            }
+            else {
+                member.coolingUntil = this.#tracker.coolingUntil(member.id);
+            }
+            member.cooldownRevision = this.#tracker.cooldownRevision(member.id);
         })().finally(() => this.#refreshes.delete(member.id));
         this.#refreshes.set(member.id, refresh);
         try {
@@ -836,10 +1011,16 @@ export class SubscriptionAccountSet {
         const existing = this.#refreshes.get(member.id);
         if (existing !== undefined)
             return existing;
+        const expectedCooldownRevision = this.#tracker.cooldownRevision(member.id);
         const refresh = (async () => {
             member.credential = await this.#provider.refresh(member.credential, signal);
-            this.#tracker.resetAfterRefresh(member.id);
-            delete member.coolingUntil;
+            if (this.#tracker.resetAfterRefresh(member.id, expectedCooldownRevision)) {
+                delete member.coolingUntil;
+            }
+            else {
+                member.coolingUntil = this.#tracker.coolingUntil(member.id);
+            }
+            member.cooldownRevision = this.#tracker.cooldownRevision(member.id);
         })().finally(() => this.#refreshes.delete(member.id));
         this.#refreshes.set(member.id, refresh);
         return refresh;
@@ -866,7 +1047,8 @@ export class SubscriptionAccountSet {
         }
     }
     #observeStream(member, response) {
-        if (response.body === null || !response.headers.get("content-type")?.includes("text/event-stream")) {
+        if (response.body === null ||
+            !response.headers.get("content-type")?.includes("text/event-stream")) {
             return response;
         }
         const decoder = new SseDecoder();

package/dist/admission.d.ts

@@ -1,9 +1,21 @@
+import type { AccountReadinessReason } from "@velum-labs/routekit-contracts";
 import type { AccountLimits, CreditSnapshot } from "./types.js";
+/** @deprecated Use AccountReadinessReason from routekit-contracts. */
+export type AdmissionReason = AccountReadinessReason;
+export type PoolReadiness = {
+    eligible: boolean;
+    reasons: AdmissionReason[];
+};
 export declare function hasUsableCredits(credits: CreditSnapshot | undefined): boolean;
 export declare function windowHeadroom(utilization: number): number;
 export declare function memberHeadroom(limits: AccountLimits | undefined, isWindowRelevant?: (key: string, limitName?: string) => boolean): number;
 export declare function isOverSwitchThreshold(headroom: number, switchThreshold: number): boolean;
-export declare function isPoolEligible(input: {
+export declare function quotaAdmissionReasons(input: {
+    limits?: AccountLimits;
+    switchThreshold: number;
+    isWindowRelevant?: (key: string, limitName?: string) => boolean;
+}): AdmissionReason[];
+export declare function poolReadiness(input: {
     limits?: AccountLimits;
     switchThreshold: number;
     coolingUntil?: number;
@@ -14,5 +26,6 @@ export declare function isPoolEligible(input: {
     model?: string;
     now?: number;
     isWindowRelevant?: (key: string, limitName?: string) => boolean;
-}): boolean;
+}): PoolReadiness;
+export declare function isPoolEligible(input: Parameters<typeof poolReadiness>[0]): boolean;
 export declare function windowAdmissionStatus(utilization: number, switchThreshold: number, credits: CreditSnapshot | undefined, providerStatus?: string): string;

package/dist/admission.js

@@ -21,29 +21,78 @@ export function memberHeadroom(limits, isWindowRelevant = () => true) {
 export function isOverSwitchThreshold(headroom, switchThreshold) {
     return headroom <= 1 - switchThreshold;
 }
-export function isPoolEligible(input) {
+function blockingProviderReason(window, status) {
+    const normalized = status?.trim().toLowerCase();
+    if (normalized === "rejected") {
+        return { code: "provider_quota_rejected", window, status: status };
+    }
+    if (normalized === "exceeded") {
+        return { code: "provider_quota_exceeded", window, status: status };
+    }
+    return undefined;
+}
+export function quotaAdmissionReasons(input) {
+    if (input.limits === undefined)
+        return [];
+    const relevant = input.isWindowRelevant ?? (() => true);
+    const creditsUsable = hasUsableCredits(input.limits.credits);
+    const reasons = [];
+    for (const [key, window] of Object.entries(input.limits.windows)) {
+        if (!relevant(key, window.limitName))
+            continue;
+        const providerReason = blockingProviderReason(key, window.status);
+        if (providerReason !== undefined) {
+            reasons.push(providerReason);
+            continue;
+        }
+        if (!creditsUsable &&
+            isOverSwitchThreshold(windowHeadroom(window.utilization), input.switchThreshold)) {
+            reasons.push({
+                code: "quota_switch_threshold",
+                window: key,
+                utilization: window.utilization,
+                switchThreshold: input.switchThreshold
+            });
+        }
+    }
+    return reasons;
+}
+export function poolReadiness(input) {
     const now = input.now ?? Date.now() / 1000;
-    if (input.catalogReady === true && (input.models?.length ?? 0) === 0)
-        return false;
+    const reasons = [];
+    if (input.catalogReady === true && (input.models?.length ?? 0) === 0) {
+        reasons.push({ code: "catalog_empty" });
+    }
     if (input.catalogReady === true &&
         input.model !== undefined &&
         input.models !== undefined &&
         !input.models.includes(input.model)) {
-        return false;
+        reasons.push({ code: "model_unavailable", model: input.model });
+    }
+    if (input.coolingUntil !== undefined && input.coolingUntil > now) {
+        reasons.push({ code: "cooldown_active", until: input.coolingUntil });
     }
-    if (input.coolingUntil !== undefined && input.coolingUntil > now)
-        return false;
     if (input.credentialExpiresAt !== undefined &&
         input.credentialExpiresAt <= now &&
         input.hasRefreshToken !== true) {
-        return false;
+        reasons.push({ code: "credential_expired", expiresAt: input.credentialExpiresAt });
     }
-    const headroom = memberHeadroom(input.limits, input.isWindowRelevant);
-    if (!isOverSwitchThreshold(headroom, input.switchThreshold))
-        return true;
-    return hasUsableCredits(input.limits?.credits);
+    reasons.push(...quotaAdmissionReasons({
+        ...(input.limits !== undefined ? { limits: input.limits } : {}),
+        switchThreshold: input.switchThreshold,
+        ...(input.isWindowRelevant !== undefined ? { isWindowRelevant: input.isWindowRelevant } : {})
+    }));
+    return { eligible: reasons.length === 0, reasons };
+}
+export function isPoolEligible(input) {
+    return poolReadiness(input).eligible;
 }
 export function windowAdmissionStatus(utilization, switchThreshold, credits, providerStatus) {
+    const providerReason = blockingProviderReason("window", providerStatus);
+    if (providerReason?.code === "provider_quota_rejected")
+        return "rejected";
+    if (providerReason?.code === "provider_quota_exceeded")
+        return "exceeded";
     if (!isOverSwitchThreshold(windowHeadroom(utilization), switchThreshold)) {
         return providerStatus ?? "ok";
     }