@bitkyc08/opencodex 2.65.0 → 2.66.0

package/src/protocols/baseline.ts

@@ -0,0 +1,88 @@
+/**
+ * The 3 ingress × 3 upstream × stream baseline: the path each combination takes in the
+ * current code for an eligible single-provider route, and the path the protocol-first-class
+ * work targets.
+ *
+ * LEAF MODULE (see `contract.ts`). `current` is a claim about today's code and must change in
+ * the same commit that changes the code it describes; `target` changes only with the plan in
+ * `devlog/_plan/260924_protocol_first_class/`. Combos, policy routes, OAuth credentials and
+ * Responses-only features are not "eligible single-provider routes" and are described by the
+ * planner, not by this table.
+ */
+import { deliveryModeForPath, PROTOCOLS, type DeliveryMode, type Protocol, type ProtocolHop } from "./contract";
+
+/** How the client receives the result. `sse-folded` = streamed internally, folded to JSON. */
+export type ResponseShape = "sse" | "json" | "sse-folded";
+
+export interface BaselinePath {
+  mode: Exclude<DeliveryMode, "blocked">;
+  requestPath: readonly ProtocolHop[];
+  /** Upstream first, client last. */
+  responsePath: readonly ProtocolHop[];
+  responseShape: ResponseShape;
+}
+
+export interface BaselineCell {
+  inbound: Protocol;
+  upstream: Protocol;
+  stream: boolean;
+  current: BaselinePath;
+  target: BaselinePath;
+}
+
+function path(requestPath: readonly ProtocolHop[], stream: boolean, folded: boolean): BaselinePath {
+  const responsePath = [...requestPath].reverse();
+  return {
+    mode: deliveryModeForPath(requestPath),
+    requestPath,
+    responsePath,
+    responseShape: stream ? "sse" : folded ? "sse-folded" : "json",
+  };
+}
+
+/** Current request path for an eligible single-provider route. */
+function currentRequestPath(inbound: Protocol, upstream: Protocol): readonly ProtocolHop[] {
+  if (inbound === upstream) {
+    // Native Messages exists today only for caller-forwarded Anthropic credentials; a
+    // proxy-managed Anthropic key still replays through Responses.
+    return inbound === "messages" ? ["messages", "responses-internal", "ir", "messages"] : [inbound, upstream];
+  }
+  if (inbound === "responses") return ["responses", "ir", upstream];
+  // Chat and Messages reach a Responses upstream through their Responses codec directly.
+  if (upstream === "responses") return [inbound, "responses"];
+  return [inbound, "responses-internal", "ir", upstream];
+}
+
+function targetRequestPath(inbound: Protocol, upstream: Protocol): readonly ProtocolHop[] {
+  if (inbound === upstream) return [inbound, upstream];
+  if (inbound !== "responses" && upstream === "responses") return [inbound, "responses"];
+  return [inbound, "ir", upstream];
+}
+
+/**
+ * Whether the current non-stream client response is folded from an internal stream. Every
+ * routed (non-native) path streams internally; native Chat and Responses passthrough honour
+ * the caller's stream bit.
+ */
+function currentFolds(inbound: Protocol, upstream: Protocol): boolean {
+  if (inbound === "responses") return false;
+  return !(inbound === "chat" && upstream === "chat");
+}
+
+export const BASELINE_MATRIX: readonly BaselineCell[] = PROTOCOLS.flatMap(inbound =>
+  PROTOCOLS.flatMap(upstream =>
+    [false, true].map((stream): BaselineCell => ({
+      inbound,
+      upstream,
+      stream,
+      current: path(currentRequestPath(inbound, upstream), stream, currentFolds(inbound, upstream)),
+      target: path(targetRequestPath(inbound, upstream), stream, false),
+    })),
+  ),
+);
+
+export function baselineCell(inbound: Protocol, upstream: Protocol, stream: boolean): BaselineCell {
+  const cell = BASELINE_MATRIX.find(row => row.inbound === inbound && row.upstream === upstream && row.stream === stream);
+  if (!cell) throw new RangeError(`no baseline cell for ${inbound}>${upstream}/${stream}`);
+  return cell;
+}

