@iislee/opencodex 2.11.0 → 2.35.0

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/provider-slot.ts

@@ -0,0 +1,56 @@
+/**
+ * Slot for the optional compatibility-evidence provider.
+ *
+ * Routing is synchronous and must stay synchronous: `routeModelInternal` is sync, and so
+ * are the subagent-fallback helpers that call `routeModel` (`isNativeModelQuotaExhausted`,
+ * `isModelHealthBlocked`, `selectAvailableSubagentModel`, ...). Making the chain async to
+ * permit a dynamic import would touch hundreds of call sites and break those APIs, so this
+ * is a plain nullable reference rather than an `await import()`.
+ *
+ * The Lab implementation is installed during activation. Installs without
+ * compatibility-gated routing profiles never register one, so the core evidence assembler
+ * never reaches the Lab module graph.
+ *
+ * See devlog/_fin/260814_lab_core_decoupling/030_router_and_startup_activation.md
+ */
+import type { OcxConfig } from "../../types";
+import type { NormalizedRoutingProfile } from "../profile";
+import type { CandidateCompatibilityEvidence } from "./types";
+
+/** Options the core assembler can supply without knowing anything Lab-specific. */
+export interface CoreEvidenceOptions {
+  configDir?: string;
+  routedProviderConfig: (providerName: string, provider: import("../../types").OcxProviderConfig)
+    => import("../../types").OcxProviderConfig;
+}
+
+/**
+ * Produce compatibility evidence per candidate, keyed `provider/model`.
+ * A candidate absent from the map has no compatibility evidence.
+ */
+export type CompatibilityEvidenceProvider = (
+  config: OcxConfig,
+  profile: NormalizedRoutingProfile,
+  policy: NonNullable<NormalizedRoutingProfile["compatibility"]>,
+  options: CoreEvidenceOptions,
+) => Map<string, CandidateCompatibilityEvidence>;
+
+let provider: CompatibilityEvidenceProvider | null = null;
+
+/** Install the provider. Returns a detach function. */
+export function setCompatibilityEvidenceProvider(next: CompatibilityEvidenceProvider): () => void {
+  provider = next;
+  return () => {
+    if (provider === next) provider = null;
+  };
+}
+
+/** The installed provider, or null when no optional subsystem is active. */
+export function resolveCompatibilityEvidenceProvider(): CompatibilityEvidenceProvider | null {
+  return provider;
+}
+
+/** Test-only reset. */
+export function resetCompatibilityEvidenceProviderForTests(): void {
+  provider = null;
+}

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);
+}

package/src/routing/compatibility/subject.ts

