@iislee/opencodex 2.11.0 → 2.31.0

package/src/server/management/request-history-routes.ts

@@ -0,0 +1,191 @@
+/**
+ * Cursor-paginated request-history API (RI-02).
+ *
+ * - `GET /api/request-history` - keyset-paginated rows with filters
+ * - `GET /api/request-history/:requestId` - one canonical row
+ * - `GET /api/request-history/:requestId/route-decision` - why-this-route
+ *   explanation (RI-09): durable trace + attempts + outcome
+ *
+ * The index is a derived projection of `usage.jsonl`; every response carries
+ * an `index` status block so callers can see schema version, indexed rows and
+ * any repair the indexer performed.
+ */
+
+import {
+  queryRequestHistory,
+  requestHistoryRowById,
+  REQUEST_HISTORY_MAX_PAGE_SIZE,
+} from "../../routing/history/indexer";
+import { InvalidCursorError } from "../../routing/history/cursor";
+import { requestLogEntryFromPersistedUsage } from "../request-log";
+import { requestLogDto } from "./shared";
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+import type { PersistedUsageEntry } from "../../usage/log";
+
+function parseQueryInt(raw: string | null): number | undefined | "invalid" {
+  if (raw === null) return undefined;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return "invalid";
+  const value = Number(trimmed);
+  return Number.isInteger(value) ? value : "invalid";
+}
+
+function finalAttemptTarget(entry: PersistedUsageEntry): { provider: string; model: string } {
+  const attempts = entry.attempts;
+  if (Array.isArray(attempts) && attempts.length > 0) {
+    const last = attempts[attempts.length - 1];
+    if (last && typeof last.provider === "string" && typeof last.model === "string") {
+      return { provider: last.provider, model: last.model };
+    }
+  }
+  return { provider: entry.provider, model: entry.model };
+}
+
+export async function handleRequestHistoryRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { url, req, config } = ctx;
+  if (!url.pathname.startsWith("/api/request-history")) return null;
+
+  if (url.pathname === "/api/request-history" && req.method === "GET") {
+    const statusRaw = parseQueryInt(url.searchParams.get("status"));
+    if (statusRaw === "invalid") {
+      return jsonResponse({ error: { code: "invalid_status", message: "status must be an integer from 100 to 599" } }, 400, req, config);
+    }
+    const status = statusRaw;
+    if (status !== undefined && (status < 100 || status > 599)) {
+      return jsonResponse({ error: { code: "invalid_status", message: "status must be an integer from 100 to 599" } }, 400, req, config);
+    }
+    const fromRaw = parseQueryInt(url.searchParams.get("from"));
+    if (fromRaw === "invalid") {
+      return jsonResponse({ error: { code: "invalid_from", message: "from must be an integer timestamp" } }, 400, req, config);
+    }
+    const toRaw = parseQueryInt(url.searchParams.get("to"));
+    if (toRaw === "invalid") {
+      return jsonResponse({ error: { code: "invalid_to", message: "to must be an integer timestamp" } }, 400, req, config);
+    }
+    const from = fromRaw;
+    const to = toRaw;
+    if (from !== undefined && to !== undefined && from > to) {
+      return jsonResponse({ error: { code: "invalid_range", message: "from must not be after to" } }, 400, req, config);
+    }
+    const limitRaw = url.searchParams.get("limit");
+    const limitParsed = limitRaw === null ? undefined : parseQueryInt(limitRaw);
+    if (limitParsed === "invalid") {
+      return jsonResponse(
+        { error: { code: "invalid_limit", message: `limit must be an integer from 1 to ${REQUEST_HISTORY_MAX_PAGE_SIZE}` } },
+        400,
+        req,
+        config,
+      );
+    }
+    const limit = limitParsed;
+    if (limit !== undefined && (limit < 1 || limit > REQUEST_HISTORY_MAX_PAGE_SIZE)) {
+      return jsonResponse(
+        { error: { code: "invalid_limit", message: `limit must be an integer from 1 to ${REQUEST_HISTORY_MAX_PAGE_SIZE}` } },
+        400,
+        req,
+        config,
+      );
+    }
+    const cursor = url.searchParams.get("cursor");
+    try {
+      const page = await queryRequestHistory({
+        provider: url.searchParams.get("provider")?.trim() || undefined,
+        model: url.searchParams.get("model")?.trim() || undefined,
+        requestedModel: url.searchParams.get("requestedModel")?.trim() || undefined,
+        status,
+        conversationId: url.searchParams.get("conversationId")?.trim() || undefined,
+        surface: url.searchParams.get("surface")?.trim() || undefined,
+        inboundProtocol: url.searchParams.get("inboundProtocol")?.trim() || undefined,
+        apiKeyId: url.searchParams.get("apiKeyId")?.trim() || undefined,
+        profileId: url.searchParams.get("profileId")?.trim() || undefined,
+        fallback: url.searchParams.get("fallback") === "true"
+          ? true
+          : url.searchParams.get("fallback") === "false" ? false : undefined,
+        from,
+        to,
+      }, cursor, limit);
+      return jsonResponse({
+        entries: page.rows.map(row => requestLogDto(requestLogEntryFromPersistedUsage(row))),
+        ...(page.nextCursor ? { nextCursor: page.nextCursor } : {}),
+        hasMore: page.hasMore,
+        index: {
+          schemaVersion: page.meta.schemaVersion,
+          indexedRows: page.meta.indexedRows,
+          sourceSize: page.meta.sourceSize,
+          sourceMtimeMs: page.meta.sourceMtimeMs,
+          builtAtMs: page.meta.builtAtMs,
+          lastError: page.meta.lastError,
+        },
+      }, 200, req, config);
+    } catch (err) {
+      if (err instanceof InvalidCursorError) {
+        return jsonResponse({ error: { code: "invalid_cursor", message: "invalid cursor" } }, 400, req, config);
+      }
+      throw err;
+    }
+  }
+
+  if (url.pathname.startsWith("/api/request-history/") && req.method === "GET") {
+    // Why-this-route explanation (RI-09): trace + attempts + outcome.
+    if (url.pathname.endsWith("/route-decision")) {
+      let requestId: string;
+      try {
+        requestId = decodeURIComponent(
+          url.pathname.slice("/api/request-history/".length, -"/route-decision".length),
+        );
+      } catch {
+        return jsonResponse({ error: { code: "not_found", message: "unknown request" } }, 404, req, config);
+      }
+      if (!requestId || requestId.includes("/")) {
+        return jsonResponse({ error: { code: "not_found", message: "unknown request" } }, 404, req, config);
+      }
+      const entry = await requestHistoryRowById(requestId);
+      if (!entry) {
+        return jsonResponse({ error: { code: "not_found", message: "unknown request" } }, 404, req, config);
+      }
+      const trace = entry.routeDecision ?? null;
+      const final = finalAttemptTarget(entry);
+      return jsonResponse({
+        requestId,
+        routeDecision: trace,
+        attemptSequence: entry.attempts ?? [],
+        outcome: {
+          status: entry.status,
+          ...(entry.terminalStatus ? { terminalStatus: entry.terminalStatus } : {}),
+          ...(entry.closeReason ? { closeReason: entry.closeReason } : {}),
+          ...(entry.errorCode ? { errorCode: entry.errorCode } : {}),
+          ...(entry.durationMs !== undefined ? { durationMs: entry.durationMs } : {}),
+          ...(entry.usageStatus ? { usageStatus: entry.usageStatus } : {}),
+        },
+        summary: {
+          requestedModel: entry.requestedModel ?? entry.model,
+          routeKind: trace?.routeKind ?? null,
+          ...(trace?.profile ? { profileId: trace.profile.id, revision: trace.profile.revision } : {}),
+          selected: trace?.selected
+            ? { provider: trace.selected.provider, model: trace.selected.model }
+            : null,
+          finalProvider: final.provider,
+          finalModel: final.model,
+        },
+      }, 200, req, config);
+    }
+
+    let requestId: string;
+    try {
+      requestId = decodeURIComponent(url.pathname.slice("/api/request-history/".length));
+    } catch {
+      return jsonResponse({ error: { code: "not_found", message: "unknown request" } }, 404, req, config);
+    }
+    if (!requestId || requestId.includes("/")) {
+      return jsonResponse({ error: { code: "not_found", message: "unknown request" } }, 404, req, config);
+    }
+    const entry = await requestHistoryRowById(requestId);
+    if (!entry) {
+      return jsonResponse({ error: { code: "not_found", message: "unknown request" } }, 404, req, config);
+    }
+    return jsonResponse(requestLogDto(requestLogEntryFromPersistedUsage(entry)), 200, req, config);
+  }
+
+  return null;
+}