package/src/protocols/codecs/chat.ts

@@ -0,0 +1,17 @@
+/**
+ * Chat Completions codec entry points (PF-06).
+ *
+ * A named surface over the existing translator so an ingress calls one codec per protocol.
+ * No behavior of its own: `chatToResponsesBody` is `chatCompletionsToResponsesBody`
+ * (`src/chat/inbound.ts`), including its validation and the fields it drops, which
+ * `src/protocols/features.ts` declares.
+ */
+import { chatCompletionsToResponsesBody } from "../../chat/inbound";
+import { featuresFromChatBody } from "../features";
+
+/** Project a Chat Completions body onto the internal Responses bridge body. */
+export function chatToResponsesBody(body: unknown): Record<string, unknown> {
+  return chatCompletionsToResponsesBody(body);
+}
+
+export const chatFeatures = featuresFromChatBody;

package/src/protocols/codecs/messages.ts

@@ -0,0 +1,18 @@
+/**
+ * Anthropic Messages codec entry points (PF-06).
+ *
+ * A named surface over the existing translator; no behavior of its own.
+ * `messagesToResponsesTranslation` is `anthropicToResponsesTranslation` (`src/claude/inbound.ts`)
+ * with the same model resolution, budget charging and prompt-cache key derivation.
+ */
+import { anthropicToResponsesTranslation, type ClaudeInboundTranslation } from "../../claude/inbound";
+import { featuresFromMessagesBody } from "../features";
+
+/** Project a Messages body onto the internal Responses bridge body. */
+export function messagesToResponsesTranslation(
+  ...args: Parameters<typeof anthropicToResponsesTranslation>
+): ClaudeInboundTranslation {
+  return anthropicToResponsesTranslation(...args);
+}
+
+export const messagesFeatures = featuresFromMessagesBody;

package/src/protocols/codecs/responses.ts

@@ -0,0 +1,17 @@
+/**
+ * Responses codec entry points (PF-06).
+ *
+ * A named surface over the existing parser; no behavior of its own. `responsesToIr` is
+ * `parseRequest` (`src/responses/parser.ts`), which turns a Responses body into the
+ * adapter-neutral `OcxParsedRequest` every adapter builds from.
+ */
+import { parseRequest } from "../../responses/parser";
+import type { OcxParsedRequest } from "../../types";
+import { featuresFromResponsesBody } from "../features";
+
+/** Parse a Responses body into the adapter-neutral request. */
+export function responsesToIr(...args: Parameters<typeof parseRequest>): OcxParsedRequest {
+  return parseRequest(...args);
+}
+
+export const responsesFeatures = featuresFromResponsesBody;

package/src/protocols/contract.ts