@@ -0,0 +1,191 @@
+import type { OcxConfig, OcxProviderConfig } from "../../types";
+import type { InboundWire } from "../../providers/registry";
+import { subjectIdForSubject } from "../../lab/digest";
+import { buildRouteSubjectV1 } from "../../lab/subject/route-subject";
+import { buildProtocolSubjectV1 } from "../../lab/subject/protocol-subject";
+import { readExistingInstallationSalt } from "../../lab/subject/installation-salt";
+import type { LabDestinationV1, LabRouteContext } from "../../lab/live/types";
+import { resolveWireProtocolOverride } from "../../server/adapter-resolve";
+import { endpointFingerprintFromBaseUrl, parseEndpointFingerprintParts } from "./endpoint";
+import {
+  providerInstanceKey,
+  resolveProductionBehaviorValues,
+  surfaceForProtocols,
+  upstreamProtocolForAdapter,
+} from "./behavior";
+import { readOpenCodexCompatibilityVersion } from "./version";
+import type { RoutingCompatibilityEvidenceLayer } from "./types";
+
+const POLICY_INBOUND_WIRE: InboundWire = "responses";
+
+export interface ResolvedPolicyRouteSubject {
+  subjectId: string;
+  routeContext: LabRouteContext;
+  destination: LabDestinationV1;
+}
+
+export interface ResolvedPolicyCompatibilitySubjects {
+  subjectIds: Partial<Record<RoutingCompatibilityEvidenceLayer, string>>;
+  route?: ResolvedPolicyRouteSubject;
+}
+
+/** Canonical Lab protocol identity for a production request wire. */
+export function inboundProtocolForWire(inboundWire: InboundWire): string {
+  switch (inboundWire) {
+    case "responses": return "openai-responses";
+    case "chat": return "openai-chat";
+    case "anthropic": return "anthropic-messages";
+  }
+}
+
+function destinationSnapshotFromBaseUrl(baseUrl: string, fingerprint: string): LabDestinationV1 {
+  const parts = parseEndpointFingerprintParts(baseUrl);
+  if (!parts) throw new Error("invalid provider baseUrl for route subject");
+  return Object.freeze({
+    scheme: parts.scheme,
+    host: parts.host,
+    port: parts.port,
+    basePath: parts.basePath,
+    sniHost: parts.host,
+    addresses: Object.freeze([]),
+    privateNetwork: false,
+    fingerprint,
+  });
+}
+
+/**
+ * Resolve subject identities for one exact inbound wire without network I/O,
+ * projection reads/rebuilds, ledger replay, or Lab-state creation.
+ */
+export function resolveCompatibilitySubjectsForInboundWire(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+  routed: OcxProviderConfig,
+  inboundWire: InboundWire,
+  configDir?: string,
+): ResolvedPolicyCompatibilitySubjects {
+  const effective = resolveWireProtocolOverride(providerName, modelId, routed, inboundWire);
+  const baseUrl = typeof effective.baseUrl === "string" ? effective.baseUrl.trim() : "";
+  const adapter = effective.adapter ?? "openai-responses";
+  const inboundProtocol = inboundProtocolForWire(inboundWire);
+  const upstreamProtocol = upstreamProtocolForAdapter(adapter);
+  const surface = surfaceForProtocols(inboundProtocol, upstreamProtocol);
+  const subjectIds: ResolvedPolicyCompatibilitySubjects["subjectIds"] = {};
+
+  try {
+    const protocolSubject = buildProtocolSubjectV1({
+      inboundProtocol,
+      upstreamProtocol,
+      surface,
+    }, adapter);
+    subjectIds.protocol_conformance = subjectIdForSubject(protocolSubject);
+  } catch {
+    // No CL-01 protocol subject exists for this exact adapter/wire identity.
+  }
+
+  if (!baseUrl) return { subjectIds };
+
+  let installationSalt: Uint8Array | null;
+  try {
+    installationSalt = readExistingInstallationSalt(configDir);
+  } catch {
+    installationSalt = null;
+  }
+  const compatibilityVersion = readOpenCodexCompatibilityVersion();
+  if (!installationSalt || !compatibilityVersion) return { subjectIds };
+
+  const endpointFp = endpointFingerprintFromBaseUrl(baseUrl, installationSalt);
+  if (!endpointFp) return { subjectIds };
+  const destination = destinationSnapshotFromBaseUrl(baseUrl, endpointFp);
+  const behaviorValues = resolveProductionBehaviorValues(
+    config,
+    providerName,
+    modelId,
+    effective,
+    installationSalt,
+  );
+  if (!behaviorValues) return { subjectIds };
+
+  const routeContext: LabRouteContext = {
+    providerId: providerName,
+    providerInstanceKey: providerInstanceKey(providerName, effective),
+    clientModelId: modelId,
+    upstreamModelId: modelId,
+    effectiveAdapter: adapter,
+    inboundProtocol,
+    upstreamProtocol,
+    surface,
+    baseUrl,
+    opencodexCompatibilityVersion: compatibilityVersion,
+    behaviorValues,
+    dependencies: [],
+  };
+
+  try {
+    const subject = buildRouteSubjectV1(routeContext, destination, configDir, installationSalt);
+    const route: ResolvedPolicyRouteSubject = {
+      subjectId: subjectIdForSubject(subject),
+      routeContext,
+      destination,
+    };
+    subjectIds.live_route_compatibility = route.subjectId;
+    return { subjectIds, route };
+  } catch {
+    return { subjectIds };
+  }
+}
+
+/**
+ * Resolve the subject identities a policy candidate may legitimately consume.
+ * CL-06 policy evaluation is a Responses-surface lookup and remains unchanged.
+ */
+export function resolvePolicyCompatibilitySubjects(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+  routed: OcxProviderConfig,
+  configDir?: string,
+): ResolvedPolicyCompatibilitySubjects {
+  return resolveCompatibilitySubjectsForInboundWire(
+    config,
+    providerName,
+    modelId,
+    routed,
+    POLICY_INBOUND_WIRE,
+    configDir,
+  );
+}
+
+/** Build exact RouteSubjectV1 identity for a policy candidate without network I/O. */
+export function resolvePolicyRouteSubject(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+  routed: OcxProviderConfig,
+  configDir?: string,
+): ResolvedPolicyRouteSubject | null {
+  return resolvePolicyCompatibilitySubjects(config, providerName, modelId, routed, configDir).route ?? null;
+}
+
+/**
+ * Build the exact production-attempt RouteSubjectV1 identity for its actual
+ * inbound wire. Returns null when no existing Lab salt/identity can be read.
+ */
+export function resolveProductionRouteSubject(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+  routed: OcxProviderConfig,
+  inboundWire: InboundWire,
+  configDir?: string,
+): ResolvedPolicyRouteSubject | null {
+  return resolveCompatibilitySubjectsForInboundWire(
+    config,
+    providerName,
+    modelId,
+    routed,
+    inboundWire,
+    configDir,
+  ).route ?? null;
+}

