@iislee/opencodex 2.11.0 → 2.35.0

package/src/routing/trace.ts

@@ -0,0 +1,776 @@
+/**
+ * Route decision trace: bounded, versioned, privacy-safe evidence of WHY a
+ * provider/model/account was selected for a request (RI-01).
+ *
+ * Contract rules (devlog/_fin/260804_router_intelligence/000_master_plan.md):
+ * - One trace per routing decision; fallback EXECUTION attempts stay in the
+ *   usage entry's existing `attempts[]` array, never in this trace.
+ * - Never persists prompts, message bodies, tool payloads, credentials,
+ *   authorization headers, raw quota responses, or hidden reasoning.
+ * - Stable wire values only; no localized strings.
+ * - Deterministic bounds: candidates <= 8, exclusions per candidate <= 16,
+ *   requirements <= 16, strings <= 128 chars, serialized trace <= 16 KiB.
+ * - Truncation is explicit: `truncated` flags are set whenever a limit was
+ *   enforced.
+ */
+
+import { randomBytes } from "node:crypto";
+
+export type RouteDecisionKind =
+  | "explicit-account"
+  | "explicit-provider"
+  | "native"
+  | "combo"
+  | "policy"
+  | "default-provider";
+
+export type Unknownable = number | boolean | "unknown";
+
+export interface RouteRequirementEvidence {
+  /** Stable wire code, e.g. "min-context-window" | "tools" | "image-input". */
+  id: string;
+  expected?: string | number | boolean;
+  actual?: Unknownable | string;
+  outcome: "satisfied" | "unsatisfied" | "unknown";
+}
+
+export interface RouteExclusionReason {
+  /** Stable wire code, e.g. "cooldown" | "disabled" | "cost-limit". */
+  code: string;
+  detail?: string;
+}
+
+export interface RouteCapabilityEvidence {
+  contextWindow?: number;
+  tools?: Unknownable;
+  image?: Unknownable;
+  structuredOutput?: Unknownable;
+  reasoningEfforts?: string[];
+  /** `"unknown"` is reserved: it encodes missing evidence, never a real tier. */
+  serviceTier?: string | "unknown";
+  localOnly?: Unknownable;
+  remoteAllowed?: Unknownable;
+  encryptedCodexTasks?: Unknownable;
+}
+
+export interface RouteHealthEvidence {
+  cooldownUntilMs?: number;
+  softAvoidUntilMs?: number;
+  successRate?: number;
+  failures?: number;
+  incompleteStreamRate?: number;
+  recentLatencyMs?: number;
+  sampleCount?: number;
+  recencyWeight?: number;
+}
+
+export interface RouteQuotaEvidence {
+  known: boolean;
+  /** Remaining headroom as a fraction 0..1 (larger is better). */
+  headroom?: number;
+  headroomTokens?: number;
+  exhausted?: boolean;
+  resetAtMs?: number;
+  reauthOrCooling?: boolean;
+  reservedHeadroomTokens?: number;
+  /** Stable wire code for the evidence source (e.g. "provider-report"). */
+  source?: string;
+}
+
+/**
+ * Stable wire outcome for `limits.maxEstimatedCostUsd` against this candidate's
+ * cost evidence. Present only when a cap is configured. Non-excluding outcomes
+ * (`satisfied`, `unknown-allowed`) must not be mirrored into `exclusions`.
+ */
+export type RouteCostCapOutcome =
+  | "satisfied"
+  | "exceeded"
+  | "unknown-allowed"
+  | "unknown-excluded";
+
+export interface RouteCostEvidence {
+  estimatedUsd?: number;
+  /** Stable wire code for the price source (e.g. "registry" | "expected"). */
+  priceSource?: string;
+  incomplete?: boolean;
+  limitUsd?: number;
+  /**
+   * Cap evaluation outcome when `limitUsd` / profile `maxEstimatedCostUsd` is set.
+   * Distinguishes "known under the cap" from "unknown cost allowed by policy"
+   * without treating the latter as an exclusion.
+   */
+  capOutcome?: RouteCostCapOutcome;
+}
+
+export interface RouteCompatibilitySuiteTrace {
+  suiteId: string;
+  evidenceLayer: string;
+  /** Privacy-safe prefix of the exact subject used for this layer/suite. */
+  subjectIdPrefix?: string;
+  verdict?: string;
+  minStatus?: string;
+  fresh?: boolean;
+  unknownPolicy?: string;
+  degradedPolicy?: string;
+  outcome: "satisfied" | "penalized" | "excluded" | "unknown";
+  reason?: string;
+}
+
+export interface RouteCompatibilityEvidence {
+  /** Legacy single-subject prefix retained for persisted trace compatibility. */
+  subjectIdPrefix?: string;
+  suites: RouteCompatibilitySuiteTrace[];
+  truncated?: true;
+}
+
+export interface RouteScoreEvidence {
+  total: number;
+  components: {
+    capability?: number;
+    health?: number;
+    quota?: number;
+    cost?: number;
+    latency?: number;
+    configuredPriority?: number;
+    compatibility?: number;
+  };
+}
+
+export interface RouteCandidateTrace {
+  provider: string;
+  model: string;
+  accountRef?: string;
+  eligible: boolean;
+  exclusions: RouteExclusionReason[];
+  capability?: RouteCapabilityEvidence;
+  health?: RouteHealthEvidence;
+  quota?: RouteQuotaEvidence;
+  cost?: RouteCostEvidence;
+  compatibility?: RouteCompatibilityEvidence;
+  score?: RouteScoreEvidence;
+}
+
+export interface RouteDecisionTraceV1 {
+  version: 1;
+  decisionId: string;
+  createdAt: number;
+  requestedModel: string;
+  routeKind: RouteDecisionKind;
+  profile?: { id: string; revision: string };
+  requirements: RouteRequirementEvidence[];
+  candidates: RouteCandidateTrace[];
+  selected: {
+    candidateIndex: number;
+    provider: string;
+    model: string;
+    accountRef?: string;
+    reason: string;
+    tieBreak?: string;
+  };
+  truncated?: {
+    candidates?: true;
+    exclusions?: true;
+    requirements?: true;
+    strings?: true;
+    compatibility?: true;
+  };
+}
+
+export const MAX_TRACE_CANDIDATES = 8;
+export const MAX_EXCLUSIONS_PER_CANDIDATE = 16;
+export const MAX_REQUIREMENTS = 16;
+export const MAX_TRACE_STRING = 128;
+export const MAX_TRACE_BYTES = 16 * 1024;
+
+const ROUTE_KINDS = new Set<RouteDecisionKind>([
+  "explicit-account",
+  "explicit-provider",
+  "native",
+  "combo",
+  "policy",
+  "default-provider",
+]);
+
+const REQUIREMENT_OUTCOMES = new Set(["satisfied", "unsatisfied", "unknown"]);
+
+/** Cap a string at MAX_TRACE_STRING and record the truncation flag. */
+function capString(value: string, budget: { strings?: true }): string {
+  if (value.length <= MAX_TRACE_STRING) return value;
+  budget.strings = true;
+  return value.slice(0, MAX_TRACE_STRING);
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function finiteNumber(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value);
+}
+
+function unknownable(value: unknown): Unknownable | undefined {
+  if (typeof value === "boolean") return value;
+  if (finiteNumber(value)) return value;
+  if (value === "unknown") return "unknown";
+  return undefined;
+}
+
+export interface TraceCandidateInput {
+  provider: string;
+  model: string;
+  accountRef?: string;
+  eligible: boolean;
+  exclusions: RouteExclusionReason[];
+  score?: RouteScoreEvidence;
+  capability?: RouteCapabilityEvidence;
+  health?: RouteHealthEvidence;
+  quota?: RouteQuotaEvidence;
+  cost?: RouteCostEvidence;
+  compatibility?: RouteCompatibilityEvidence;
+}
+
+export interface TraceBuildInput {
+  requestedModel: string;
+  routeKind: RouteDecisionKind;
+  selected: {
+    provider: string;
+    model: string;
+    accountRef?: string;
+    reason: string;
+    tieBreak?: string;
+    /** Index into `candidates`; defaults to 0. */
+    candidateIndex?: number;
+  };
+  profile?: { id: string; revision: string };
+  requirements?: RouteRequirementEvidence[];
+  candidates?: TraceCandidateInput[];
+  now?: number;
+}
+
+interface ParseCaps {
+  candidates?: true;
+  exclusions?: true;
+  requirements?: true;
+  strings?: true;
+  compatibility?: true;
+}
+
+/** Bounded candidate copy: strings capped, exclusions sliced, score/evidence kept. */
+function buildCandidate(input: TraceCandidateInput, budget: ParseCaps): RouteCandidateTrace {
+  const exclusions = input.exclusions.slice(0, MAX_EXCLUSIONS_PER_CANDIDATE);
+  if (exclusions.length < input.exclusions.length) budget.exclusions = true;
+  const capability = input.capability ? parseCapability(input.capability, budget) : undefined;
+  const health = input.health ? parseHealth(input.health) : undefined;
+  const quota = input.quota ? parseQuota(input.quota, budget) : undefined;
+  const cost = input.cost ? parseCost(input.cost, budget) : undefined;
+  const compatibility = input.compatibility ? parseCompatibility(input.compatibility, budget) : undefined;
+  return {
+    provider: capString(input.provider, budget),
+    model: capString(input.model, budget),
+    ...(input.accountRef !== undefined
+      ? { accountRef: capString(input.accountRef, budget) }
+      : {}),
+    eligible: input.eligible,
+    exclusions: exclusions.map(exclusion => ({
+      code: capString(exclusion.code, budget),
+      ...(exclusion.detail !== undefined
+        ? { detail: capString(exclusion.detail, budget) }
+        : {}),
+    })),
+    ...(input.score ? { score: input.score } : {}),
+    ...(capability ? { capability } : {}),
+    ...(health ? { health } : {}),
+    ...(quota ? { quota } : {}),
+    ...(cost ? { cost } : {}),
+    ...(compatibility ? { compatibility } : {}),
+  };
+}
+
+/** Bounded requirement copy with capped strings. */
+function buildRequirement(requirement: RouteRequirementEvidence, budget: { strings?: true }): RouteRequirementEvidence {
+  return {
+    id: capString(requirement.id, budget),
+    ...(requirement.expected !== undefined
+      ? { expected: typeof requirement.expected === "string"
+          ? capString(requirement.expected, budget)
+          : requirement.expected }
+      : {}),
+    ...(requirement.actual !== undefined
+      ? { actual: typeof requirement.actual === "string"
+          ? capString(requirement.actual, budget)
+          : requirement.actual }
+      : {}),
+    outcome: requirement.outcome,
+  };
+}
+
+/**
+ * Build a bounded decision trace. The builder never receives credentials: callers
+ * pass provider/model NAME strings and opaque account references only.
+ */
+export function buildRouteDecisionTrace(input: TraceBuildInput): RouteDecisionTraceV1 {
+  const budget: ParseCaps = {};
+  const now = input.now ?? Date.now();
+  const truncated: RouteDecisionTraceV1["truncated"] = {};
+  let selectedIndex = Number.isInteger(input.selected.candidateIndex ?? 0)
+    ? (input.selected.candidateIndex ?? 0)
+    : 0;
+
+  let candidates = (input.candidates ?? []).map(candidate => buildCandidate(candidate, budget));
+  if (candidates.length > MAX_TRACE_CANDIDATES) {
+    candidates = selectedIndex < MAX_TRACE_CANDIDATES
+      ? candidates.slice(0, MAX_TRACE_CANDIDATES)
+      : [...candidates.slice(0, MAX_TRACE_CANDIDATES - 1), candidates[selectedIndex]!];
+    selectedIndex = Math.min(selectedIndex, candidates.length - 1);
+    truncated.candidates = true;
+  }
+  if (candidates.length === 0) {
+    candidates = [{
+      provider: capString(input.selected.provider, budget),
+      model: capString(input.selected.model, budget),
+      ...(input.selected.accountRef !== undefined
+        ? { accountRef: capString(input.selected.accountRef, budget) }
+        : {}),
+      eligible: true,
+      exclusions: [],
+    }];
+  }
+
+  let requirements = (input.requirements ?? []).map(requirement => buildRequirement(requirement, budget));
+  if (requirements.length > MAX_REQUIREMENTS) {
+    requirements = requirements.slice(0, MAX_REQUIREMENTS);
+    truncated.requirements = true;
+  }
+
+  if (selectedIndex < 0 || selectedIndex >= candidates.length) selectedIndex = 0;
+
+  const trace: RouteDecisionTraceV1 = {
+    version: 1,
+    decisionId: randomBytes(6).toString("hex"),
+    createdAt: now,
+    requestedModel: capString(input.requestedModel, budget),
+    routeKind: input.routeKind,
+    ...(input.profile
+      ? {
+        profile: {
+          id: capString(input.profile.id, budget),
+          revision: capString(input.profile.revision, budget),
+        },
+      }
+      : {}),
+    requirements,
+    candidates,
+    selected: {
+      candidateIndex: selectedIndex,
+      provider: capString(input.selected.provider, budget),
+      model: capString(input.selected.model, budget),
+      ...(input.selected.accountRef !== undefined
+        ? { accountRef: capString(input.selected.accountRef, budget) }
+        : {}),
+      reason: capString(input.selected.reason, budget),
+      ...(input.selected.tieBreak !== undefined
+        ? { tieBreak: capString(input.selected.tieBreak, budget) }
+        : {}),
+    },
+  };
+
+  if (budget.strings) truncated.strings = true;
+  if (budget.exclusions) truncated.exclusions = true;
+  if (budget.candidates) truncated.candidates = true;
+  if (budget.compatibility) truncated.compatibility = true;
+  if (Object.keys(truncated).length > 0) trace.truncated = truncated;
+
+  return enforceByteBudget(trace);
+}
+
+/** Serialized UTF-8 length of a value (JSON is measured in bytes, not code units). */
+function serializedByteLength(value: unknown): number {
+  return Buffer.byteLength(JSON.stringify(value), "utf8");
+}
+
+/** Deterministic byte-budget enforcement: drop details, then shrink candidates. */
+function enforceByteBudget(trace: RouteDecisionTraceV1): RouteDecisionTraceV1 {
+  if (serializedByteLength(trace) <= MAX_TRACE_BYTES) return trace;
+  const truncated = { ...trace.truncated, strings: true as const };
+  const candidates = trace.candidates.map(candidate => ({
+    ...candidate,
+    exclusions: candidate.exclusions.map(exclusion => ({ code: exclusion.code })),
+  }));
+  const slimmed: RouteDecisionTraceV1 = { ...trace, truncated, candidates };
+  if (serializedByteLength(slimmed) <= MAX_TRACE_BYTES) return slimmed;
+  const half = Math.max(1, Math.floor(MAX_TRACE_CANDIDATES / 2));
+  const selectedIndex = trace.selected.candidateIndex;
+  const kept = selectedIndex < half
+    ? slimmed.candidates.slice(0, half)
+    : [...slimmed.candidates.slice(0, half - 1), slimmed.candidates[selectedIndex]!];
+  let result: RouteDecisionTraceV1 = {
+    ...slimmed,
+    truncated: { ...truncated, candidates: true as const },
+    candidates: kept,
+    selected: { ...slimmed.selected, candidateIndex: Math.min(selectedIndex, kept.length - 1) },
+  };
+  for (let stage = 0; stage < 4 && serializedByteLength(result) > MAX_TRACE_BYTES; stage++) {
+    if (stage === 0) {
+      result = {
+        ...result,
+        truncated: { ...result.truncated, exclusions: true as const },
+        candidates: result.candidates.map(candidate => ({
+          ...candidate,
+          exclusions: candidate.exclusions.slice(0, 8),
+        })),
+      };
+    } else if (stage === 1) {
+      result = {
+        ...result,
+        truncated: { ...result.truncated, exclusions: true as const },
+        candidates: result.candidates.map(candidate => ({ ...candidate, exclusions: [] })),
+      };
+    } else {
+      const half = Math.max(1, Math.ceil(result.candidates.length / 2));
+      const index = result.selected.candidateIndex;
+      const shrinkKept = index < half
+        ? result.candidates.slice(0, half)
+        : [...result.candidates.slice(0, half - 1), result.candidates[index]!];
+      result = {
+        ...result,
+        truncated: { ...result.truncated, candidates: true as const },
+        candidates: shrinkKept,
+        selected: { ...result.selected, candidateIndex: Math.min(index, shrinkKept.length - 1) },
+      };
+    }
+  }
+  return result;
+}
+
+/** Defensive parse of one persisted exclusion reason. */
+function parseExclusion(raw: unknown, caps: ParseCaps): RouteExclusionReason | null {
+  if (!isPlainRecord(raw)) return null;
+  const code = raw.code;
+  if (typeof code !== "string" || code.length === 0) return null;
+  if (code.length > MAX_TRACE_STRING) caps.strings = true;
+  const out: RouteExclusionReason = { code: code.slice(0, MAX_TRACE_STRING) };
+  if (typeof raw.detail === "string") {
+    if (raw.detail.length > MAX_TRACE_STRING) caps.strings = true;
+    out.detail = raw.detail.slice(0, MAX_TRACE_STRING);
+  }
+  return out;
+}
+
+/** Defensive parse of one persisted requirement; rejects unknown outcomes. */
+function parseRequirement(raw: unknown, caps: ParseCaps): RouteRequirementEvidence | null {
+  if (!isPlainRecord(raw)) return null;
+  const id = raw.id;
+  const outcome = raw.outcome;
+  if (typeof id !== "string" || id.length === 0) return null;
+  if (typeof outcome !== "string" || !REQUIREMENT_OUTCOMES.has(outcome)) return null;
+  if (id.length > MAX_TRACE_STRING) caps.strings = true;
+  const out: RouteRequirementEvidence = {
+    id: id.slice(0, MAX_TRACE_STRING),
+    outcome: outcome as RouteRequirementEvidence["outcome"],
+  };
+  if (typeof raw.expected === "string") {
+    if (raw.expected.length > MAX_TRACE_STRING) caps.strings = true;
+    out.expected = raw.expected.slice(0, MAX_TRACE_STRING);
+  } else if (typeof raw.expected === "number" || typeof raw.expected === "boolean") {
+    out.expected = raw.expected;
+  }
+  if (typeof raw.actual === "string") {
+    if (raw.actual.length > MAX_TRACE_STRING) caps.strings = true;
+    out.actual = raw.actual.slice(0, MAX_TRACE_STRING);
+  } else if (unknownable(raw.actual) !== undefined) {
+    out.actual = unknownable(raw.actual);
+  }
+  return out;
+}
+
+/** Whitelisted capability-evidence parse; unknown fields are dropped. */
+function parseCapability(raw: unknown, caps: ParseCaps): RouteCapabilityEvidence | undefined {
+  if (!isPlainRecord(raw)) return undefined;
+  const out: RouteCapabilityEvidence = {};
+  if (finiteNumber(raw.contextWindow)) out.contextWindow = raw.contextWindow;
+  const tools = unknownable(raw.tools);
+  if (tools !== undefined) out.tools = tools;
+  const image = unknownable(raw.image);
+  if (image !== undefined) out.image = image;
+  const structuredOutput = unknownable(raw.structuredOutput);
+  if (structuredOutput !== undefined) out.structuredOutput = structuredOutput;
+  const rawReasoningEfforts = Array.isArray(raw.reasoningEfforts)
+    ? raw.reasoningEfforts
+    : undefined;
+  const reasoningEfforts = rawReasoningEfforts
+    ? Array.from(
+      { length: Math.min(rawReasoningEfforts.length, 8) },
+      (_, index) => rawReasoningEfforts[index],
+    )
+    : undefined;
+  if (reasoningEfforts
+    && reasoningEfforts.every((value): value is string => typeof value === "string")) {
+    if (reasoningEfforts.some((value: unknown) => typeof value === "string"
+      && value.length > MAX_TRACE_STRING)) caps.strings = true;
+    out.reasoningEfforts = reasoningEfforts.map(value => value.slice(0, MAX_TRACE_STRING));
+  }
+  if (raw.serviceTier === "unknown") {
+    out.serviceTier = "unknown";
+  } else if (typeof raw.serviceTier === "string" && raw.serviceTier) {
+    if (raw.serviceTier.length > MAX_TRACE_STRING) caps.strings = true;
+    out.serviceTier = raw.serviceTier.slice(0, MAX_TRACE_STRING);
+  }
+  const localOnly = unknownable(raw.localOnly);
+  if (localOnly !== undefined) out.localOnly = localOnly;
+  const remoteAllowed = unknownable(raw.remoteAllowed);
+  if (remoteAllowed !== undefined) out.remoteAllowed = remoteAllowed;
+  const encryptedCodexTasks = unknownable(raw.encryptedCodexTasks);
+  if (encryptedCodexTasks !== undefined) out.encryptedCodexTasks = encryptedCodexTasks;
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** Whitelisted health-evidence parse; non-numeric fields are dropped. */
+function parseHealth(raw: unknown): RouteHealthEvidence | undefined {
+  if (!isPlainRecord(raw)) return undefined;
+  const out: RouteHealthEvidence = {};
+  if (finiteNumber(raw.cooldownUntilMs)) out.cooldownUntilMs = raw.cooldownUntilMs;
+  if (finiteNumber(raw.softAvoidUntilMs)) out.softAvoidUntilMs = raw.softAvoidUntilMs;
+  if (finiteNumber(raw.successRate)) out.successRate = raw.successRate;
+  if (finiteNumber(raw.failures)) out.failures = raw.failures;
+  if (finiteNumber(raw.incompleteStreamRate)) out.incompleteStreamRate = raw.incompleteStreamRate;
+  if (finiteNumber(raw.recentLatencyMs)) out.recentLatencyMs = raw.recentLatencyMs;
+  if (finiteNumber(raw.sampleCount)) out.sampleCount = raw.sampleCount;
+  if (finiteNumber(raw.recencyWeight)) out.recencyWeight = raw.recencyWeight;
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+/** Whitelisted quota-evidence parse; requires a boolean `known`. */
+function parseQuota(raw: unknown, caps: ParseCaps): RouteQuotaEvidence | undefined {
+  if (!isPlainRecord(raw)) return undefined;
+  if (typeof raw.known !== "boolean") return undefined;
+  const out: RouteQuotaEvidence = { known: raw.known };
+  if (finiteNumber(raw.headroom)) out.headroom = Math.max(0, Math.min(1, raw.headroom));
+  if (finiteNumber(raw.headroomTokens)) out.headroomTokens = raw.headroomTokens;
+  if (typeof raw.exhausted === "boolean") out.exhausted = raw.exhausted;
+  if (finiteNumber(raw.resetAtMs)) out.resetAtMs = raw.resetAtMs;
+  if (typeof raw.reauthOrCooling === "boolean") out.reauthOrCooling = raw.reauthOrCooling;
+  if (finiteNumber(raw.reservedHeadroomTokens)) out.reservedHeadroomTokens = raw.reservedHeadroomTokens;
+  if (typeof raw.source === "string" && raw.source) {
+    if (raw.source.length > MAX_TRACE_STRING) caps.strings = true;
+    out.source = raw.source.slice(0, MAX_TRACE_STRING);
+  }
+  return out;
+}
+
+const COST_CAP_OUTCOMES = new Set<RouteCostCapOutcome>([
+  "satisfied",
+  "exceeded",
+  "unknown-allowed",
+  "unknown-excluded",
+]);
+
+/** Whitelisted cost-evidence parse. */
+function parseCost(raw: unknown, caps: ParseCaps): RouteCostEvidence | undefined {
+  if (!isPlainRecord(raw)) return undefined;
+  const out: RouteCostEvidence = {};
+  if (finiteNumber(raw.estimatedUsd)) out.estimatedUsd = raw.estimatedUsd;
+  if (typeof raw.priceSource === "string" && raw.priceSource) {
+    if (raw.priceSource.length > MAX_TRACE_STRING) caps.strings = true;
+    out.priceSource = raw.priceSource.slice(0, MAX_TRACE_STRING);
+  }
+  if (typeof raw.incomplete === "boolean") out.incomplete = raw.incomplete;
+  if (finiteNumber(raw.limitUsd)) out.limitUsd = raw.limitUsd;
+  if (out.limitUsd !== undefined
+    && typeof raw.capOutcome === "string"
+    && COST_CAP_OUTCOMES.has(raw.capOutcome as RouteCostCapOutcome)) {
+    out.capOutcome = raw.capOutcome as RouteCostCapOutcome;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+const MAX_COMPATIBILITY_SUITES = 8;
+const COMPATIBILITY_OUTCOMES = new Set(["satisfied", "penalized", "excluded", "unknown"]);
+
+function parseCompatibility(raw: unknown, caps: ParseCaps): RouteCompatibilityEvidence | undefined {
+  if (!isPlainRecord(raw)) return undefined;
+  const suitesRaw = Array.isArray(raw.suites) ? raw.suites : [];
+  if (suitesRaw.length > MAX_COMPATIBILITY_SUITES || raw.truncated === true) caps.compatibility = true;
+  const suites: RouteCompatibilitySuiteTrace[] = [];
+  for (const entry of suitesRaw.slice(0, MAX_COMPATIBILITY_SUITES)) {
+    if (!isPlainRecord(entry)) continue;
+    const suiteId = entry.suiteId;
+    const evidenceLayer = entry.evidenceLayer;
+    const outcome = entry.outcome;
+    if (typeof suiteId !== "string" || typeof evidenceLayer !== "string") continue;
+    if (typeof outcome !== "string" || !COMPATIBILITY_OUTCOMES.has(outcome)) continue;
+    const row: RouteCompatibilitySuiteTrace = {
+      suiteId: capString(suiteId, caps),
+      evidenceLayer: capString(evidenceLayer, caps),
+      outcome: outcome as RouteCompatibilitySuiteTrace["outcome"],
+    };
+    if (typeof entry.subjectIdPrefix === "string" && entry.subjectIdPrefix) {
+      row.subjectIdPrefix = capString(entry.subjectIdPrefix, caps);
+    }
+    for (const key of ["verdict", "minStatus", "reason", "unknownPolicy", "degradedPolicy"] as const) {
+      if (typeof entry[key] === "string") row[key] = capString(entry[key] as string, caps);
+    }
+    if (typeof entry.fresh === "boolean") row.fresh = entry.fresh;
+    suites.push(row);
+  }
+  const out: RouteCompatibilityEvidence = {
+    suites,
+    ...(raw.truncated === true ? { truncated: true as const } : {}),
+  };
+  if (typeof raw.subjectIdPrefix === "string" && raw.subjectIdPrefix) {
+    out.subjectIdPrefix = capString(raw.subjectIdPrefix, caps);
+  }
+  return suites.length > 0 || out.subjectIdPrefix || out.truncated ? out : undefined;
+}
+
+/** Whitelisted score parse; requires a finite `total` and bounded components. */
+function parseScore(raw: unknown): RouteScoreEvidence | undefined {
+  if (!isPlainRecord(raw)) return undefined;
+  if (!finiteNumber(raw.total)) return undefined;
+  const components = isPlainRecord(raw.components) ? raw.components : {};
+  const parsedComponents: RouteScoreEvidence["components"] = {};
+  for (const key of ["capability", "health", "quota", "cost", "latency", "configuredPriority", "compatibility"] as const) {
+    if (finiteNumber(components[key])) parsedComponents[key] = components[key];
+  }
+  return { total: raw.total, components: parsedComponents };
+}
+
+/** Defensive parse of one persisted candidate with bounded evidence blocks. */
+function parseCandidate(raw: unknown, caps: ParseCaps): RouteCandidateTrace | null {
+  if (!isPlainRecord(raw)) return null;
+  const provider = raw.provider;
+  const model = raw.model;
+  if (typeof provider !== "string" || provider.length === 0) return null;
+  if (typeof model !== "string" || model.length === 0) return null;
+  if (provider.length > MAX_TRACE_STRING) caps.strings = true;
+  if (model.length > MAX_TRACE_STRING) caps.strings = true;
+  if (typeof raw.accountRef === "string" && raw.accountRef.length > MAX_TRACE_STRING) caps.strings = true;
+  if (typeof raw.eligible !== "boolean") return null;
+  if (Array.isArray(raw.exclusions) && raw.exclusions.length > MAX_EXCLUSIONS_PER_CANDIDATE) caps.exclusions = true;
+  const exclusions = Array.isArray(raw.exclusions)
+    ? raw.exclusions.slice(0, MAX_EXCLUSIONS_PER_CANDIDATE)
+      .map(value => parseExclusion(value, caps))
+      .filter((value): value is RouteExclusionReason => value !== null)
+    : [];
+  const capability = parseCapability(raw.capability, caps);
+  const health = parseHealth(raw.health);
+  const quota = parseQuota(raw.quota, caps);
+  const cost = parseCost(raw.cost, caps);
+  const compatibility = parseCompatibility(raw.compatibility, caps);
+  const score = parseScore(raw.score);
+  return {
+    provider: provider.slice(0, MAX_TRACE_STRING),
+    model: model.slice(0, MAX_TRACE_STRING),
+    ...(typeof raw.accountRef === "string"
+      ? { accountRef: raw.accountRef.slice(0, MAX_TRACE_STRING) }
+      : {}),
+    eligible: raw.eligible,
+    exclusions: exclusions.slice(0, MAX_EXCLUSIONS_PER_CANDIDATE),
+    ...(capability ? { capability } : {}),
+    ...(health ? { health } : {}),
+    ...(quota ? { quota } : {}),
+    ...(cost ? { cost } : {}),
+    ...(compatibility ? { compatibility } : {}),
+    ...(score ? { score } : {}),
+  };
+}
+
+/**
+ * Defensive parse of a persisted trace. Returns null when the row is not a
+ * version-1 trace; otherwise returns a bounded, whitelisted copy. Invalid
+ * evidence objects are dropped rather than poisoning the DTO.
+ */
+export function normalizeRouteDecisionTrace(raw: unknown): RouteDecisionTraceV1 | null {
+  if (!isPlainRecord(raw)) return null;
+  if (raw.version !== 1) return null;
+  const caps: ParseCaps = {};
+  const decisionId = raw.decisionId;
+  const createdAt = raw.createdAt;
+  const requestedModel = raw.requestedModel;
+  const routeKind = raw.routeKind;
+  if (typeof decisionId !== "string" || decisionId.length === 0) return null;
+  if (!/^[0-9a-f]{12}$/.test(decisionId)) return null;
+  if (decisionId.length > MAX_TRACE_STRING) caps.strings = true;
+  if (!finiteNumber(createdAt)) return null;
+  if (typeof requestedModel !== "string" || requestedModel.length === 0) return null;
+  if (requestedModel.length > MAX_TRACE_STRING) caps.strings = true;
+  if (typeof routeKind !== "string" || !ROUTE_KINDS.has(routeKind as RouteDecisionKind)) return null;
+  if (!Array.isArray(raw.candidates) || raw.candidates.length === 0) return null;
+  if (raw.candidates.length > MAX_TRACE_CANDIDATES) caps.candidates = true;
+
+  const candidates = raw.candidates
+    .slice(0, MAX_TRACE_CANDIDATES)
+    .map(value => parseCandidate(value, caps))
+    .filter((value): value is RouteCandidateTrace => value !== null)
+    .slice(0, MAX_TRACE_CANDIDATES);
+  if (candidates.length === 0) return null;
+
+  const selected = isPlainRecord(raw.selected) ? raw.selected : null;
+  if (!selected) return null;
+  const selectedProvider = selected.provider;
+  const selectedModel = selected.model;
+  const selectedReason = selected.reason;
+  if (typeof selectedProvider !== "string" || typeof selectedModel !== "string") return null;
+  if (typeof selectedReason !== "string") return null;
+  if (selectedProvider.length > MAX_TRACE_STRING) caps.strings = true;
+  if (selectedModel.length > MAX_TRACE_STRING) caps.strings = true;
+  if (selectedReason.length > MAX_TRACE_STRING) caps.strings = true;
+  if (typeof selected.accountRef === "string" && selected.accountRef.length > MAX_TRACE_STRING) caps.strings = true;
+  if (typeof selected.tieBreak === "string" && selected.tieBreak.length > MAX_TRACE_STRING) caps.strings = true;
+  const candidateIndex = Number.isInteger(selected.candidateIndex)
+    ? selected.candidateIndex as number
+    : 0;
+  if (candidateIndex < 0 || candidateIndex >= candidates.length) return null;
+
+  const rawRequirements = Array.isArray(raw.requirements) ? raw.requirements : [];
+  if (rawRequirements.length > MAX_REQUIREMENTS) caps.requirements = true;
+  const requirements = rawRequirements
+    .slice(0, MAX_REQUIREMENTS)
+    .map(value => parseRequirement(value, caps))
+    .filter((value): value is RouteRequirementEvidence => value !== null)
+    .slice(0, MAX_REQUIREMENTS);
+
+  const profile = isPlainRecord(raw.profile)
+    && typeof raw.profile.id === "string"
+    && typeof raw.profile.revision === "string"
+    ? (() => {
+      if (raw.profile.id.length > MAX_TRACE_STRING) caps.strings = true;
+      if (raw.profile.revision.length > MAX_TRACE_STRING) caps.strings = true;
+      return {
+        id: raw.profile.id.slice(0, MAX_TRACE_STRING),
+        revision: raw.profile.revision.slice(0, MAX_TRACE_STRING),
+      };
+    })()
+    : undefined;
+
+  const incoming = isPlainRecord(raw.truncated) ? raw.truncated : {};
+  const truncated: RouteDecisionTraceV1["truncated"] = {};
+  if (incoming.candidates === true || caps.candidates) truncated.candidates = true;
+  if (incoming.exclusions === true || caps.exclusions) truncated.exclusions = true;
+  if (incoming.requirements === true || caps.requirements) truncated.requirements = true;
+  if (incoming.strings === true || caps.strings) truncated.strings = true;
+  if (incoming.compatibility === true || caps.compatibility) truncated.compatibility = true;
+
+  return {
+    version: 1,
+    decisionId: decisionId.slice(0, MAX_TRACE_STRING),
+    createdAt,
+    requestedModel: requestedModel.slice(0, MAX_TRACE_STRING),
+    routeKind: routeKind as RouteDecisionKind,
+    ...(profile ? { profile } : {}),
+    requirements,
+    candidates,
+    selected: {
+      candidateIndex,
+      provider: selectedProvider.slice(0, MAX_TRACE_STRING),
+      model: selectedModel.slice(0, MAX_TRACE_STRING),
+      ...(typeof selected.accountRef === "string"
+        ? { accountRef: selected.accountRef.slice(0, MAX_TRACE_STRING) }
+        : {}),
+      reason: selectedReason.slice(0, MAX_TRACE_STRING),
+      ...(typeof selected.tieBreak === "string"
+        ? { tieBreak: selected.tieBreak.slice(0, MAX_TRACE_STRING) }
+        : {}),
+    },
+    ...(Object.keys(truncated).length > 0 ? { truncated } : {}),
+  };
+}