@@ -0,0 +1,185 @@
+/**
+ * Shared protocol vocabulary for the three public inference APIs.
+ *
+ * LEAF MODULE. The dashboard imports this file directly (`gui/src/*` reaches `src/` for pure
+ * contracts), so it must not import server, provider, router, or Lab code — not even as a type.
+ * Internal spellings that predate this vocabulary (`InboundWire` "anthropic", adapter ids, Lab
+ * protocol identities) are connected through the explicit mapping functions below rather than
+ * renamed in place; persisted rows and existing enums keep their spelling.
+ */
+
+/** Bumped when a reason code, hop, mode, or feature disposition changes meaning. */
+export const PROTOCOL_CONTRACT_VERSION = "2026-09-25.2";
+
+export const PROTOCOLS = ["responses", "chat", "messages"] as const;
+/** A public inference API a client can speak to this proxy. */
+export type Protocol = (typeof PROTOCOLS)[number];
+
+export const UPSTREAM_WIRES = ["responses", "chat", "messages", "other"] as const;
+/**
+ * The wire the final provider receives. `other` covers adapters whose upstream is none of
+ * the three public protocols (Gemini, Kiro, Cursor, ...); nothing is claimed about them here.
+ */
+export type UpstreamWire = (typeof UPSTREAM_WIRES)[number];
+
+export const PROTOCOL_HOPS = ["responses", "chat", "messages", "other", "ir", "responses-internal"] as const;
+/**
+ * One node of a request or response path.
+ *
+ * - a wire name: that wire's JSON/SSE is actually produced at this point;
+ * - `ir`: the adapter-neutral request (`OcxParsedRequest`) or event (`AdapterEvent`) form;
+ * - `responses-internal`: Responses JSON/SSE produced only as an internal bridge, never sent to
+ *   the provider. Its presence is what makes a path `legacy-bridge`.
+ */
+export type ProtocolHop = (typeof PROTOCOL_HOPS)[number];
+
+export const DELIVERY_MODES = ["native", "translated", "legacy-bridge", "blocked"] as const;
+/**
+ * How one request (or one attempt) reached its upstream.
+ *
+ * - `native`: same wire end to end; the source body is the wire source. Model rewrites, auth
+ *   injection and declared provider policy can still apply, so native is not byte-identical.
+ * - `translated`: cross-wire conversion whose only intermediate is the IR or the target wire.
+ * - `legacy-bridge`: the path contains `responses-internal`.
+ * - `blocked`: refused before any upstream send.
+ */
+export type DeliveryMode = (typeof DELIVERY_MODES)[number];
+
+export const FIDELITIES = ["preserved", "degraded", "unknown"] as const;
+export type Fidelity = (typeof FIDELITIES)[number];
+
+/**
+ * Fixed reason codes. Never conversation-derived, never free text: plan and trace records carry
+ * only these, which is what keeps them safe to persist and to show on a remote dashboard.
+ */
+export const PROTOCOL_REASON_CODES = [
+  "same-wire-native",
+  "cross-wire-codec",
+  "cross-wire-ir",
+  "combo-or-policy-route",
+  "responses-only-feature",
+  "hosted-tool",
+  "vision-preprocessing",
+  "tool-result-image",
+  "auth-mode-not-native",
+  "effort-row",
+  "fast-row",
+  "caller-credential-required",
+  "not-migrated",
+  "surface-disabled",
+  "feature-unrepresentable",
+  "compatibility-reject",
+  "unknown-model",
+  "upstream-other",
+  "rollout-disabled",
+  /** Operator policy that only the bridge applies (pinned effort, skill elision, a sidecar). */
+  "bridge-only-policy",
+  /** A pooled Anthropic OAuth account set: the bridge owns rotation and affinity. */
+  "oauth-account-pool",
+  /** Caller `anthropic-beta` values outside the native lane's allowlist were not forwarded. */
+  "anthropic-beta-dropped",
+  /** Thinking signatures or `redacted_thinking` removed for a destination that cannot verify them. */
+  "opaque-state-stripped",
+] as const;
+export type ProtocolReasonCode = (typeof PROTOCOL_REASON_CODES)[number];
+
+const PROTOCOL_SET = new Set<string>(PROTOCOLS);
+const UPSTREAM_SET = new Set<string>(UPSTREAM_WIRES);
+const HOP_SET = new Set<string>(PROTOCOL_HOPS);
+const MODE_SET = new Set<string>(DELIVERY_MODES);
+const FIDELITY_SET = new Set<string>(FIDELITIES);
+const REASON_SET = new Set<string>(PROTOCOL_REASON_CODES);
+
+export function isProtocol(value: unknown): value is Protocol {
+  return typeof value === "string" && PROTOCOL_SET.has(value);
+}
+export function isUpstreamWire(value: unknown): value is UpstreamWire {
+  return typeof value === "string" && UPSTREAM_SET.has(value);
+}
+export function isProtocolHop(value: unknown): value is ProtocolHop {
+  return typeof value === "string" && HOP_SET.has(value);
+}
+export function isDeliveryMode(value: unknown): value is DeliveryMode {
+  return typeof value === "string" && MODE_SET.has(value);
+}
+export function isFidelity(value: unknown): value is Fidelity {
+  return typeof value === "string" && FIDELITY_SET.has(value);
+}
+export function isProtocolReasonCode(value: unknown): value is ProtocolReasonCode {
+  return typeof value === "string" && REASON_SET.has(value);
+}
+
+/** The routing-layer spelling (`InboundWire` in `src/providers/registry/types.ts`). */
+export type InboundWireSpelling = "responses" | "chat" | "anthropic";
+
+export function protocolFromInboundWire(wire: InboundWireSpelling): Protocol {
+  return wire === "anthropic" ? "messages" : wire;
+}
+
+export function inboundWireForProtocol(protocol: Protocol): InboundWireSpelling {
+  return protocol === "messages" ? "anthropic" : protocol;
+}
+
+/** Lab protocol identities (`src/lab/conformance/fixtures/*`) to the public vocabulary. */
+export function protocolFromLabProtocol(identity: string): Protocol | undefined {
+  switch (identity) {
+    case "openai-responses":
+      return "responses";
+    case "openai-chat":
+      return "chat";
+    case "anthropic-messages":
+      return "messages";
+    default:
+      return undefined;
+  }
+}
+
+export function labProtocolForProtocol(protocol: Protocol): string {
+  switch (protocol) {
+    case "responses":
+      return "openai-responses";
+    case "chat":
+      return "openai-chat";
+    case "messages":
+      return "anthropic-messages";
+  }
+}
+
+/**
+ * The upstream wire a provider adapter id speaks. Only the three adapters whose request body
+ * is one of the public protocols map to a protocol; every other adapter is `other`.
+ */
+export function upstreamWireForAdapter(adapter: string): UpstreamWire {
+  switch (adapter) {
+    case "openai-responses":
+      return "responses";
+    case "openai-chat":
+      return "chat";
+    case "anthropic":
+      return "messages";
+    default:
+      return "other";
+  }
+}
+
+/**
+ * The wire-producing nodes of a path: `ir` is dropped and `responses-internal` counts as
+ * Responses, because a feature lost in an internal Responses body is lost all the same.
+ */
+export function protocolNodes(path: readonly ProtocolHop[]): UpstreamWire[] {
+  const nodes: UpstreamWire[] = [];
+  for (const hop of path) {
+    if (hop === "ir") continue;
+    const node: UpstreamWire = hop === "responses-internal" ? "responses" : hop;
+    if (nodes[nodes.length - 1] !== node) nodes.push(node);
+  }
+  return nodes;
+}
+
+/** Mode implied by a request path. `blocked` is never implied; a refusal has no path. */
+export function deliveryModeForPath(path: readonly ProtocolHop[]): Exclude<DeliveryMode, "blocked"> {
+  if (path.includes("responses-internal")) return "legacy-bridge";
+  const first = path[0];
+  const last = path[path.length - 1];
+  return path.length === 2 && first === last && first !== "other" ? "native" : "translated";
+}