package/src/routing/compatibility/types.ts

@@ -0,0 +1,64 @@
+import type { CompatibilityVerdict, EvidenceLayer } from "../../lab/constants";
+import type { OcxRoutingUnknownEvidenceMode } from "../../types";
+
+export type RoutingCompatibilityEvidenceLayer = Extract<
+  EvidenceLayer,
+  "protocol_conformance" | "live_route_compatibility"
+>;
+
+export interface CompatibilitySuiteRequirement {
+  suiteId: string;
+  evidenceLayer: RoutingCompatibilityEvidenceLayer;
+}
+
+export interface NormalizedCompatibilityPolicy {
+  requiredSuites: CompatibilitySuiteRequirement[];
+  minStatus?: "PROBED" | "VERIFIED";
+  maxEvidenceAgeMs?: number;
+  unknownEvidence: OcxRoutingUnknownEvidenceMode;
+  degradedEvidence: OcxRoutingUnknownEvidenceMode;
+}
+
+export interface ObservedSuiteVerdict {
+  subjectId: string;
+  suiteId: string;
+  evidenceLayer: RoutingCompatibilityEvidenceLayer;
+  suiteVersion: string;
+  suiteManifestDigest: string;
+  verdict: CompatibilityVerdict;
+  asOf: number;
+  /** Current catalog freshness ceiling for this exact suite identity. */
+  maxAgeMs: number | null;
+  notes: string[];
+}
+
+export interface CandidateCompatibilityEvidence {
+  subjectIds: Partial<Record<RoutingCompatibilityEvidenceLayer, string>>;
+  projectionAvailable: boolean;
+  suites: ObservedSuiteVerdict[];
+}
+
+export interface CompatibilityEvaluationOutcome {
+  exclusions: Array<{ code: string; detail?: string }>;
+  /** Numeric floor applied only when an explicit penalize policy fires. */
+  penaltyScore: number | null;
+  suiteTraces: Array<{
+    suiteId: string;
+    evidenceLayer: RoutingCompatibilityEvidenceLayer;
+    subjectIdPrefix?: string;
+    verdict?: CompatibilityVerdict;
+    minStatus?: "PROBED" | "VERIFIED";
+    fresh?: boolean;
+    unknownPolicy?: OcxRoutingUnknownEvidenceMode;
+    degradedPolicy?: OcxRoutingUnknownEvidenceMode;
+    outcome: "satisfied" | "penalized" | "excluded" | "unknown";
+    reason?: string;
+  }>;
+  traceTruncated: boolean;
+}
+
+export const COMPATIBILITY_UNKNOWN_PENALTY_SCORE = 0.3;
+/** Compatibility is a bounded penalty dimension, not a universal score. */
+export const COMPATIBILITY_WEIGHT = 0.05;
+export const MAX_TRACE_COMPATIBILITY_SUITES = 8;
+export const MAX_COMPATIBILITY_REQUIRED_SUITES = MAX_TRACE_COMPATIBILITY_SUITES;