package/src/server/management/routing-analytics-routes.ts

@@ -0,0 +1,74 @@
+/**
+ * Routing analytics API (RI-03): `GET /api/routing-analytics`.
+ *
+ * Returns source-backed reliability/latency/cost metrics over the
+ * request-history index. Read-only; never changes routing behavior.
+ */
+
+import {
+  ANALYTICS_API_DEFAULT_ROWS,
+  ANALYTICS_MAX_ROWS,
+  computeRoutingAnalytics,
+} from "../../routing/analytics";
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+
+function parseQueryInt(raw: string | null): number | undefined | "invalid" {
+  if (raw === null) return undefined;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return "invalid";
+  const value = Number(trimmed);
+  return Number.isInteger(value) ? value : "invalid";
+}
+
+export async function handleRoutingAnalyticsRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { url, req, config } = ctx;
+  if (url.pathname !== "/api/routing-analytics" || req.method !== "GET") return null;
+
+  const fromParsed = parseQueryInt(url.searchParams.get("from"));
+  if (fromParsed === "invalid") {
+    return jsonResponse({ error: { code: "invalid_from", message: "from must be an integer timestamp" } }, 400, req, config);
+  }
+  const toParsed = parseQueryInt(url.searchParams.get("to"));
+  if (toParsed === "invalid") {
+    return jsonResponse({ error: { code: "invalid_to", message: "to must be an integer timestamp" } }, 400, req, config);
+  }
+  const from = fromParsed;
+  const to = toParsed;
+  if (from !== undefined && to !== undefined && from > to) {
+    return jsonResponse({ error: { code: "invalid_range", message: "from must not be after to" } }, 400, req, config);
+  }
+  const limitParsed = parseQueryInt(url.searchParams.get("limit"));
+  if (limitParsed === "invalid") {
+    return jsonResponse(
+      { error: { code: "invalid_limit", message: "limit must be an integer" } },
+      400,
+      req,
+      config,
+    );
+  }
+  const maxRows = limitParsed ?? ANALYTICS_API_DEFAULT_ROWS;
+  if (maxRows < 1 || maxRows > ANALYTICS_MAX_ROWS) {
+    return jsonResponse(
+      {
+        error: {
+          code: "invalid_limit",
+          message: `limit must be between 1 and ${ANALYTICS_MAX_ROWS}`,
+        },
+      },
+      400,
+      req,
+      config,
+    );
+  }
+
+  const result = await computeRoutingAnalytics({
+    provider: url.searchParams.get("provider")?.trim() || undefined,
+    model: url.searchParams.get("model")?.trim() || undefined,
+    profileId: url.searchParams.get("profileId")?.trim() || undefined,
+    surface: url.searchParams.get("surface")?.trim() || undefined,
+    from,
+    to,
+  }, { maxRows });
+  return jsonResponse(result, 200, req, config);
+}

