cartethyia 2.7.8 → 2.8.0

package/src/transport/routing/router.ts

@@ -25,17 +25,26 @@ import {
   type RequiredCapability,
 } from "../../protocol/translation/capabilities";
 import { planAllowsCandidate } from "./plan-gate";
+import { accountReservePct, routingStickyWarmMs, routingStickyMaxSessions } from "../../config/routing";
+import type { NormalizedQuotaFact } from "./route-model";
 import { InMemoryAdmissionController, admissionKey } from "./admission";
 import { ReservationManager } from "./reservations";
-import { createRoundRobinMap, RoundRobinState } from "./round-robin";
+import { createRoundRobinMap, RoundRobinState, StickySessionStore } from "./round-robin";
+import { drainScore, isInReserve } from "./drain-reserve";
 import {
   lookupRouteCandidates,
   parseModelReference,
   routeCandidateIndex,
 } from "./candidate-index";
-import { totalRemainingCredit, type ProviderQuotaWindow } from "../../providers/quota/quota-contracts";
-import { getCachedQuotaEntry, quotaLens } from "../../providers/quota/cache";
-import { readQuotaSnapshot } from "../../providers/quota/snapshot";
+import {
+  totalRemainingCredit,
+  totalRemainingPercent,
+  type ProviderQuotaResult,
+  type ProviderQuotaWindow,
+} from "../../providers/quota/quota-contracts";
+import { getCachedQuotaEntries, quotaLens, type CachedQuotaEntry } from "../../providers/quota/cache";
+import { readQuotaSnapshots } from "../../providers/quota/snapshot";
+import type { ProviderQuotaResultSnapshot } from "../../persistence/schema";
 import type { CartethyiaDatabase } from "../../persistence/db-handle";
 import type { RedisClient } from "../../persistence/redis";
 import { sharedClaudeSlowLanes } from "../../providers/integrations/claude/claude-slow-lane";
@@ -88,6 +97,179 @@ export function filterCandidateQuotaWindows(
   return windows;
 }
 
