@mupt-ai/dari-router 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,152 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export type Provider = string;
+export type ChatMessage = {
+    role: string;
+    content?: string | Array<Record<string, unknown>> | null;
+    tool_call_id?: string;
+    tool_calls?: Array<Record<string, unknown>>;
+    reasoning_content?: string;
+    reasoning?: string;
+    reasoning_text?: string;
+    reasoning_details?: Array<Record<string, unknown>>;
+};
+export declare const REASONING_EFFORTS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export type ReasoningEffort = (typeof REASONING_EFFORTS)[number];
+export declare function isReasoningEffort(value: unknown): value is ReasoningEffort;
+export type ResponseFormat = {
+    type: "text";
+} | {
+    type: "json_object";
+} | {
+    type: "json_schema";
+    json_schema: {
+        name: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+        description?: string;
+    };
+};
+export type ChatCompletionRequest = {
+    model?: string;
+    messages?: ChatMessage[];
+    stream?: boolean;
+    source_protocol?: "anthropic_messages" | "openai_chat" | "openai_responses";
+    prompt_cache_key?: string;
+    temperature?: number;
+    top_p?: number;
+    max_tokens?: number;
+    max_completion_tokens?: number;
+    stop?: string | string[];
+    tools?: Array<Record<string, unknown>>;
+    tool_choice?: string | Record<string, unknown>;
+    parallel_tool_calls?: boolean;
+    response_format?: ResponseFormat;
+    reasoning_effort?: ReasoningEffort;
+    metadata?: Record<string, unknown>;
+    user?: string;
+};
+export type RoutingCandidate = {
+    model: string;
+    reasoningEffort: ReasoningEffort;
+};
+export declare function routingCandidateKey(candidate: RoutingCandidate): string;
+export declare function sameRoutingCandidate(left: RoutingCandidate, right: RoutingCandidate): boolean;
+export type RoutingDecision = {
+    selectedModel: string;
+    reasoningEffort: ReasoningEffort;
+    reason: string;
+    leaseTurnsRemaining?: number;
+};
+export type RouterEvalScore = {
+    model_id: string;
+    score: number;
+    notes?: string | null;
+    thinking_level?: ReasoningEffort | null;
+};
+export type RouterEval = {
+    id: string;
+    name: string;
+    description?: string | null;
+    min_score: number;
+    max_score: number;
+    scores: RouterEvalScore[];
+};
+export type RouterPrefixHit = {
+    hash: string;
+    loose_hash?: string | null;
+    conversation_id: string;
+    model: string;
+    next_model?: string | null;
+    next_reasoning_effort?: ReasoningEffort | null;
+    message_depth: number;
+    block_depth: number;
+    provider_block_depth?: number | null;
+    prompt_anchor_depth?: number | null;
+    prompt_tokens: number;
+    benchmark_replay_depth?: number | null;
+    input_tokens: number;
+    cache_read_tokens: number;
+    cache_write_tokens: number;
+    tool_choice_fp: string;
+    response_format_fp: string;
+    reasoning_bucket?: string | null;
+    lease_turns_remaining?: number | null;
+    pending_lease_model?: string | null;
+    pending_lease_reasoning_effort?: ReasoningEffort | null;
+    pending_lease_turns?: number | null;
+    pending_lease_reason?: string | null;
+    pending_lease_output_text?: string | null;
+    reason: string | null;
+    updated_at: string;
+};
+export type RoutingStrategy = "slm" | "custom";
+export type CustomRouterRule = {
+    when: string;
+    use: string;
+    thinking_level?: ReasoningEffort | null;
+};
+export type CustomRouterConfig = {
+    rules: CustomRouterRule[];
+    default?: string | null;
+    default_thinking_level?: ReasoningEffort | null;
+};
+export type RouterModelPrice = {
+    input: number;
+    output: number;
+    cached_input?: number | null;
+    cache_write?: number | null;
+};
+export type PrefixHit = {
+    entry: RouterPrefixHit;
+    depth: number;
+};
+export type ChainHits = {
+    deepest?: PrefixHit;
+    perModel: Map<string, PrefixHit>;
+    perModelBuckets: Map<string, Map<string | null, PrefixHit>>;
+};
+export type TurnCostProjection = {
+    projected_turns: number;
+    total_cost_usd: number;
+};
+export type FixedTurnCostEstimate = {
+    output_tokens_per_turn: number;
+    assumed_reasoning_effort: ReasoningEffort;
+    projections: TurnCostProjection[];
+};
+export type CandidateCostEstimate = {
+    model: string;
+    reasoning_effort: ReasoningEffort;
+    warm_tokens: number;
+    est_prompt_tokens: number;
+    est_input_cost_usd: number | null;
+    output_cost_per_mtok: number | null;
+    pricing_known: boolean;
+    fixed_turn_cost_estimate: FixedTurnCostEstimate | null;
+};
+export type PreviousDecision = {
+    model: string;
+    reasoningEffort: ReasoningEffort;
+    reason: string;
+};
+export type HardCapability = "image_input" | "structured_output" | "openai_hosted_web_search";

