@cortexkit/anthropic-auth-core 2.0.1 → 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/codec.d.ts

@@ -1,5 +1,7 @@
 export interface QuotaCodec {
     readonly validate: (value: unknown) => boolean;
+    /** Normalize persisted data before validation; older codecs may omit this. */
+    readonly decode?: (value: unknown) => unknown;
     readonly merge: (stored: unknown, observation: unknown) => unknown;
 }
 /**

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,9 +1,9 @@
 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 { CreditBudgetCleared, CreditBudgetEntry, CreditBudgetReading, QuotaAbsentEntry, QuotaEntry, QuotaMap, QuotaReadingEntry, QuotaRetiredEntry, } from './map.js';
-export { ALL_SCOPE, DEFAULT_REQUIRED_LABELS, emptyQuotaMap, isQuotaMap, } from './map.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';
 export { isQuotaObservation, mergeQuotaObservation, QuotaCodecError, } from './merge.js';
 export type { ExhaustionReset, ProjectedBudget, ProjectedLimit, ProjectedQuota, } from './projection.js';

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

@@ -44,16 +44,27 @@ export interface CreditBudgetCleared {
     checkedAt: number;
 }
 export type CreditBudgetEntry = CreditBudgetReading | CreditBudgetCleared;
+export interface QuotaCounter {
+    value: number;
+    checkedAt: number;
+}
 export interface QuotaMap {
     limits: QuotaEntry[];
     /** Absent means no observation has reported on the budget yet. */
     budget?: CreditBudgetEntry;
+    /** Provider-named counts, each with its own observation time. */
+    counters?: Record<string, QuotaCounter>;
 }
 export declare function emptyQuotaMap(): QuotaMap;
 /** The time an entry speaks for: its reading, retirement or absence time. */
 export declare function entryTime(entry: QuotaEntry): number;
 export declare function limitKey(scope: string, label: string): string;
 export declare function isCreditBudgetEntry(value: unknown): value is CreditBudgetEntry;
+export declare function isQuotaCounters(value: unknown): value is Record<string, QuotaCounter>;
+/** Keep usable counters without letting one malformed count hide a quota map. */
+export declare function readQuotaCounters(value: unknown): Record<string, QuotaCounter> | undefined;
+/** Decode persisted quota, dropping malformed counters but not limit evidence. */
+export declare function decodeQuotaMap(value: unknown): QuotaMap | undefined;
 /**
  * True when `value` is a well-formed quota map. Unrecognised top-level keys
  * are tolerated (and preserved by merge) so a newer writer's additions

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

@@ -1,4 +1,4 @@
-import { type QuotaMap } from './map.js';
+import { type QuotaCounter, type QuotaMap } from './map.js';
 export interface ObservedReading {
     /** Defaults to `all`. */
     scope?: string;
@@ -32,6 +32,8 @@ export interface QuotaObservation {
     coverage?: ObservedPair[];
     /** Absent means the observation says nothing about the budget. */
     budget?: ObservedBudget;
+    /** Each named count uses its own time, independently of limits and budget. */
+    counters?: Record<string, QuotaCounter>;
 }
 /** Thrown by `mergeQuotaObservation` when either argument is malformed. */
 export declare class QuotaCodecError extends TypeError {

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

@@ -1,4 +1,4 @@
-import { type QuotaMap } from './map.js';
+import { type QuotaCounter, type QuotaMap } from './map.js';
 export interface ProjectedLimit {
     scope: string;
     label: string;
@@ -30,6 +30,7 @@ export interface ProjectedQuota {
     checkedAt?: number;
     /** Present only when the stored budget is a reading, not cleared. */
     budget?: ProjectedBudget;
+    counters?: Record<string, QuotaCounter>;
 }
 /**
  * Resolves `map` for a request in `scope` (`all` or a model family). A family

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>;