cartethyia 2.7.9 → 2.8.1

package/src/transport/routing/route-catalog.ts

@@ -86,7 +86,6 @@ export function cliMappingSourceKeys(toolId: string, sourceModel: string): reado
 
 const HARD_COOLDOWN_CATEGORIES: Readonly<Record<string, true>> = {
   quota_exhausted: true,
-  policy_blocked: true,
   auth_invalidated: true,
 };
 
@@ -528,7 +527,8 @@ class RouteCatalogRepository {
     }
 
     // Per-tenant pool selection strategy; an absent row reads as the
-    // `least_loaded` default at selection time.
+    // `least_loaded` default at selection time. The local map resolves
+    // per-candidate during the build; it is NOT stored in RouteSnapshot.
     const poolRouting: Record<string, PoolRoutingSetting> = {};
     for (const row of poolSettingRows) {
       if (tenantId === undefined || row.tenantId === tenantId) {
@@ -662,6 +662,72 @@ class RouteCatalogRepository {
       return limit === undefined ? {} : { network_pool_provider_limit: limit };
     }
 
+    /**
+     * The field set shared by every `RoutedCandidate` literal in the fan-out
+     * below. The four sites used to re-declare the same ~15-field shape, so a
+     * field added to one had to be added to all four. `opts` carries only the
+     * deltas that genuinely differ per site; health stamping is deliberately
+     * NOT merged here — it happens at each site (inside the pool-account
+     * literal, never for configured-pool tenants, conditional for public,
+     * after construction for account rows), and collapsing those branches
+     * would change routing.
+     */
+    function buildCandidateBase(
+      model: MergedModelRow,
+      capabilityProfile: Record<string, boolean>,
+      opts: {
+        readonly tenantId: string | null;
+        /** `false` emits `requires_account: false` (credential-less route). */
+        readonly requiresAccount?: boolean;
+        readonly ownerTenantId?: string | null;
+        readonly userAgent?: string;
+        readonly accountId?: string;
+        readonly proOnly?: boolean;
+        readonly accountPlan?: string | null;
+        readonly maxInflight?: number;
+        readonly pools?: {
+          readonly ids: readonly string[];
+          readonly limits: Record<string, number>;
+          readonly weights: Record<string, number>;
+          /** `undefined` (from `resolveNetworkPools`) means no routing strategy. */
+          readonly routing?: (PoolRoutingSetting & { tenantId: string }) | undefined;
+        };
+      },
+    ): RoutedCandidate {
+      return {
+        provider_id: model.providerId,
+        model_id: model.modelId,
+        wire_family: model.wireFamily as WireFamily,
+        ...(model.dialect == null ? {} : { dialect: model.dialect }),
+        service_kind: model.serviceKind,
+        endpoint: model.endpointPath,
+        ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
+        capability_profile: capabilityProfile,
+        ...(opts.userAgent === undefined ? {} : { user_agent: opts.userAgent }),
+        tenant_id: opts.tenantId,
+        ...(model.freeTier === true ? { free_tier: true } : {}),
+        // Public credential-less candidates have no account to own them.
+        owner_tenant_id: opts.ownerTenantId ?? null,
+        ...(opts.accountId === undefined ? {} : { provider_account_id: opts.accountId }),
+        ...(opts.proOnly === true ? { pro_only: true } : {}),
+        ...(opts.accountPlan === null || opts.accountPlan === undefined
+          ? {}
+          : { account_plan: opts.accountPlan }),
+        ...(opts.maxInflight === undefined ? {} : { max_inflight: opts.maxInflight }),
+        ...(opts.requiresAccount === false ? { requires_account: false as const } : {}),
+        ...(opts.pools
+          ? {
+              network_pool_ids: opts.pools.ids,
+              network_pool_required: true,
+              network_pool_limits: opts.pools.limits,
+              network_pool_weights: opts.pools.weights,
+              ...(opts.pools.routing ? { network_pool_routing: opts.pools.routing } : {}),
+              ...providerLimitFor(model.providerId, opts.tenantId),
+            }
+          : {}),
+      };
+    }
+
     // Group usable accounts per provider (not per provider-tenant). Built-in
     // providers are `tenant_id IS NULL` but their accounts are per-tenant, so
     // grouping by `providerTenantId` would make every global model look
@@ -716,38 +782,30 @@ class RouteCatalogRepository {
               const tenantPools = resolveNetworkPools(model.providerId, tenantOwnerId);
               if (!tenantPools) continue;
               emittedPoolAccount = true;
-              const tenantCandidate: RoutedCandidate = {
-                provider_id: model.providerId,
-                model_id: model.modelId,
-                wire_family: model.wireFamily as WireFamily,
-                ...(model.dialect == null ? {} : { dialect: model.dialect }),
-                service_kind: model.serviceKind,
-                endpoint: model.endpointPath,
-                ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
-                capability_profile: capabilityProfile,
-                tenant_id: tenantOwnerId,
-                ...(model.freeTier === true ? { free_tier: true } : {}),
-                // Public credential-less candidates have no account to own them.
-                owner_tenant_id: null,
-                requires_account: false as const,
-                network_pool_ids: [poolId],
-                network_pool_required: true,
-                network_pool_limits: tenantPools.limits,
-                network_pool_weights: tenantPools.weights,
-                ...(tenantPools.routing ? { network_pool_routing: tenantPools.routing } : {}),
-                ...providerLimitFor(model.providerId, tenantOwnerId),
-                ...(first.status === "disabled"
-                  ? { health_status: "disabled" as const }
-                  : first.status === "cooldown"
-                    ? {
-                        health_status: "cooldown" as const,
-                        cooldown_kind: hardCooldownCategory(first.lastErrorCategory) ? "hard" : "soft",
-                        ...(first.cooldownUntil && first.cooldownUntil.getTime() > Date.now()
-                          ? { cooldown_until: first.cooldownUntil.getTime() }
-                          : {}),
-                      }
-                    : {}),
-              };
+              const tenantCandidate = buildCandidateBase(model, capabilityProfile, {
+                tenantId: tenantOwnerId,
+                requiresAccount: false,
+                pools: {
+                  ids: [poolId],
+                  limits: tenantPools.limits,
+                  weights: tenantPools.weights,
+                  routing: tenantPools.routing,
+                },
+              });
+              // Pool-account health from the row: a spent egress is excluded
+              // exactly like a cooling account, and the deadline rides along so
+              // `plan()` can quote the real reset on an all-cooling answer.
+              if (first.status === "disabled") {
+                tenantCandidate.health_status = "disabled";
+              } else if (first.status === "cooldown") {
+                tenantCandidate.health_status = "cooldown";
+                tenantCandidate.cooldown_kind = hardCooldownCategory(first.lastErrorCategory)
+                  ? "hard"
+                  : "soft";
+                if (first.cooldownUntil && first.cooldownUntil.getTime() > Date.now()) {
+                  tenantCandidate.cooldown_until = first.cooldownUntil.getTime();
+                }
+              }
               if (tenantId === undefined || tenantId === tenantOwnerId) {
                 candidates.push(tenantCandidate);
               }
@@ -757,27 +815,16 @@ class RouteCatalogRepository {
           for (const tId of configuredPoolTenants) {
             const tenantPools = resolveNetworkPools(model.providerId, tId);
             if (tenantPools) {
-              const tenantCandidate: RoutedCandidate = {
-                provider_id: model.providerId,
-                model_id: model.modelId,
-                wire_family: model.wireFamily as WireFamily,
-                ...(model.dialect == null ? {} : { dialect: model.dialect }),
-                service_kind: model.serviceKind,
-                endpoint: model.endpointPath,
-                ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
-                capability_profile: capabilityProfile,
-                tenant_id: tId,
-                ...(model.freeTier === true ? { free_tier: true } : {}),
-                // Public credential-less candidates have no account to own them.
-                owner_tenant_id: null,
-                requires_account: false as const,
-                network_pool_ids: tenantPools.ids,
-                network_pool_required: true,
-                network_pool_limits: tenantPools.limits,
-                network_pool_weights: tenantPools.weights,
-                ...(tenantPools.routing ? { network_pool_routing: tenantPools.routing } : {}),
-                ...providerLimitFor(model.providerId, tId),
-              };
+              const tenantCandidate = buildCandidateBase(model, capabilityProfile, {
+                tenantId: tId,
+                requiresAccount: false,
+                pools: {
+                  ids: tenantPools.ids,
+                  limits: tenantPools.limits,
+                  weights: tenantPools.weights,
+                  routing: tenantPools.routing,
+                },
+              });
               if (tenantId === undefined || tenantId === tId) {
                 candidates.push(tenantCandidate);
               }
@@ -787,33 +834,17 @@ class RouteCatalogRepository {
         const networkPools = providerRequiresAccount
           ? undefined
           : resolveNetworkPools(model.providerId, providerTenantId);
-        const candidate: RoutedCandidate = {
-          provider_id: model.providerId,
-          model_id: model.modelId,
-          wire_family: model.wireFamily as WireFamily,
-          ...(model.dialect == null ? {} : { dialect: model.dialect }),
-          service_kind: model.serviceKind,
-          endpoint: model.endpointPath,
-          ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
-          capability_profile: capabilityProfile,
-          tenant_id: providerTenantId,
-          ...(model.freeTier === true ? { free_tier: true } : {}),
-          // Public credential-less candidates have no account to own them.
-          owner_tenant_id: null,
-          ...(providerRequiresAccount
-            ? { health_status: "disabled" as const }
-            : { requires_account: false as const }),
-          ...(networkPools
-            ? {
-                network_pool_ids: networkPools.ids,
-                network_pool_required: true,
-                network_pool_limits: networkPools.limits,
-                network_pool_weights: networkPools.weights,
-                ...(networkPools.routing ? { network_pool_routing: networkPools.routing } : {}),
-                ...providerLimitFor(model.providerId, providerTenantId),
-              }
-            : {}),
-        };
+        const candidate = buildCandidateBase(model, capabilityProfile, {
+          tenantId: providerTenantId,
+          // A provider that requires an account but has none is unusable: the
+          // public candidate is stamped disabled below. A genuinely
+          // credential-less provider carries `requires_account: false` instead.
+          ...(providerRequiresAccount ? {} : { requiresAccount: false }),
+          ...(networkPools ? { pools: networkPools } : {}),
+        });
+        if (providerRequiresAccount) {
+          candidate.health_status = "disabled";
+        }
         if (tenantId === undefined || candidate.tenant_id === null || candidate.tenant_id === tenantId) {
           candidates.push(candidate);
         }
@@ -831,46 +862,28 @@ class RouteCatalogRepository {
         }
         const networkPools = resolveNetworkPools(model.providerId, rowTenantId);
         const routeUserAgent = resolveUserAgent(model.providerId, rowTenantId);
-        const candidate: RoutedCandidate = {
-          provider_id: model.providerId,
-          model_id: model.modelId,
-          wire_family: model.wireFamily as WireFamily,
-          ...(model.dialect == null ? {} : { dialect: model.dialect }),
-          service_kind: model.serviceKind,
-          endpoint: model.endpointPath,
-          ...(model.outputLimit == null ? {} : { output_limit: model.outputLimit }),
-          capability_profile: capabilityProfile,
-          ...(routeUserAgent === undefined ? {} : { user_agent: routeUserAgent }),
-          ...(model.freeTier === true ? { free_tier: true } : {}),
-          tenant_id: rowTenantId,
-          provider_account_id: account.id,
+        const candidate = buildCandidateBase(model, capabilityProfile, {
+          tenantId: rowTenantId,
+          accountId: account.id,
           // The account's owning tenant (null = shared pool-wide) — the bucket
           // key for admission, distinct from the requesting tenant.
-          owner_tenant_id: account.tenantId ?? null,
+          ownerTenantId: account.tenantId ?? null,
           // The plan gate is per (account, model): the model may be refused on
           // a free plan and the account may be on one. Both ride here because
           // `plan()` sees the candidate and nothing else.
-          ...(model.proOnly === true ? { pro_only: true } : {}),
+          ...(model.proOnly === true ? { proOnly: true } : {}),
           ...(account.quotaPlan === null || account.quotaPlan === undefined
             ? {}
-            : { account_plan: account.quotaPlan }),
+            : { accountPlan: account.quotaPlan }),
           // Provider-wide concurrency ceiling from Routing Strategy; legacy
           // account overrides are never read here.
           ...(() => {
             const resolved = resolveMaxInflight(model.providerId, rowTenantId);
-            return resolved === undefined ? {} : { max_inflight: resolved };
+            return resolved === undefined ? {} : { maxInflight: resolved };
           })(),
-          ...(networkPools
-            ? {
-                network_pool_required: true,
-                network_pool_ids: networkPools.ids,
-                network_pool_limits: networkPools.limits,
-                network_pool_weights: networkPools.weights,
-                ...(networkPools.routing ? { network_pool_routing: networkPools.routing } : {}),
-                ...providerLimitFor(model.providerId, rowTenantId),
-              }
-            : {}),
-        };
+          ...(routeUserAgent === undefined ? {} : { userAgent: routeUserAgent }),
+          ...(networkPools ? { pools: networkPools } : {}),
+        });
         if (account.status === "cooldown") {
           // A row that still says `cooldown` stays excluded until the sweeper
           // flips it back to `active`. An *expired* deadline used to read as
@@ -995,7 +1008,6 @@ class RouteCatalogRepository {
       cli_aliases: cliAliases,
       combos,
       ...(routingMap ? { providerRouting: routingMap } : {}),
-      ...(Object.keys(poolRouting).length > 0 ? { poolRouting } : {}),
       ...(invokeDisabledTenants.size > 0 ? { invokeDisabledTenants } : {}),
     };
   }

package/src/transport/routing/route-model.ts

@@ -108,6 +108,8 @@ export interface RouteCandidate {
   readonly quota_windows?: readonly ProviderQuotaWindow[];
   /** A successful Start Plan balance authoritatively lists its model grants. */
   readonly quota_entitlements_known?: boolean;
+  /** Normalized quota/plan fact stamped at plan time (unified engine). */
+  readonly quota_fact?: NormalizedQuotaFact;
 }
 
 /**
@@ -141,6 +143,27 @@ export type RoutedCandidate = RouteCandidate & {
    * activity is read live via `sharedClaudeSlowLanes.isActive`).
    */
   lane?: "slow";
+  /**
+   * Normalized quota/plan fact stamped at plan time by the routing decision
+   * engine. The decision engine reads this instead of re-deriving window state.
+   */
+  quota_fact?: NormalizedQuotaFact;
+  /**
+   * Operator-configured account priority (0 when unset). Higher ranks ahead
+   * within the same rank group, before usage measurement.
+   */
+  account_priority?: number;
+  /**
+   * True when the account's remaining quota fraction is at or below the
+   * configured reserve percent. A reserved account stays eligible but orders
+   * behind non-reserve siblings.
+   */
+  in_reserve?: boolean;
+  /**
+   * Drain urgency score: headroom fraction / remaining hours until reset.
+   * Higher = quota about to expire unused, ranked first within a rank group.
+   */
+  drain_score?: number;
 };
 
 /**
@@ -256,10 +279,13 @@ export interface RoutePlan {
 
 /** How eligible a candidate is and why — written once, read by every layer. */
 export const ROUTING_RANK = {
-  FRESH: 0,
-  SLOW: 1,
-  COOLING: 2,
-  SATURATED: 3,
+  /** Fresh candidate with a positive known quota / above its usage floor. */
+  FRESH_KNOWN: 0,
+  /** Fresh candidate whose quota state is unknown (no read, unsupported, stale). */
+  FRESH_UNKNOWN: 1,
+  SLOW: 2,
+  COOLING: 3,
+  SATURATED: 4,
 } as const;
 export type RoutingRank = (typeof ROUTING_RANK)[keyof typeof ROUTING_RANK];
 
@@ -275,6 +301,22 @@ export interface RoutingDecision {
   readonly saturated?: boolean;
 }
 
+/**
+ * The normalized quota/plan fact the unified routing engine evaluates per
+ * candidate. Produced once per candidate before `evaluateCandidate`, so the
+ * decision engine never re-reads quota sources or re-derives window state.
+ */
+export interface NormalizedQuotaFact {
+  /** `available` = positive known balance; `exhausted` = known spent/below floor. */
+  readonly quotaState: "available" | "exhausted" | "unknown";
+  readonly quotaSource: "live_cache" | "snapshot" | "unsupported" | "none";
+  /** Epoch ms of the observation, when one exists (used for freshness). */
+  readonly quotaObservedAt: number | null;
+  /** True when the observed quota is older than the freshness horizon. */
+  readonly isStale: boolean;
+  readonly usageFloorState: "above" | "below" | "unknown";
+}
+
 import type { ComboStrategy, PoolRoutingStrategy, ProviderRoutingStrategy } from "../../persistence/schema";
 import { providerRoutingStrategy } from "../../persistence/schema";
 
@@ -299,8 +341,6 @@ export interface RouteSnapshot {
   readonly created_at: number;
   /** Optional per-provider routing preferences keyed by tenant. */
   readonly providerRouting?: ProviderRoutingMap;
-  /** Optional per-tenant pool selection strategy (absent = `least_loaded`). */
-  readonly poolRouting?: Readonly<Record<string, PoolRoutingSetting>>;
   /**
    * Tenants whose invoke switch is off, so `/v1/*` must be refused outright.
    *
@@ -319,6 +359,9 @@ export type EligibilityReason =
   | "cooldown_hard"
   | "model_cooldown"
   | "quota_exhausted"
+  | "quota_unknown"
+  | "plan_gate"
+  | "capability_unsupported"
   | "disabled"
 
 export interface EligibilityDecision {
@@ -392,6 +435,8 @@ const ELIGIBILITY_REASON_LABELS: Readonly<Record<string, string>> = {
   disabled: "all accounts are disabled",
   credit_floor_reached: "credit or quota is exhausted",
   quota_exhausted: "every account has an exhausted quota window or is below its configured usage floor",
+  quota_unknown: "accounts have no known quota state (unknown, unsupported, or stale)",
+  plan_gate: "the plan explicitly proves these accounts cannot serve this model",
   capability_unsupported: "the accounts serving this model do not support the request's capabilities (e.g. images, tools, or reasoning)",
 };
 
@@ -703,9 +748,6 @@ export class InMemoryRouteSnapshotService implements RouteSnapshotService {
       ...(built.cli_aliases ? { cli_aliases: Object.freeze({ ...built.cli_aliases }) } : {}),
       combos: Object.freeze({ ...built.combos }),
       ...(providerRouting ? { providerRouting } : {}),
-      // Unfrozen copy: deepFreeze must reach the inner per-tenant settings —
-      // a pre-frozen record trips its is-frozen guard and skips recursion.
-      ...(built.poolRouting ? { poolRouting: { ...built.poolRouting } } : {}),
       created_at: built.created_at ?? Date.now(),
     });
     // A mutation during the build means this snapshot describes a catalog that