package/dist/types.js

@@ -0,0 +1,14 @@
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export const REASONING_EFFORTS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+export function isReasoningEffort(value) {
+    return typeof value === "string" && REASONING_EFFORTS.some((effort) => effort === value);
+}
+export function routingCandidateKey(candidate) {
+    return `${candidate.model}\u0000${candidate.reasoningEffort}`;
+}
+export function sameRoutingCandidate(left, right) {
+    return left.model === right.model && left.reasoningEffort === right.reasoningEffort;
+}
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,QAAQ,CAAC,KAAc;IACrC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAiBD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAU,CAAC;AAGtG,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,iBAAiB,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC;AAC3F,CAAC;AAwCD,MAAM,UAAU,mBAAmB,CAAC,SAA2B;IAC7D,OAAO,GAAG,SAAS,CAAC,KAAK,SAAS,SAAS,CAAC,eAAe,EAAE,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,oBAAoB,CAClC,IAAsB,EACtB,KAAuB;IAEvB,OAAO,IAAI,CAAC,KAAK,KAAK,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,eAAe,KAAK,KAAK,CAAC,eAAe,CAAC;AACtF,CAAC"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@mupt-ai/dari-router",
+  "version": "0.1.0",
+  "description": "End-to-end TypeScript framework for routing across LLMs with built-in Pi AI execution and pluggable policies and executors.",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mupt-ai/dari-router-core.git"
+  },
+  "homepage": "https://docs.dari.dev/framework/overview",
+  "bugs": {
+    "url": "https://github.com/mupt-ai/dari-router-core/issues"
+  },
+  "keywords": [
+    "llm",
+    "router",
+    "llm-router",
+    "model-routing",
+    "openai",
+    "anthropic",
+    "chat-completions",
+    "dari"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun run typecheck && bun test && bun run build",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "example": "bun run examples/create_router.ts",
+    "example:pi": "bun run examples/pi_runtime.ts",
+    "example:dari-policy": "bun run examples/dari_policy.ts",
+    "example:decision-pipeline": "bun run examples/basic_route.ts",
+    "example:lease-stores": "bun run examples/lease_stores.ts"
+  },
+  "dependencies": {
+    "@mupt-ai/pi-ai": "0.80.6-mupt.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.4",
+    "@types/node": "^24.10.2",
+    "typescript": "^5.6.3"
+  }
+}

package/src/anonymous_actions.ts

