@cortexkit/anthropic-auth-core 2.0.2 → 2.0.3

package/dist/internal-types/claustrum/interlock.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The declined-account interlock: the user's "do not use this vault account",
+ * kept on the consumer side because the vault has no notion of it.
+ *
+ * A decline follows the provider account, not the vault record: an entry made
+ * while the account was known matches any credential id or alias that logs
+ * into that same account, so relabelling, adding an alias or removing and
+ * re-adding the account never lifts it. A credential id that now logs into a
+ * different known account does not match, because that account has its own
+ * policy. While either side's account is unknown the entry falls back to the
+ * credential id, so an adapter that makes no identity claim cannot slip past
+ * it. Never keyed on the record version, so a token refresh cannot lift it.
+ */
+export interface DeclinedAccount {
+    readonly credentialId: string;
+    readonly accountIdentity?: string;
+}
+export declare function isDeclined(entries: readonly DeclinedAccount[], credentialId: string, accountIdentity?: string): boolean;
+export declare function declineAccount(entries: readonly DeclinedAccount[], credentialId: string, accountIdentity?: string): DeclinedAccount[];
+/**
+ * Lift every entry that declines a row: the row's credential ids (the
+ * representative and its aliases) under the row's account. An entry for a
+ * different known account is left alone even when it names one of these
+ * credential ids, so accepting a replacement never re-enables the account the
+ * user declined.
+ */
+export declare function acceptAccount(entries: readonly DeclinedAccount[], credentialIds: readonly string[], accountIdentity?: string): DeclinedAccount[];

package/dist/internal-types/claustrum/roster.d.ts

