@bitkyc08/opencodex 2.12.0 → 2.13.0

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;

package/src/routing/compatibility/version.ts

@@ -0,0 +1,104 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { jcsStringify } from "../../lab/digest";
+
+const VERSION_DOMAIN = "ocx-lab:compatibility-version:v1";
+let cachedVersion: string | null | undefined;
+let testOverride: string | null | undefined;
+
+interface CompatibilityVersionManifest {
+  schemaVersion: 1;
+  assertionDslVersion: string;
+  evidenceSchemaVersion: string;
+  bunRuntimeVersion: string;
+  files: Array<{ path: string; sha256: string }>;
+}
+
+function isSha256Hex(value: string): boolean {
+  return /^[0-9a-f]{64}$/.test(value);
+}
+
+function hashManifest(manifest: unknown): string {
+  const hash = createHash("sha256");
+  hash.update(new TextEncoder().encode(`${VERSION_DOMAIN}\0`));
+  hash.update(new TextEncoder().encode(jcsStringify(manifest)));
+  return hash.digest("hex");
+}
+
+function parseEmbeddedManifest(raw: unknown): CompatibilityVersionManifest | null {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const record = raw as Record<string, unknown>;
+  if (record.schemaVersion !== 1
+    || typeof record.assertionDslVersion !== "string"
+    || typeof record.evidenceSchemaVersion !== "string"
+    || typeof record.bunRuntimeVersion !== "string"
+    || !Array.isArray(record.files)
+    || record.files.length === 0) return null;
+  const files: CompatibilityVersionManifest["files"] = [];
+  const seen = new Set<string>();
+  for (const row of record.files) {
+    if (!row || typeof row !== "object" || Array.isArray(row)) return null;
+    const path = (row as Record<string, unknown>).path;
+    const sha256 = (row as Record<string, unknown>).sha256;
+    if (typeof path !== "string" || !path || path.includes("\\") || path.startsWith("/") || path.split("/").includes("..")) return null;
+    if (typeof sha256 !== "string" || !isSha256Hex(sha256) || seen.has(path)) return null;
+    seen.add(path);
+    files.push({ path, sha256 });
+  }
+  return {
+    schemaVersion: 1,
+    assertionDslVersion: record.assertionDslVersion,
+    evidenceSchemaVersion: record.evidenceSchemaVersion,
+    // The runtime version is part of the canonical identity. The embedded file
+    // hashes remain valid across bundled Bun updates, while this field reflects
+    // the actual executing runtime rather than the package-build runtime.
+    bunRuntimeVersion: Bun.version,
+    files,
+  };
+}
+
+function readEmbeddedManifest(): CompatibilityVersionManifest | null {
+  const candidates = [
+    join(import.meta.dir, "..", "..", "generated", "compatibility-version.json"),
+    join(import.meta.dir, "..", "..", "..", "src", "generated", "compatibility-version.json"),
+  ];
+  for (const path of candidates) {
+    try {
+      const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+      const manifest = parseEmbeddedManifest(parsed);
+      if (manifest) return manifest;
+    } catch {
+      // try next candidate
+    }
+  }
+  return null;
+}
+
+/**
+ * OpenCodex compatibility version for route subject identity.
+ *
+ * There is intentionally no runtime-only fallback: without the generated file
+ * manifest we cannot prove exact implementation identity, so live-route subject
+ * resolution fails closed and follows the profile's unknown-evidence policy.
+ */
+export function readOpenCodexCompatibilityVersion(): string | null {
+  if (testOverride !== undefined) return testOverride;
+  if (cachedVersion !== undefined) return cachedVersion;
+  const embedded = readEmbeddedManifest();
+  cachedVersion = embedded ? hashManifest(embedded) : null;
+  return cachedVersion;
+}
+
+/** Test-only exact identity override; never sourced from process environment. */
+export function setCompatibilityVersionOverrideForTests(value: string | null): void {
+  if (value !== null && !isSha256Hex(value)) throw new Error("invalid test compatibility version");
+  testOverride = value;
+  cachedVersion = undefined;
+}
+
+/** Test-only reset of the compatibility version memo and override. */
+export function resetCompatibilityVersionCacheForTests(): void {
+  cachedVersion = undefined;
+  testOverride = undefined;
+}

package/src/routing/evaluator.ts