+/**
+ * Global freshness horizon for persisted quota/plan evidence. A plan or
+ * snapshot older than this is downgraded to `unknown` by routing instead of
+ * being trusted indefinitely. First cut uses one global value (not
+ * provider-specific); see proposal locked decision #4.
+ */
+export const QUOTA_FRESHNESS_HORIZON_MS = 6 * 60 * 60 * 1000;
+
+/** The account's total remaining absolute credit, or `null` when unknown. */
+function accountRemainingCredit(candidate: RoutedCandidate): number | null {
+  const windows = candidate.quota_windows;
+  if (windows === undefined || windows.length === 0) return null;
+  return totalRemainingCredit(windows);
+}
+
+/**
+ * Evaluates whether the candidate sits below its configured usage floor.
+ * Mirrors the legacy ordering heuristic (credit vs lowest independent percent),
+ * but returns a tri-state used for proactive exclusion under the unified
+ * routing engine.
+ */
+function usageFloorStateFor(candidate: RoutedCandidate): "above" | "below" | "unknown" {
+  const floor = candidate.usage_floor;
+  if (floor === null || floor === undefined || floor <= 0) return "unknown";
+  if (candidate.free_tier === true) return "above";
+  const windows = candidate.quota_windows;
+  if (windows === undefined || windows.length === 0) return "unknown";
+  if (candidate.usage_floor_unit === "credit") {
+    const credit = accountRemainingCredit(candidate);
+    if (credit === null) return "unknown";
+    return credit >= floor ? "above" : "below";
+  }
+  const percent = totalRemainingPercent(windows);
+  if (percent === null) return "unknown";
+  return percent >= floor ? "above" : "below";
+}
+
+/** Earliest stated reset across exhausted windows, when any carries one. */
+function exhaustedResetMs(windows: readonly ProviderQuotaWindow[] | undefined): number | undefined {
+  if (windows === undefined) return undefined;
+  let earliest: number | undefined;
+  for (const window of windows) {
+    if (window.resetsAt === null || window.resetsAt === undefined) continue;
+    const at = Date.parse(window.resetsAt);
+    if (!Number.isFinite(at)) continue;
+    if (earliest === undefined || at < earliest) earliest = at;
+  }
+  return earliest;
+}
+
+/** True when every relevant quota window for the candidate is known-spent. */
+function allWindowsExhausted(windows: readonly ProviderQuotaWindow[]): boolean {
+  if (windows.length === 0) return false;
+  for (const window of windows) {
+    if (window.accounting === "pooled") {
+      const remaining = window.remaining;
+      if (remaining !== null && remaining !== undefined && remaining > 0) return false;
+      const limit = window.limit;
+      if (limit !== null && limit !== undefined) {
+        const used = window.used;
+        if (used !== null && used !== undefined && used < limit) return false;
+        if (used === null && window.remainingPercent !== null && window.remainingPercent > 0) {
+          return false;
+        }
+      } else if (window.remainingPercent !== null && window.remainingPercent > 0) {
+        return false;
+      } else if (remaining === null && window.used === null) {
+        // No evidence of either remaining or used — not provably spent.
+        return false;
+      } else if (remaining !== null && limit === null) {
+        // Remaining=0 but no limit: cannot prove the pool is exhausted without
+        // knowing the total. This is the "credit window without a known ceiling"
+        // shape — treat as unknown, not exhausted.
+        return false;
+      }
+    } else {
+      const remainingPercent = window.remainingPercent;
+      if (remainingPercent !== null && remainingPercent > 0) return false;
+      if (remainingPercent === null) {
+        // Unknown independent window: cannot prove exhaustion.
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+/**
+ * Derives the normalized quota fact the routing decision engine evaluates.
+ */
+function normalizeQuotaFact(
+  candidate: RoutedCandidate,
+  cacheEntry: { readonly fetchedAt: string | null; readonly quota: ProviderQuotaResult } | null | undefined,
+  snapshotEntry: { readonly fetchedAt: string; readonly quota: ProviderQuotaResult } | null | undefined,
+  now = Date.now(),
+): NormalizedQuotaFact {
+  const windows = candidate.quota_windows;
+  const source =
+    cacheEntry?.quota !== undefined
+      ? cacheEntry.quota.error === null
+        ? ("live_cache" as const)
+        : ("unsupported" as const)
+      : snapshotEntry?.quota !== undefined
+        ? snapshotEntry.quota.error === null
+          ? ("snapshot" as const)
+          : ("unsupported" as const)
+        : ("none" as const);
+
+  // Freshness: only live-cache and snapshot evidence carries an observed-at.
+  const observedSrc =
+    cacheEntry?.quota !== undefined && cacheEntry.quota.error === null
+      ? cacheEntry
+      : snapshotEntry?.quota !== undefined && snapshotEntry.quota.error === null
+        ? snapshotEntry
+        : null;
+  const rawObservedAt = observedSrc?.fetchedAt;
+  const observedAt =
+    rawObservedAt === null || rawObservedAt === undefined ? Number.NaN : Date.parse(rawObservedAt);
+  const hasObservedAt = Number.isFinite(observedAt) && observedAt > 0;
+  // Stale is only meaningful when we have an observation timestamp to judge.
+  // Without one (candidate-stamped windows, no cache/snapshot metadata) there
+  // is nothing to mark stale, so the windows remain usable evidence.
+  const isStale = hasObservedAt && now - observedAt > QUOTA_FRESHNESS_HORIZON_MS;
+
+  const usageFloorState = usageFloorStateFor(candidate);
+  // Stale evidence is downgraded to unknown — the freshness horizon (locked
+  // decision #4) means routing must not trust a weeks-old balance for either
+  // exhaustion or floor decisions.
+  if (isStale) {
+    return {
+      quotaState: "unknown",
+      quotaSource: source,
+      quotaObservedAt: hasObservedAt ? observedAt : null,
+      isStale: true,
+      usageFloorState: "unknown",
+    };
+  }
+  if (windows === undefined || windows.length === 0) {
+    return {
+      quotaState: "unknown",
+      quotaSource: source,
+      quotaObservedAt: hasObservedAt ? observedAt : null,
+      isStale: false,
+      usageFloorState,
+    };
+  }
+  if (usageFloorState === "below") {
+    return {
+      quotaState: "exhausted",
+      quotaSource: source,
+      quotaObservedAt: hasObservedAt ? observedAt : null,
+      isStale,
+      usageFloorState,
+    };
+  }
+  if (allWindowsExhausted(windows)) {
+    return {
+      quotaState: "exhausted",
+      quotaSource: source,
+      quotaObservedAt: hasObservedAt ? observedAt : null,
+      isStale,
+      usageFloorState,
+    };
+  }
+  return {
+    quotaState: "available",
+    quotaSource: source,
+    quotaObservedAt: hasObservedAt ? observedAt : null,
+    isStale,
+    usageFloorState,
+  };
+}
+
 /**
  * Routing priority for an account's remaining allowance when two candidates sit
  * in the same rank group: positive remaining credit first, then unknown, then
@@ -103,6 +285,23 @@ function creditPriority(candidate: RoutedCandidate): number {
   return credit > 0 ? 1 : -1;
 }
 
+/**
+ * Hot-window guard: true when the account's most-urgent window is ≥85% used.
+ * A nearly exhausted short window means an imminent mid-session block, so these
+ * candidates rank behind cooler siblings no matter their drain score — overflow
+ * lands on the next-most-urgent cool account instead.
+ */
+function hotWindow(windows: readonly ProviderQuotaWindow[] | undefined): boolean {
+  if (windows === undefined || windows.length === 0) return false;
+  for (const window of windows) {
+    const used = window.usedPercent;
+    if (typeof used === "number" && Number.isFinite(used) && used >= 85) return true;
+    const remaining = window.remainingPercent;
+    if (typeof remaining === "number" && Number.isFinite(remaining) && remaining <= 15) return true;
+  }
+  return false;
+}
+
 /**
  * Normalizes a requested model name before alias lookup. Coding-agent CLIs
  * version their model ids with variant suffixes (`claude-opus-5[1m]`,
@@ -299,13 +498,6 @@ export class EligibilityEvaluator {
       return { eligible: true, reason: "cooldown", candidate, ...spreadDeadline(candidate.cooldown_until) };
     return { eligible: true, reason: "healthy", candidate };
   }
-
-  filter(candidates: readonly RouteCandidate[]): readonly RouteCandidate[] {
-    return candidates
-      .map((c) => this.evaluate(c))
-      .filter((d) => d.eligible)
-      .map((d) => d.candidate);
-  }
 }
 
 export class RoutingEngine {
@@ -313,6 +505,7 @@ export class RoutingEngine {
   private readonly _roundRobinByProvider = createRoundRobinMap();
   private readonly eligibility = new EligibilityEvaluator();
   private readonly reservations = new ReservationManager();
+  private readonly sticky = new StickySessionStore(routingStickyMaxSessions());
 
   constructor(
     private readonly admission: AdmissionController = new InMemoryAdmissionController(),
@@ -440,6 +633,8 @@ export class RoutingEngine {
     candidate: RouteCandidate,
     snapshot: RouteSnapshot,
     tenantId: string | null,
+    quotaCache: ReadonlyMap<string, CachedQuotaEntry>,
+    snapshotMap: ReadonlyMap<string, ProviderQuotaResultSnapshot>,
   ): Promise<RouteCandidate> {
     const accountId = candidate.provider_account_id;
     if (accountId === undefined) return candidate;
@@ -448,11 +643,7 @@ export class RoutingEngine {
       candidate.provider_id,
       candidate.tenant_id ?? tenantId,
     );
-    const cached = await getCachedQuotaEntry(
-      quotaLens(candidate.tenant_id ?? tenantId),
-      accountId,
-      this.redis,
-    ).catch(() => undefined);
+    const cached = quotaCache.get(accountId);
     // The live cache is authoritative when warm; when it is cold (e.g. right
     // after a restart, before the sweep re-reads accounts), fall back to the
     // persisted quota snapshot — the durable source of truth — so routing
@@ -460,9 +651,13 @@ export class RoutingEngine {
     // is never fresher than the cache, but a stale balance beats an unknown
     // one for ordering, and the sweep refreshes it on schedule.
     let quota = cached?.quota;
-    if (quota === undefined && this.db !== undefined) {
-      const stored = await readQuotaSnapshot(this.db, accountId).catch(() => null);
-      quota = stored?.quota;
+    let stored: { readonly fetchedAt: string; readonly quota: ProviderQuotaResult } | null = null;
+    if (quota === undefined) {
+      const snap = snapshotMap.get(accountId);
+      if (snap !== undefined) {
+        stored = { fetchedAt: snap.fetchedAt, quota: snap.quota };
+        quota = snap.quota;
+      }
     }
     const rawWindows = quota?.windows;
     // The cache is authoritative when it has a reading; when it does not,
@@ -472,14 +667,32 @@ export class RoutingEngine {
       rawWindows === undefined
         ? undefined
         : candidate.provider_id === "zcode-start" ? rawWindows : filterCandidateQuotaWindows(rawWindows, candidate);
-    return {
+    const stamped: RoutedCandidate = {
       ...candidate,
       ...(setting?.usageFloor == null
         ? {}
         : { usage_floor: setting.usageFloor, usage_floor_unit: setting.usageFloorUnit }),
-      ...(quotaWindows === undefined ? {} : { quota_windows: quotaWindows }),
+      // When no cache/snapshot evidence exists, keep the candidate's own
+      // stamped windows (unit tests and in-memory fixture route this way).
+      ...(quotaWindows === undefined
+        ? candidate.quota_windows === undefined
+          ? {}
+          : { quota_windows: candidate.quota_windows }
+        : { quota_windows: quotaWindows }),
       ...(quota?.source === "zcode-start" && quota.error === null ? { quota_entitlements_known: true } : {}),
+      // Drain urgency and reserve are derived from the same windows the credit
+      // ordering already reads. They are ordering preferences, never
+      // exclusions: an account in reserve or with a zero drain score stays
+      // eligible and routed.
+      ...(quotaWindows === undefined && candidate.quota_windows === undefined
+        ? {}
+        : { drain_score: drainScore(quotaWindows ?? candidate.quota_windows) }),
+      ...(quotaWindows === undefined && candidate.quota_windows === undefined
+        ? {}
+        : { in_reserve: isInReserve(quotaWindows ?? candidate.quota_windows, accountReservePct()) }),
     };
+    const fact = normalizeQuotaFact(stamped, cached, stored);
+    return { ...stamped, quota_fact: fact };
   }
 
   /**
@@ -526,6 +739,24 @@ export class RoutingEngine {
         },
       };
     }
+    // Unified decision engine: normalized quota/plan fact.
+    const fact = candidate.quota_fact;
+    if (fact !== undefined) {
+      if (fact.quotaState === "exhausted" || fact.usageFloorState === "below") {
+        const reset = exhaustedResetMs(candidate.quota_windows);
+        return {
+          candidate,
+          decision: {
+            eligible: false,
+            rank: ROUTING_RANK.SATURATED,
+            reason: "quota_exhausted",
+            floor_blocked: fact.usageFloorState === "below",
+            saturated: false,
+            ...(reset === undefined ? {} : { cooldown_until: reset }),
+          },
+        };
+      }
+    }
     // Plan gate (free plan).
     if (!planAllowsCandidate(candidate)) {
       return {
@@ -552,11 +783,54 @@ export class RoutingEngine {
         };
       }
     }
+    // A soft cooldown is a deprioritization, not an exclusion: the evaluator
+    // returned it eligible (so a single-account deployment still routes), but
+    // it must still behind every fresh/slow sibling. Without this branch the
+    // candidate falls through to the quota classification below, which labels
+    // it FRESH_KNOWN/FRESH_UNKNOWN and lets it sort ahead of healthy accounts —
+    // the "still hit a cooled-down account, never failed over" report. The raw
+    // `reason` stays `"cooldown"` so `ELIGIBILITY_REASON_LABELS` and the
+    // envelope `reasons` stream are untouched, and the reset deadline rides
+    // along for the all-cooling 429 answer.
+    if (eligibility.reason === "cooldown") {
+      return {
+        candidate,
+        decision: {
+          eligible: true,
+          rank: ROUTING_RANK.COOLING,
+          reason: "cooldown",
+          ...(eligibility.cooldown_until !== undefined
+            ? { cooldown_until: eligibility.cooldown_until }
+            : {}),
+        },
+      };
+    }
+    // Unified engine: unknown quota is eligible but lower-rank than known-available.
+    if (fact !== undefined) {
+      if (fact.quotaState === "unknown") {
+        return {
+          candidate,
+          decision: {
+            eligible: true,
+            rank: ROUTING_RANK.FRESH_UNKNOWN,
+            reason: "quota_unknown",
+          },
+        };
+      }
+      return {
+        candidate,
+        decision: {
+          eligible: true,
+          rank: ROUTING_RANK.FRESH_KNOWN,
+          reason: "healthy",
+        },
+      };
+    }
     return {
       candidate,
       decision: {
         eligible: true,
-        rank: ROUTING_RANK.FRESH,
+        rank: ROUTING_RANK.FRESH_KNOWN,
         reason: "healthy",
       },
     };
@@ -578,11 +852,11 @@ export class RoutingEngine {
     let i = 0;
     while (i < eligible.length) {
       const cur = eligible[i]!;
-      const rank = decisions.get(admissionKey(cur))?.rank ?? ROUTING_RANK.FRESH;
+      const rank = decisions.get(admissionKey(cur))?.rank ?? ROUTING_RANK.FRESH_KNOWN;
       let j = i + 1;
       while (j < eligible.length) {
         const next = eligible[j]!;
-        const nextRank = decisions.get(admissionKey(next))?.rank ?? ROUTING_RANK.FRESH;
+        const nextRank = decisions.get(admissionKey(next))?.rank ?? ROUTING_RANK.FRESH_KNOWN;
         if (
           next.provider_id !== cur.provider_id ||
           next.model_id !== cur.model_id ||
@@ -674,7 +948,7 @@ export class RoutingEngine {
       const decision = pinnedDecisions.find((d) => d.candidate === candidate);
       decisions.set(admissionKey(candidate), {
         eligible: true,
-        rank: ROUTING_RANK.FRESH,
+        rank: ROUTING_RANK.FRESH_KNOWN,
         reason: "healthy",
         ...(decision?.cooldown_until !== undefined
           ? { cooldown_until: decision.cooldown_until }
@@ -699,6 +973,7 @@ export class RoutingEngine {
     allowCliMappings = false,
     keyId?: string,
     continuationAffinity?: RouteContinuationAffinity,
+    sessionId?: string,
   ): Promise<RoutePlan> {
     const tid = tenantId ?? null;
     const { resolved, matching, unmatchedMembers } = this.resolveMatchingCandidates(
@@ -751,9 +1026,49 @@ export class RoutingEngine {
     // single per-candidate decision. `plan()` then sorts once by rank and
     // hands the full `decisions` map downstream, so no later layer re-derives
     // a competing ordering.
+    //
+    // Quota evidence is read in batch before the per-candidate pass: one
+    // in-memory/Redis `MGET` per lens and one DB query for the accounts the
+    // cache did not answer, instead of a serial round trip per candidate. The
+    // per-candidate stamping below then consumes the shared maps, keeping the
+    // live-cache-authoritative / snapshot-fallback semantics identical.
+    const quotaCacheByAccount = new Map<string, CachedQuotaEntry>();
+    const lensToAccounts = new Map<string, string[]>();
+    for (const candidate of matching) {
+      const accountId = candidate.provider_account_id;
+      if (accountId === undefined) continue;
+      const lens = quotaLens(candidate.tenant_id ?? tid);
+      const accounts = lensToAccounts.get(lens);
+      if (accounts === undefined) lensToAccounts.set(lens, [accountId]);
+      else accounts.push(accountId);
+    }
+    for (const [lens, accountIds] of lensToAccounts) {
+      const entries = await getCachedQuotaEntries(lens, accountIds, this.redis).catch(
+        () => new Map<string, CachedQuotaEntry>(),
+      );
+      for (const [accountId, entry] of entries) quotaCacheByAccount.set(accountId, entry);
+    }
+    const snapshotByAccount = new Map<string, ProviderQuotaResultSnapshot>();
+    if (this.db !== undefined) {
+      const needingSnapshot = matching
+        .map((candidate) => candidate.provider_account_id)
+        .filter((accountId): accountId is string => accountId !== undefined && !quotaCacheByAccount.has(accountId));
+      if (needingSnapshot.length > 0) {
+        const snaps = await readQuotaSnapshots(this.db, needingSnapshot).catch(
+          () => new Map<string, ProviderQuotaResultSnapshot>(),
+        );
+        for (const [accountId, snap] of snaps) snapshotByAccount.set(accountId, snap);
+      }
+    }
     const evaluations = await Promise.all(
       matching.map(async (candidate) => {
-        const stamped = await this.applyUsageFloorToCandidate(candidate, snapshot, tid);
+        const stamped = await this.applyUsageFloorToCandidate(
+          candidate,
+          snapshot,
+          tid,
+          quotaCacheByAccount,
+          snapshotByAccount,
+        );
         return this.evaluateCandidate(stamped, snapshot, tid, requiredCapabilities);
       }),
     );
@@ -810,7 +1125,9 @@ export class RoutingEngine {
 
     // Every eligible candidate cooling and no healthy/slow sibling → 429.
     const healthyCount = [...decisions.values()].filter(
-      (d) => d.eligible && (d.reason === "healthy" || d.reason === "slow"),
+      (d) =>
+        d.eligible &&
+        (d.reason === "healthy" || d.reason === "slow" || d.reason === "quota_unknown"),
     ).length;
     if (healthyCount === 0) {
       throw accountsRateLimitedError(
@@ -821,13 +1138,50 @@ export class RoutingEngine {
     }
 
     // Single sort by rank (fresh → slow → cooling → saturated), stable. Within
-    // the same rank, accounts with remaining credit come first unless the model
-    // is free tier, which routes to any account.
+    // the same rank, ordered by credit → reserve → hot-window guard → measured
+    // usage → drain → round-robin. The drain score chases quota about to expire
+    // unused; reserve yields to non-reserve siblings; a hot primary window (≥85%
+    // used) defers to cooler accounts so overflow lands on a cool sibling.
+    const reservePct = accountReservePct();
+    const stickyWarmMs = routingStickyWarmMs();
+    const stickyEntry = stickyWarmMs > 0 ? this.sticky.get(eligible[0]?.provider_id ?? "", sessionId) : undefined;
+    const stickyAccountId = stickyEntry?.accountId;
+    const stickyWarm = stickyEntry !== undefined && Date.now() - stickyEntry.lastUsedAtMs < stickyWarmMs;
     eligible = [...eligible].sort((left, right) => {
-      const leftRank = decisions.get(admissionKey(left))?.rank ?? ROUTING_RANK.FRESH;
-      const rightRank = decisions.get(admissionKey(right))?.rank ?? ROUTING_RANK.FRESH;
+      const leftRank = decisions.get(admissionKey(left))?.rank ?? ROUTING_RANK.FRESH_KNOWN;
+      const rightRank = decisions.get(admissionKey(right))?.rank ?? ROUTING_RANK.FRESH_KNOWN;
       if (leftRank !== rightRank) return leftRank - rightRank;
-      return creditPriority(right) - creditPriority(left);
+      // A free-tier model routes to any account: skip every quota-derived
+      // preference (credit, reserve, hot-window, drain) so the original order
+      // is preserved. Sticky warm pins still apply — they are about prompt
+      // cache warmth, not quota.
+      const bothFree = left.free_tier === true && right.free_tier === true;
+      // Sticky warm pin: within the warm window the account that last served
+      // this session wins outright (explicit pins always win).
+      const leftSticky = left.provider_account_id === stickyAccountId;
+      const rightSticky = right.provider_account_id === stickyAccountId;
+      if (leftSticky !== rightSticky) {
+        if (stickyEntry?.explicit === true) return leftSticky ? -1 : 1;
+        if (stickyWarm) return leftSticky ? -1 : 1;
+      }
+      if (bothFree) return 0;
+      const leftReserve = (left as RoutedCandidate).in_reserve ??
+        isInReserve(left.quota_windows, reservePct);
+      const rightReserve = (right as RoutedCandidate).in_reserve ??
+        isInReserve(right.quota_windows, reservePct);
+      if (leftReserve !== rightReserve) return leftReserve ? 1 : -1;
+      const leftPriority = (left as RoutedCandidate).account_priority ?? 0;
+      const rightPriority = (right as RoutedCandidate).account_priority ?? 0;
+      if (leftPriority !== rightPriority) return rightPriority - leftPriority;
+      const leftHot = hotWindow(left.quota_windows);
+      const rightHot = hotWindow(right.quota_windows);
+      if (leftHot !== rightHot) return leftHot ? 1 : -1;
+      const credit = creditPriority(right) - creditPriority(left);
+      if (credit !== 0) return credit;
+      const leftDrain = (left as RoutedCandidate).drain_score ?? 0;
+      const rightDrain = (right as RoutedCandidate).drain_score ?? 0;
+      if (leftDrain !== rightDrain) return rightDrain - leftDrain;
+      return 0;
     });
 
     // Provider routing rotates accounts within the same rank group only; it can
@@ -836,6 +1190,13 @@ export class RoutingEngine {
     eligible = this.applyProviderRoutingSorted(eligible, decisions, snapshot, tid);
 
     const chosen = eligible[0]!;
+    // Record which account served this session so a follow-up request within the
+    // warm window can prefer it (prompt-cache warmth). Explicit operator pins are
+    // recorded as explicit so they win even past the warm window.
+    if (sessionId !== undefined && chosen.provider_account_id !== undefined) {
+      const explicitPin = continuationAffinity?.providerAccountId === chosen.provider_account_id;
+      this.sticky.set(chosen.provider_id, sessionId, chosen.provider_account_id, explicitPin);
+    }
     return {
       revision: snapshot.revision,
       candidates: eligible,
@@ -928,7 +1289,31 @@ export class RoutingEngine {
         matching = groups.flat();
       }
     }
-    if (matching.length === 0) throw modelNotFoundError(requestedModel, modelIds);
+    if (matching.length === 0) {
+      // A qualified `provider/model` reference whose model is not in the
+      // catalog still routes: clone the provider's first live candidate (any
+      // model) and retarget it at the requested model. This is the passthrough
+      // contract — a provider that accepts arbitrary model ids (BYOK, custom
+      // gateways, or a model the catalog has not fetched yet) must be able to
+      // serve them. The clone inherits the provider's endpoint, wire family,
+      // dialect, capabilities, tenant scoping and account/network-pool wiring;
+      // only the model id changes. A provider with zero candidates cannot be
+      // synthesized, so bare-model misses and empty providers still 404.
+      if (parsedModels.length === 1 && parsedModels[0]!.parsed.providerId !== null) {
+        const providerId = parsedModels[0]!.parsed.providerId;
+        const sibling = [...index.qualified.entries()]
+          .filter(([key]) => key.startsWith(`${providerId}/`))
+          .flatMap(([, group]) => group)
+          .find((candidate) => candidate.tenant_id == null || candidate.tenant_id === tid);
+        if (sibling !== undefined) {
+          matching = [{
+            ...sibling,
+            model_id: parsedModels[0]!.parsed.modelId,
+          }];
+        }
+      }
+      if (matching.length === 0) throw modelNotFoundError(requestedModel, modelIds);
+    }
     const owners = [...new Set(matching.map((candidate) => candidate.provider_id))];
     if (owners.length > 1 && !resolved.model.includes("/") && !combo)
       throw ambiguousModelError(requestedModel, owners);

package/src/transport/surface/adapters.ts

@@ -113,13 +113,22 @@ function endpointPathSurface(path: string): SourceSurface | undefined {
   return undefined;
 }
 
-export class SurfaceAdapterRegistry {
-  constructor(private readonly adapters: SurfaceAdapter[]) {
+export class SurfaceAdapterRegistry<T extends SurfaceAdapter = SurfaceAdapter> {
+  constructor(private readonly adapters: T[]) {
     if (!adapters || adapters.length === 0) {
       throw new Error("SurfaceAdapterRegistry requires at least one adapter");
     }
   }
 
+  /**
+   * Map of surface → adapter. The keys are the adapters' `surface` values, so
+   * this is the single place pipeline composition derives the adapter lookup
+   * from — never re-spell the adapter list beside the registry.
+   */
+  bySurface(): ReadonlyMap<SourceSurface, T> {
+    return new Map(this.adapters.map((adapter) => [adapter.surface, adapter]));
+  }
+
   /**
    * Evaluates every signal once, then picks a winner by the fixed precedence
    * above. Evaluating all three even when an earlier signal already wins is

package/src/transport/surface/chat/adapter.ts

@@ -2,9 +2,9 @@ import type { CanonicalEvent, CanonicalMessage, CanonicalRequest, ContentPart }
 import type { SurfaceAdapter, SurfaceInput, SurfaceOutput } from "../adapters";
 import { isRecord } from "../../../protocol/codecs";
 import { readString } from "../../../protocol/codecs";
+import { decodeWireBody } from "../content-parts";
 import type { ChatEncodeOptions } from "./parse";
 import {
-  decodeBody,
   parseGenerationControls,
   parseMessage,
   requestBody,
@@ -38,7 +38,7 @@ export class ChatAdapter implements SurfaceAdapter {
    * false "ambiguous body shape" disagreement while routing correctly.
    */
   matchesBodyShape(body: unknown): boolean {
-    const value = decodeBody(body);
+    const value = decodeWireBody(body);
     if (!isRecord(value) || "input" in value || !Array.isArray(value.messages)) return false;
     if (value.messages.length === 0) return false;
     return value.messages.some((message) => isRecord(message) && typeof message.role === "string");