@bitkyc08/opencodex 2.12.0 → 2.13.0

package/src/routing/compatibility/behavior.ts

@@ -0,0 +1,224 @@
+import type { OcxConfig, OcxProviderConfig } from "../../types";
+import { PROVIDER_REGISTRY, type ProviderAuthKind } from "../../providers/registry";
+import { localFingerprint } from "../../lab/digest";
+import type { LabBehaviorSource, LabBehaviorValues } from "../../lab/live/types";
+
+export function upstreamProtocolForAdapter(adapter: string): string {
+  switch (adapter) {
+    case "openai-responses":
+      return "openai-responses";
+    case "openai-chat":
+    case "command-code":
+    case "cursor":
+    case "azure":
+    case "azure-openai":
+    case "kiro":
+    case "mimo-free":
+      return "openai-chat";
+    case "anthropic":
+      return "anthropic-messages";
+    case "google":
+      return "google-generate";
+    default:
+      return "openai-responses";
+  }
+}
+
+export function surfaceForProtocols(inboundProtocol: string, upstreamProtocol: string): string {
+  if (inboundProtocol === "anthropic-messages") return "anthropic-messages-http";
+  if (upstreamProtocol === "anthropic-messages") return "responses-http";
+  if (upstreamProtocol === "openai-chat") return "responses-sse";
+  return "responses-http";
+}
+
+function behaviorRow(source: LabBehaviorSource, value: unknown) {
+  return { source, value };
+}
+
+function includesModel(list: string[] | undefined, modelId: string): boolean {
+  return Array.isArray(list) && list.includes(modelId);
+}
+
+function modelValue<T>(map: Record<string, T> | undefined, modelId: string): T | undefined {
+  return map?.[modelId];
+}
+
+const CREDENTIAL_HEADER = /(authorization|api[-_]?key|token|secret|credential|cookie)/i;
+
+function nonCredentialHeaderDigest(
+  headers: Record<string, string> | undefined,
+  installationSalt: Uint8Array | string,
+): string {
+  const rows = Object.entries(headers ?? {})
+    .filter(([name]) => !CREDENTIAL_HEADER.test(name))
+    .map(([name, value]) => [name.toLowerCase().trim(), value] as const)
+    .sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  return localFingerprint("nonCredentialHeaders", rows, installationSalt);
+}
+
+function authTransportFor(
+  effective: OcxProviderConfig,
+  adapter: string,
+  mode: ProviderAuthKind,
+): string {
+  if (mode === "oauth") return "oauth_bearer";
+  if (mode === "forward") return "forwarded_authorization";
+  if (mode === "local") return "none";
+  if (adapter === "anthropic" && effective.apiKeyTransport !== "bearer") return "x_api_key";
+  return "authorization_bearer";
+}
+
+function effectiveOpenRouterRouting(effective: OcxProviderConfig, modelId: string) {
+  return effective.modelOpenRouterRouting?.[modelId] ?? effective.openRouterRouting;
+}
+
+/**
+ * Production behavior resolver for route-subject fingerprinting.
+ *
+ * The caller supplies the already-resolved effective provider config. This is
+ * deliberately the same effective config used for routeContext identity so a
+ * model wire override cannot disagree with the behavior fingerprint.
+ */
+export function resolveProductionBehaviorValues(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+  effective: OcxProviderConfig,
+  installationSalt: Uint8Array | string,
+): LabBehaviorValues | null {
+  const provider = config.providers[providerName];
+  if (!provider || provider.disabled === true) return null;
+  const adapter = effective.adapter ?? "openai-responses";
+  const upstreamProtocol = upstreamProtocolForAdapter(adapter);
+  const registryEntry = PROVIDER_REGISTRY.find(entry => entry.id === providerName);
+  const authMode = effective.authMode ?? registryEntry?.authKind ?? "key";
+  const reasoningEfforts = modelValue(effective.modelReasoningEfforts, modelId)
+    ?? effective.reasoningEfforts
+    ?? [];
+  const defaultReasoningEffort = modelValue(effective.modelDefaultReasoningEfforts, modelId) ?? null;
+  const reasoningEffortMap = modelValue(effective.modelReasoningEffortMap, modelId)
+    ?? effective.reasoningEffortMap
+    ?? {};
+  const openRouterRouting = effectiveOpenRouterRouting(effective, modelId);
+  const project = typeof effective.project === "string" && effective.project ? effective.project : null;
+  const location = typeof effective.location === "string" && effective.location ? effective.location : null;
+  const nativeLocalExec = effective.nativeLocalExec === "on" || effective.unsafeAllowNativeLocalExec === true;
+
+  const values: LabBehaviorValues = {
+    "wire.adapter": behaviorRow("provider_config", adapter),
+    "wire.upstreamProtocol": behaviorRow("provider_config", upstreamProtocol),
+    "wire.responsesPath": behaviorRow("provider_config", effective.responsesPath ?? null),
+    "wire.commandCodeVersion": behaviorRow("provider_config", effective.commandCodeVersion ?? null),
+    "wire.modelSuffixMode": behaviorRow(
+      "provider_config",
+      effective.modelSuffixBracketStrip === true ? "bracket_strip" : "none",
+    ),
+    "auth.mode": behaviorRow("provider_config", authMode),
+    "auth.transport": behaviorRow("provider_config", authTransportFor(effective, adapter, authMode)),
+    "responses.stateful": behaviorRow("provider_config", effective.statelessResponses !== true),
+    "responses.serviceTier": behaviorRow("provider_config", effective.supportsServiceTier ?? null),
+    "responses.snapshotRepair": behaviorRow("provider_config", effective.responsesSnapshotRepair === true),
+    "responses.itemIdRepair": behaviorRow("provider_config", effective.responsesItemIdRepair ?? null),
+    "limits.contextWindow": behaviorRow(
+      "provider_config",
+      modelValue(effective.modelContextWindows, modelId) ?? effective.contextWindow ?? null,
+    ),
+    "limits.maxInputTokens": behaviorRow(
+      "provider_config",
+      modelValue(effective.modelMaxInputTokens, modelId) ?? null,
+    ),
+    "limits.maxOutputTokens": behaviorRow(
+      "provider_config",
+      modelValue(effective.modelMaxOutputTokens, modelId) ?? effective.defaultMaxOutputTokens ?? null,
+    ),
+    "modalities.input": behaviorRow(
+      "provider_config",
+      modelValue(effective.modelInputModalities, modelId) ?? ["text"],
+    ),
+    "sampling.omitTemperature": behaviorRow("provider_config", includesModel(effective.noTemperatureModels, modelId)),
+    "sampling.omitTopP": behaviorRow("provider_config", includesModel(effective.noTopPModels, modelId)),
+    "sampling.omitPenalties": behaviorRow("provider_config", includesModel(effective.noPenaltyModels, modelId)),
+    "reasoning.supported": behaviorRow(
+      "provider_config",
+      includesModel(effective.noReasoningModels, modelId)
+        ? false
+        : reasoningEfforts.length > 0 || Boolean(registryEntry?.reasoningEfforts),
+    ),
+    "reasoning.efforts": behaviorRow("provider_config", reasoningEfforts),
+    "reasoning.defaultEffort": behaviorRow("provider_config", defaultReasoningEffort),
+    "reasoning.effortMap": behaviorRow("provider_config", reasoningEffortMap),
+    "reasoning.wireFormat": behaviorRow("provider_config", effective.reasoningWireFormat ?? null),
+    "reasoning.summaryMode": behaviorRow("provider_config", {
+      supported: modelValue(effective.modelSupportsReasoningSummaries, modelId) ?? null,
+      delivery: modelValue(effective.modelReasoningSummaryDelivery, modelId) ?? null,
+    }),
+    "reasoning.replayMode": behaviorRow("provider_config", {
+      preserveResponses: effective.preserveResponsesReasoningContent === true,
+      preserveContent: includesModel(effective.preserveReasoningContentModels, modelId),
+      placeholder: includesModel(effective.requiresReasoningPlaceholderModels, modelId),
+    }),
+    "reasoning.splitMode": behaviorRow("provider_config", includesModel(effective.reasoningSplitModels, modelId)),
+    "reasoning.toggleMode": behaviorRow("provider_config", includesModel(effective.thinkingToggleModels, modelId)),
+    "reasoning.budgetMode": behaviorRow("provider_config", includesModel(effective.thinkingBudgetModels, modelId)),
+    "tools.choiceRestrictions": behaviorRow(
+      "provider_config",
+      includesModel(effective.autoToolChoiceOnlyModels, modelId) ? ["auto"] : [],
+    ),
+    "tools.parallel": behaviorRow(
+      "provider_config",
+      effective.parallelToolCalls ?? (upstreamProtocol === "openai-chat"),
+    ),
+    "tools.hostedPreference": behaviorRow("provider_config", {
+      tools: modelValue(effective.modelPreferHostedTools, modelId) ?? [],
+    }),
+    "tools.builtinNameEscaping": behaviorRow("provider_config", effective.escapeBuiltinToolNames === true),
+    "cache.forwarding": behaviorRow("provider_config", effective.promptCacheKey === true),
+    "cache.retention": behaviorRow("global_config", config.cacheRetention ?? "short"),
+    "anthropic.eofPolicy": behaviorRow("provider_config", effective.anthropicEofTolerance === true ? "tolerant" : "strict"),
+    "google.mode": behaviorRow("provider_config", effective.googleMode ?? null),
+    "google.projectFingerprint": behaviorRow(
+      "provider_config",
+      project ? localFingerprint("googleProject", project, installationSalt) : null,
+    ),
+    "google.locationFingerprint": behaviorRow(
+      "provider_config",
+      location ? localFingerprint("googleLocation", location, installationSalt) : null,
+    ),
+    "openrouter.order": behaviorRow("provider_config", openRouterRouting?.order ?? []),
+    "openrouter.only": behaviorRow("provider_config", openRouterRouting?.only ?? []),
+    "openrouter.allowFallbacks": behaviorRow("provider_config", openRouterRouting?.allowFallbacks ?? null),
+    "sidecars.vision": behaviorRow(
+      "global_config",
+      localFingerprint("visionSidecar", config.visionSidecar ?? null, installationSalt),
+    ),
+    "sidecars.webSearch": behaviorRow(
+      "global_config",
+      localFingerprint("webSearchSidecar", config.webSearchSidecar ?? null, installationSalt),
+    ),
+    "mcp.maxTools": behaviorRow("provider_config", effective.mcpMaxTools ?? null),
+    "mcp.maxSchemaBytes": behaviorRow("provider_config", effective.mcpMaxSchemaBytes ?? null),
+    "mcp.maxResultBytes": behaviorRow("provider_config", effective.mcpMaxResultBytes ?? null),
+    "mcp.nativeLocalExec": behaviorRow("provider_config", nativeLocalExec),
+    "runtime.bunVersion": behaviorRow("registry_runtime_default", Bun.version),
+    "runtime.platform": behaviorRow("registry_runtime_default", process.platform),
+    "runtime.arch": behaviorRow("registry_runtime_default", process.arch),
+    "runtime.streamMode": behaviorRow("global_config", config.streamMode ?? "auto"),
+    "runtime.fastMode": behaviorRow("global_config", config.fastMode === true),
+    "runtime.effortCap": behaviorRow("global_config", config.effortCap ?? null),
+    "headers.nonCredentialBehaviorDigest": behaviorRow(
+      "provider_config",
+      nonCredentialHeaderDigest(effective.headers, installationSalt),
+    ),
+  };
+
+  return values;
+}
+
+export function providerInstanceKey(
+  providerName: string,
+  effective: OcxProviderConfig,
+): string {
+  const baseUrl = typeof effective.baseUrl === "string" ? effective.baseUrl.trim() : "";
+  const adapter = typeof effective.adapter === "string" ? effective.adapter : "";
+  return `${providerName}\0${baseUrl}\0${adapter}`;
+}