@@ -0,0 +1,221 @@
+import { type QuotaMap, type QuotaObservation } from '../quota/index.js';
+import type { RoutingRow } from '../routing/index.js';
+import type { ClaustrumScopedAttempt, ClaustrumScopedCustody, SkippedVaultRecord, VaultCredential, VaultCredentialType, VaultInventory } from './custody.js';
+import { type DeclinedAccount } from './interlock.js';
+/**
+ * One vault account as the pool sees it. It carries no bearer material: the
+ * access token is fetched from the vault for every send. Several vault
+ * records logged into the same provider account collapse into one row, so
+ * duplicate logins never count as extra quota.
+ */
+export interface VaultRosterRow {
+    routeId: string;
+    credentialId: string;
+    credentialType: VaultCredentialType;
+    accountIdentity?: string;
+    /** Other credential ids logged into the same provider account. */
+    aliases?: string[];
+    state: string;
+    label: string;
+    email?: string;
+    orgName?: string;
+    enabled: boolean;
+    addedAt: number;
+    quota?: QuotaMap;
+    /**
+     * The vault listed this record in a form this consumer could not use, so the
+     * row is the last good projection kept as it was rather than dropped.
+     */
+    stale?: true;
+    /**
+     * The vault's latest list named no account for `credentialId`, so
+     * `accountIdentity` is the last account that credential was known to log
+     * into, kept until the vault names one again. It proves neither that the
+     * credential still logs into that account nor that it changed accounts.
+     */
+    unclaimed?: true;
+}
+export interface VaultRosterFile {
+    version: 1;
+    view?: string;
+    /**
+     * False when the vault's reply carried records this consumer could not use.
+     * An incomplete reply never removes an account it may still hold: every
+     * previous member it does not account for is kept.
+     */
+    complete: boolean;
+    /** The unusable records of an incomplete reply: a safe id and a fixed reason. */
+    rejected?: SkippedVaultRecord[];
+    rows: VaultRosterRow[];
+    declined: DeclinedAccount[];
+}
+/** How a vault credential is presented in the pool. */
+export type AccountMapper = (credential: VaultCredential) => {
+    label?: string;
+};
+export interface ProjectionOptions {
+    /** Ids already used by local rows; a vault route never takes one. */
+    reservedRouteIds?: ReadonlySet<string>;
+    /** Prefix for vault route ids, so they read differently from local ids. */
+    routePrefix?: string;
+    mapAccount?: AccountMapper;
+    now?: number;
+}
+export declare const DEFAULT_ROUTE_PREFIX = "vault:";
+/**
+ * Project the vault's list onto the previous roster. Pure: callers serialize
+ * discovery and commit. Route ids, quota and the time an account was added
+ * survive for the same account; a credential that now logs into a different
+ * known account gets a new route id and no inherited quota.
+ *
+ * A record listed without an identity keeps the last account it was known to
+ * log into (the row is marked `unclaimed`). Dropping that binding would let a
+ * later different account look like an identity learned for the first time
+ * and inherit the first account's route and quota.
+ *
+ * A reply with unusable records is incomplete: a previous member it does not
+ * account for (its record was rejected, or a rejected record has no usable id
+ * and could be any of them) is kept, as an alias of its live account or as a
+ * `stale` row. Only a complete reply removes an account.
+ */
+export declare function projectVaultRoster(previous: VaultRosterFile | undefined, inventory: VaultInventory, options?: ProjectionOptions): VaultRosterFile;
+/**
+ * The rows `/routing` selects among. Only enabled, active accounts route;
+ * a declined or cold vault account stays listed for the menu but never
+ * reaches admission.
+ */
+export declare function vaultRoutingRows(roster: VaultRosterFile | undefined): RoutingRow[];
+export declare function readVaultRoster(path: string): Promise<VaultRosterFile | undefined>;
+/** The ownership assertion available to a roster mutation callback. */
+export interface VaultRosterLockContext {
+    assertOwned: () => Promise<void>;
+}
+export interface MutateVaultRosterOptions {
+    /**
+     * Runs when the new roster is fully staged on disk, immediately before the
+     * rename that publishes it, so a caller can confirm a lease of its own at
+     * the moment of publication rather than when `change` returned. If it
+     * throws, nothing is published and the staged file is removed. The
+     * roster's own write lock is reasserted right after it.
+     */
+    beforePublish?: () => Promise<void>;
+}
+/**
+ * Read, change and write the roster under its write lock. `change` returns
+ * undefined to leave the file as it is. Call `assertOwned()` immediately
+ * before any rename performed inside `change`; if it throws, do not rename.
+ */
+export declare function mutateVaultRoster<T>(path: string, change: (current: VaultRosterFile | undefined, context: VaultRosterLockContext) => Promise<{
+    next?: VaultRosterFile;
+    result: T;
+}> | {
+    next?: VaultRosterFile;
+    result: T;
+}, options?: MutateVaultRosterOptions): Promise<T>;
+/** Mark a vault account declined; it stays listed but never routes. */
+export declare function declineVaultRoute(path: string, routeId: string): Promise<undefined>;
+/** Lift the user's decline for a vault account and every alias of it. */
+export declare function acceptVaultRoute(path: string, routeId: string): Promise<undefined>;
+/**
+ * The receipt fields a quota or profile observation must carry to say which
+ * send (credential and account) it came from. Pass the
+ * `ClaustrumScopedAttempt` that send was authorized with.
+ */
+export type QuotaReceipt = Pick<ClaustrumScopedAttempt, 'credentialId' | 'accountIdentity' | 'accountIdentitySource' | 'expectedAccountIdentity'>;
+/**
+ * Merge a quota observation into a vault row through `/quota`'s merge. The
+ * write is fenced on the receipt the reading was taken with: it lands only
+ * while the row still holds that receipt's credential (as representative or
+ * alias) and account, so a slow read for a replaced account can never land on
+ * its successor. Returns whether the observation was kept.
+ */
+export declare function recordVaultQuota(path: string, input: QuotaReceipt & {
+    routeId: string;
+    observation: QuotaObservation;
+}): Promise<boolean>;
+/**
+ * Merge a quota observation that belongs to an account rather than to a
+ * served credential, such as a background reading from insula. The write
+ * lands only while the row is still bound to that exact known account, so a
+ * reading taken before a replacement never reaches the successor. Unlike
+ * `recordVaultQuota` it never binds an account: a row without a known account
+ * is refused. Returns whether the observation was kept.
+ */
+export declare function recordVaultAccountQuota(path: string, input: {
+    routeId: string;
+    accountIdentity: string;
+    observation: QuotaObservation;
+}): Promise<boolean>;
+/**
+ * Discover and commit the roster. The lease covers the list call and the
+ * commit, not just the write: an opaque view cannot tell a delayed old reply
+ * from a newer one, so a run that lost its lease is refused at commit. A
+ * failed list, or custody switching off mid-run, never writes anything; a
+ * peer holding the lease means its last committed roster is served instead.
+ */
+export declare function refreshVaultRoster(options: {
+    path: string;
+    custody: Pick<ClaustrumScopedCustody, 'discover'>;
+    isActive?: () => boolean | Promise<boolean>;
+    signal?: AbortSignal;
+    projection?: ProjectionOptions | (() => ProjectionOptions);
+}): Promise<VaultRosterFile | undefined>;
+/**
+ * A host-owned main account as last verified from the vault: the plugin's
+ * logical route, the credential that serves it and the account it logs into.
+ */
+export interface VaultPrimaryBinding {
+    routeId: string;
+    credentialId: string;
+    accountIdentity: string;
+    view: string;
+}
+export type VaultPrimaryUnavailableReason = 'malformed' | 'unclaimed' | 'incomplete' | 'identity-changed';
+export type VaultPrimary = 
+/**
+ * Main is bound. `replaced` is the previous binding when it named a
+ * different account: everything owned by that account (quota, profile,
+ * backoff, cache affinity) must be dropped, and outstanding observations
+ * for it fenced, even though the logical route stays the same.
+ */
+{
+    status: 'ready';
+    binding: VaultPrimaryBinding;
+    replaced?: VaultPrimaryBinding;
+}
+/** A complete reply lists no primary record: there is no main. */
+ | {
+    status: 'absent';
+}
+/**
+ * The reply cannot say who main is. Not the same as absent: the last
+ * verified binding is handed back untouched, and serving it still needs a
+ * fresh receipt that matches it.
+ */
+ | {
+    status: 'unavailable';
+    reason: VaultPrimaryUnavailableReason;
+    lastVerified?: VaultPrimaryBinding;
+};
+/**
+ * The seam for a plugin that keeps a main account: one fixed account the host
+ * owns under a logical route, outside the pool's rotating rows. The library
+ * has no main convention of its own: the plugin names the
+ * vault record that holds the role (`primaryCredentialId`) and its logical
+ * route. Main follows the account that record claims; another credential of
+ * that same account may serve it when the record itself is not active, but a
+ * credential of any other account is never promoted into main.
+ *
+ * Inputs are the plugin's filtered inventory, whether that inventory is
+ * complete (defaults to the reply having no unusable records; pass the
+ * roster's `complete` or false to override), the previous verified binding
+ * and, on the request path, the account the chosen request expects.
+ */
+export declare function resolveVaultPrimary(input: {
+    inventory: VaultInventory;
+    complete?: boolean;
+    previous?: VaultPrimaryBinding;
+    expectedAccountIdentity?: string;
+    primaryCredentialId: string;
+    routeId: string;
+}): VaultPrimary;