package/src/server/management/routing-profile-routes.ts

@@ -0,0 +1,380 @@
+/**
+ * Routing-profile management API (RI-04).
+ *
+ * - `GET    /api/routing-profiles` - normalized profiles with revisions
+ * - `PUT    /api/routing-profiles` - create or replace one validated profile
+ * - `DELETE /api/routing-profiles?id=<id>` - remove one profile
+ * - `POST   /api/routing-profiles/dry-run` - deterministic dry-run evaluation
+ *   (never dispatches an upstream request)
+ */
+
+import {
+  getRoutingProfile,
+  listRoutingProfileIds,
+  normalizeRoutingProfile,
+  policyPublicModelId,
+  routingProfileIssues,
+} from "../../routing/profile";
+import { evaluatePolicyProfile, type PolicyCandidateEvidence, type PolicyRequestEvidence } from "../../routing/evaluator";
+import { assemblePolicyCandidateEvidence } from "../../routing/compatibility/assemble";
+import { activateLab, labActivationRequired } from "../../lib/lab-activation";
+import { quotaEvidenceForCandidate } from "../../routing/quota";
+import { routedProviderConfig } from "../../router";
+import { saveConfigPreservingClaudeCode, getConfigDir } from "../../config";
+import { reconcileLiveStateStores } from "../../lib/state-store-registrations";
+import { isPlainRecord } from "./shared";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import { jsonResponse } from "../auth-cors";
+import type { ManagementContext } from "./context";
+import type { OcxConfig, OcxRoutingProfileConfig } from "../../types";
+
+function profileDto(config: Parameters<typeof getRoutingProfile>[0], id: string): Record<string, unknown> | null {
+  const profile = getRoutingProfile(config, id);
+  if (!profile) return null;
+  return {
+    id,
+    alias: profile.alias,
+    model: policyPublicModelId(id, profile),
+    revision: profile.revision,
+    candidates: profile.candidates,
+    require: profile.require,
+    optimize: profile.optimize,
+    limits: profile.limits,
+    unknownEvidence: profile.unknownEvidence,
+    ...(profile.compatibility ? { compatibility: profile.compatibility } : {}),
+  };
+}
+
+function parseEvidence(raw: unknown): { evidence: PolicyRequestEvidence; ok: boolean } {
+  // Absent evidence is empty evidence, mirroring the absent-candidates case.
+  if (raw === undefined) return { evidence: {}, ok: true };
+  if (!isPlainRecord(raw)) return { evidence: {}, ok: false };
+  const record = raw as Record<string, unknown>;
+  const evidence: PolicyRequestEvidence = {};
+  if (typeof record.contextWindow === "number" && Number.isFinite(record.contextWindow) && record.contextWindow >= 0) {
+    evidence.contextWindow = record.contextWindow;
+  }
+  for (const key of ["toolsRequired", "imageInputRequired", "structuredOutputRequired", "encryptedCodexTask"] as const) {
+    if (typeof record[key] === "boolean") evidence[key] = record[key];
+  }
+  if (typeof record.reasoningEffort === "string") evidence.reasoningEffort = record.reasoningEffort;
+  if (typeof record.serviceTier === "string") evidence.serviceTier = record.serviceTier;
+  return { evidence, ok: true };
+}
+
+function parseCandidateEvidence(raw: unknown): PolicyCandidateEvidence[] | null {
+  if (!Array.isArray(raw)) return null;
+  const out: PolicyCandidateEvidence[] = [];
+  for (const item of raw) {
+    if (!isPlainRecord(item)) return null;
+    const provider = item.provider;
+    const model = item.model;
+    if (typeof provider !== "string" || typeof model !== "string") return null;
+    out.push({
+      provider,
+      model,
+      ...(typeof item.accountRef === "string" ? { accountRef: item.accountRef } : {}),
+      ...(typeof item.codexAccountId === "string" ? { codexAccountId: item.codexAccountId } : {}),
+      // Dry-run evidence is caller-supplied and echoed back in the result as
+      // given; the trace's candidate rows carry only score/exclusions, which
+      // the trace builder bounds. Structural casts keep the API permissive.
+      ...(isPlainRecord(item.capability) ? { capability: item.capability as unknown as PolicyCandidateEvidence["capability"] } : {}),
+      ...(isPlainRecord(item.health) ? { health: item.health as unknown as PolicyCandidateEvidence["health"] } : {}),
+      ...(isPlainRecord(item.quota) ? { quota: item.quota as unknown as PolicyCandidateEvidence["quota"] } : {}),
+      ...(isPlainRecord(item.cost) ? { cost: item.cost as unknown as PolicyCandidateEvidence["cost"] } : {}),
+      // Derive account-scoped quota evidence from the documented refs when the
+      // caller does not supply an explicit quota object, so a dry-run following
+      // the documented shape reports the same cached account quota as routing.
+      ...(item.quota === undefined && typeof item.codexAccountId === "string"
+        ? { quota: quotaEvidenceForCandidate({ provider, model, codexAccountId: item.codexAccountId }) }
+        : {}),
+      ...(item.quota === undefined && typeof item.accountRef === "string" && typeof item.codexAccountId !== "string"
+        ? { quota: quotaEvidenceForCandidate({ provider, model, accountRef: item.accountRef }) }
+        : {}),
+    });
+  }
+  return out;
+}
+
+function assembleCandidateEvidence(
+  config: OcxConfig,
+  profile: NonNullable<ReturnType<typeof getRoutingProfile>>,
+  now: number,
+): PolicyCandidateEvidence[] {
+  return assemblePolicyCandidateEvidence(config, profile, now, {
+    routedProviderConfig,
+  });
+}
+
+function storedProfile(
+  id: string,
+  raw: OcxRoutingProfileConfig,
+): OcxRoutingProfileConfig {
+  const normalized = normalizeRoutingProfile(id, raw);
+  const {
+    id: _id,
+    revision: _revision,
+    alias,
+    ...profile
+  } = normalized;
+  return alias === null ? profile : { ...profile, alias };
+}
+
+/**
+ * Rewrite config references from one public model id to another (alias change
+ * on update). Mirrors the /api/combos migration: model-valued config that
+ * still names the old alias must follow it, or requests fall through to
+ * ordinary routing and send the obsolete alias upstream.
+ */
+/**
+ * Detect a modelMap key collision that the alias migration would silently
+ * resolve by dropping one mapping: the map already contains the new public
+ * model as a key with a different target than the old-alias key's target.
+ */
+function modelMapMigrationCollision(
+  config: OcxConfig,
+  oldPublicModel: string,
+  newPublicModel: string,
+): string | null {
+  const map = config.claudeCode?.modelMap;
+  if (!map) return null;
+  if (oldPublicModel === newPublicModel) return null;
+  const oldTarget = map[oldPublicModel];
+  if (oldTarget === undefined) return null;
+  const newTarget = map[newPublicModel];
+  if (newTarget === undefined) return null;
+  if (oldTarget === newTarget) return null;
+  return `modelMap already maps \"${newPublicModel}\" to \"${newTarget}\"; renaming \"${oldPublicModel}\" (→ \"${newTarget}\") would drop one mapping. Resolve the conflict and retry.`;
+}
+
+/**
+ * Rewrite config references from one public model id to another (alias change
+ * on update). Mirrors the /api/combos migration: model-valued config that
+ * still names the old alias must follow it, or requests fall through to
+ * ordinary routing and send the obsolete alias upstream.
+ */
+function migrateProfileModelReferences(
+  config: OcxConfig,
+  oldPublicModel: string,
+  newPublicModel: string,
+): boolean {
+  if (oldPublicModel === newPublicModel) return false;
+  const migrateReference = (model: string): string => (
+    model === oldPublicModel ? newPublicModel : model
+  );
+  let shouldSyncClaudeAgentDefs = false;
+  const migrateAgentReference = (model: string): string => {
+    const migrated = migrateReference(model);
+    if (migrated !== model) shouldSyncClaudeAgentDefs = true;
+    return migrated;
+  };
+  const migrateReferences = (models: string[]): string[] => [
+    ...new Set(models.map(migrateReference)),
+  ];
+  if (config.disabledModels) {
+    config.disabledModels = migrateReferences(config.disabledModels);
+  }
+  if (config.subagentModels) {
+    config.subagentModels = [...new Set(config.subagentModels.map(migrateAgentReference))];
+  }
+  if (config.subagentModelFallback) {
+    config.subagentModelFallback = [...new Set(config.subagentModelFallback.map(migrateAgentReference))];
+  }
+  if (config.injectionModel && config.injectionModel === oldPublicModel) {
+    config.injectionModel = newPublicModel;
+  }
+  if (config.shadowCallIntercept?.model && config.shadowCallIntercept.model === oldPublicModel) {
+    config.shadowCallIntercept = { ...config.shadowCallIntercept, model: newPublicModel };
+  }
+  if (config.claudeCode) {
+    const claudeCode = { ...config.claudeCode };
+    for (const field of ["model", "smallFastModel"] as const) {
+      if (claudeCode[field]) claudeCode[field] = migrateAgentReference(claudeCode[field]);
+    }
+    if (claudeCode.tierModels) {
+      claudeCode.tierModels = Object.fromEntries(
+        Object.entries(claudeCode.tierModels).map(([tier, model]) => [tier, migrateAgentReference(model)]),
+      );
+    }
+    if (claudeCode.modelMap) {
+      // Keys are the inbound ids matched for reroute (src/claude/inbound.ts);
+      // an old-alias key must follow the rename or that request stops intercepting.
+      claudeCode.modelMap = Object.fromEntries(
+        Object.entries(claudeCode.modelMap).map(([source, model]) => [
+          migrateAgentReference(source),
+          migrateAgentReference(model),
+        ]),
+      );
+    }
+    config.claudeCode = claudeCode;
+  }
+  return shouldSyncClaudeAgentDefs;
+}
+export async function handleRoutingProfileRoutes(ctx: ManagementContext): Promise<Response | null> {
+  const { req, url, config, deps, convergeCodexCatalog, syncClaudeAgentDefsBestEffort } = ctx;
+
+  if (url.pathname === "/api/routing-profiles" && req.method === "GET") {
+    const profiles = listRoutingProfileIds(config).map(id => profileDto(config, id)).filter(
+      (profile): profile is Record<string, unknown> => profile !== null,
+    );
+    return jsonResponse({ profiles }, 200, req, config);
+  }
+
+  if (url.pathname === "/api/routing-profiles" && req.method === "PUT") {
+    let rawBody: unknown;
+    try {
+      rawBody = await readManagementJsonBody(req);
+    } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      return jsonResponse({ error: "invalid JSON body" }, 400, req, config);
+    }
+    if (!isPlainRecord(rawBody)) {
+      return jsonResponse({ error: "request body must be an object" }, 400, req, config);
+    }
+    const body = rawBody as Record<string, unknown>;
+    const id = typeof body.id === "string" ? body.id.trim() : "";
+    if (!id) {
+      return jsonResponse({ error: { code: "missing_profile_id", message: "id is required" } }, 400, req, config);
+    }
+    const mode = body.mode === "create" || body.mode === "update" ? body.mode : null;
+    if (!mode) {
+      return jsonResponse({ error: { code: "invalid_profile_mode", message: "mode must be create or update" } }, 400, req, config);
+    }
+    const exists = Object.hasOwn(config.routingProfiles ?? {}, id);
+    if (mode === "create" && exists) {
+      return jsonResponse({ error: { code: "profile_exists", message: `routing profile already exists: ${id}` } }, 409, req, config);
+    }
+    if (mode === "update" && !exists) {
+      return jsonResponse({ error: { code: "unknown_profile", message: `unknown routing profile: ${id}` } }, 404, req, config);
+    }
+    if (mode === "update") {
+      const expectedRevision = typeof body.expectedRevision === "string" && body.expectedRevision.trim()
+        ? body.expectedRevision.trim()
+        : undefined;
+      if (expectedRevision) {
+        const current = getRoutingProfile(config, id);
+        if (current && current.revision !== expectedRevision) {
+          return jsonResponse({
+            error: {
+              code: "profile_revision_conflict",
+              message: `routing profile ${id} changed since it was loaded; reload and retry`,
+              currentRevision: current.revision,
+            },
+          }, 409, req, config);
+        }
+      }
+    }
+    const issues = routingProfileIssues(id, body.profile, config, { excludeProfileId: id });
+    if (issues.length > 0) {
+      return jsonResponse({
+        error: {
+          code: "invalid_profile",
+          message: issues[0]!.message,
+          issues,
+        },
+      }, 400, req, config);
+    }
+
+    const previousProfile = mode === "update" ? getRoutingProfile(config, id) : undefined;
+    if (mode === "update" && previousProfile) {
+      const oldPublicModel = policyPublicModelId(id, previousProfile);
+      const newProfile = normalizeRoutingProfile(id, body.profile as OcxRoutingProfileConfig);
+      const newPublicModel = policyPublicModelId(id, newProfile);
+      const collision = modelMapMigrationCollision(config, oldPublicModel, newPublicModel);
+      if (collision) {
+        return jsonResponse({
+          error: { code: "alias_reference_conflict", message: collision },
+        }, 409, req, config);
+      }
+    }
+    const nextProfiles = { ...(config.routingProfiles ?? {}) };
+    nextProfiles[id] = storedProfile(id, body.profile as OcxRoutingProfileConfig);
+    config.routingProfiles = nextProfiles;
+    // Creating the first profile on a process started profile-less must install the
+    // compatibility provider now; activation is synchronous and idempotent per configDir.
+    if (labActivationRequired(config, getConfigDir())) activateLab(config, getConfigDir());
+    // An alias change on update renames the public model id; rewrite config
+    // references (disabledModels, subagentModels, injectionModel,
+    // shadowCallIntercept, claudeCode) so they follow the new alias.
+    let shouldSyncClaudeAgentDefs = false;
+    if (previousProfile) {
+      const oldPublicModel = policyPublicModelId(id, previousProfile);
+      const newPublicModel = policyPublicModelId(id, getRoutingProfile(config, id)!);
+      shouldSyncClaudeAgentDefs = migrateProfileModelReferences(config, oldPublicModel, newPublicModel);
+    }
+    const save = deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode;
+    save(config);
+    reconcileLiveStateStores();
+    const catalogRefresh = await convergeCodexCatalog();
+    if (shouldSyncClaudeAgentDefs) await syncClaudeAgentDefsBestEffort();
+    const profile = profileDto(config, id)!;
+    return jsonResponse({
+      success: true,
+      id,
+      model: profile.model,
+      profile,
+      catalogRefresh,
+    }, 200, req, config);
+  }
+
+  if (url.pathname === "/api/routing-profiles" && req.method === "DELETE") {
+    const id = url.searchParams.get("id")?.trim();
+    if (!id) {
+      return jsonResponse({ error: "id query param is required" }, 400, req, config);
+    }
+    if (!Object.hasOwn(config.routingProfiles ?? {}, id)) {
+      return jsonResponse({ error: "unknown routing profile" }, 404, req, config);
+    }
+
+    const nextProfiles = { ...(config.routingProfiles ?? {}) };
+    delete nextProfiles[id];
+    if (Object.keys(nextProfiles).length > 0) config.routingProfiles = nextProfiles;
+    else delete config.routingProfiles;
+    const saveConfigPreservingClaudeCodeSafe = deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode;
+    saveConfigPreservingClaudeCodeSafe(config);
+    reconcileLiveStateStores();
+    const catalogRefresh = await convergeCodexCatalog();
+    return jsonResponse({ success: true, id, catalogRefresh }, 200, req, config);
+  }
+
+  if (url.pathname === "/api/routing-profiles/dry-run" && req.method === "POST") {
+    let rawBody: unknown;
+    try { rawBody = await readManagementJsonBody(req); } catch (error) {
+      rethrowManagementBodyTooLarge(error);
+      return jsonResponse({ error: "invalid JSON body" }, 400, req, config);
+    }
+    if (!isPlainRecord(rawBody)) {
+      return jsonResponse({ error: "request body must be an object" }, 400, req, config);
+    }
+    const body = rawBody as Record<string, unknown>;
+    const profile = typeof body.profile === "string" ? body.profile.trim() : "";
+    if (!profile) {
+      return jsonResponse({ error: { code: "missing_profile", message: "profile is required" } }, 400, req, config);
+    }
+    const resolvedProfile = getRoutingProfile(config, profile);
+    if (!resolvedProfile) {
+      return jsonResponse({ error: { code: "unknown_profile", message: `unknown routing profile: ${profile}` } }, 404, req, config);
+    }
+    const { evidence, ok } = parseEvidence(body.evidence);
+    if (!ok) {
+      return jsonResponse({ error: { code: "invalid_evidence", message: "evidence must be an object" } }, 400, req, config);
+    }
+    // One clock read for both assembly and evaluation keeps freshness, health,
+    // and trace timestamps mutually consistent with the production router.
+    const now = Date.now();
+    // R3-1: dry-run assembles candidate evidence independently of the startup gate, so an
+    // operator preview on a process started without profiles would silently omit
+    // compatibility evidence and disagree with production. Activate first.
+    if (labActivationRequired(config, getConfigDir())) activateLab(config, getConfigDir());
+    const candidateEvidence = body.candidates === undefined
+      ? assembleCandidateEvidence(config, resolvedProfile, now)
+      : parseCandidateEvidence(body.candidates);
+    if (candidateEvidence === null) {
+      return jsonResponse({ error: { code: "invalid_candidates", message: "candidates must be an array of evidence objects" } }, 400, req, config);
+    }
+    const result = evaluatePolicyProfile(config, profile, evidence, candidateEvidence, now);
+    return jsonResponse(result, 200, req, config);
+  }
+
+  return null;
+}