package/src/routing/compatibility/catalog.ts

@@ -0,0 +1,99 @@
+import { queryLabCatalog } from "../../lab/query/catalog";
+import type { CatalogScenarioDto } from "../../lab/query/types";
+import type {
+  CompatibilitySuiteRequirement,
+  RoutingCompatibilityEvidenceLayer,
+} from "./types";
+
+export interface CompatibilityCatalogSuite {
+  suiteId: string;
+  evidenceLayer: RoutingCompatibilityEvidenceLayer;
+  suiteVersion: string;
+  suiteManifestDigest: string;
+  maxAgeMs: number | null;
+}
+
+export type CompatibilityCatalogSnapshot = Map<string, CompatibilityCatalogSuite>;
+
+export function compatibilitySuiteKey(
+  evidenceLayer: RoutingCompatibilityEvidenceLayer,
+  suiteId: string,
+): string {
+  return `${evidenceLayer}:${suiteId}`;
+}
+
+function scenarioMaxAge(row: CatalogScenarioDto): number | null | undefined {
+  if (!row.freshness || typeof row.freshness !== "object") return undefined;
+  if (!Object.hasOwn(row.freshness, "maxAgeMs")) return undefined;
+  const value = row.freshness.maxAgeMs;
+  if (value === null) return null;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) return undefined;
+  return value;
+}
+
+/**
+ * Resolve current suite identities/freshness once per evidence layer before a
+ * routing evaluation. The pure evaluator never performs manifest I/O.
+ */
+export function loadCompatibilityCatalogSnapshot(
+  requirements: readonly CompatibilitySuiteRequirement[],
+): CompatibilityCatalogSnapshot {
+  const wanted = new Map<RoutingCompatibilityEvidenceLayer, Set<string>>();
+  for (const requirement of requirements) {
+    const suites = wanted.get(requirement.evidenceLayer) ?? new Set<string>();
+    suites.add(requirement.suiteId);
+    wanted.set(requirement.evidenceLayer, suites);
+  }
+
+  const out: CompatibilityCatalogSnapshot = new Map();
+  const invalid = new Set<string>();
+
+  for (const [layer, suiteIds] of wanted) {
+    let rows: CatalogScenarioDto[];
+    try {
+      rows = queryLabCatalog({ layer });
+    } catch {
+      // Catalog/manifest failure is fail-safe: affected requirements become
+      // missing evidence and follow the profile's unknown-evidence policy.
+      continue;
+    }
+
+    for (const row of rows) {
+      if (!suiteIds.has(row.suiteId)) continue;
+      const key = compatibilitySuiteKey(layer, row.suiteId);
+      if (invalid.has(key)) continue;
+      const maxAgeMs = scenarioMaxAge(row);
+      if (maxAgeMs === undefined) {
+        out.delete(key);
+        invalid.add(key);
+        continue;
+      }
+
+      const prior = out.get(key);
+      if (prior && (
+        prior.suiteVersion !== row.suiteVersion
+        || prior.suiteManifestDigest !== row.suiteManifestDigest
+      )) {
+        // One current suite id must have one exact version/digest identity.
+        out.delete(key);
+        invalid.add(key);
+        continue;
+      }
+
+      const effectiveMaxAge = prior?.maxAgeMs == null
+        ? maxAgeMs
+        : maxAgeMs == null
+          ? prior.maxAgeMs
+          : Math.min(prior.maxAgeMs, maxAgeMs);
+      out.set(key, {
+        suiteId: row.suiteId,
+        evidenceLayer: layer,
+        suiteVersion: row.suiteVersion,
+        suiteManifestDigest: row.suiteManifestDigest,
+        maxAgeMs: effectiveMaxAge,
+      });
+    }
+  }
+
+  return out;
+}

