@remodex/rmx 1.0.2

package/src/routing/analytics.ts

@@ -0,0 +1,377 @@
+/**
+ * Source-backed routing analytics (RI-03).
+ *
+ * All metrics derive from the rebuildable request-history index
+ * (`routing-history.sqlite`), never from repeated full JSONL scans. The
+ * analysis is read-only: no routing decision, profile, or weight changes here
+ * (ADR-10 - no automatic self-tuning).
+ *
+ * Bounds: at most ANALYTICS_MAX_ROWS matching rows are analyzed per call; a
+ * larger population sets `historyTruncated: true` so readers never mistake a
+ * sample for the full history.
+ */
+
+import type { PersistedUsageEntry, PersistedUsageAttempt } from "../usage/log";
+import { estimateRequestCost, serviceTierContext } from "../usage/cost";
+import { openRequestHistoryIndex, requestHistoryDb } from "./history/indexer";
+
+export const ANALYTICS_MAX_ROWS = 50_000;
+/** Default row cap for the management API (full cap remains available via `limit`). */
+export const ANALYTICS_API_DEFAULT_ROWS = 5_000;
+
+export interface RoutingAnalyticsFilters {
+  provider?: string;
+  model?: string;
+  profileId?: string;
+  surface?: string;
+  from?: number;
+  to?: number;
+}
+
+export type AnalyticsConfidence = "high" | "medium" | "low";
+
+export interface AnalyticsBreakdownRow {
+  provider: string;
+  model: string;
+  accountRef?: string;
+  profileId?: string;
+  requests: number;
+  successes: number;
+  failures: number;
+  cancelled: number;
+  successRate: number | null;
+  p50DurationMs?: number;
+  estimatedCostUsdPerSuccessfulRequest?: number | null;
+}
+
+export interface AnalyticsProfileRow {
+  profileId: string;
+  profileRevision?: string;
+  requests: number;
+  successes: number;
+  failures: number;
+  fallbacks: number;
+  successRate: number | null;
+}
+
+export interface RoutingAnalyticsResult {
+  generatedAt: number;
+  totalRequests: number;
+  scannedRows: number;
+  historyTruncated: boolean;
+  confidence: AnalyticsConfidence | null;
+  successRate: number | null;
+  failureRate: number | null;
+  cancelledRate: number | null;
+  fallbackRate: number | null;
+  totalAttempts: number;
+  averageAttemptsPerRequest: number | null;
+  incompleteStreamRate: number | null;
+  cooldownTriggeringFailures: number;
+  durationMs: {
+    p50?: number;
+    p95?: number;
+    p99?: number;
+    sampleCount: number;
+  };
+  firstOutputMs: {
+    p50?: number;
+    p95?: number;
+    p99?: number;
+    sampleCount: number;
+    /** Share of scanned requests with a TTFT measurement (0..1). */
+    coverage: number | null;
+  };
+  estimatedCostUsdPerSuccessfulRequest: number | null;
+  estimatedCostUsdTotalSuccessful: number | null;
+  usageCoverage: number | null;
+  priceCoverage: number | null;
+  breakdown: AnalyticsBreakdownRow[];
+  profileBreakdown: AnalyticsProfileRow[];
+}
+
+interface ScannedRow {
+  provider: string;
+  model: string;
+  apiKeyId?: string | null;
+  profileId?: string | null;
+  profileRevision?: string | null;
+  status: number;
+  durationMs: number;
+  firstOutputMs?: number | null;
+  closeReason?: string | null;
+  terminalStatus?: string | null;
+  usageStatus: string;
+  usageJson?: string | null;
+  attemptCount: number;
+  fallback: number;
+  rowJson: string;
+}
+
+interface Bucket extends AnalyticsBreakdownRow {
+  durations: number[];
+  costUsdSum: number;
+  costRows: number;
+}
+
+const COOLDOWN_RECOVERY_KINDS = new Set([
+  "rate-limit-429",
+  "key-429",
+  "oauth-401",
+  "anthropic-oauth-429",
+]);
+
+function percentile(sorted: number[], p: number): number | undefined {
+  if (sorted.length === 0) return undefined;
+  const index = Math.max(0, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[Math.min(index, sorted.length - 1)];
+}
+
+function classifyRow(row: ScannedRow): "success" | "failure" | "cancelled" {
+  if (row.closeReason === "client_cancel" || row.status === 499) return "cancelled";
+  if (row.terminalStatus === "incomplete") return "failure";
+  if (row.terminalStatus && row.terminalStatus !== "completed") return "failure";
+  if (row.status >= 400) return "failure";
+  return "success";
+}
+
+function parseEntry(rowJson: string): PersistedUsageEntry | null {
+  try {
+    const parsed = JSON.parse(rowJson) as PersistedUsageEntry;
+    return parsed && typeof parsed === "object" && typeof parsed.requestId === "string" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function attemptsOf(entry: PersistedUsageEntry | null): PersistedUsageAttempt[] | undefined {
+  return entry?.attempts;
+}
+
+function cooldownTriggering(entry: PersistedUsageEntry | null, status: number): boolean {
+  if (status === 429) return true;
+  const attempts = attemptsOf(entry) ?? [];
+  return attempts.some(attempt => attempt.recoveryKinds.some(kind => COOLDOWN_RECOVERY_KINDS.has(kind)));
+}
+
+function successCostUsd(
+  row: Pick<ScannedRow, "provider" | "model">,
+  entry: PersistedUsageEntry,
+): number | null {
+  if (!entry.usage) return null;
+  const estimate = estimateRequestCost({
+    provider: row.provider,
+    model: row.model,
+    usage: entry.usage,
+    usageStatus: entry.usageStatus,
+    serviceTier: serviceTierContext(entry),
+  });
+  return estimate ? estimate.cost.total : null;
+}
+
+export async function computeRoutingAnalytics(
+  filters: RoutingAnalyticsFilters,
+  options: { maxRows?: number } = {},
+): Promise<RoutingAnalyticsResult> {
+  await openRequestHistoryIndex();
+  const handle = requestHistoryDb();
+  const maxRows = Math.min(
+    Math.max(1, Math.trunc(options.maxRows ?? ANALYTICS_MAX_ROWS)),
+    ANALYTICS_MAX_ROWS,
+  );
+
+  const where: string[] = [];
+  const values: Array<string | number> = [];
+  const add = (clause: string, value: string | number) => {
+    where.push(clause);
+    values.push(value);
+  };
+  if (filters.provider !== undefined) add("provider = ?", filters.provider);
+  if (filters.model !== undefined) add("model = ?", filters.model);
+  if (filters.profileId !== undefined) add("profile_id = ?", filters.profileId);
+  if (filters.surface !== undefined) add("surface = ?", filters.surface);
+  if (filters.from !== undefined) add("timestamp >= ?", filters.from);
+  if (filters.to !== undefined) add("timestamp <= ?", filters.to);
+  const whereSql = where.length > 0 ? ` WHERE ${where.join(" AND ")}` : "";
+
+  const rows = handle.query(
+    `SELECT provider, model, api_key_id AS apiKeyId, profile_id AS profileId,
+            profile_revision AS profileRevision, status,
+            duration_ms AS durationMs, first_output_ms AS firstOutputMs,
+            close_reason AS closeReason, terminal_status AS terminalStatus,
+            usage_status AS usageStatus, usage_json AS usageJson,
+            attempt_count AS attemptCount, fallback, row_json AS rowJson
+     FROM requests${whereSql} ORDER BY timestamp DESC LIMIT ?`,
+  ).all(...values, maxRows + 1) as ScannedRow[];
+
+  const scanned = rows.slice(0, maxRows);
+  const historyTruncated = rows.length > maxRows;
+
+  let successes = 0;
+  let failures = 0;
+  let cancelled = 0;
+  let fallbacks = 0;
+  let totalAttempts = 0;
+  let incompleteStreams = 0;
+  let cooldownFailures = 0;
+  let usageReported = 0;
+  const durations: number[] = [];
+  const firstOutputs: number[] = [];
+  let costTotalUsd = 0;
+  let costCount = 0;
+
+  const byKey = new Map<string, Bucket>();
+  const byProfile = new Map<string, AnalyticsProfileRow>();
+
+  for (const row of scanned) {
+    const kind = classifyRow(row);
+    if (kind === "success") successes += 1;
+    else if (kind === "failure") failures += 1;
+    else cancelled += 1;
+    if (row.fallback === 1) fallbacks += 1;
+    totalAttempts += row.attemptCount;
+    if (row.terminalStatus === "incomplete") incompleteStreams += 1;
+    durations.push(row.durationMs);
+    if (row.firstOutputMs !== null && row.firstOutputMs !== undefined && row.firstOutputMs >= 0) {
+      firstOutputs.push(row.firstOutputMs);
+    }
+    if (row.usageStatus !== "unreported") usageReported += 1;
+
+    let rowCostUsd: number | null = null;
+    if (kind === "success") {
+      const entry = parseEntry(row.rowJson);
+      if (entry) {
+        rowCostUsd = successCostUsd(row, entry);
+        if (rowCostUsd !== null) {
+          costTotalUsd += rowCostUsd;
+          costCount += 1;
+        }
+      }
+    }
+
+    if (kind === "failure") {
+      const failureEntry = parseEntry(row.rowJson);
+      if (cooldownTriggering(failureEntry, row.status)) cooldownFailures += 1;
+    }
+
+    const key = `${row.provider}\0${row.model}\0${row.apiKeyId ?? ""}\0${row.profileId ?? ""}`;
+    let bucket: Bucket | undefined = byKey.get(key);
+    if (!bucket) {
+      bucket = {
+        provider: row.provider,
+        model: row.model,
+        ...(row.apiKeyId ? { accountRef: row.apiKeyId } : {}),
+        ...(row.profileId ? { profileId: row.profileId } : {}),
+        requests: 0,
+        successes: 0,
+        failures: 0,
+        cancelled: 0,
+        successRate: null,
+        durations: [],
+        costUsdSum: 0,
+        costRows: 0,
+      };
+      byKey.set(key, bucket);
+    }
+    bucket.requests += 1;
+    if (kind === "success") bucket.successes += 1;
+    else if (kind === "failure") bucket.failures += 1;
+    else bucket.cancelled += 1;
+    bucket.durations.push(row.durationMs);
+    if (rowCostUsd !== null) {
+      bucket.costUsdSum += rowCostUsd;
+      bucket.costRows += 1;
+    }
+
+    if (row.profileId) {
+      let profile = byProfile.get(row.profileId);
+      if (!profile) {
+        profile = {
+          profileId: row.profileId,
+          ...(row.profileRevision ? { profileRevision: row.profileRevision } : {}),
+          requests: 0,
+          successes: 0,
+          failures: 0,
+          fallbacks: 0,
+          successRate: null,
+        };
+        byProfile.set(row.profileId, profile);
+      }
+      profile.requests += 1;
+      if (kind === "success") profile.successes += 1;
+      else if (kind === "failure") profile.failures += 1;
+      if (row.fallback === 1) profile.fallbacks += 1;
+    }
+  }
+
+  durations.sort((a, b) => a - b);
+  firstOutputs.sort((a, b) => a - b);
+  const total = scanned.length;
+  const rate = (count: number): number | null => (total > 0 ? count / total : null);
+
+  const breakdown: AnalyticsBreakdownRow[] = [...byKey.values()].map(bucket => {
+    const sorted = bucket.durations.sort((a, b) => a - b);
+    const p50DurationMs = percentile(sorted, 50);
+    return {
+      provider: bucket.provider,
+      model: bucket.model,
+      ...(bucket.accountRef ? { accountRef: bucket.accountRef } : {}),
+      ...(bucket.profileId ? { profileId: bucket.profileId } : {}),
+      requests: bucket.requests,
+      successes: bucket.successes,
+      failures: bucket.failures,
+      cancelled: bucket.cancelled,
+      successRate: bucket.requests > 0 ? bucket.successes / bucket.requests : null,
+      ...(p50DurationMs !== undefined ? { p50DurationMs } : {}),
+      ...(bucket.requests > 0
+        ? { estimatedCostUsdPerSuccessfulRequest: bucket.costRows > 0
+          ? bucket.costUsdSum / bucket.costRows
+          : null }
+        : {}),
+    };
+  }).sort((a, b) => b.requests - a.requests);
+
+  const profileBreakdown: AnalyticsProfileRow[] = [...byProfile.values()].map(profile => ({
+    ...profile,
+    successRate: profile.requests > 0 ? profile.successes / profile.requests : null,
+  })).sort((a, b) => b.requests - a.requests);
+
+  const confidence: AnalyticsConfidence | null = total === 0
+    ? null
+    : total >= 100 ? "high" : total >= 20 ? "medium" : "low";
+
+  return {
+    generatedAt: Date.now(),
+    totalRequests: total,
+    scannedRows: scanned.length,
+    historyTruncated,
+    confidence,
+    successRate: rate(successes),
+    failureRate: rate(failures),
+    cancelledRate: rate(cancelled),
+    fallbackRate: rate(fallbacks),
+    totalAttempts,
+    averageAttemptsPerRequest: total > 0 ? totalAttempts / total : null,
+    incompleteStreamRate: rate(incompleteStreams),
+    cooldownTriggeringFailures: cooldownFailures,
+    durationMs: {
+      ...(percentile(durations, 50) !== undefined ? { p50: percentile(durations, 50) } : {}),
+      ...(percentile(durations, 95) !== undefined ? { p95: percentile(durations, 95) } : {}),
+      ...(percentile(durations, 99) !== undefined ? { p99: percentile(durations, 99) } : {}),
+      sampleCount: durations.length,
+    },
+    firstOutputMs: {
+      ...(percentile(firstOutputs, 50) !== undefined ? { p50: percentile(firstOutputs, 50) } : {}),
+      ...(percentile(firstOutputs, 95) !== undefined ? { p95: percentile(firstOutputs, 95) } : {}),
+      ...(percentile(firstOutputs, 99) !== undefined ? { p99: percentile(firstOutputs, 99) } : {}),
+      sampleCount: firstOutputs.length,
+      coverage: total > 0 ? firstOutputs.length / total : null,
+    },
+    estimatedCostUsdPerSuccessfulRequest: costCount > 0 ? costTotalUsd / costCount : null,
+    estimatedCostUsdTotalSuccessful: costCount > 0 ? costTotalUsd : null,
+    usageCoverage: total > 0 ? usageReported / total : null,
+    priceCoverage: successes > 0 ? costCount / successes : null,
+    breakdown,
+    profileBreakdown,
+  };
+}

package/src/routing/capability.ts

@@ -0,0 +1,205 @@
+/**
+ * Candidate capability evidence for policy routing (RI-05).
+ *
+ * Evidence comes from canonical local sources only - provider config maps,
+ * the provider registry, the cached Codex catalog file, and the native-model
+ * metadata helpers. No live network fetch happens at routing time.
+ *
+ * "Unknown is not zero": any dimension without canonical evidence stays
+ * `undefined` (unknown) and the profile's `unknownEvidence` policy decides
+ * how that affects eligibility.
+ */
+
+import type { OcxConfig } from "../types";
+import { isCanonicalOpenAiForwardProvider } from "../providers/openai-tiers";
+import { PROVIDER_REGISTRY } from "../providers/registry";
+import {
+  nativeInputModalities,
+  nativeOpenAiContextWindow,
+  nativeParallelToolCalls,
+  nativeReasoningEfforts,
+} from "../codex/catalog/metadata";
+import { readCatalog, readCodexCatalogPath } from "../codex/catalog/parsing";
+import { statSync } from "node:fs";
+import type { RouteCapabilityEvidence } from "./trace";
+
+type CatalogModelRow = {
+  provider: string;
+  id: string;
+  contextWindow?: number;
+  inputModalities?: string[];
+  reasoningEfforts?: string[];
+  capabilities?: string[];
+};
+
+/**
+ * Catalog rows memoized by path + mtime: the cached Codex catalog is stable
+ * between refreshes, and re-reading/parsing the whole file per candidate on
+ * the request path would multiply a synchronous disk + JSON cost by the
+ * profile candidate count for every policy-routed request.
+ */
+let catalogCache: { path: string; mtimeMs: number; rows: CatalogModelRow[] } | null = null;
+
+function cachedCatalogModels(): CatalogModelRow[] {
+  try {
+    const path = readCodexCatalogPath();
+    const mtimeMs = statSync(path).mtimeMs;
+    if (catalogCache && catalogCache.path === path && catalogCache.mtimeMs === mtimeMs) {
+      return catalogCache.rows;
+    }
+    const catalog = readCatalog(path);
+    const models = catalog?.models;
+    if (!Array.isArray(models)) return [];
+    const rows = models
+      .filter((model): model is Record<string, unknown> & { id: string; provider: string } =>
+        typeof model === "object" && model !== null && typeof model.id === "string" && typeof model.provider === "string")
+      .map(model => ({
+        provider: model.provider,
+        id: model.id,
+        ...(typeof model.contextWindow === "number" ? { contextWindow: model.contextWindow } : {}),
+        ...(Array.isArray(model.inputModalities)
+          ? { inputModalities: model.inputModalities.filter((value): value is string => typeof value === "string") }
+          : {}),
+        ...(Array.isArray(model.reasoningEfforts)
+          ? { reasoningEfforts: model.reasoningEfforts.filter((value): value is string => typeof value === "string") }
+          : {}),
+        ...(Array.isArray(model.capabilities)
+          ? { capabilities: model.capabilities.filter((value): value is string => typeof value === "string") }
+          : {}),
+      }));
+    catalogCache = { path, mtimeMs, rows };
+    return rows;
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Classify a hostname for locality evidence. `URL.hostname` keeps IPv6
+ * literals bracketed (`[::1]`), so strip the brackets before matching.
+ * Anything not positively local or private stays unknown: "unknown is not
+ * zero", so an unrecognized host must never assert `remoteAllowed`.
+ */
+function classifyHostname(hostname: string): "local" | "private" | null {
+  const host = hostname.trim().toLowerCase().replace(/\.$/, "").replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host.endsWith(".localhost") || host === "0.0.0.0") return "local";
+  if (host === "::1" || /^127\./.test(host)) return "local";
+  if (/^10\./.test(host)
+    || /^192\.168\./.test(host)
+    || /^169\.254\./.test(host)
+    || /^172\.(1[6-9]|2\d|3[01])\./.test(host)
+    || /^f[cd][0-9a-f]{2}:/.test(host)
+    || /^fe80:/.test(host)
+    || /^::ffff:(?:10\.|127\.|192\.168\.|169\.254\.|172\.(?:1[6-9]|2\d|3[01])\.)/.test(host)) {
+    return "private";
+  }
+  return null;
+}
+
+/**
+ * Adapters whose upstream protocol supports function/tool calling. Mirrors
+ * the adapter ids the resolver accepts (including the `azure` alias for
+ * `azure-openai`); `kiro` and `mimo-free` send/delegate tool calls.
+ */
+const TOOL_CAPABLE_ADAPTERS = new Set([
+  "openai-chat",
+  "openai-responses",
+  "anthropic",
+  "cursor",
+  "google",
+  "azure-openai",
+  "azure",
+  "kiro",
+  "mimo-free",
+  "command-code",
+]);
+
+function localRemoteEvidence(baseUrl: string | undefined): Pick<RouteCapabilityEvidence, "localOnly" | "remoteAllowed"> {
+  if (typeof baseUrl !== "string" || baseUrl.length === 0) return {};
+  try {
+    const hostname = new URL(baseUrl).hostname;
+    if (!hostname) return {};
+    const kind = classifyHostname(hostname);
+    if (kind === null) return {};
+    // Both booleans are emitted once classified: definitive negative evidence,
+    // so a local host cannot satisfy `require.remoteAllowed` (or vice versa)
+    // under `unknownEvidence.capability: "allow"`/`"penalize"`.
+    return kind === "local" || kind === "private"
+      ? { localOnly: true, remoteAllowed: false }
+      : { remoteAllowed: true, localOnly: false };
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Assemble canonical capability evidence for one `provider/model` candidate.
+ * Sources (in priority order): provider config maps, provider registry hints,
+ * cached Codex catalog row, native-model metadata.
+ */
+export function candidateCapabilityEvidence(
+  config: OcxConfig,
+  providerName: string,
+  modelId: string,
+): RouteCapabilityEvidence {
+  const provider = config.providers[providerName];
+  const registryEntry = PROVIDER_REGISTRY.find(entry => entry.id === providerName);
+  const catalogRow = cachedCatalogModels().find(model => model.provider === providerName && model.id === modelId);
+  const isNative = providerName === "openai" && !modelId.includes("/");
+
+  const contextWindow = provider?.modelContextWindows?.[modelId]
+    ?? provider?.contextWindow
+    ?? registryEntry?.modelContextWindows?.[modelId]
+    ?? catalogRow?.contextWindow
+    ?? (isNative ? nativeOpenAiContextWindow(modelId) : undefined);
+
+  const modalities = provider?.modelInputModalities?.[modelId]
+    ?? registryEntry?.modelInputModalities?.[modelId]
+    ?? catalogRow?.inputModalities
+    ?? (isNative ? nativeInputModalities(modelId) : undefined);
+  const image = Array.isArray(modalities)
+    ? modalities.includes("image")
+    : undefined;
+
+  const capabilities = catalogRow?.capabilities ?? [];
+  // The catalog `capabilities` list is a positive per-model signal; a row
+  // without "tools" is treated as unknown, never as a negative. Without a
+  // catalog row the adapter protocol itself is the signal: tool-capable
+  // adapters run single tool calls even when the parallel-call opt-in is
+  // unset or false. `parallelToolCalls` stays a positive provider-level
+  // override.
+  const tools = capabilities.includes("tools")
+    || isNative
+    || (catalogRow === undefined && provider !== undefined && TOOL_CAPABLE_ADAPTERS.has(provider.adapter))
+    || provider?.parallelToolCalls === true
+    || undefined;
+
+  const reasoningEfforts = provider?.modelReasoningEfforts?.[modelId]
+    ?? registryEntry?.modelReasoningEfforts?.[modelId]
+    ?? catalogRow?.reasoningEfforts
+    ?? (isNative ? nativeReasoningEfforts(modelId) : undefined);
+
+  const tierSupport = provider?.supportsServiceTier
+    ?? registryEntry?.supportsServiceTier;
+  const serviceTier = tierSupport === true
+    ? "supported"
+    : tierSupport === false ? "unsupported" : "unknown";
+
+  const localRemote = localRemoteEvidence(provider?.baseUrl);
+  // Only emit a definitive encryptedCodexTasks value when the provider is
+  // present. An absent/unconfigured provider must stay unknown so
+  // require.encryptedCodexTasks does not fail closed on missing config.
+  const encryptedCodexTasks = provider === undefined
+    ? undefined
+    : isCanonicalOpenAiForwardProvider(provider);
+
+  return {
+    ...(typeof contextWindow === "number" ? { contextWindow } : {}),
+    ...(typeof image === "boolean" ? { image } : {}),
+    ...(typeof tools === "boolean" ? { tools } : {}),
+    ...(reasoningEfforts !== undefined && reasoningEfforts.length > 0 ? { reasoningEfforts } : {}),
+    ...(serviceTier !== "unknown" ? { serviceTier } : {}),
+    ...localRemote,
+    ...(typeof encryptedCodexTasks === "boolean" ? { encryptedCodexTasks } : {}),
+  };
+}

package/src/routing/cost.ts

@@ -0,0 +1,77 @@
+/**
+ * Cost-aware policy scoring and limits (RI-08).
+ *
+ * Reuses the canonical price/cost normalization (`src/usage/cost.ts`).
+ * Evidence distinguishes estimated vs authoritative usage and registry vs
+ * expected prices. Unknown prices stay unknown (never free); the profile's
+ * `unknownEvidence.cost` policy decides how unknown evidence is handled.
+ *
+ * No billing, invoicing, or hidden budgets - a hard per-request ceiling
+ * (`limits.maxEstimatedCostUsd`) is evaluated deterministically.
+ */
+
+import type { OcxUsage } from "../types";
+import type { UsageStatus } from "../usage/log";
+import { estimateRequestCost, type ServiceTierInput } from "../usage/cost";
+import type { RouteCostEvidence } from "./trace";
+
+/** Reference cost (USD) for the relative cost score when no limit is set. */
+export const COST_SCORE_REFERENCE_USD = 1.0;
+
+export interface CostEvidenceInput {
+  provider: string;
+  model: string;
+  usage?: OcxUsage;
+  usageStatus?: UsageStatus;
+  serviceTier?: ServiceTierInput;
+  limitUsd?: number;
+}
+
+/**
+ * Assemble cost evidence from the canonical price model. Returns unknown-ish
+ * evidence (`incomplete: true`, no estimate) when usage or a price is
+ * missing - never a fabricated zero.
+ */
+export function costEvidenceForCandidate(input: CostEvidenceInput): RouteCostEvidence {
+  const limitUsd = input.limitUsd;
+  if (!input.usage) {
+    return {
+      ...(limitUsd !== undefined ? { limitUsd } : {}),
+      incomplete: true,
+    };
+  }
+  const estimate = estimateRequestCost({
+    provider: input.provider,
+    model: input.model,
+    usage: input.usage,
+    usageStatus: input.usageStatus ?? "estimated",
+    ...(input.serviceTier ? { serviceTier: input.serviceTier } : {}),
+  });
+  if (!estimate) {
+    return {
+      ...(limitUsd !== undefined ? { limitUsd } : {}),
+      incomplete: true,
+      priceSource: "unmatched",
+    };
+  }
+  const priceSource = estimate.price?.source ?? "registry";
+  return {
+    estimatedUsd: estimate.cost.total,
+    priceSource,
+    incomplete: estimate.estimated || priceSource === "expected",
+    ...(limitUsd !== undefined ? { limitUsd } : {}),
+  };
+}
+
+/**
+ * Deterministic cost score in [0,1]: cheaper is better, relative to
+ * `COST_SCORE_REFERENCE_USD` (or the profile limit when set). Unknown
+ * estimates return null so the profile's unknownEvidence policy applies.
+ */
+export function costScore(evidence: RouteCostEvidence | undefined): number | null {
+  if (evidence?.estimatedUsd === undefined || !Number.isFinite(evidence.estimatedUsd)) return null;
+  const reference = typeof evidence.limitUsd === "number" && evidence.limitUsd > 0
+    ? evidence.limitUsd
+    : COST_SCORE_REFERENCE_USD;
+  return Math.max(0, Math.min(1, 1 - evidence.estimatedUsd / reference));
+}