@bitkyc08/opencodex 2.65.0 → 2.66.0

package/src/protocols/plan-snapshot.ts

@@ -0,0 +1,226 @@
+/**
+ * Builds the planner's input from live config, for a preview that sends nothing.
+ *
+ * SERVER SIDE (not a leaf): this reads the router and the ingress eligibility rules so the
+ * snapshot is the route the request would actually settle on. It must stay free of side
+ * effects, which is why it does not simply call `routeModel` for every selector:
+ *
+ * - a combo selector would go through `tryPickComboModel`, which advances round-robin state.
+ *   Combos are expanded here from their configured targets, each resolved with
+ *   `routeConcreteModel` (no combo or policy lookup, no pick);
+ * - a policy selector would run the evaluator, whose clock-dependent pick is not what a
+ *   preview describes. Policies are expanded from their configured candidates the same way;
+ * - every other selector takes `routeModel`'s deterministic branches, which read config and
+ *   the last-known model cache and never fetch, refresh or write.
+ *
+ * Messages caller-forward passthrough depends on the caller's own Anthropic credential, which
+ * a preview does not have; it is reported as `caller-credential-required`, never assumed.
+ */
+import { resolveInboundModel } from "../claude/inbound-model-options";
+import { getCombo, preservesPhysicalComboProvider, resolveComboId } from "../combos";
+import { captureRouteStaticPolicy, routeConcreteModel, routeModel, type RouteResult } from "../router";
+import { getRoutingProfile, POLICY_NAMESPACE, resolvePolicyProfileId } from "../routing/profile";
+import { resolveWireProtocolOverride } from "../server/adapter-resolve";
+import { nativeChatDeclineReason } from "../server/chat-native-eligibility";
+import { nativeMessagesDeclineReason } from "../server/messages-native-eligibility";
+import { parseSyntheticRowId } from "../server/fast-row";
+import type { OcxConfig } from "../types";
+import { inboundWireForProtocol, type Protocol, type ProtocolReasonCode } from "./contract";
+import type { ProtocolPlanV1 } from "./dto";
+import type { ProtocolFeature } from "./features";
+import { planProtocol, type ProtocolPlanCandidateInput, type ProtocolPlanInput } from "./plan";
+import { protocolPolicyRevision, resolveApiSurfaceSettings, resolveProtocolSettings } from "./settings";
+
+export interface ProtocolPlanRequest {
+  model: string;
+  inbound: Protocol;
+  features: readonly ProtocolFeature[];
+}
+
+type SettledRouteKind = Exclude<ProtocolPlanV1["routeKind"], "unknown">;
+
+interface SettledTargets {
+  routeKind: SettledRouteKind;
+  routes: RouteResult[];
+}
+
+function concreteRoutes(config: OcxConfig, targets: readonly { provider: string; model: string }[]): RouteResult[] {
+  const routes: RouteResult[] = [];
+  for (const target of targets) {
+    try {
+      routes.push(routeConcreteModel(config, `${target.provider}/${target.model}`));
+    } catch {
+      // An unconfigured or disabled target is skipped at dispatch time as well.
+    }
+  }
+  return routes;
+}
+
+/** The route targets a selector settles on, or `undefined` when nothing routes it. */
+function settleTargets(config: OcxConfig, modelId: string): SettledTargets | undefined {
+  const policyId = resolvePolicyProfileId(config, modelId);
+  if (policyId !== null || modelId.startsWith(`${POLICY_NAMESPACE}/`)) {
+    const profile = policyId ? getRoutingProfile(config, policyId) : undefined;
+    return profile ? { routeKind: "policy", routes: concreteRoutes(config, profile.candidates) } : undefined;
+  }
+  if (!preservesPhysicalComboProvider(config)) {
+    const comboId = resolveComboId(config, modelId);
+    if (comboId !== null) {
+      const combo = getCombo(config, comboId);
+      return combo ? { routeKind: "combo", routes: concreteRoutes(config, combo.targets) } : undefined;
+    }
+  }
+  try {
+    return { routeKind: "direct", routes: [routeModel(config, modelId)] };
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * A structural stand-in for a Chat body carrying the requested features, for the
+ * eligibility rules that inspect the body. Never derived from a real request.
+ */
+function chatBodyForFeatures(features: ReadonlySet<ProtocolFeature>): Record<string, unknown> {
+  const content = features.has("request.images")
+    ? [{ type: "image_url", image_url: { url: "data:image/png;base64,AA==" } }]
+    : "";
+  return {
+    messages: [{ role: "user", content }],
+    ...(features.has("request.tools") ? { tools: [{ type: "function", function: { name: "preview" } }] } : {}),
+  };
+}
+
+/** The Messages counterpart of `chatBodyForFeatures`. */
+function messagesBodyForFeatures(features: ReadonlySet<ProtocolFeature>): Record<string, unknown> {
+  const content = features.has("request.images")
+    ? [{ type: "image", source: { type: "base64", media_type: "image/png", data: "AA==" } }]
+    : "";
+  return { messages: [{ role: "user", content }] };
+}
+
+interface SyntheticRows {
+  effortRow: boolean;
+  fastRow: boolean;
+  /** The resolved selector the bridge would parse; the effort pin reads it. */
+  routeSelector: string;
+}
+
+function candidateFor(
+  config: OcxConfig,
+  inbound: Protocol,
+  route: RouteResult,
+  routeKind: SettledRouteKind,
+  features: ReadonlySet<ProtocolFeature>,
+  rows: SyntheticRows,
+): ProtocolPlanCandidateInput {
+  const wire = inboundWireForProtocol(inbound);
+  // The same two steps every ingress runs: recapture static policy for the original inbound,
+  // then settle the wire from it.
+  const staticPolicy = captureRouteStaticPolicy(
+    route.providerName, route.modelId, route.provider, route.staticPolicy.effectiveAlias, wire,
+  );
+  const provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, wire, staticPolicy);
+  const adapter = provider.adapter ?? "openai-responses";
+  let declineReasons: ProtocolReasonCode[] = [];
+  let nativeEligible = false;
+  // With `nativeChatCombos` on, the combo loop judges each Chat candidate as the concrete route it
+  // is (PF-07), so the preview must too; a policy still resolves one candidate on the bridge.
+  const comboChildNative = inbound === "chat" && routeKind === "combo"
+    && resolveProtocolSettings(config).rollout.nativeChatCombos;
+  const settled: RouteResult = {
+    ...route,
+    provider,
+    staticPolicy,
+    ...(routeKind === "direct" || comboChildNative ? {} : { routeKind }),
+  };
+  if (inbound === "chat") {
+    const reason = rows.effortRow ? "effort-row" : nativeChatDeclineReason(settled, chatBodyForFeatures(features), config);
+    nativeEligible = reason === undefined;
+    if (reason) declineReasons = [reason];
+  } else if (inbound === "messages" && resolveProtocolSettings(config).rollout.managedMessagesNative) {
+    // The runtime rule itself. With the switch off nothing is judged, so the default preview
+    // is exactly what it was before the managed native lane existed.
+    // Pinned effort is judged from config and the route; blocked-skill elision and the web-search
+    // sidecar depend on body content no feature describes, so a preview cannot predict them.
+    // Anthropic OAuth (PF-10) is judged from config alone: the rollout switch, the provider, its
+    // host and `anthropicAccountPool.enabled`. The stored-account quorum a sender supplies is
+    // never read here, so a preview selects, resolves and refreshes no account.
+    const reason = nativeMessagesDeclineReason(settled, messagesBodyForFeatures(features), config, {
+      ...rows,
+      claudeCode: config.claudeCode,
+    });
+    nativeEligible = reason === undefined;
+    if (reason) declineReasons = [reason];
+  }
+  return { provider: route.providerName, model: route.modelId, adapter, nativeEligible, declineReasons };
+}
+
+/** Whether the Messages ingress could forward this selector with a caller's own credential. */
+function messagesPassthroughPossible(config: OcxConfig, model: string): boolean {
+  if (config.claudeCode?.nativePassthrough === false) return false;
+  if (!/^(claude|anthropic)/i.test(model)) return false;
+  try {
+    return resolveInboundModel(model, config.claudeCode) === model;
+  } catch {
+    return false;
+  }
+}
+
+export function buildProtocolPlanSnapshot(
+  config: OcxConfig,
+  request: ProtocolPlanRequest,
+  basis: ProtocolPlanV1["basis"] = "preview",
+): ProtocolPlanInput {
+  const base = {
+    inbound: request.inbound,
+    requestedModel: request.model,
+    features: [...request.features],
+    surfaces: resolveApiSurfaceSettings(config),
+    settings: resolveProtocolSettings(config),
+    policyRevision: protocolPolicyRevision(config),
+    basis,
+  };
+  const reasonCodes: ProtocolReasonCode[] = [];
+  let routeKey = request.model;
+  let effortRow = false;
+  let fastRow = false;
+  let syntheticRow = false;
+  try {
+    const parsed = parseSyntheticRowId(request.model, config);
+    if (parsed.effortRow) {
+      routeKey = parsed.effortRow.baseId;
+      effortRow = true;
+      syntheticRow = true;
+    } else if (parsed.fastRow) {
+      routeKey = parsed.fastRow.baseId;
+      fastRow = true;
+      syntheticRow = true;
+    }
+  } catch {
+    // An unparseable synthetic id routes as written, exactly as the ingress falls through.
+  }
+  if (request.inbound === "messages") {
+    // A synthetic row needs the proxy-owned adapter, so it never takes the passthrough.
+    if (!syntheticRow && messagesPassthroughPossible(config, request.model)) reasonCodes.push("caller-credential-required");
+    try {
+      routeKey = resolveInboundModel(routeKey, config.claudeCode);
+    } catch {
+      return { ...base, routeKind: "unknown", candidates: [], reasonCodes };
+    }
+  }
+  const settled = settleTargets(config, routeKey);
+  if (!settled || settled.routes.length === 0) return { ...base, routeKind: "unknown", candidates: [], reasonCodes };
+  const features = new Set(request.features);
+  return {
+    ...base,
+    routeKind: settled.routeKind,
+    candidates: settled.routes.map(route => candidateFor(config, request.inbound, route, settled.routeKind, features, { effortRow, fastRow, routeSelector: routeKey })),
+    reasonCodes,
+  };
+}
+
+/** A preview plan for one selector, computed from config alone. */
+export function previewProtocolPlan(config: OcxConfig, request: ProtocolPlanRequest): ProtocolPlanV1 {
+  return planProtocol(buildProtocolPlanSnapshot(config, request, "preview"));
+}

package/src/protocols/plan.ts

@@ -0,0 +1,192 @@
+/**
+ * The protocol planner: given a snapshot of what the router settled, predict the path each
+ * candidate would take, what it does to the request's features, and whether it would be
+ * refused under the unrepresentable policy.
+ *
+ * LEAF MODULE (see `contract.ts`) and PURE. The planner never selects a provider and never
+ * reads config; `plan-snapshot.ts` builds its input on the server. Paths come from
+ * `path.ts`, the same rule the observed trace uses, so a preview and the log of the same
+ * request cannot disagree about how a lane maps to hops. Settings and surfaces are taken
+ * structurally rather than imported from `settings.ts`, which reads config types and is
+ * therefore not a leaf.
+ */
+import { PROTOCOL_CONTRACT_VERSION, upstreamWireForAdapter, type Protocol, type ProtocolReasonCode } from "./contract";
+import {
+  PROTOCOL_DTO_LIMITS,
+  PROTOCOL_PLAN_SCHEMA_VERSION,
+  type ProtocolPlanCandidateV1,
+  type ProtocolPlanV1,
+} from "./dto";
+import { featureEffectsForPath, PROTOCOL_FEATURES, unrepresentableFeatures, type ProtocolFeature } from "./features";
+import { deliveryModeForLane, requestPathForLane, responsePathForLane, type ProtocolLane } from "./path";
+
+/** One settled route target, as the server resolved it. */
+export interface ProtocolPlanCandidateInput {
+  provider: string;
+  model: string;
+  /** Final adapter id after the wire override for this inbound. */
+  adapter: string;
+  /** True when the ingress would send its own wire to this candidate. */
+  nativeEligible: boolean;
+  /** Why the ingress declined its native lane, when it did. */
+  declineReasons: readonly ProtocolReasonCode[];
+}
+
+export interface ProtocolPlanInput {
+  inbound: Protocol;
+  requestedModel: string;
+  routeKind: ProtocolPlanV1["routeKind"];
+  candidates: readonly ProtocolPlanCandidateInput[];
+  features: readonly ProtocolFeature[];
+  surfaces: Readonly<Record<Protocol, { readonly enabled: boolean }>>;
+  settings: { readonly unrepresentable: "legacy" | "reject" };
+  policyRevision: string;
+  basis: ProtocolPlanV1["basis"];
+  /** Plan-level reasons the snapshot observed, such as `caller-credential-required`. */
+  reasonCodes?: readonly ProtocolReasonCode[];
+}
+
+function bounded(codes: Iterable<ProtocolReasonCode>): ProtocolReasonCode[] {
+  return [...new Set(codes)].slice(0, PROTOCOL_DTO_LIMITS.reasonCodes);
+}
+
+function orderedFeatures(features: Iterable<ProtocolFeature>): ProtocolFeature[] {
+  const present = new Set(features);
+  return PROTOCOL_FEATURES.filter(feature => present.has(feature));
+}
+
+function blockedCandidate(candidate: ProtocolPlanCandidateInput, reason: ProtocolReasonCode): ProtocolPlanCandidateV1 {
+  return {
+    provider: candidate.provider,
+    model: candidate.model,
+    adapter: candidate.adapter,
+    upstream: upstreamWireForAdapter(candidate.adapter),
+    mode: "blocked",
+    requestPath: [],
+    responsePath: [],
+    fidelity: "unknown",
+    reasonCodes: [reason],
+    featureEffects: [],
+    unknownFeatures: [],
+    eligible: false,
+  };
+}
+
+function planCandidate(
+  input: ProtocolPlanInput,
+  candidate: ProtocolPlanCandidateInput,
+  features: readonly ProtocolFeature[],
+): ProtocolPlanCandidateV1 {
+  const upstream = upstreamWireForAdapter(candidate.adapter);
+  // A native lane only exists toward the ingress's own wire; an inconsistent snapshot must
+  // not produce a path that claims the source body reached a different wire untouched.
+  const lane: ProtocolLane = candidate.nativeEligible && upstream === input.inbound ? "native" : "bridge";
+  const requestPath = requestPathForLane(input.inbound, lane, upstream);
+  const responsePath = responsePathForLane(input.inbound, lane, upstream);
+  const mode = deliveryModeForLane(input.inbound, lane, upstream);
+  const effects = featureEffectsForPath(input.inbound, requestPath, features);
+  const eligible = input.settings.unrepresentable !== "reject" || unrepresentableFeatures(effects.effects).length === 0;
+
+  const reasons: ProtocolReasonCode[] = [];
+  if (mode === "native") reasons.push("same-wire-native");
+  else if (mode === "translated") reasons.push(requestPath.length === 2 ? "cross-wire-codec" : "cross-wire-ir");
+  else reasons.push("not-migrated");
+  if (upstream === "other") reasons.push("upstream-other");
+  // Why the native lane was declined matters only where a native lane could exist: toward a
+  // different wire the path reason above already says it.
+  if (lane === "bridge" && input.inbound !== "responses" && upstream === input.inbound) {
+    reasons.push(...candidate.declineReasons);
+  }
+  if (!eligible) reasons.push("feature-unrepresentable");
+
+  return {
+    provider: candidate.provider,
+    model: candidate.model,
+    adapter: candidate.adapter,
+    upstream,
+    mode,
+    requestPath,
+    responsePath,
+    fidelity: effects.fidelity,
+    reasonCodes: bounded(reasons),
+    featureEffects: effects.effects.map(effect => ({ feature: effect.feature, disposition: effect.disposition })),
+    unknownFeatures: effects.unknown,
+    eligible,
+  };
+}
+
+/** Features preserved (passthrough or translated) by every / by only some eligible candidates. */
+function featureSplit(
+  eligible: readonly ProtocolPlanCandidateV1[],
+  features: readonly ProtocolFeature[],
+): { guaranteed: ProtocolFeature[]; partial: ProtocolFeature[] } {
+  const guaranteed: ProtocolFeature[] = [];
+  const partial: ProtocolFeature[] = [];
+  if (eligible.length === 0) return { guaranteed, partial };
+  for (const feature of features) {
+    let preserved = 0;
+    for (const candidate of eligible) {
+      const effect = candidate.featureEffects.find(entry => entry.feature === feature);
+      if (effect && (effect.disposition === "passthrough" || effect.disposition === "translated")) preserved++;
+    }
+    if (preserved === eligible.length) guaranteed.push(feature);
+    else if (preserved > 0) partial.push(feature);
+  }
+  return { guaranteed, partial };
+}
+
+export function planProtocol(input: ProtocolPlanInput): ProtocolPlanV1 {
+  const features = orderedFeatures(input.features);
+  const snapshotCandidates = input.candidates.slice(0, PROTOCOL_DTO_LIMITS.candidates);
+  const base = {
+    schemaVersion: PROTOCOL_PLAN_SCHEMA_VERSION,
+    basis: input.basis,
+    contractVersion: PROTOCOL_CONTRACT_VERSION,
+    policyRevision: input.policyRevision,
+    inbound: input.inbound,
+    requestedModel: input.requestedModel,
+    routeKind: input.routeKind,
+  } as const;
+
+  if (!input.surfaces[input.inbound].enabled) {
+    return {
+      ...base,
+      mode: "blocked",
+      reasonCodes: ["surface-disabled"],
+      candidates: snapshotCandidates.map(candidate => blockedCandidate(candidate, "surface-disabled")),
+      guaranteedFeatures: [],
+      partialFeatures: [],
+    };
+  }
+
+  if (input.routeKind === "unknown" || snapshotCandidates.length === 0) {
+    return {
+      ...base,
+      mode: "blocked",
+      reasonCodes: bounded([...(input.reasonCodes ?? []), "unknown-model"]),
+      candidates: [],
+      guaranteedFeatures: [],
+      partialFeatures: [],
+    };
+  }
+
+  const candidates = snapshotCandidates.map(candidate => planCandidate(input, candidate, features));
+  const eligible = candidates.filter(candidate => candidate.eligible);
+  const first = eligible[0];
+  const { guaranteed, partial } = featureSplit(eligible, features);
+  const routeReasons: ProtocolReasonCode[] = input.routeKind === "combo" || input.routeKind === "policy"
+    ? ["combo-or-policy-route"]
+    : [];
+  return {
+    ...base,
+    mode: first ? first.mode : "blocked",
+    reasonCodes: bounded([
+      ...(input.reasonCodes ?? []),
+      ...routeReasons,
+      ...(first ? first.reasonCodes : ["feature-unrepresentable" as const]),
+    ]),
+    candidates,
+    guaranteedFeatures: guaranteed,
+    partialFeatures: partial,
+  };
+}

package/src/protocols/provider-summary.ts

@@ -0,0 +1,101 @@
+/**
+ * The `provider` block of `GET /api/protocols?provider=<name>`: which upstream wire one
+ * provider receives and who decided it.
+ *
+ * SERVER SIDE (not a leaf): it reads the provider registry through
+ * `captureRouteStaticPolicy`, the same resolver every ingress uses, so the answer is the
+ * resolved static policy and never a second copy of the adapter rules. It is free of side
+ * effects: no fetch, no model-cache refresh, no config write. Only the adapter id, its
+ * provenance, the auth mode and model ids leave this module; no credential, base URL or header.
+ *
+ * Model overrides are resolved for a Responses client, the Codex default. A registry wire
+ * default declared for another client API only shows up in that API's plan preview.
+ */
+import { PROVIDER_REGISTRY } from "../providers/registry";
+import type { StaticPolicySource } from "../providers/resolved-model-policy";
+import { captureRouteStaticPolicy } from "../router";
+import { captureWireAdapterHardPins, type OcxConfig, type OcxProviderConfig } from "../types";
+import { upstreamWireForAdapter } from "./contract";
+import {
+  PROTOCOL_DTO_LIMITS,
+  PROTOCOL_PROVIDER_OVERRIDE_LIMIT,
+  type ProtocolAdapterSource,
+  type ProtocolProviderModelOverrideV1,
+  type ProtocolProviderSummaryV1,
+} from "./dto";
+
+/** Upper bound on the model ids examined, so a provider with a huge static list stays cheap. */
+const MODEL_SCAN_LIMIT = 1024;
+
+/** Collapse the resolver's provenance vocabulary onto the four public decision sources. */
+export function protocolAdapterSource(source: StaticPolicySource | undefined): ProtocolAdapterSource {
+  switch (source) {
+    case "hard-pin":
+      return "hard-pin";
+    case "operator":
+    case "operator-capability":
+      return "operator";
+    case "registry":
+      return "registry";
+    default:
+      return "provider-default";
+  }
+}
+
+function usableModelId(model: unknown): model is string {
+  return typeof model === "string" && model.length > 0 && model.length <= PROTOCOL_DTO_LIMITS.identifierLength
+    && !/[\u0000-\u001f\u007f]/.test(model);
+}
+
+/**
+ * Model ids whose wire could differ from the provider's: explicit overrides, registry wire
+ * defaults, exact-id hard pins and the listed models. Prefix pins cannot be enumerated; a
+ * listed model they match is still found.
+ */
+function candidateModelIds(name: string, provider: Readonly<OcxProviderConfig>): string[] {
+  const registry = PROVIDER_REGISTRY.find(entry => entry.id === name);
+  const ids = new Set<string>();
+  const add = (model: unknown) => {
+    if (ids.size < MODEL_SCAN_LIMIT && usableModelId(model)) ids.add(model);
+  };
+  for (const model of Object.keys(provider.modelAdapters ?? {})) add(model);
+  for (const model of Object.keys(registry?.modelWireDefaults ?? {})) add(model);
+  for (const model of Object.keys(captureWireAdapterHardPins(name))) add(model);
+  add(provider.defaultModel);
+  for (const model of provider.models ?? []) add(model);
+  return [...ids].sort((left, right) => left.localeCompare(right));
+}
+
+/**
+ * Summarize one configured provider, or `undefined` when no provider has that name. The
+ * provider-level adapter is resolved without a model; each override is resolved for its model.
+ */
+export function buildProtocolProviderSummary(config: Readonly<OcxConfig>, name: string): ProtocolProviderSummaryV1 | undefined {
+  if (!Object.hasOwn(config.providers ?? {}, name)) return undefined;
+  const provider = config.providers[name];
+  if (!provider) return undefined;
+  const base = captureRouteStaticPolicy(name, "", provider);
+  const adapter = base.provider.adapter;
+  const overrides: ProtocolProviderModelOverrideV1[] = [];
+  let truncated = false;
+  for (const model of candidateModelIds(name, provider)) {
+    const policy = captureRouteStaticPolicy(name, model, provider);
+    const source = protocolAdapterSource(policy.provenance.model.adapter);
+    if (source === "provider-default" && policy.model.adapter === adapter) continue;
+    if (overrides.length >= PROTOCOL_PROVIDER_OVERRIDE_LIMIT) {
+      truncated = true;
+      break;
+    }
+    overrides.push({ model, adapter: policy.model.adapter, source });
+  }
+  const authMode = base.provider.authMode;
+  return {
+    name,
+    adapter,
+    adapterSource: protocolAdapterSource(base.provenance.provider.adapter),
+    authMode: typeof authMode === "string" && authMode.length > 0 ? authMode : null,
+    upstream: upstreamWireForAdapter(adapter),
+    modelOverrides: overrides,
+    ...(truncated ? { modelOverridesTruncated: true as const } : {}),
+  };
+}

package/src/protocols/settings.ts

@@ -0,0 +1,118 @@
+/**
+ * The single reader of `apiSurfaces` and `protocols` config.
+ *
+ * Nothing else reads those keys directly: endpoint admission, `count_tokens`, the endpoint
+ * metadata DTO and the dashboard all resolve through here, so they cannot disagree about
+ * whether an API is open. Type-only config import keeps this module free of runtime edges.
+ */
+import type { OcxConfig } from "../types";
+import type { Protocol } from "./contract";
+
+export type ApiSurfaceSource =
+  /** Responses and Chat Completions: always served. */
+  | "fixed"
+  /** An explicit boolean in `apiSurfaces`. */
+  | "api-surfaces"
+  /** No explicit value; inherited from `claudeCode.enabled`. */
+  | "claude-code-legacy"
+  /** A present but malformed value; the surface is closed. */
+  | "invalid";
+
+export interface ApiSurfaceSetting {
+  enabled: boolean;
+  source: ApiSurfaceSource;
+}
+
+export type ApiSurfaceSettings = Readonly<Record<Protocol, Readonly<ApiSurfaceSetting>>>;
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function resolveMessagesSurface(config: Pick<OcxConfig, "apiSurfaces" | "claudeCode">): ApiSurfaceSetting {
+  const raw: unknown = config.apiSurfaces;
+  if (raw !== undefined) {
+    if (!isRec(raw)) return { enabled: false, source: "invalid" };
+    const messages = raw.messages;
+    if (messages !== undefined) {
+      if (!isRec(messages)) return { enabled: false, source: "invalid" };
+      if (Object.hasOwn(messages, "enabled")) {
+        return typeof messages.enabled === "boolean"
+          ? { enabled: messages.enabled, source: "api-surfaces" }
+          : { enabled: false, source: "invalid" };
+      }
+    }
+  }
+  return { enabled: config.claudeCode?.enabled !== false, source: "claude-code-legacy" };
+}
+
+export function resolveApiSurfaceSettings(config: Pick<OcxConfig, "apiSurfaces" | "claudeCode">): ApiSurfaceSettings {
+  return Object.freeze({
+    responses: Object.freeze({ enabled: true, source: "fixed" as const }),
+    chat: Object.freeze({ enabled: true, source: "fixed" as const }),
+    messages: Object.freeze(resolveMessagesSurface(config)),
+  });
+}
+
+export type UnrepresentablePolicy = "legacy" | "reject";
+
+export interface ProtocolRolloutSettings {
+  nativeChatCombos: boolean;
+  managedMessagesNative: boolean;
+  managedMessagesNativeOAuth: boolean;
+  directEncoders: boolean;
+  shadowPlan: boolean;
+}
+
+export interface ProtocolSettings {
+  unrepresentable: UnrepresentablePolicy;
+  rollout: Readonly<ProtocolRolloutSettings>;
+}
+
+/** Resolve protocol policy with conservative defaults for every absent or malformed field. */
+export function resolveProtocolSettings(config: Pick<OcxConfig, "protocols">): Readonly<ProtocolSettings> {
+  const raw: unknown = config.protocols;
+  const protocols = isRec(raw) ? raw : {};
+  const rollout = isRec(protocols.rollout) ? protocols.rollout : {};
+  const on = (key: keyof ProtocolRolloutSettings): boolean => rollout[key] === true;
+  const managedMessagesNative = on("managedMessagesNative");
+  return Object.freeze({
+    unrepresentable: protocols.unrepresentable === "reject" ? "reject" : "legacy",
+    rollout: Object.freeze({
+      nativeChatCombos: on("nativeChatCombos"),
+      managedMessagesNative,
+      // OAuth extension is meaningless without the key-auth path it extends.
+      managedMessagesNativeOAuth: managedMessagesNative && on("managedMessagesNativeOAuth"),
+      directEncoders: on("directEncoders"),
+      shadowPlan: on("shadowPlan"),
+    }),
+  });
+}
+
+/**
+ * Short, stable digest of every config input a protocol plan reads. Plans carry it so the
+ * dashboard can tell a preview computed under an older policy from a current one. Not a
+ * security boundary; FNV-1a over a canonical JSON projection.
+ */
+export function protocolPolicyRevision(config: Pick<OcxConfig, "apiSurfaces" | "claudeCode" | "protocols">): string {
+  const surfaces = resolveApiSurfaceSettings(config);
+  const settings = resolveProtocolSettings(config);
+  const canonical = JSON.stringify({
+    messages: [surfaces.messages.enabled, surfaces.messages.source],
+    unrepresentable: settings.unrepresentable,
+    rollout: [
+      settings.rollout.nativeChatCombos,
+      settings.rollout.managedMessagesNative,
+      settings.rollout.managedMessagesNativeOAuth,
+      settings.rollout.directEncoders,
+      settings.rollout.shadowPlan,
+    ],
+  });
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < canonical.length; i++) {
+    hash ^= canonical.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return `p1-${hash.toString(16).padStart(8, "0")}`;
+}

package/src/protocols/shadow-plan.ts

@@ -0,0 +1,36 @@
+/**
+ * Shadow plan recording (PF-12, `protocols.rollout.shadowPlan`, default off).
+ *
+ * SERVER SIDE (not a leaf): it reads config through `plan-snapshot.ts`. An ingress calls
+ * `recordProtocolShadowPlan` right after its entry mark. With the switch off it returns before
+ * reading anything else. With it on it builds the same side-effect-free snapshot the dashboard
+ * preview uses, with basis `dispatch`, from the selector the client sent and the features the
+ * entry mark already collected, and stores it beside the marks. `trace.ts` runs the pure planner
+ * on it at finalize and compares.
+ *
+ * Nothing here sends, fetches, advances combo state or writes: the snapshot expands combos and
+ * policies from config and uses `routeModel`'s deterministic branches only. The stored input is
+ * fixed vocabulary plus the provider and model names the server already exposes. Any throw is
+ * swallowed: a shadow plan is diagnostics and never fails or changes the request it describes.
+ */
+import type { OcxConfig } from "../types";
+import type { Protocol } from "./contract";
+import { buildProtocolPlanSnapshot } from "./plan-snapshot";
+import { resolveProtocolSettings } from "./settings";
+import { markProtocolShadowPlanInput, protocolMarkFeatures } from "./trace";
+
+export function recordProtocolShadowPlan(
+  logCtx: object,
+  config: OcxConfig,
+  request: { inbound: Protocol; model: unknown },
+): void {
+  try {
+    if (!resolveProtocolSettings(config).rollout.shadowPlan) return;
+    if (typeof request.model !== "string" || request.model.length === 0) return;
+    const features = protocolMarkFeatures(logCtx) ?? [];
+    const input = buildProtocolPlanSnapshot(config, { model: request.model, inbound: request.inbound, features }, "dispatch");
+    markProtocolShadowPlanInput(logCtx, input);
+  } catch {
+    /* a shadow plan must never fail the request it describes */
+  }
+}