package/dist/internal-types/fs/refresh-file-lock.d.ts

@@ -13,7 +13,7 @@ export interface RefreshFileLock {
     whenLost(): Promise<LockLoss>;
     hasLost(): boolean;
 }
-export declare function acquireRefreshFileLock(options: {
+type RefreshFileLockOptions = {
     name: string;
     ttlMs: number;
     /**
@@ -22,7 +22,6 @@ export declare function acquireRefreshFileLock(options: {
      * be one host's path.
      */
     path: string;
-    now?: () => number;
     renew?: boolean;
     renewIntervalMs?: number;
     /** Notifies a live-owner refusal without awaiting; observer failures are ignored. */
@@ -30,4 +29,11 @@ export declare function acquireRefreshFileLock(options: {
     /** Synchronous, never awaited; throws and returned promise/thenable rejections are isolated. */
     onRenewalTimer?: (event: 'scheduled' | 'cancelled') => void;
     onStep?: (step: 'stale-marker-stat' | 'stale-marker-claimed' | 'stale-lock-observed' | 'lock-read-ready' | 'lock-missing' | 'stale-lock-confirmed' | 'stale-lock-removed' | 'stale-lock-recreated' | 'eviction-marker-acquired' | 'renewal-owner-confirmed' | 'renewal-marker-unavailable' | 'renewal-write-fenced' | 'renewal-write-ready' | 'renewal-write-finished' | 'relinquish-read' | 'renewal-finished' | 'release-owner-confirmed') => void | Promise<void>;
+};
+/** Filesystem leases share wall time across all callers and processes. */
+export declare function acquireRefreshFileLock(options: RefreshFileLockOptions): Promise<RefreshFileLock | null>;
+/** @internal Clock seam for lease tests; not exported by the package's fs entry point. */
+export declare function acquireRefreshFileLockWithClock(options: RefreshFileLockOptions & {
+    now?: () => number;
 }): Promise<RefreshFileLock | null>;
+export {};

package/dist/internal-types/quota/format.d.ts

@@ -21,6 +21,26 @@ export interface QuotaTextOptions {
     /** Defaults to `QUOTA_STALE_AFTER_MS`. */
     staleAfterMs?: number;
 }
+export interface QuotaWindowPart {
+    kind: 'window' | 'budget';
+    /** The display name of a quota window, or `credits` for the budget. */
+    name: string;
+    /** The shared figure wording, including `credits` for budget figures. */
+    figure: string;
+    /** The unrounded remaining percentage, clamped to 0–100, when known. */
+    remainingPercent?: number;
+    /** A bare relative reset span such as `4d`, only when the reset is future. */
+    resetIn?: string;
+    checkedAt: number;
+    /** Whether the reset followed this reading and has arrived by `now`. */
+    resetSinceReading: boolean;
+}
+export interface QuotaParts {
+    /** Reported windows in display order, followed by the budget when present. */
+    windows: QuotaWindowPart[];
+    /** The shared checked-age wording, present only when the reading is stale. */
+    age?: string;
+}
 /**
  * The name a window is shown under. A general window (scope `all`) is named
  * by its stored length; a model-scoped window keeps the label the plugin
@@ -29,6 +49,12 @@ export interface QuotaTextOptions {
  * were recorded) falls back to its label.
  */
 export declare function quotaWindowName(limit: Pick<ProjectedLimit, 'scope' | 'label' | 'windowMinutes'>): string;
+/**
+ * Structured quota wording for layouts that need one row per window. The
+ * windows use the same filtering and order as `quotaTextParts`; future resets
+ * and the optional age keep the shared formatter's wording.
+ */
+export declare function quotaWindowParts(quota: ProjectedQuota | undefined, options: QuotaTextOptions): QuotaParts;
 /**
  * The pieces of a quota text, in order: one per reported window
  * (`5h 58% left, resets 2h`), then the credit budget when there is one, then

package/dist/internal-types/quota/index.d.ts

@@ -1,7 +1,7 @@
 export type { QuotaCodec } from './codec.js';
 export { quotaCodec } from './codec.js';
-export type { QuotaTextForm, QuotaTextOptions } from './format.js';
-export { formatQuota, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaTextParts, quotaWindowName, } from './format.js';
+export type { QuotaParts, QuotaTextForm, QuotaTextOptions, QuotaWindowPart, } from './format.js';
+export { formatQuota, NO_LIMITS_REPORTED, NO_QUOTA_READING, QUOTA_STALE_AFTER_MS, quotaTextParts, quotaWindowName, quotaWindowParts, } from './format.js';
 export type { CreditBudgetCleared, CreditBudgetEntry, CreditBudgetReading, QuotaAbsentEntry, QuotaCounter, QuotaEntry, QuotaMap, QuotaReadingEntry, QuotaRetiredEntry, } from './map.js';
 export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, decodeQuotaMap, emptyQuotaMap, isQuotaMap, } from './map.js';
 export type { ObservedBudget, ObservedPair, ObservedReading, QuotaObservation, } from './merge.js';

package/dist/internal-types/routing/admission.d.ts

@@ -0,0 +1,93 @@
+import { type QuotaMap } from '../quota/map.js';
+import { type ProjectedQuota } from '../quota/projection.js';
+export type RowKind = 'oauth' | 'api-key';
+export interface RoutingRow {
+    id: string;
+    kind: RowKind;
+    /** The row's stored quota map; absent is the same as an empty map. */
+    quota?: QuotaMap;
+}
+export interface WindowRef {
+    scope: string;
+    label: string;
+}
+export interface ExclusionInputs {
+    /** Row id to the time (ms) a rate-limit mark expires. */
+    rateLimitMarks?: ReadonlyMap<string, number>;
+    /** Row id to the time (ms) a failed refresh may be retried. */
+    refreshBackoff?: ReadonlyMap<string, number>;
+}
+export interface AdmissionInput extends ExclusionInputs {
+    rows: readonly RoutingRow[];
+    /** `all` (the default) or a model family. */
+    scope?: string;
+    /** Labels the scope requires an entry for; defaults to `['primary']`. */
+    requiredLabels?: readonly string[];
+    now: number;
+    /**
+     * Called synchronously, once per refusal at gates 2 to 4, with the row id.
+     * Its return value is ignored and never awaited, so a pull the caller
+     * starts from here cannot delay the refusal.
+     */
+    requestPull?: (rowId: string) => void;
+}
+export type AdmissionRefusal = {
+    id: string;
+    stage: 1;
+    gate: 2;
+    reason: 'needs-first-reading';
+    pullRequested: true;
+} | {
+    id: string;
+    stage: 1;
+    gate: 3;
+    reason: 'unknown-window';
+    window: WindowRef;
+    pullRequested: true;
+} | {
+    id: string;
+    stage: 1;
+    gate: 4;
+    reason: 'unknown-reset';
+    window: WindowRef;
+    pullRequested: true;
+} | {
+    id: string;
+    stage: 1;
+    gate: 5;
+    reason: 'exhausted';
+    window: WindowRef;
+    resetsAt: string;
+    resetAtMs: number;
+} | {
+    id: string;
+    stage: 2;
+    reason: 'budget-spent';
+    resetsAt: string;
+    resetAtMs: number;
+};
+export interface AdmissionExclusion {
+    id: string;
+    reason: 'rate-limited' | 'refresh-backoff';
+    until: number;
+}
+export interface AdmittedRow {
+    id: string;
+    kind: RowKind;
+    /** The projection admission judged; absent for API-key rows. */
+    projection?: ProjectedQuota;
+    /** Set when a spent budget was kept because no other path survived. */
+    lastPath?: true;
+}
+export interface AdmissionResult {
+    /** In input order. */
+    admitted: AdmittedRow[];
+    refused: AdmissionRefusal[];
+    excluded: AdmissionExclusion[];
+    /** Ids a pull was requested for, in input order. */
+    pulls: string[];
+}
+/** The exclusion that applies to `id` at `now`, if any. */
+export declare function exclusionFor(id: string, inputs: ExclusionInputs, now: number): AdmissionExclusion | undefined;
+/** Runs both admission stages over `input.rows`. */
+export declare function admit(input: AdmissionInput): AdmissionResult;

package/dist/internal-types/routing/index.d.ts

@@ -0,0 +1,8 @@
+export type { AdmissionExclusion, AdmissionInput, AdmissionRefusal, AdmissionResult, AdmittedRow, ExclusionInputs, RoutingRow, RowKind, WindowRef, } from './admission.js';
+export { admit, exclusionFor } from './admission.js';
+export type { OrderedAttempt, OrderedPlacement, OrderedRoute, OrderedRouteInput, ResolvedRoutingMode, RoutingMode, } from './ordered.js';
+export { DEFAULT_FORMER_MAIN_ID, nextOrderedAttempt, orderForPlacement, resolveRoutingMode, routeOrdered, } from './ordered.js';
+export type { StickyPin } from './pins.js';
+export { isPinValid, pendingBytesForPins } from './pins.js';
+export type { PinAction, StickyBreakDecision, StickyRoute, StickyRouteInput, StickySelection, StickySelectionCandidate, StickySelectionInput, StickyStatusClass, StickyStatusClassifier, } from './sticky.js';
+export { decideStickyBreak, defaultStickyStatusClass, MIN_RESET_HOURS, MIN_WEIGHT, QUOTA_STALENESS_MS, routeSticky, selectStickyCandidate, snapshotCheckedAt, sustainableWindowWeight, } from './sticky.js';

package/dist/internal-types/routing/ordered.d.ts

@@ -0,0 +1,47 @@
+import { type AdmissionInput, type AdmissionResult } from './admission.js';
+export type RoutingMode = 'ordered' | 'sticky-balanced';
+/** Where `ordered` routing places the former main row. */
+export type OrderedPlacement = 'roster' | 'main-first' | 'fallback-first';
+export interface ResolvedRoutingMode {
+    mode: RoutingMode;
+    placement: OrderedPlacement;
+}
+/** The former main row's id when the caller supplies none. */
+export declare const DEFAULT_FORMER_MAIN_ID = "main";
+/**
+ * Resolves a persisted `routing.mode` value. `main-first` and
+ * `fallback-first` are aliases of `ordered` that move the former main row;
+ * an absent or unrecognised value is `ordered` in roster order. The
+ * persisted value is only read here, never rewritten.
+ */
+export declare function resolveRoutingMode(value: unknown): ResolvedRoutingMode;
+/**
+ * Orders `ids` (in roster order) for a placement: `main-first` moves the row
+ * named `formerMainId` to the front, `fallback-first` to the back, and
+ * `roster` (or a missing former main row) keeps roster order.
+ */
+export declare function orderForPlacement(ids: readonly string[], placement: OrderedPlacement, formerMainId?: string): string[];
+export interface OrderedRouteInput extends AdmissionInput {
+    placement?: OrderedPlacement;
+    formerMainId?: string;
+    /** Killswitch verdict per row; `false` drops the row, a missing row passes. */
+    killswitch?: ReadonlyMap<string, boolean>;
+}
+export interface OrderedRoute {
+    /** Admitted, non-killed row ids in the order they are to be tried. */
+    order: string[];
+    admission: AdmissionResult;
+}
+export declare function routeOrdered(input: OrderedRouteInput): OrderedRoute;
+export interface OrderedAttempt {
+    id: string;
+    /** The response status; undefined when no response arrived. */
+    status?: number;
+}
+/**
+ * The next row to try, given the attempts so far: the first row when none
+ * has been tried, the next untried row when the last attempt's status is one
+ * of `retryStatuses`, and undefined otherwise (the last response stands) or
+ * when every row has been tried.
+ */
+export declare function nextOrderedAttempt(order: readonly string[], attempts: readonly OrderedAttempt[], retryStatuses: readonly number[]): string | undefined;

package/dist/internal-types/routing/pins.d.ts

@@ -0,0 +1,22 @@
+export interface StickyPin {
+    accountId: string;
+    /** The row's recorded wire identity when the pin was made, if known. */
+    wireIdentity?: string;
+    /** The request size recorded with the pin; weighs pending bytes. */
+    inputBytes?: number;
+    /** The projection time the placement was judged on. */
+    quotaCheckedAt?: number;
+}
+/**
+ * A pin survives while its row id is in `validIds` and the row still holds
+ * the account it was placed on. Only two known, differing identities prove
+ * the account changed: an unknown identity on either side keeps the pin,
+ * because re-placing a session on missing evidence throws its cache away.
+ */
+export declare function isPinValid(pin: StickyPin, validIds: ReadonlySet<string>, currentIdentity: string | undefined): boolean;
+/**
+ * Sums the request bytes of every other session's pin per row, as openai-auth
+ * does. A pin counts only while it was judged on the row's current
+ * projection time, so a fresh reading resets the row's pending load.
+ */
+export declare function pendingBytesForPins(pins: Iterable<readonly [sessionKey: string, pin: StickyPin]>, quotaCheckedAtById: ReadonlyMap<string, number | undefined>, excludedSessionKey?: string): Map<string, number>;

package/dist/internal-types/routing/sticky.d.ts

@@ -0,0 +1,158 @@
+import { type ProjectedQuota } from '../quota/projection.js';
+import { type AdmissionInput, type AdmissionRefusal, type AdmissionResult, type RoutingRow, type WindowRef } from './admission.js';
+import { type StickyPin } from './pins.js';
+export declare const QUOTA_STALENESS_MS: number;
+export declare const MIN_RESET_HOURS: number;
+export declare const MIN_WEIGHT = 0.000001;
+/** The projection's time, else the caller's cache-entry time. */
+export declare function snapshotCheckedAt(quota: ProjectedQuota | null | undefined, entryCheckedAt?: number): number | undefined;
+export type StickyBreakDecision = {
+    action: 'retain';
+    reason: 'unknown' | 'stale' | 'healthy' | 'transient';
+} | {
+    action: 'migrate';
+    reason: 'exhausted' | 'permanent' | 'killswitch';
+    /** The exhausted limit, named by its (scope, label), not its position. */
+    window?: WindowRef;
+    resetsAt?: string;
+};
+/**
+ * How the adapter reads a failed response's HTTP status for the break
+ * decision. `permanent` moves the session off its row before any quota is
+ * consulted; `transient` and `healthy` keep it unless the quota says the row
+ * is spent. A missing status means the request failed without a response.
+ */
+export type StickyStatusClass = 'permanent' | 'transient' | 'healthy';
+export type StickyStatusClassifier = (status: number | undefined) => StickyStatusClass;
+/**
+ * The status rule used when the adapter supplies none, carried from
+ * openai-auth: 401 and 403 are permanent; no response, 0, a non-finite
+ * status, 429 and 5xx are transient; anything else leaves the row healthy.
+ * A provider whose 403 can mean an organisation or model policy rather than
+ * a dead account supplies its own classifier and can fall back to this one
+ * for the statuses it does not single out.
+ */
+export declare function defaultStickyStatusClass(status: number | undefined): StickyStatusClass;
+/** Classifies whether a pinned session should leave its row after a failure. */
+export declare function decideStickyBreak(input: {
+    quota: ProjectedQuota | null | undefined;
+    quotaCheckedAt?: number;
+    status?: number;
+    now: number;
+    killswitchPasses?: boolean;
+    /** Defaults to `defaultStickyStatusClass`. */
+    classifyStatus?: StickyStatusClassifier;
+}): StickyBreakDecision;
+export declare function sustainableWindowWeight(window: {
+    remainingPercent: number;
+    resetsAt?: string;
+}, reservePercent: number, now: number): number;
+export interface StickySelectionCandidate {
+    accountId: string;
+    quota: ProjectedQuota | null | undefined;
+    quotaCheckedAt?: number;
+    /** Reserve percent per window label; a missing label reserves nothing. */
+    reservePercent: Readonly<Record<string, number>>;
+    configuredOrder: number;
+    resetCreditsApplicable?: number;
+    /** `false` excludes the candidate from weighted and fallback placement. */
+    killswitchPasses?: boolean;
+}
+export interface StickySelectionInput {
+    candidates: readonly StickySelectionCandidate[];
+    pendingBytes: ReadonlyMap<string, number>;
+    requestBytes: number;
+    now: number;
+    onEmptyWeightedSet?: () => void;
+}
+export interface StickySelection {
+    accountId: string;
+    quotaCheckedAt?: number;
+    source: 'weighted' | 'mode-fallback';
+}
+/**
+ * Places a session: the lowest projected pressure among candidates with a
+ * fresh positive weight, else (`mode-fallback`) the first candidate in
+ * configured order, preferring one with an applicable reset credit.
+ */
+export declare function selectStickyCandidate(input: StickySelectionInput): StickySelection | undefined;
+/** Reserve percent per window label; a missing label reserves nothing. */
+export type ReservePercent = Readonly<Record<string, number>>;
+/**
+ * Reserve percentages per row: a map keyed by row id, or a function of the
+ * row. A row the map lacks, or for which the function returns undefined,
+ * takes the shared `reservePercent`.
+ */
+export type RowReservePercent = ReadonlyMap<string, ReservePercent> | ((row: RoutingRow) => ReservePercent | undefined);
+/**
+ * What a valid pin does when its row is not dispatched.
+ *
+ * `keep`: the pin is retained whatever kept its row from this request.
+ *
+ * `move-on-confirmed-exhaustion`: the pin moves to the row this request is
+ * dispatched to when its own row was refused as confirmed exhausted (a spent
+ * window with a future reset, or a spent credit budget) or killed by the
+ * killswitch. A refusal for unknown quota (no reading yet, a missing window,
+ * an exhausted reading without a usable reset) and an exclusion (rate-limit
+ * mark, refresh backoff) keep the pin while this request is served elsewhere.
+ * With no admissible row the pin is retained either way.
+ */
+export type RefusedPinPolicy = 'keep' | 'move-on-confirmed-exhaustion';
+export interface StickyRouteInput extends AdmissionInput {
+    requestBytes: number;
+    /** Bytes already committed per row, for example from other sessions' pins. */
+    pendingBytes?: ReadonlyMap<string, number>;
+    /** Killswitch verdict per row; a missing row passes. */
+    killswitch?: ReadonlyMap<string, boolean>;
+    /** Reserve percent per window label, for every row without its own. */
+    reservePercent?: ReservePercent;
+    /** Per-row reserves, which replace `reservePercent` for the rows they cover. */
+    rowReservePercent?: RowReservePercent;
+    /** Defaults to `keep`. */
+    refusedPinPolicy?: RefusedPinPolicy;
+    resetCreditsApplicable?: ReadonlyMap<string, number>;
+    /** The session's current pin, if it has one. */
+    pin?: StickyPin;
+    /** Each row's recorded wire identity; missing means unknown. */
+    identities?: ReadonlyMap<string, string | undefined>;
+    onEmptyWeightedSet?: () => void;
+}
+/**
+ * What the caller does with the session's pin: keep it, replace it with
+ * `pin`, or drop it. Under the default `keep` policy a valid pin is always
+ * kept, even when this request was routed elsewhere because its row was
+ * refused, excluded or killed; `refusedPinPolicy` can move it instead.
+ */
+export type PinAction = {
+    action: 'retain';
+} | {
+    action: 'assign';
+    pin: StickyPin;
+} | {
+    action: 'clear';
+} | {
+    action: 'none';
+};
+export type StickyRoute = {
+    outcome: 'dispatch';
+    accountId: string;
+    source: 'pin' | 'weighted' | 'mode-fallback';
+    quotaCheckedAt?: number;
+    pin: PinAction;
+    /** Rows that selection chose and admission then refused, in selection order. */
+    refusedSelections: AdmissionRefusal[];
+    admission: AdmissionResult;
+} | {
+    outcome: 'no-admissible-account';
+    pin: PinAction;
+    refusedSelections: AdmissionRefusal[];
+    admission: AdmissionResult;
+};
+/**
+ * Routes one request in `sticky-balanced` mode. A valid pin whose row is
+ * admitted, not excluded and not killed is dispatched as is. Otherwise
+ * selection runs over the non-excluded rows; each selected row admission
+ * refused is removed and selection re-runs, so the loop ends either on an
+ * admitted row or with no admissible account.
+ */
+export declare function routeSticky(input: StickyRouteInput): StickyRoute;