package/src/protocols/dto.ts

@@ -0,0 +1,267 @@
+/**
+ * Wire shapes for protocol plans (predicted) and protocol traces (observed).
+ *
+ * LEAF MODULE (see `contract.ts`). Both the management API and the dashboard validate with
+ * the functions here, so a record from an older or newer server is rejected rather than
+ * half-rendered. Every field is drawn from a fixed vocabulary or is a bounded identifier the
+ * server already exposes (provider and model names); nothing is conversation-derived.
+ */
+import {
+  isDeliveryMode,
+  isFidelity,
+  isProtocol,
+  isProtocolHop,
+  isProtocolReasonCode,
+  isUpstreamWire,
+  type DeliveryMode,
+  type Fidelity,
+  type Protocol,
+  type ProtocolHop,
+  type ProtocolReasonCode,
+  type UpstreamWire,
+} from "./contract";
+import { isProtocolFeature, type FeatureDisposition, type ProtocolFeature } from "./features";
+
+export const PROTOCOL_PLAN_SCHEMA_VERSION = 1 as const;
+export const PROTOCOL_TRACE_SCHEMA_VERSION = 1 as const;
+
+/** Upper bounds shared by producers and validators. */
+export const PROTOCOL_DTO_LIMITS = {
+  pathHops: 6,
+  reasonCodes: 8,
+  featureEffects: 24,
+  candidates: 16,
+  attempts: 16,
+  identifierLength: 200,
+} as const;
+
+export interface ProtocolFeatureEffectV1 {
+  feature: ProtocolFeature;
+  disposition: FeatureDisposition;
+}
+
+/** One candidate route a plan considered. A direct route has exactly one. */
+export interface ProtocolPlanCandidateV1 {
+  provider: string;
+  model: string;
+  adapter: string;
+  upstream: UpstreamWire;
+  mode: DeliveryMode;
+  requestPath: ProtocolHop[];
+  responsePath: ProtocolHop[];
+  fidelity: Fidelity;
+  reasonCodes: ProtocolReasonCode[];
+  featureEffects: ProtocolFeatureEffectV1[];
+  /** Present features with no declared disposition on this candidate's path. */
+  unknownFeatures: ProtocolFeature[];
+  /** False when this candidate would be refused under the active unrepresentable policy. */
+  eligible: boolean;
+}
+
+export interface ProtocolPlanV1 {
+  schemaVersion: typeof PROTOCOL_PLAN_SCHEMA_VERSION;
+  basis: "preview" | "dispatch";
+  contractVersion: string;
+  /** Opaque digest of the config inputs the plan read; changes when a relevant setting changes. */
+  policyRevision: string;
+  inbound: Protocol;
+  requestedModel: string;
+  routeKind: "direct" | "combo" | "policy" | "unknown";
+  /** Mode of the first eligible candidate, or `blocked` when none is eligible. */
+  mode: DeliveryMode;
+  reasonCodes: ProtocolReasonCode[];
+  candidates: ProtocolPlanCandidateV1[];
+  /** Features every eligible candidate preserves (passthrough or translated). */
+  guaranteedFeatures: ProtocolFeature[];
+  /** Features preserved by some, but not all, eligible candidates. */
+  partialFeatures: ProtocolFeature[];
+}
+
+/** What one physical attempt actually did. */
+export interface ProtocolAttemptTraceV1 {
+  ordinal: number;
+  upstream: UpstreamWire;
+  mode: Exclude<DeliveryMode, "blocked">;
+  requestPath: ProtocolHop[];
+  /** Omitted when it is the reverse of `requestPath`. */
+  responsePath?: ProtocolHop[];
+}
+
+/** What one request actually did, recorded at the send boundary and persisted with the log row. */
+export interface ProtocolTraceV1 {
+  v: typeof PROTOCOL_TRACE_SCHEMA_VERSION;
+  inbound: Protocol;
+  /** Final attempt's mode, or `blocked` when refused before any send. */
+  mode: DeliveryMode;
+  upstream?: UpstreamWire;
+  requestPath: ProtocolHop[];
+  responsePath: ProtocolHop[];
+  reasonCodes: ProtocolReasonCode[];
+  featureEffects?: ProtocolFeatureEffectV1[];
+  attempts?: ProtocolAttemptTraceV1[];
+  /** Set only by shadow-plan comparison (`protocols.rollout.shadowPlan`) when the dispatch plan disagreed. */
+  planMismatch?: true;
+  contractVersion: string;
+}
+
+/** Who decided the wire a provider (or one of its models) receives. */
+export const PROTOCOL_ADAPTER_SOURCES = ["hard-pin", "operator", "registry", "provider-default"] as const;
+export type ProtocolAdapterSource = (typeof PROTOCOL_ADAPTER_SOURCES)[number];
+
+/** Upper bound on the per-model overrides one provider summary lists. */
+export const PROTOCOL_PROVIDER_OVERRIDE_LIMIT = 64;
+
+/** One model whose upstream wire differs from, or was decided apart from, the provider's. */
+export interface ProtocolProviderModelOverrideV1 {
+  model: string;
+  adapter: string;
+  source: ProtocolAdapterSource;
+}
+
+/**
+ * The `provider` block of `GET /api/protocols?provider=<name>`: the upstream wire a provider
+ * receives and who decided it. Static config only; no credential, base URL or header.
+ */
+export interface ProtocolProviderSummaryV1 {
+  name: string;
+  adapter: string;
+  adapterSource: ProtocolAdapterSource;
+  /** Resolved auth mode (`key`, `oauth`, `forward`, `local`), or null when none resolves. */
+  authMode: string | null;
+  upstream: UpstreamWire;
+  modelOverrides: ProtocolProviderModelOverrideV1[];
+  /** Set when more overrides exist than `PROTOCOL_PROVIDER_OVERRIDE_LIMIT` allows to list. */
+  modelOverridesTruncated?: true;
+}
+
+type Rec = Record<string, unknown>;
+function isRec(value: unknown): value is Rec {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+const DISPOSITIONS = new Set<string>(["passthrough", "translated", "degraded", "unsupported"]);
+
+function boundedArray<T>(value: unknown, max: number, item: (entry: unknown) => entry is T): value is T[] {
+  return Array.isArray(value) && value.length <= max && value.every(item);
+}
+function isIdentifier(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0 && value.length <= PROTOCOL_DTO_LIMITS.identifierLength
+    && !/[\u0000-\u001f\u007f]/.test(value);
+}
+function isFeatureEffect(value: unknown): value is ProtocolFeatureEffectV1 {
+  return isRec(value) && isProtocolFeature(value.feature) && typeof value.disposition === "string"
+    && DISPOSITIONS.has(value.disposition);
+}
+function isPath(value: unknown): value is ProtocolHop[] {
+  return boundedArray(value, PROTOCOL_DTO_LIMITS.pathHops, isProtocolHop) && value.length > 0;
+}
+function isReasonCodes(value: unknown): value is ProtocolReasonCode[] {
+  return boundedArray(value, PROTOCOL_DTO_LIMITS.reasonCodes, isProtocolReasonCode);
+}
+function isFeatureList(value: unknown): value is ProtocolFeature[] {
+  return boundedArray(value, PROTOCOL_DTO_LIMITS.featureEffects, isProtocolFeature);
+}
+
+export function isProtocolPlanCandidateV1(value: unknown): value is ProtocolPlanCandidateV1 {
+  return isRec(value)
+    && isIdentifier(value.provider)
+    && isIdentifier(value.model)
+    && isIdentifier(value.adapter)
+    && isUpstreamWire(value.upstream)
+    && isDeliveryMode(value.mode)
+    && (value.mode === "blocked" ? Array.isArray(value.requestPath) : isPath(value.requestPath))
+    && (value.mode === "blocked" ? Array.isArray(value.responsePath) : isPath(value.responsePath))
+    && isFidelity(value.fidelity)
+    && isReasonCodes(value.reasonCodes)
+    && boundedArray(value.featureEffects, PROTOCOL_DTO_LIMITS.featureEffects, isFeatureEffect)
+    && isFeatureList(value.unknownFeatures)
+    && typeof value.eligible === "boolean";
+}
+
+export function isProtocolPlanV1(value: unknown): value is ProtocolPlanV1 {
+  return isRec(value)
+    && value.schemaVersion === PROTOCOL_PLAN_SCHEMA_VERSION
+    && (value.basis === "preview" || value.basis === "dispatch")
+    && typeof value.contractVersion === "string"
+    && typeof value.policyRevision === "string"
+    && isProtocol(value.inbound)
+    && isIdentifier(value.requestedModel)
+    && (value.routeKind === "direct" || value.routeKind === "combo" || value.routeKind === "policy" || value.routeKind === "unknown")
+    && isDeliveryMode(value.mode)
+    && isReasonCodes(value.reasonCodes)
+    && boundedArray(value.candidates, PROTOCOL_DTO_LIMITS.candidates, isProtocolPlanCandidateV1)
+    && isFeatureList(value.guaranteedFeatures)
+    && isFeatureList(value.partialFeatures);
+}
+
+function isAttemptTrace(value: unknown): value is ProtocolAttemptTraceV1 {
+  return isRec(value)
+    && typeof value.ordinal === "number" && Number.isInteger(value.ordinal) && value.ordinal > 0
+    && isUpstreamWire(value.upstream)
+    && isDeliveryMode(value.mode) && value.mode !== "blocked"
+    && isPath(value.requestPath)
+    && (value.responsePath === undefined || isPath(value.responsePath));
+}
+
+export function isProtocolTraceV1(value: unknown): value is ProtocolTraceV1 {
+  if (!isRec(value) || value.v !== PROTOCOL_TRACE_SCHEMA_VERSION) return false;
+  if (!isProtocol(value.inbound) || !isDeliveryMode(value.mode)) return false;
+  if (value.upstream !== undefined && !isUpstreamWire(value.upstream)) return false;
+  const pathsOk = value.mode === "blocked"
+    ? Array.isArray(value.requestPath) && value.requestPath.length === 0
+      && Array.isArray(value.responsePath) && value.responsePath.length === 0
+    : isPath(value.requestPath) && isPath(value.responsePath);
+  if (!pathsOk || !isReasonCodes(value.reasonCodes) || typeof value.contractVersion !== "string") return false;
+  if (value.featureEffects !== undefined
+    && !boundedArray(value.featureEffects, PROTOCOL_DTO_LIMITS.featureEffects, isFeatureEffect)) return false;
+  if (value.attempts !== undefined && !boundedArray(value.attempts, PROTOCOL_DTO_LIMITS.attempts, isAttemptTrace)) return false;
+  if (value.planMismatch !== undefined && value.planMismatch !== true) return false;
+  return true;
+}
+
+/**
+ * Parse a persisted or received trace into a detached copy, or `undefined` when it is not a
+ * valid v1 trace. Old rows without a trace stay `undefined`; callers render "no path data"
+ * instead of guessing.
+ */
+export function parseProtocolTraceV1(value: unknown): ProtocolTraceV1 | undefined {
+  if (!isProtocolTraceV1(value)) return undefined;
+  return {
+    v: PROTOCOL_TRACE_SCHEMA_VERSION,
+    inbound: value.inbound,
+    mode: value.mode,
+    ...(value.upstream !== undefined ? { upstream: value.upstream } : {}),
+    requestPath: [...value.requestPath],
+    responsePath: [...value.responsePath],
+    reasonCodes: [...value.reasonCodes],
+    ...(value.featureEffects ? { featureEffects: value.featureEffects.map(effect => ({ ...effect })) } : {}),
+    ...(value.attempts ? {
+      attempts: value.attempts.map(attempt => ({
+        ...attempt,
+        requestPath: [...attempt.requestPath],
+        ...(attempt.responsePath ? { responsePath: [...attempt.responsePath] } : {}),
+      })),
+    } : {}),
+    ...(value.planMismatch ? { planMismatch: true as const } : {}),
+    contractVersion: value.contractVersion,
+  };
+}
+
+const ADAPTER_SOURCES = new Set<string>(PROTOCOL_ADAPTER_SOURCES);
+function isAdapterSource(value: unknown): value is ProtocolAdapterSource {
+  return typeof value === "string" && ADAPTER_SOURCES.has(value);
+}
+
+function isModelOverride(value: unknown): value is ProtocolProviderModelOverrideV1 {
+  return isRec(value) && isIdentifier(value.model) && isIdentifier(value.adapter) && isAdapterSource(value.source);
+}
+
+export function isProtocolProviderSummaryV1(value: unknown): value is ProtocolProviderSummaryV1 {
+  return isRec(value)
+    && isIdentifier(value.name)
+    && isIdentifier(value.adapter)
+    && isAdapterSource(value.adapterSource)
+    && (value.authMode === null || isIdentifier(value.authMode))
+    && isUpstreamWire(value.upstream)
+    && boundedArray(value.modelOverrides, PROTOCOL_PROVIDER_OVERRIDE_LIMIT, isModelOverride)
+    && (value.modelOverridesTruncated === undefined || value.modelOverridesTruncated === true);
+}