@@ -24,6 +24,9 @@ import { getRoutingProfile, policyModelId, type NormalizedRoutingProfile } from
 import { healthScore } from "./health";
 import { quotaScore } from "./quota";
 import { costScore } from "./cost";
+import { evaluateCompatibilityForCandidate } from "./compatibility/policy";
+import { COMPATIBILITY_WEIGHT, type CandidateCompatibilityEvidence } from "./compatibility/types";
+import type { RouteCompatibilityEvidence } from "./trace";
 
 /** Unknown health under "penalize": a low-but-not-zero deterministic floor. */
 export const HEALTH_UNKNOWN_PENALTY_SCORE = 0.3;
@@ -55,6 +58,7 @@ export interface PolicyCandidateEvidence {
   health?: RouteHealthEvidence;
   quota?: RouteQuotaEvidence;
   cost?: RouteCostEvidence;
+  compatibility?: CandidateCompatibilityEvidence;
 }
 
 export interface PolicyEvaluationCandidate {
@@ -68,6 +72,7 @@ export interface PolicyEvaluationCandidate {
   health?: RouteHealthEvidence;
   quota?: RouteQuotaEvidence;
   cost?: RouteCostEvidence;
+  compatibility?: RouteCompatibilityEvidence;
   score?: RouteScoreEvidence;
 }
 
@@ -85,8 +90,6 @@ function booleanRequirement(
   actual: Unknownable | undefined,
 ): RouteRequirementEvidence | null {
   if (required === undefined) return null;
-  // Note: `required === false` is a negative assertion ("must NOT have X"),
-  // not "don't care"; an absent field is the only "no requirement" form.
   if (actual === undefined || actual === "unknown") {
     return { id, expected: required, outcome: "unknown" };
   }
@@ -117,11 +120,6 @@ function requirementFor(
       requirements.push({ id: "min-context-window", expected: require.minContextWindow, outcome: "unknown" });
     }
   }
-  // minQuotaHeadroom gates only KNOWN quota via the normalized score, which
-  // maps exhaustion to zero and unknown/incomplete evidence to null. Unknown
-  // quota is governed by the profile's `unknownEvidence.quota` policy
-  // (exclude / penalize / allow) via the quota score path - never by the
-  // capability unknown policy.
   if (require.minQuotaHeadroom !== undefined) {
     const quotaHeadroom = quotaScore(quota);
     if (quotaHeadroom !== null) {
@@ -186,12 +184,6 @@ function configuredPriorityScore(index: number, total: number): number {
   return total > 1 ? (total - index) / total : 1;
 }
 
-/**
- * Requirements derived from the request evidence supplied to a dry-run. A
- * candidate must satisfy both the profile `require` block and the request
- * needs (context window, tools, image input, structured output, reasoning
- * effort, service tier, encrypted Codex tasks) to be eligible.
- */
 function requestRequirementFor(
   request: PolicyRequestEvidence,
   capability: RouteCapabilityEvidence | undefined,
@@ -210,7 +202,6 @@ function requestRequirementFor(
       requirements.push({ id: "request-context-window", expected: request.contextWindow, outcome: "unknown" });
     }
   }
-  // Absent flags mean "no requirement": only a positive request need adds a row.
   if (request.toolsRequired === true) {
     const tools = booleanRequirement("request-tools", true, capability?.tools);
     if (tools) requirements.push(tools);
@@ -297,10 +288,6 @@ export function evaluatePolicyProfile(
     }
     const unsatisfied = bad.some(requirement => requirement.outcome === "unsatisfied");
     const unknown = bad.some(requirement => requirement.outcome === "unknown");
-    // Unknown capability handling per profile: exclude (default), penalize,
-    // or allow. "penalize" cannot move the score while configuredPriorityScore
-    // is the only component; the capability score dimension is still future
-    // (RI-06+), so "penalize" behaves identically to "allow" in this release.
     const excludedByUnknown = unknown && profile.unknownEvidence.capability === "exclude";
     const costLimit = profile.limits.maxEstimatedCostUsd;
     const estimatedCost = evidence.cost?.estimatedUsd;
@@ -357,9 +344,18 @@ export function evaluatePolicyProfile(
       }
     }
 
-    // Health scoring (RI-06): live hard cooldown is authoritative and
-    // excludes; unknown health follows the profile's unknownEvidence policy;
-    // historical health never overrides explicit ineligibility.
+    const compatibilityEval = evaluateCompatibilityForCandidate(
+      profile.compatibility,
+      evidence.compatibility,
+      now,
+    );
+    if (compatibilityEval.exclusions.length > 0) {
+      exclusions.push(...compatibilityEval.exclusions);
+      eligible = false;
+    }
+    const compatibilityValue = compatibilityEval.penaltyScore;
+    const compatibilityTrace = compatibilityEval.trace;
+
     const health = evidence.health;
     let healthValue = health ? healthScore(health, now) : null;
     if (health?.cooldownUntilMs !== undefined && health.cooldownUntilMs > now) {
@@ -371,13 +367,9 @@ export function evaluatePolicyProfile(
     } else if (healthValue === null && profile.unknownEvidence.health === "penalize") {
       healthValue = HEALTH_UNKNOWN_PENALTY_SCORE;
     } else if (healthValue === null && profile.unknownEvidence.health === "allow") {
-      // Neutral midpoint: blending keeps an unknown candidate from outranking
-      // a measured one with the same configured priority.
       healthValue = HEALTH_UNKNOWN_NEUTRAL_SCORE;
     }
 
-    // Quota scoring (RI-07): unknown quota follows the profile policy;
-    // exhausted or low-headroom evidence lowers the score.
     const quota = evidence.quota;
     let quotaValue = quota ? quotaScore(quota) : null;
     if (quotaValue === null) {
@@ -406,11 +398,6 @@ export function evaluatePolicyProfile(
     const healthWeight = profile.optimize.health;
     const quotaWeight = profile.optimize.quota;
     const costWeight = profile.optimize.cost;
-    // Only spend a dimension's weight when a value is actually present:
-    // "allow" leaves missing health/quota/cost components null, so subtracting
-    // their weights would shrink the priority share for evidence the profile
-    // explicitly permits to be absent. Renormalize those weights back into
-    // priority instead of silently changing the ranking semantics.
     const spentHealth = healthValue !== null ? healthWeight : 0;
     const spentQuota = quotaValue !== null ? quotaWeight : 0;
     const spentCost = costValue !== null ? costWeight : 0;
@@ -429,6 +416,13 @@ export function evaluatePolicyProfile(
       total += costWeight * costValue;
       components.cost = costValue;
     }
+    if (compatibilityValue !== null) {
+      // Compatibility is a penalty-only dimension. A penalized candidate loses
+      // a bounded fraction of its existing score; satisfied/allowed evidence
+      // does not receive a synthetic bonus or alter configured priority.
+      total = Math.max(0, total - COMPATIBILITY_WEIGHT * (1 - compatibilityValue));
+      components.compatibility = compatibilityValue;
+    }
     const score: RouteScoreEvidence = { total, components };
     const evaluated: PolicyEvaluationCandidate = {
       provider: evidence.provider,
@@ -440,6 +434,8 @@ export function evaluatePolicyProfile(
       ...(evidence.capability ? { capability: evidence.capability } : {}),
       ...(evidence.health ? { health: evidence.health } : {}),
       ...(evidence.quota ? { quota: evidence.quota } : {}),
+      ...(evidence.cost ? { cost: evidence.cost } : {}),
+      ...(compatibilityTrace ? { compatibility: compatibilityTrace } : {}),
       ...(costForCandidate ? { cost: costForCandidate } : {}),
       score,
     };
@@ -455,8 +451,6 @@ export function evaluatePolicyProfile(
     requestedModel: policyModelId(profileId),
     routeKind: "policy",
     profile: { id: profile.id, revision: profile.revision },
-    // Flat, capped summary (truncation is flagged by the builder); per-candidate
-    // attribution lives in each candidate's `requirements`/`exclusions`.
     requirements: candidates.flatMap(candidate => candidate.requirements).slice(0, MAX_REQUIREMENTS),
     candidates: candidates.map(candidate => ({
       provider: candidate.provider,
@@ -469,6 +463,7 @@ export function evaluatePolicyProfile(
       ...(candidate.health ? { health: candidate.health } : {}),
       ...(candidate.quota ? { quota: candidate.quota } : {}),
       ...(candidate.cost ? { cost: candidate.cost } : {}),
+      ...(candidate.compatibility ? { compatibility: candidate.compatibility } : {}),
     })),
     selected: selectedIndex === null
       ? { provider: candidates[0]?.provider ?? "", model: candidates[0]?.model ?? "", reason: "no-eligible-candidate" }