@@ -0,0 +1,434 @@
+// Anonymous candidate-action selector protocol. Candidates are shuffled into
+// anonymous action slots ("A", "B", ..., "AA", ...) and every model-identifying
+// field in the selector input is replaced by its slot, so a trained policy
+// cannot memorize model names or list positions. This is the canonical
+// open-weight selector protocol used by Dari's SLM routing strategy; the
+// named-candidate protocol in selector_input.ts/prompts.ts remains available
+// for custom routers that use a general-purpose LLM selector.
+
+import { ANONYMOUS_ACTION_SYSTEM_PROMPT } from "./prompts.js";
+import {
+  jsonRecord,
+  jsonValue,
+  requiredString,
+  type JsonObject,
+  type JsonValue,
+} from "./json.js";
+import type { TurnCostProjection } from "./types.js";
+
+// Deterministic random source in [0, 1). Callers own seeding so experiment
+// harnesses can reproduce recorded permutations with their own PRNG.
+export type Rng = () => number;
+
+export type AnonymousActionCandidate = {
+  model: string;
+  reasoningEffort: string;
+};
+
+export type AnonymousActionSlot = {
+  action: string;
+  candidate: AnonymousActionCandidate;
+};
+
+export type AnonymousSelectorMessage = {
+  role: "system" | "user";
+  content: string;
+};
+
+export type AnonymousPolicyPrompt = {
+  messages: [system: AnonymousSelectorMessage, user: AnonymousSelectorMessage];
+  actions: string[];
+};
+
+export type AnonymousActionSelection = {
+  action: string;
+  candidate: AnonymousActionCandidate;
+  // Turns the selection commits to when the caller offered a lease menu;
+  // absent for single-turn selectors.
+  turns?: number;
+};
+
+// The de-identified selector input. Every field is JSON-serializable so it can
+// cross a process boundary, but it is a concrete type rather than a bag: it is
+// produced by anonymizeSelectorInput and consumed by the prompt formatter, so
+// nothing downstream needs to re-parse it.
+export type AnonymousEvalScore = {
+  action: string;
+  rank: number;
+  rank_total: number;
+  z_score: number;
+};
+
+export type AnonymousEvalCard = {
+  name: string;
+  description: string | null;
+  scores: AnonymousEvalScore[];
+};
+
+export type AnonymousActionCost = {
+  action: string;
+  projections: TurnCostProjection[];
+};
+
+export type AnonymousSelectorInput = {
+  candidate_actions: Array<{ action: string }>;
+  imported_evals: AnonymousEvalCard[];
+  previous_action: { action: string } | null;
+  cost_estimates: AnonymousActionCost[];
+  messages: JsonValue;
+};
+
+// Shuffles candidates into spreadsheet-style action slots A..Z, AA..AZ, ...
+// with the injected rng.
+export function assignAnonymousActions(
+  candidates: readonly AnonymousActionCandidate[],
+  rng: Rng,
+): AnonymousActionSlot[] {
+  if (candidates.length < 2) {
+    throw new Error(`Anonymous action routing requires at least two candidates, got ${candidates.length}`);
+  }
+  const keys = new Set<string>();
+  for (const candidate of candidates) {
+    const key = candidateKey(candidate.model, candidate.reasoningEffort);
+    if (keys.has(key)) throw new Error(`Duplicate anonymous action candidate ${key}`);
+    keys.add(key);
+  }
+  return shuffled(candidates, rng).map((candidate, index) => ({
+    action: actionForIndex(index),
+    candidate,
+  }));
+}
+
+function actionForIndex(index: number): string {
+  let remaining = index;
+  let action = "";
+  do {
+    action = String.fromCharCode("A".charCodeAt(0) + (remaining % 26)) + action;
+    remaining = Math.floor(remaining / 26) - 1;
+  } while (remaining >= 0);
+  return action;
+}
+
+// Rewrites a named-candidate selector input (see selector_input.ts) into its
+// anonymous-action form. The input must reference exactly the candidates in
+// `slots`; any mismatch is an error rather than a silent partial rewrite.
+export function anonymizeSelectorInput(
+  selectorInput: JsonObject,
+  slots: readonly AnonymousActionSlot[],
+): AnonymousSelectorInput {
+  const input = jsonRecord(structuredClone(selectorInput), "selector input");
+  const byCandidate = new Map(
+    slots.map((slot) => [candidateKey(slot.candidate.model, slot.candidate.reasoningEffort), slot.action]),
+  );
+  assertSelectorCandidates(input["candidate_pairs"], byCandidate);
+
+  return {
+    candidate_actions: slots.map((slot) => ({ action: slot.action })),
+    imported_evals: anonymizeEvals(input["imported_evals"], byCandidate),
+    previous_action: anonymizePreviousDecision(input["previous_decision"], byCandidate),
+    cost_estimates: anonymizeCosts(input["cost_estimates"], byCandidate),
+    messages: jsonValue(input["messages"], "selector input messages"),
+  };
+}
+
+export function buildAnonymousPolicyPrompt(
+  anonymousSelectorInput: AnonymousSelectorInput,
+  slots: readonly AnonymousActionSlot[],
+): AnonymousPolicyPrompt {
+  return {
+    messages: [
+      { role: "system", content: ANONYMOUS_ACTION_SYSTEM_PROMPT },
+      { role: "user", content: formatAnonymousPolicyInput(anonymousSelectorInput) },
+    ],
+    actions: slots.map((slot) => slot.action),
+  };
+}
+
+// Renders the anonymous selector input as sectioned text rather than raw JSON.
+// One block per action carries that action's benchmark standing and its
+// projected cost, so the policy compares like against like instead of
+// re-deriving comparisons from scores on incomparable scales and six cost
+// fields. How to read those blocks lives in ANONYMOUS_ACTION_SYSTEM_PROMPT,
+// keeping this message pure data. The conversation goes last: it is the only
+// section that grows turn over turn, so keeping it at the end preserves the
+// shared prefix.
+export function formatAnonymousPolicyInput(input: AnonymousSelectorInput): string {
+  const sections = [
+    ...(input.imported_evals.length > 0
+      ? [section("benchmarks", input.imported_evals.map(glossaryLine).join("\n"))]
+      : []),
+    section(
+      "candidates",
+      input.candidate_actions
+        .map((candidate) => candidateBlock(candidate.action, input))
+        .join("\n\n"),
+    ),
+    ...(input.previous_action === null
+      ? []
+      : [section("previous_action", input.previous_action.action)]),
+    section("conversation", JSON.stringify(input.messages)),
+  ];
+  return sections.join("\n\n");
+}
+
+function section(name: string, body: string): string {
+  return `<${name}>\n${body}\n</${name}>`;
+}
+
+function candidateBlock(action: string, input: AnonymousSelectorInput): string {
+  const cost = input.cost_estimates.find((entry) => entry.action === action);
+  const lines = [`## Action ${action}`];
+  if (cost !== undefined) lines.push(costLine(cost));
+  for (const card of input.imported_evals) {
+    const score = card.scores.find((entry) => entry.action === action);
+    if (score !== undefined) {
+      lines.push(
+        `- ${card.name}: Rank ${score.rank}/${score.rank_total}, Z ${signed(score.z_score)}`,
+      );
+    }
+  }
+  return lines.join("\n");
+}
+
+// One line, one unit, the same horizons for every action.
+function costLine(cost: AnonymousActionCost): string {
+  const horizons = cost.projections.map(
+    (projection) =>
+      `${projection.projected_turns} turn${projection.projected_turns === 1 ? "" : "s"} ${usd(projection.total_cost_usd)}`,
+  );
+  return `- Cost: ${horizons.join(", ")}`;
+}
+
+function signed(value: number): string {
+  return value >= 0 ? `+${value.toFixed(2)}` : value.toFixed(2);
+}
+
+function usd(value: number): string {
+  if (value >= 1) return `$${value.toFixed(2)}`;
+  const trimmed = value.toPrecision(3).replace(/0+$/, "").replace(/\.$/, "");
+  return `$${trimmed}`;
+}
+
+function glossaryLine(card: AnonymousEvalCard): string {
+  return card.description === null ? `- ${card.name}` : `- ${card.name}: ${card.description}`;
+}
+
+function previousAction(value: unknown): string | null {
+  if (value === null || value === undefined) return null;
+  return requiredString(
+    jsonRecord(value, "anonymous previous_action")["action"],
+    "anonymous previous_action.action",
+  );
+}
+
+function isRecordValue(value: unknown): value is Record<string, JsonValue> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// Parses a policy completion against the permutation's slots. Without a lease
+// menu the exact shape is {"action":"B"}; with one it is
+// {"action":"B","turns":10} and turns must be on the menu.
+export function parseAnonymousActionSelection(
+  completion: string,
+  slots: readonly AnonymousActionSlot[],
+  leaseTurns?: readonly number[],
+): AnonymousActionSelection {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(completion);
+  } catch {
+    throw new Error("Anonymous action completion is not valid JSON");
+  }
+  const record = jsonRecord(parsed, "anonymous action completion");
+  const keys = Object.keys(record);
+  // An empty menu means the caller routes one turn at a time, same as no menu.
+  const offeredLeaseTurns =
+    leaseTurns !== undefined && leaseTurns.length > 0 ? leaseTurns : undefined;
+  const expected = offeredLeaseTurns === undefined ? ["action"] : ["action", "turns"];
+  if (keys.length !== expected.length || expected.some((key, i) => keys[i] !== key)) {
+    throw new Error(
+      `Anonymous action completion must contain exactly {${expected
+        .map((key) => `"${key}":...`)
+        .join(",")}}`,
+    );
+  }
+  const action = record["action"];
+  if (typeof action !== "string") {
+    throw new Error("Anonymous action completion action must be a string");
+  }
+  const slot = slots.find((candidate) => candidate.action === action);
+  if (slot === undefined) {
+    throw new Error(`Anonymous action completion selected unavailable action ${action}`);
+  }
+  if (offeredLeaseTurns === undefined) return { action, candidate: slot.candidate };
+  const turns = record["turns"];
+  if (typeof turns !== "number" || !offeredLeaseTurns.includes(turns)) {
+    throw new Error(
+      `Anonymous action completion turns must be one of ${offeredLeaseTurns.join(", ")}`,
+    );
+  }
+  return { action, candidate: slot.candidate, turns };
+}
+
+// Fisher-Yates copy, drawing from the end, matching d3-array's shuffler so an
+// injected rng reproduces permutations recorded by harnesses that used d3.
+function shuffled<T>(items: readonly T[], rng: Rng): T[] {
+  const array = [...items];
+  let m = array.length;
+  while (m) {
+    const i = (rng() * m--) | 0;
+    const t = array[m]!;
+    array[m] = array[i]!;
+    array[i] = t;
+  }
+  return array;
+}
+
+function assertSelectorCandidates(
+  value: unknown,
+  byCandidate: ReadonlyMap<string, string>,
+): void {
+  if (!Array.isArray(value)) {
+    throw new Error("Selector input candidate_pairs must be an array");
+  }
+  const selectorKeys = new Set(
+    value.map((candidate, index) => {
+      const record = jsonRecord(candidate, `selector candidate[${index}]`);
+      return candidateKey(
+        requiredString(record["model"], `selector candidate[${index}].model`),
+        requiredString(
+          record["thinking_level"],
+          `selector candidate[${index}].thinking_level`,
+        ),
+      );
+    }),
+  );
+  if (selectorKeys.size !== byCandidate.size || [...byCandidate.keys()].some((key) => !selectorKeys.has(key))) {
+    throw new Error("Routing and selector candidates do not match");
+  }
+}
+
+function anonymizeEvals(
+  value: unknown,
+  byCandidate: ReadonlyMap<string, string>,
+): AnonymousEvalCard[] {
+  if (!Array.isArray(value)) {
+    throw new Error("Selector input imported_evals must be an array");
+  }
+  return value.map((entry, evalIndex) => {
+    const card = jsonRecord(entry, `selector eval[${evalIndex}]`);
+    const scores = card["scores"];
+    if (!Array.isArray(scores)) {
+      throw new Error(`selector eval[${evalIndex}].scores must be an array`);
+    }
+    return {
+      name: requiredString(card["name"], `selector eval[${evalIndex}].name`),
+      description: typeof card["description"] === "string" ? card["description"] : null,
+      // Explicit allowlist: notes and any future field can name the model.
+      scores: scores.map((entryScore, scoreIndex) => {
+        const label = `selector eval[${evalIndex}].scores[${scoreIndex}]`;
+        const score = jsonRecord(entryScore, label);
+        return {
+          action: actionForCandidate(
+            byCandidate,
+            requiredString(score["model_id"], `${label}.model_id`),
+            requiredString(score["thinking_level"], `${label}.thinking_level`),
+          ),
+          rank: requiredNumber(score["rank"], `${label}.rank`),
+          rank_total: requiredNumber(score["rank_total"], `${label}.rank_total`),
+          z_score: requiredNumber(score["z_score"], `${label}.z_score`),
+        };
+      }),
+    };
+  });
+}
+
+function anonymizePreviousDecision(
+  value: unknown,
+  byCandidate: ReadonlyMap<string, string>,
+): { action: string } | null {
+  if (value === null || value === undefined) return null;
+  const previous = jsonRecord(value, "selector previous_decision");
+  const model = requiredString(previous["model"], "selector previous_decision.model");
+  const thinkingLevel = requiredString(
+    previous["thinking_level"],
+    "selector previous_decision.thinking_level",
+  );
+  return {
+    action: actionForCandidate(byCandidate, model, thinkingLevel),
+  };
+}
+
+function anonymizeCosts(
+  value: unknown,
+  byCandidate: ReadonlyMap<string, string>,
+): AnonymousActionCost[] {
+  if (value === null || value === undefined) return [];
+  if (!Array.isArray(value)) {
+    throw new Error("Selector input cost_estimates must be an array or null");
+  }
+  // Only the loop projections survive. The per-request fields the prompt does
+  // not show would be dead weight, and assumed_reasoning_effort names the
+  // candidate's thinking level, which the protocol exists to hide.
+  return value.flatMap((entry, index) => {
+    const label = `selector cost_estimates[${index}]`;
+    const cost = jsonRecord(entry, label);
+    const action = actionForCandidate(
+      byCandidate,
+      requiredString(cost["model"], `${label}.model`),
+      requiredString(cost["reasoning_effort"], `${label}.reasoning_effort`),
+    );
+    const fixedTurn = cost["fixed_turn_cost_estimate"];
+    if (fixedTurn === null || fixedTurn === undefined) return [];
+    if (!isRecordValue(fixedTurn) || !Array.isArray(fixedTurn["projections"])) {
+      // A present estimate without projections is the pre-projection schema.
+      // Reject it loudly: silently dropping it would show "Cost: unavailable"
+      // for a candidate whose cost the caller thinks it supplied.
+      throw new Error(
+        `${label}.fixed_turn_cost_estimate must carry a projections array`,
+      );
+    }
+    return [
+      {
+        action,
+        projections: fixedTurn["projections"].map((projection, projectionIndex) => {
+          const projectionLabel = `${label}.fixed_turn_cost_estimate.projections[${projectionIndex}]`;
+          const record = jsonRecord(projection, projectionLabel);
+          return {
+            projected_turns: requiredNumber(
+              record["projected_turns"],
+              `${projectionLabel}.projected_turns`,
+            ),
+            total_cost_usd: requiredNumber(
+              record["total_cost_usd"],
+              `${projectionLabel}.total_cost_usd`,
+            ),
+          };
+        }),
+      },
+    ];
+  });
+}
+
+function requiredNumber(value: JsonValue | undefined, label: string): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`${label} must be a finite number`);
+  }
+  return value;
+}
+
+function actionForCandidate(
+  byCandidate: ReadonlyMap<string, string>,
+  model: string,
+  thinkingLevel: string,
+): string {
+  const action = byCandidate.get(candidateKey(model, thinkingLevel));
+  if (action === undefined) {
+    throw new Error(`Selector field references unavailable candidate ${model}/${thinkingLevel}`);
+  }
+  return action;
+}
+
+function candidateKey(model: string, thinkingLevel: string): string {
+  return `${model}\u0000${thinkingLevel}`;
+}