package/src/routing/compatibility/endpoint.ts

@@ -0,0 +1,52 @@
+/**
+ * DNS-free endpoint fingerprint for routing-time route subject construction.
+ * Mirrors the snapshot fields hashed in `createLabDestination` without resolution.
+ */
+import { localFingerprint } from "../../lab/digest";
+
+function normalizeBasePath(pathname: string): string {
+  if (!pathname || pathname === "/") return "";
+  const trimmed = pathname.endsWith("/") ? pathname.slice(0, -1) : pathname;
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+export interface EndpointFingerprintParts {
+  scheme: "http" | "https";
+  host: string;
+  port: number;
+  basePath: string;
+}
+
+/** Parse and normalize a provider base URL without network I/O. */
+export function parseEndpointFingerprintParts(baseUrl: string): EndpointFingerprintParts | null {
+  try {
+    const parsed = new URL(baseUrl);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    if (parsed.username || parsed.password || parsed.search || parsed.hash) return null;
+    const scheme = parsed.protocol === "https:" ? "https" as const : "http" as const;
+    const port = parsed.port ? Number(parsed.port) : scheme === "https" ? 443 : 80;
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) return null;
+    return {
+      scheme,
+      host: parsed.hostname.toLowerCase(),
+      port,
+      basePath: normalizeBasePath(parsed.pathname),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function endpointFingerprintFromBaseUrl(
+  baseUrl: string,
+  installationSalt: Uint8Array | string,
+): string | null {
+  const parts = parseEndpointFingerprintParts(baseUrl);
+  if (!parts) return null;
+  return localFingerprint("endpoint", {
+    scheme: parts.scheme,
+    host: parts.host,
+    port: parts.port,
+    basePath: parts.basePath,
+  }, installationSalt);
+}

package/src/routing/compatibility/policy.ts

@@ -0,0 +1,181 @@
+import type { CompatibilityVerdict } from "../../lab/constants";
+import type { NormalizedRoutingProfileCompatibility } from "../profile";
+import type {
+  CandidateCompatibilityEvidence,
+  CompatibilityEvaluationOutcome,
+} from "./types";
+import { COMPATIBILITY_UNKNOWN_PENALTY_SCORE, MAX_TRACE_COMPATIBILITY_SUITES } from "./types";
+import type { RouteCompatibilityEvidence } from "../trace";
+
+function positiveThresholdMet(
+  verdict: CompatibilityVerdict,
+  minStatus: "PROBED" | "VERIFIED" | undefined,
+): boolean {
+  if (!minStatus) return true;
+  if (minStatus === "PROBED") return verdict === "PROBED" || verdict === "VERIFIED";
+  return verdict === "VERIFIED";
+}
+
+function effectiveMaxAgeMs(
+  catalogMaxAgeMs: number | null,
+  profileMaxAgeMs: number | undefined,
+): number | null {
+  if (catalogMaxAgeMs === null) return profileMaxAgeMs ?? null;
+  if (profileMaxAgeMs === undefined) return catalogMaxAgeMs;
+  return Math.min(catalogMaxAgeMs, profileMaxAgeMs);
+}
+
+function mergePenalty(current: number | null, next: number | null): number | null {
+  if (current === null) return next;
+  if (next === null) return current;
+  return Math.min(current, next);
+}
+
+function applyUnknownPolicy(
+  policy: NormalizedRoutingProfileCompatibility["unknownEvidence"],
+  code: string,
+  detail: string,
+): Pick<CompatibilityEvaluationOutcome, "exclusions" | "penaltyScore"> {
+  if (policy === "exclude") {
+    return { exclusions: [{ code, detail }], penaltyScore: null };
+  }
+  if (policy === "penalize") {
+    return { exclusions: [], penaltyScore: COMPATIBILITY_UNKNOWN_PENALTY_SCORE };
+  }
+  return { exclusions: [], penaltyScore: null };
+}
+
+export function evaluateCompatibilityForCandidate(
+  policy: NormalizedRoutingProfileCompatibility | undefined,
+  evidence: CandidateCompatibilityEvidence | undefined,
+  now = Date.now(),
+): CompatibilityEvaluationOutcome & { trace?: RouteCompatibilityEvidence } {
+  const outcome: CompatibilityEvaluationOutcome = {
+    exclusions: [],
+    penaltyScore: null,
+    suiteTraces: [],
+    traceTruncated: false,
+  };
+  if (!policy || policy.requiredSuites.length === 0) return outcome;
+
+  const pushTrace = (entry: CompatibilityEvaluationOutcome["suiteTraces"][number]): void => {
+    if (outcome.suiteTraces.length < MAX_TRACE_COMPATIBILITY_SUITES) {
+      outcome.suiteTraces.push(entry);
+    } else {
+      outcome.traceTruncated = true;
+    }
+  };
+
+  let penaltyScore: number | null = null;
+  for (const requirement of policy.requiredSuites) {
+    const subjectId = evidence?.subjectIds[requirement.evidenceLayer];
+    const row = evidence?.suites.find(suite =>
+      suite.subjectId === subjectId
+      && suite.suiteId === requirement.suiteId
+      && suite.evidenceLayer === requirement.evidenceLayer);
+    const maxAgeMs = row
+      ? effectiveMaxAgeMs(row.maxAgeMs, policy.maxEvidenceAgeMs)
+      : policy.maxEvidenceAgeMs ?? null;
+    const ageMs = row ? now - row.asOf : Number.POSITIVE_INFINITY;
+    const fresh = row ? ageMs >= 0 && (maxAgeMs === null || ageMs <= maxAgeMs) : false;
+    const verdict = row?.verdict;
+
+    const trace = {
+      suiteId: requirement.suiteId,
+      evidenceLayer: requirement.evidenceLayer,
+      ...(subjectId ? { subjectIdPrefix: subjectId.slice(0, 16) } : {}),
+      ...(verdict ? { verdict } : {}),
+      ...(policy.minStatus ? { minStatus: policy.minStatus } : {}),
+      fresh,
+      unknownPolicy: policy.unknownEvidence,
+      degradedPolicy: policy.degradedEvidence,
+      outcome: "unknown" as const,
+    };
+
+    if (!subjectId) {
+      const applied = applyUnknownPolicy(policy.unknownEvidence, "compatibility-unknown", requirement.suiteId);
+      outcome.exclusions.push(...applied.exclusions);
+      penaltyScore = mergePenalty(penaltyScore, applied.penaltyScore);
+      pushTrace({
+        ...trace,
+        outcome: applied.exclusions.length ? "excluded" : applied.penaltyScore !== null ? "penalized" : "unknown",
+        reason: "subject-unresolved",
+      });
+      continue;
+    }
+
+    if (!evidence?.projectionAvailable) {
+      const applied = applyUnknownPolicy(policy.unknownEvidence, "compatibility-unknown", requirement.suiteId);
+      outcome.exclusions.push(...applied.exclusions);
+      penaltyScore = mergePenalty(penaltyScore, applied.penaltyScore);
+      pushTrace({
+        ...trace,
+        outcome: applied.exclusions.length ? "excluded" : applied.penaltyScore !== null ? "penalized" : "unknown",
+        reason: "projection-unavailable",
+      });
+      continue;
+    }
+
+    if (!row || !fresh) {
+      const applied = applyUnknownPolicy(
+        policy.unknownEvidence,
+        row && !fresh ? "compatibility-stale" : "compatibility-unknown",
+        requirement.suiteId,
+      );
+      outcome.exclusions.push(...applied.exclusions);
+      penaltyScore = mergePenalty(penaltyScore, applied.penaltyScore);
+      pushTrace({
+        ...trace,
+        outcome: applied.exclusions.length ? "excluded" : applied.penaltyScore !== null ? "penalized" : "unknown",
+        reason: !row ? "missing-evidence" : "stale-evidence",
+      });
+      continue;
+    }
+
+    if (verdict === "UNSUPPORTED") {
+      outcome.exclusions.push({ code: "compatibility-unsupported", detail: requirement.suiteId });
+      pushTrace({ ...trace, outcome: "excluded", reason: "unsupported" });
+      continue;
+    }
+
+    if (verdict === "DEGRADED") {
+      if (policy.degradedEvidence === "exclude") {
+        outcome.exclusions.push({ code: "compatibility-degraded", detail: requirement.suiteId });
+        pushTrace({ ...trace, outcome: "excluded", reason: "degraded" });
+      } else if (policy.degradedEvidence === "penalize") {
+        penaltyScore = mergePenalty(penaltyScore, COMPATIBILITY_UNKNOWN_PENALTY_SCORE);
+        pushTrace({ ...trace, outcome: "penalized", reason: "degraded" });
+      } else {
+        pushTrace({ ...trace, outcome: "satisfied", reason: "degraded-allowed" });
+      }
+      continue;
+    }
+
+    if (verdict === "UNKNOWN" || verdict === "CLAIMED" || verdict === "BLOCKED") {
+      const applied = applyUnknownPolicy(policy.unknownEvidence, "compatibility-unknown", requirement.suiteId);
+      outcome.exclusions.push(...applied.exclusions);
+      penaltyScore = mergePenalty(penaltyScore, applied.penaltyScore);
+      pushTrace({
+        ...trace,
+        outcome: applied.exclusions.length ? "excluded" : applied.penaltyScore !== null ? "penalized" : "unknown",
+        reason: verdict.toLowerCase(),
+      });
+      continue;
+    }
+
+    if (!positiveThresholdMet(verdict!, policy.minStatus)) {
+      outcome.exclusions.push({ code: "compatibility-insufficient", detail: requirement.suiteId });
+      pushTrace({ ...trace, outcome: "excluded", reason: "below-min-status" });
+      continue;
+    }
+
+    pushTrace({ ...trace, outcome: "satisfied", reason: "threshold-met" });
+  }
+
+  outcome.penaltyScore = penaltyScore;
+  const trace: RouteCompatibilityEvidence = {
+    suites: outcome.suiteTraces,
+    ...(outcome.traceTruncated ? { truncated: true } : {}),
+  };
+  return { ...outcome, trace };
+}

package/src/routing/compatibility/reader.ts

@@ -0,0 +1,110 @@
+import type { CompatibilityVerdict, EvidenceLayer } from "../../lab/constants";
+import { closeLabReadConnection, openLabReadConnection } from "../../lab/query/connection";
+
+export interface VerdictRow {
+  subjectId: string;
+  evidenceLayer: EvidenceLayer;
+  suiteId: string;
+  suiteVersion: string;
+  suiteManifestDigest: string;
+  verdict: CompatibilityVerdict;
+  asOf: number;
+  notes: string[];
+}
+
+export interface CompatibilityEvidenceSnapshot {
+  projectionAvailable: boolean;
+  projectionIncompatible: boolean;
+  bySubject: Map<string, VerdictRow[]>;
+}
+
+function parseNotes(raw: string): string[] {
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return Array.isArray(parsed) ? parsed.filter((item): item is string => typeof item === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Bounded read-only compatibility verdict snapshot for routing evaluation.
+ * One connection + one query for all subject IDs.
+ */
+export function loadCompatibilityEvidenceSnapshot(
+  subjectIds: readonly string[],
+  configDir?: string,
+): CompatibilityEvidenceSnapshot {
+  const empty: CompatibilityEvidenceSnapshot = {
+    projectionAvailable: false,
+    projectionIncompatible: false,
+    bySubject: new Map(),
+  };
+  if (subjectIds.length === 0) return { ...empty, projectionAvailable: true };
+
+  try {
+    const conn = openLabReadConnection(configDir);
+    try {
+      const uniqueSubjectIds = [...new Set(subjectIds)];
+      const placeholders = uniqueSubjectIds.map(() => "?").join(", ");
+      const rows = conn.db.prepare(
+        `SELECT subject_id, evidence_layer, suite_id, suite_version, suite_manifest_digest, verdict, as_of, notes_json
+         FROM verdicts
+         WHERE subject_id IN (${placeholders})`,
+      ).all(...uniqueSubjectIds) as Array<{
+        subject_id: string;
+        evidence_layer: string;
+        suite_id: string;
+        suite_version: string;
+        suite_manifest_digest: string;
+        verdict: string;
+        as_of: number;
+        notes_json: string;
+      }>;
+
+      const bySubject = new Map<string, VerdictRow[]>();
+      for (const row of rows) {
+        const list = bySubject.get(row.subject_id) ?? [];
+        list.push({
+          subjectId: row.subject_id,
+          evidenceLayer: row.evidence_layer as EvidenceLayer,
+          suiteId: row.suite_id,
+          suiteVersion: row.suite_version,
+          suiteManifestDigest: row.suite_manifest_digest,
+          verdict: row.verdict as CompatibilityVerdict,
+          asOf: row.as_of,
+          notes: parseNotes(row.notes_json),
+        });
+        bySubject.set(row.subject_id, list);
+      }
+      return { projectionAvailable: true, projectionIncompatible: false, bySubject };
+    } finally {
+      closeLabReadConnection(conn);
+    }
+  } catch (err) {
+    if (err && typeof err === "object" && "code" in err) {
+      const code = String((err as { code: unknown }).code);
+      if (code === "lab_projection_incompatible") {
+        return { projectionAvailable: false, projectionIncompatible: true, bySubject: new Map() };
+      }
+    }
+    return empty;
+  }
+}
+
+/** Match the current canonical projection identity, never a stale suite revision. */
+export function findVerdictForSuite(
+  snapshot: CompatibilityEvidenceSnapshot,
+  subjectId: string,
+  evidenceLayer: EvidenceLayer,
+  suiteId: string,
+  suiteVersion: string,
+  suiteManifestDigest: string,
+): VerdictRow | undefined {
+  const rows = snapshot.bySubject.get(subjectId) ?? [];
+  return rows.find(row =>
+    row.evidenceLayer === evidenceLayer
+    && row.suiteId === suiteId
+    && row.suiteVersion === suiteVersion
+    && row.suiteManifestDigest === suiteManifestDigest);
+}