@iislee/opencodex 2.11.0 → 2.35.0

package/src/routing/analytics.ts

@@ -0,0 +1,379 @@
+/**
+ * Source-backed routing analytics (RI-03).
+ *
+ * All metrics derive from the rebuildable request-history index
+ * (`routing-history.sqlite`), never from repeated full JSONL scans. The
+ * analysis is read-only: no routing decision, profile, or weight changes here
+ * (ADR-10 - no automatic self-tuning).
+ *
+ * Bounds: at most ANALYTICS_MAX_ROWS matching rows are analyzed per call; a
+ * larger population sets `historyTruncated: true` so readers never mistake a
+ * sample for the full history.
+ */
+
+import type { PersistedUsageEntry } from "../usage/log";
+import { estimateRequestCost, serviceTierContext } from "../usage/cost";
+import { openRequestHistoryIndex, requestHistoryDb } from "./history/indexer";
+
+export const ANALYTICS_MAX_ROWS = 50_000;
+/** Default row cap for the management API (full cap remains available via `limit`). */
+export const ANALYTICS_API_DEFAULT_ROWS = 5_000;
+
+export interface RoutingAnalyticsFilters {
+  provider?: string;
+  model?: string;
+  profileId?: string;
+  surface?: string;
+  from?: number;
+  to?: number;
+}
+
+export type AnalyticsConfidence = "high" | "medium" | "low";
+
+export interface AnalyticsBreakdownRow {
+  provider: string;
+  model: string;
+  accountRef?: string;
+  profileId?: string;
+  requests: number;
+  successes: number;
+  failures: number;
+  cancelled: number;
+  successRate: number | null;
+  p50DurationMs?: number;
+  estimatedCostUsdPerSuccessfulRequest?: number | null;
+}
+
+export interface AnalyticsProfileRow {
+  profileId: string;
+  profileRevision?: string;
+  requests: number;
+  successes: number;
+  failures: number;
+  fallbacks: number;
+  successRate: number | null;
+}
+
+export interface RoutingAnalyticsResult {
+  generatedAt: number;
+  totalRequests: number;
+  scannedRows: number;
+  historyTruncated: boolean;
+  confidence: AnalyticsConfidence | null;
+  successRate: number | null;
+  failureRate: number | null;
+  cancelledRate: number | null;
+  fallbackRate: number | null;
+  totalAttempts: number;
+  averageAttemptsPerRequest: number | null;
+  incompleteStreamRate: number | null;
+  cooldownTriggeringFailures: number;
+  durationMs: {
+    p50?: number;
+    p95?: number;
+    p99?: number;
+    sampleCount: number;
+  };
+  firstOutputMs: {
+    p50?: number;
+    p95?: number;
+    p99?: number;
+    sampleCount: number;
+    /** Share of scanned requests with a TTFT measurement (0..1). */
+    coverage: number | null;
+  };
+  estimatedCostUsdPerSuccessfulRequest: number | null;
+  estimatedCostUsdTotalSuccessful: number | null;
+  usageCoverage: number | null;
+  priceCoverage: number | null;
+  breakdown: AnalyticsBreakdownRow[];
+  profileBreakdown: AnalyticsProfileRow[];
+}
+
+interface ScannedRow {
+  provider: string;
+  model: string;
+  apiKeyId?: string | null;
+  profileId?: string | null;
+  profileRevision?: string | null;
+  status: number;
+  durationMs: number;
+  firstOutputMs?: number | null;
+  closeReason?: string | null;
+  terminalStatus?: string | null;
+  usageStatus: string;
+  usageJson?: string | null;
+  attemptCount: number;
+  fallback: number;
+  rowJson: string;
+}
+
+interface Bucket extends AnalyticsBreakdownRow {
+  durations: number[];
+  costUsdSum: number;
+  costRows: number;
+}
+
+const COOLDOWN_RECOVERY_KINDS = new Set([
+  "rate-limit-429",
+  "key-429",
+  "oauth-401",
+  "anthropic-oauth-429",
+  "oauth-account-429",
+]);
+
+function percentile(sorted: number[], p: number): number | undefined {
+  if (sorted.length === 0) return undefined;
+  const index = Math.max(0, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[Math.min(index, sorted.length - 1)];
+}
+
+function classifyRow(row: ScannedRow): "success" | "failure" | "cancelled" {
+  if (row.closeReason === "client_cancel" || row.status === 499) return "cancelled";
+  if (row.terminalStatus === "incomplete") return "failure";
+  if (row.terminalStatus && row.terminalStatus !== "completed") return "failure";
+  if (row.status >= 400) return "failure";
+  return "success";
+}
+
+function parseEntry(rowJson: string): PersistedUsageEntry | null {
+  try {
+    const parsed = JSON.parse(rowJson) as PersistedUsageEntry;
+    return parsed && typeof parsed === "object" && typeof parsed.requestId === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function cooldownTriggering(entry: PersistedUsageEntry | null, status: number): boolean {
+  if (status === 429) return true;
+  if (!Array.isArray(entry?.attempts)) return false;
+  return entry.attempts.some((attempt: unknown) => {
+    if (!attempt || typeof attempt !== "object") return false;
+    const recoveryKinds = (attempt as { recoveryKinds?: unknown }).recoveryKinds;
+    return Array.isArray(recoveryKinds)
+      && recoveryKinds.some(kind => typeof kind === "string" && COOLDOWN_RECOVERY_KINDS.has(kind));
+  });
+}
+
+function successCostUsd(
+  row: Pick<ScannedRow, "provider" | "model">,
+  entry: PersistedUsageEntry,
+): number | null {
+  if (!entry.usage) return null;
+  const estimate = estimateRequestCost({
+    provider: row.provider,
+    model: row.model,
+    usage: entry.usage,
+    usageStatus: entry.usageStatus,
+    serviceTier: serviceTierContext(entry),
+  });
+  return estimate ? estimate.cost.total : null;
+}
+
+export async function computeRoutingAnalytics(
+  filters: RoutingAnalyticsFilters,
+  options: { maxRows?: number } = {},
+): Promise<RoutingAnalyticsResult> {
+  await openRequestHistoryIndex();
+  const handle = requestHistoryDb();
+  const maxRows = Math.min(
+    Math.max(1, Math.trunc(options.maxRows ?? ANALYTICS_MAX_ROWS)),
+    ANALYTICS_MAX_ROWS,
+  );
+
+  const where: string[] = [];
+  const values: Array<string | number> = [];
+  const add = (clause: string, value: string | number) => {
+    where.push(clause);
+    values.push(value);
+  };
+  if (filters.provider !== undefined) add("provider = ?", filters.provider);
+  if (filters.model !== undefined) add("model = ?", filters.model);
+  if (filters.profileId !== undefined) add("profile_id = ?", filters.profileId);
+  if (filters.surface !== undefined) add("surface = ?", filters.surface);
+  if (filters.from !== undefined) add("timestamp >= ?", filters.from);
+  if (filters.to !== undefined) add("timestamp <= ?", filters.to);
+  const whereSql = where.length > 0 ? ` WHERE ${where.join(" AND ")}` : "";
+
+  const rows = handle.query(
+    `SELECT provider, model, api_key_id AS apiKeyId, profile_id AS profileId,
+            profile_revision AS profileRevision, status,
+            duration_ms AS durationMs, first_output_ms AS firstOutputMs,
+            close_reason AS closeReason, terminal_status AS terminalStatus,
+            usage_status AS usageStatus, usage_json AS usageJson,
+            attempt_count AS attemptCount, fallback, row_json AS rowJson
+     FROM requests${whereSql} ORDER BY timestamp DESC LIMIT ?`,
+  ).all(...values, maxRows + 1) as ScannedRow[];
+
+  const scanned = rows.slice(0, maxRows);
+  const historyTruncated = rows.length > maxRows;
+
+  let successes = 0;
+  let failures = 0;
+  let cancelled = 0;
+  let fallbacks = 0;
+  let totalAttempts = 0;
+  let incompleteStreams = 0;
+  let cooldownFailures = 0;
+  let usageReported = 0;
+  const durations: number[] = [];
+  const firstOutputs: number[] = [];
+  let costTotalUsd = 0;
+  let costCount = 0;
+
+  const byKey = new Map<string, Bucket>();
+  const byProfile = new Map<string, AnalyticsProfileRow>();
+
+  for (const row of scanned) {
+    const kind = classifyRow(row);
+    if (kind === "success") successes += 1;
+    else if (kind === "failure") failures += 1;
+    else cancelled += 1;
+    if (row.fallback === 1) fallbacks += 1;
+    totalAttempts += row.attemptCount;
+    if (row.terminalStatus === "incomplete") incompleteStreams += 1;
+    durations.push(row.durationMs);
+    if (row.firstOutputMs !== null && row.firstOutputMs !== undefined && row.firstOutputMs >= 0) {
+      firstOutputs.push(row.firstOutputMs);
+    }
+    if (row.usageStatus !== "unreported") usageReported += 1;
+
+    let rowCostUsd: number | null = null;
+    if (kind === "success") {
+      const entry = parseEntry(row.rowJson);
+      if (entry) {
+        rowCostUsd = successCostUsd(row, entry);
+        if (rowCostUsd !== null) {
+          costTotalUsd += rowCostUsd;
+          costCount += 1;
+        }
+      }
+    }
+
+    if (kind === "failure") {
+      const failureEntry = parseEntry(row.rowJson);
+      if (cooldownTriggering(failureEntry, row.status)) cooldownFailures += 1;
+    }
+
+    const key = `${row.provider}\0${row.model}\0${row.apiKeyId ?? ""}\0${row.profileId ?? ""}`;
+    let bucket: Bucket | undefined = byKey.get(key);
+    if (!bucket) {
+      bucket = {
+        provider: row.provider,
+        model: row.model,
+        ...(row.apiKeyId ? { accountRef: row.apiKeyId } : {}),
+        ...(row.profileId ? { profileId: row.profileId } : {}),
+        requests: 0,
+        successes: 0,
+        failures: 0,
+        cancelled: 0,
+        successRate: null,
+        durations: [],
+        costUsdSum: 0,
+        costRows: 0,
+      };
+      byKey.set(key, bucket);
+    }
+    bucket.requests += 1;
+    if (kind === "success") bucket.successes += 1;
+    else if (kind === "failure") bucket.failures += 1;
+    else bucket.cancelled += 1;
+    bucket.durations.push(row.durationMs);
+    if (rowCostUsd !== null) {
+      bucket.costUsdSum += rowCostUsd;
+      bucket.costRows += 1;
+    }
+
+    if (row.profileId) {
+      let profile = byProfile.get(row.profileId);
+      if (!profile) {
+        profile = {
+          profileId: row.profileId,
+          ...(row.profileRevision ? { profileRevision: row.profileRevision } : {}),
+          requests: 0,
+          successes: 0,
+          failures: 0,
+          fallbacks: 0,
+          successRate: null,
+        };
+        byProfile.set(row.profileId, profile);
+      }
+      profile.requests += 1;
+      if (kind === "success") profile.successes += 1;
+      else if (kind === "failure") profile.failures += 1;
+      if (row.fallback === 1) profile.fallbacks += 1;
+    }
+  }
+
+  durations.sort((a, b) => a - b);
+  firstOutputs.sort((a, b) => a - b);
+  const total = scanned.length;
+  const rate = (count: number): number | null => (total > 0 ? count / total : null);
+
+  const breakdown: AnalyticsBreakdownRow[] = [...byKey.values()].map(bucket => {
+    const sorted = bucket.durations.sort((a, b) => a - b);
+    const p50DurationMs = percentile(sorted, 50);
+    return {
+      provider: bucket.provider,
+      model: bucket.model,
+      ...(bucket.accountRef ? { accountRef: bucket.accountRef } : {}),
+      ...(bucket.profileId ? { profileId: bucket.profileId } : {}),
+      requests: bucket.requests,
+      successes: bucket.successes,
+      failures: bucket.failures,
+      cancelled: bucket.cancelled,
+      successRate: bucket.requests > 0 ? bucket.successes / bucket.requests : null,
+      ...(p50DurationMs !== undefined ? { p50DurationMs } : {}),
+      ...(bucket.requests > 0
+        ? { estimatedCostUsdPerSuccessfulRequest: bucket.costRows > 0
+          ? bucket.costUsdSum / bucket.costRows
+          : null }
+        : {}),
+    };
+  }).sort((a, b) => b.requests - a.requests);
+
+  const profileBreakdown: AnalyticsProfileRow[] = [...byProfile.values()].map(profile => ({
+    ...profile,
+    successRate: profile.requests > 0 ? profile.successes / profile.requests : null,
+  })).sort((a, b) => b.requests - a.requests);
+
+  const confidence: AnalyticsConfidence | null = total === 0
+    ? null
+    : total >= 100 ? "high" : total >= 20 ? "medium" : "low";
+
+  return {
+    generatedAt: Date.now(),
+    totalRequests: total,
+    scannedRows: scanned.length,
+    historyTruncated,
+    confidence,
+    successRate: rate(successes),
+    failureRate: rate(failures),
+    cancelledRate: rate(cancelled),
+    fallbackRate: rate(fallbacks),
+    totalAttempts,
+    averageAttemptsPerRequest: total > 0 ? totalAttempts / total : null,
+    incompleteStreamRate: rate(incompleteStreams),
+    cooldownTriggeringFailures: cooldownFailures,
+    durationMs: {
+      ...(percentile(durations, 50) !== undefined ? { p50: percentile(durations, 50) } : {}),
+      ...(percentile(durations, 95) !== undefined ? { p95: percentile(durations, 95) } : {}),
+      ...(percentile(durations, 99) !== undefined ? { p99: percentile(durations, 99) } : {}),
+      sampleCount: durations.length,
+    },
+    firstOutputMs: {
+      ...(percentile(firstOutputs, 50) !== undefined ? { p50: percentile(firstOutputs, 50) } : {}),
+      ...(percentile(firstOutputs, 95) !== undefined ? { p95: percentile(firstOutputs, 95) } : {}),
+      ...(percentile(firstOutputs, 99) !== undefined ? { p99: percentile(firstOutputs, 99) } : {}),
+      sampleCount: firstOutputs.length,
+      coverage: total > 0 ? firstOutputs.length / total : null,
+    },
+    estimatedCostUsdPerSuccessfulRequest: costCount > 0 ? costTotalUsd / costCount : null,
+    estimatedCostUsdTotalSuccessful: costCount > 0 ? costTotalUsd : null,
+    usageCoverage: total > 0 ? usageReported / total : null,
+    priceCoverage: successes > 0 ? costCount / successes : null,
+    breakdown,
+    profileBreakdown,
+  };
+}

package/src/routing/capability.ts

@@ -0,0 +1,244 @@
+/**
+ * Candidate capability evidence for policy routing (RI-05).
+ *
+ * Evidence comes from canonical local sources only - provider config maps,
+ * the provider registry, the cached Codex catalog file, and the native-model
+ * metadata helpers. No live network fetch happens at routing time.
+ *
+ * "Unknown is not zero": any dimension without canonical evidence stays
+ * `undefined` (unknown) and the profile's `unknownEvidence` policy decides
+ * how that affects eligibility.
+ */
+
+import { modelInList, type OcxConfig } from "../types";
+import { isCanonicalOpenAiForwardProvider, OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
+import { serviceTierSupportForModel } from "../providers/service-tier";
+import { PROVIDER_REGISTRY } from "../providers/registry";
+import {
+  nativeInputModalities,
+  nativeContextLimits, nativeOpenAiContextWindow,
+  nativeParallelToolCalls,
+  nativeReasoningEfforts,
+} from "../codex/catalog/metadata";
+import { readCatalog, readCodexCatalogPath } from "../codex/catalog/parsing";
+import { modelRecordValue } from "../reasoning-effort";
+import { statSync } from "node:fs";
+import type { RouteCapabilityEvidence } from "./trace";
+
+type CatalogModelRow = {
+  /** Exact provider/native-id identity, from the provenance block. */
+  provider: string;
+  id: string;
+  /** Only values a real source asserted; never a strict-parser default. */
+  contextWindow?: number;
+  inputModalities?: string[];
+  capabilities?: string[];
+};
+
+/**
+ * Catalog rows memoized by path + mtime: the cached Codex catalog is stable
+ * between refreshes, and re-reading/parsing the whole file per candidate on
+ * the request path would multiply a synchronous disk + JSON cost by the
+ * profile candidate count for every policy-routed request.
+ */
+let catalogCache: { path: string; mtimeMs: number; rows: CatalogModelRow[] } | null = null;
+
+function cachedCatalogModels(): CatalogModelRow[] {
+  try {
+    const path = readCodexCatalogPath();
+    const mtimeMs = statSync(path).mtimeMs;
+    if (catalogCache && catalogCache.path === path && catalogCache.mtimeMs === mtimeMs) {
+      return catalogCache.rows;
+    }
+    const catalog = readCatalog(path);
+    const models = catalog?.models;
+    if (!Array.isArray(models)) return [];
+    // Read ONLY `opencodex_capability_provenance` (written by
+    // applyCatalogModelMetadata). The row's own `context_window` and
+    // `input_modalities` always exist because ensureStrictCatalogFields fills them
+    // with compatibility defaults for Codex's strict parser, so reading them would
+    // turn "nobody asserted anything" into a confident `image: false` and a
+    // fabricated 128000 — the opposite of this module's contract. A row without
+    // provenance contributes nothing.
+    const rows = models.flatMap((model): CatalogModelRow[] => {
+      if (typeof model !== "object" || model === null) return [];
+      const provenance = (model as Record<string, unknown>).opencodex_capability_provenance;
+      if (typeof provenance !== "object" || provenance === null) return [];
+      const source = provenance as Record<string, unknown>;
+      if (typeof source.provider !== "string" || typeof source.model_id !== "string") return [];
+      return [{
+        provider: source.provider,
+        id: source.model_id,
+        ...(typeof source.context_window === "number" && source.context_window > 0
+          ? { contextWindow: source.context_window }
+          : {}),
+        ...(Array.isArray(source.input_modalities)
+          ? { inputModalities: source.input_modalities.filter((value): value is string => typeof value === "string") }
+          : {}),
+        ...(Array.isArray(source.capabilities)
+          ? { capabilities: source.capabilities.filter((value): value is string => typeof value === "string") }
+          : {}),
+      }];
+    });
+    catalogCache = { path, mtimeMs, rows };
+    return rows;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Classify a hostname for locality evidence. `URL.hostname` keeps IPv6
+ * literals bracketed (`[::1]`), so strip the brackets before matching.
+ * Anything not positively local or private stays unknown: "unknown is not
+ * zero", so an unrecognized host must never assert `remoteAllowed`.
+ */
+function classifyHostname(hostname: string): "local" | "private" | null {
+  const host = hostname.trim().toLowerCase().replace(/\.$/, "").replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host.endsWith(".localhost") || host === "0.0.0.0") return "local";
+  if (host === "::1" || /^127\./.test(host)) return "local";
+  if (/^10\./.test(host)
+    || /^192\.168\./.test(host)
+    || /^169\.254\./.test(host)
+    || /^172\.(1[6-9]|2\d|3[01])\./.test(host)
+    || /^f[cd][0-9a-f]{2}:/.test(host)
+    || /^fe80:/.test(host)
+    || /^::ffff:(?:10\.|127\.|192\.168\.|169\.254\.|172\.(?:1[6-9]|2\d|3[01])\.)/.test(host)) {
+    return "private";
+  }
+  return null;
+}
+
+/**
+ * Adapters whose upstream protocol supports function/tool calling. Mirrors
+ * the adapter ids the resolver accepts (including the `azure` alias for
+ * `azure-openai`); `kiro` and `mimo-free` send/delegate tool calls.
+ */
+const TOOL_CAPABLE_ADAPTERS = new Set([
+  "openai-chat",
+  "openai-responses",
+  "anthropic",
+  "cursor",
+  "google",
+  "azure-openai",
+  "azure",
+  "kiro",
+  "mimo-free",
+  "command-code",
+]);
+
+function localRemoteEvidence(baseUrl: string | undefined): Pick<RouteCapabilityEvidence, "localOnly" | "remoteAllowed"> {
+  if (typeof baseUrl !== "string" || baseUrl.length === 0) return {};
+  try {
+    const hostname = new URL(baseUrl).hostname;
+    if (!hostname) return {};
+    const kind = classifyHostname(hostname);
+    if (kind === null) return {};
+    // Both booleans are emitted once classified: definitive negative evidence,
+    // so a local host cannot satisfy `require.remoteAllowed` (or vice versa)
+    // under `unknownEvidence.capability: "allow"`/`"penalize"`.
+    return kind === "local" || kind === "private"
+      ? { localOnly: true, remoteAllowed: false }
+      : { remoteAllowed: true, localOnly: false };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Assemble canonical capability evidence for one `provider/model` candidate.
+ * Sources (in priority order): provider config maps, provider registry hints,
+ * cached Codex catalog row, native-model metadata.
+ */
+export function candidateCapabilityEvidence(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+): RouteCapabilityEvidence {
+  const provider = config.providers[providerName];
+  const registryEntry = PROVIDER_REGISTRY.find(entry => entry.id === providerName);
+  const catalogRow = cachedCatalogModels().find(model => model.provider === providerName && model.id === modelId);
+  const isNative = providerName === OPENAI_CODEX_PROVIDER_ID && !modelId.includes("/");
+
+  // `modelRecordValue`, not a bare lookup: every runtime reader of these three maps
+  // resolves them that way, so a `gpt-oss` entry covers `gpt-oss:120b`. Reading raw
+  // made the evidence disagree with the resolver it claims to describe — and for the
+  // window it did not even degrade to unknown, it fell through to the provider-wide
+  // value, which is a definite wrong answer rather than an absent one.
+  const rawContextWindow = modelRecordValue(provider?.modelContextWindows, modelId)
+    ?? provider?.contextWindow
+    ?? modelRecordValue(registryEntry?.modelContextWindows, modelId)
+    ?? catalogRow?.contextWindow
+    ?? (isNative ? nativeOpenAiContextWindow(modelId, nativeContextLimits(config)) : undefined);
+  // Native rows go through the accessor (raise-to-ceiling + opt-in). Routed rows keep
+  // the raw value; a provider cap on openai must not invent a window they do not have.
+  const contextWindow = isNative
+    ? (nativeOpenAiContextWindow(modelId, nativeContextLimits(config)) ?? rawContextWindow)
+    : rawContextWindow;
+
+  // `noVisionModels` is checked before the modality chain because that is the order
+  // `isModelTextOnly` uses: it matches the no-vision list and returns true before it
+  // ever reads `modelInputModalities` (`src/vision/index.ts:32`). So a `gpt-oss`
+  // no-vision entry beats an exact `gpt-oss:120b` entry that lists "image", and
+  // deriving `image` from the modality chain alone reported vision on a model the
+  // runtime refuses it for. That matters more here than on the CLI surface fixed in
+  // #2086: routing *acts* on this evidence, so it would select the candidate for image
+  // work that execution then rejects.
+  const noVision = modelInList(provider?.noVisionModels, modelId);
+  const modalities = noVision
+    ? ["text"]
+    : (modelRecordValue(provider?.modelInputModalities, modelId)
+      ?? modelRecordValue(registryEntry?.modelInputModalities, modelId)
+      ?? catalogRow?.inputModalities
+      ?? (isNative ? nativeInputModalities(modelId) : undefined));
+  const image = Array.isArray(modalities)
+    ? modalities.includes("image")
+    : undefined;
+
+  const capabilities = catalogRow?.capabilities ?? [];
+  // The catalog `capabilities` list is a positive per-model signal; a row
+  // without "tools" is treated as unknown, never as a negative. Without a
+  // catalog row the adapter protocol itself is the signal: tool-capable
+  // adapters run single tool calls even when the parallel-call opt-in is
+  // unset or false. `parallelToolCalls` stays a positive provider-level
+  // override.
+  const tools = capabilities.includes("tools")
+    || isNative
+    // The adapter protocol is positive evidence on its own. This was once gated
+    // on `catalogRow === undefined`, which was only safe while the catalog lookup
+    // never matched anything: once it matches, a row that simply does not
+    // enumerate "tools" would silently revoke tool support for every openai-chat
+    // and anthropic candidate.
+    || (provider !== undefined && TOOL_CAPABLE_ADAPTERS.has(provider.adapter))
+    || provider?.parallelToolCalls === true
+    || undefined;
+
+  const reasoningEfforts = modelRecordValue(provider?.modelReasoningEfforts, modelId)
+    ?? modelRecordValue(registryEntry?.modelReasoningEfforts, modelId)
+    ?? (isNative ? nativeReasoningEfforts(modelId) : undefined);
+
+  const tierSupport = provider
+    ? serviceTierSupportForModel(provider, modelId, providerName)
+    : registryEntry ? serviceTierSupportForModel(registryEntry, modelId, providerName) : undefined;
+  const serviceTier = tierSupport === true
+    ? "supported"
+    : tierSupport === false ? "unsupported" : "unknown";
+
+  const localRemote = localRemoteEvidence(provider?.baseUrl);
+  // Only emit a definitive encryptedCodexTasks value when the provider is
+  // present. An absent/unconfigured provider must stay unknown so
+  // require.encryptedCodexTasks does not fail closed on missing config.
+  const encryptedCodexTasks = provider === undefined
+    ? undefined
+    : isCanonicalOpenAiForwardProvider(provider);
+
+  return {
+    ...(typeof contextWindow === "number" ? { contextWindow } : {}),
+    ...(typeof image === "boolean" ? { image } : {}),
+    ...(typeof tools === "boolean" ? { tools } : {}),
+    ...(reasoningEfforts !== undefined && reasoningEfforts.length > 0 ? { reasoningEfforts } : {}),
+    ...(serviceTier !== "unknown" ? { serviceTier } : {}),
+    ...localRemote,
+    ...(typeof encryptedCodexTasks === "boolean" ? { encryptedCodexTasks } : {}),
+  };
+}

package/src/routing/compatibility/assemble.ts

@@ -0,0 +1,73 @@
+import type { OcxConfig, OcxProviderConfig } from "../../types";
+import { candidateCapabilityEvidence } from "../capability";
+import { costEvidenceForCandidate } from "../cost";
+import type { PolicyCandidateEvidence } from "../evaluator";
+import { policyCandidateHealthEvidence } from "../health";
+import type { NormalizedRoutingProfile } from "../profile";
+import { quotaEvidenceForCandidate } from "../quota";
+import { resolveCompatibilityEvidenceProvider, type CoreEvidenceOptions } from "./provider-slot";
+
+export type RoutedProviderResolver = (
+  providerName: string,
+  provider: OcxProviderConfig,
+) => OcxProviderConfig;
+
+/**
+ * Options the core assembler needs. Provider-specific test seams (subject resolution,
+ * catalog and projection loading) belong to the compatibility provider, not here -- keeping
+ * them out is what stops the core assembler from naming Lab-backed contracts.
+ *
+ * The provider reads its own seams off the same object, so callers may still pass a
+ * `LabCompatibilityProviderOptions`; that type extends this one.
+ */
+export type AssemblePolicyEvidenceOptions = CoreEvidenceOptions;
+
+/**
+ * Assemble production policy candidate evidence including compatibility snapshots.
+ * Compatibility work is completely skipped for legacy/no-requirement profiles.
+ * Active compatibility profiles use one catalog snapshot and one bounded SQLite
+ * read for all candidate subject IDs.
+ */
+export function assemblePolicyCandidateEvidence(
+  config: OcxConfig,
+  profile: NormalizedRoutingProfile,
+  now: number,
+  options: AssemblePolicyEvidenceOptions,
+): PolicyCandidateEvidence[] {
+  const compatibilityPolicy = profile.compatibility;
+  const hasCompatibilityRequirements = Boolean(
+    compatibilityPolicy && compatibilityPolicy.requiredSuites.length > 0,
+  );
+  // Compatibility evidence is supplied by an opt-in subsystem. With no provider registered
+  // -- every install without compatibility-gated profiles -- the evaluator sees no
+  // compatibility evidence and scores on capability, health, quota, and cost exactly as it
+  // did before compatibility policy existed.
+  const compatibilityProvider = hasCompatibilityRequirements && compatibilityPolicy
+    ? resolveCompatibilityEvidenceProvider()
+    : null;
+  const compatibilityByCandidate = compatibilityProvider && compatibilityPolicy
+    ? compatibilityProvider(config, profile, compatibilityPolicy, options)
+    : null;
+
+  return profile.candidates.map(candidate => {
+    const key = `${candidate.provider}/${candidate.model}`;
+    const compatibility = compatibilityByCandidate?.get(key);
+
+    return {
+      provider: candidate.provider,
+      model: candidate.model,
+      capability: candidateCapabilityEvidence(config, candidate.provider, candidate.model),
+      health: policyCandidateHealthEvidence(config, candidate, now),
+      quota: quotaEvidenceForCandidate({
+        provider: candidate.provider,
+        model: candidate.model,
+      }),
+      cost: costEvidenceForCandidate({
+        provider: candidate.provider,
+        model: candidate.model,
+        limitUsd: profile.limits.maxEstimatedCostUsd,
+      }),
+      ...(compatibility ? { compatibility } : {}),
+    };
+  });
+}