@mupt-ai/dari-router 0.1.0

package/src/protocol_validation.ts

@@ -0,0 +1,202 @@
+import { RouterFrameworkError } from "./framework_error.js";
+import type {
+  RouterContent,
+  RouterSelection,
+  RouterTool,
+  RouterToolChoice,
+} from "./framework_types.js";
+import { isRecord } from "./types.js";
+
+export function invalidProtocolRequest(
+  message: string,
+  param?: string,
+): RouterFrameworkError {
+  return new RouterFrameworkError(
+    "invalid_request",
+    message,
+    "invalid_request",
+    param,
+  );
+}
+
+export function rejectUnknownFields(
+  value: Record<string, unknown>,
+  allowed: readonly string[],
+  prefix?: string,
+): void {
+  const field = Object.keys(value).find((name) => !allowed.includes(name));
+  if (field === undefined) return;
+  const param = prefix ? `${prefix}.${field}` : field;
+  throw new RouterFrameworkError(
+    "invalid_request",
+    `${param} is not supported by the portable router contract.`,
+    "unsupported_field",
+    param,
+  );
+}
+
+export function validateToolChoice(
+  choice: RouterToolChoice | undefined,
+  tools: readonly RouterTool[],
+): void {
+  if (choice === undefined || choice === "none" || choice === "auto") return;
+  if (tools.length === 0) {
+    throw invalidProtocolRequest("tool_choice requires at least one tool.", "tool_choice");
+  }
+  if (typeof choice !== "string" && !tools.some((tool) => tool.name === choice.name)) {
+    throw invalidProtocolRequest(
+      `tool_choice references unknown tool '${choice.name}'.`,
+      "tool_choice",
+    );
+  }
+}
+
+// `dari_routing` response metadata, matching the managed Dari platform's wire shape.
+export function dariRoutingPayload<Metadata>(
+  requestedModel: string,
+  selection: RouterSelection<Metadata>,
+): Record<string, unknown> {
+  return {
+    requested_model: requestedModel,
+    selected_model: selection.decision.selectedModel,
+    reasoning_effort: selection.decision.reasoningEffort,
+    reason: selection.decision.reason,
+  };
+}
+
+export function requiredString(value: unknown, param: string): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw invalidProtocolRequest(`${param} must be a non-empty string.`, param);
+  }
+  return value;
+}
+
+export function optionalString(value: unknown, param: string): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "string") {
+    throw invalidProtocolRequest(`${param} must be a string.`, param);
+  }
+  return value;
+}
+
+// Empty and whitespace-only cache keys mean "no cache key": preserving them
+// would make every such request share one lease bucket.
+export function optionalCacheKey(value: unknown, param: string): string | undefined {
+  const cacheKey = optionalString(value, param);
+  return cacheKey !== undefined && cacheKey.trim() ? cacheKey : undefined;
+}
+
+export function optionalNumberInRange(
+  value: unknown,
+  param: string,
+  minimum: number,
+  maximum: number,
+): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (
+    typeof value !== "number" ||
+    !Number.isFinite(value) ||
+    value < minimum ||
+    value > maximum
+  ) {
+    throw invalidProtocolRequest(
+      `${param} must be between ${minimum} and ${maximum}.`,
+      param,
+    );
+  }
+  return value;
+}
+
+export function positiveInteger(value: unknown, param: string): number {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw invalidProtocolRequest(`${param} must be a positive integer.`, param);
+  }
+  return value;
+}
+
+export function optionalPositiveInteger(
+  value: unknown,
+  param: string,
+): number | undefined {
+  if (value === undefined || value === null) return undefined;
+  return positiveInteger(value, param);
+}
+
+export function optionalBoolean(value: unknown, param: string): boolean | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "boolean") {
+    throw invalidProtocolRequest(`${param} must be a boolean.`, param);
+  }
+  return value;
+}
+
+export function optionalRecord(
+  value: unknown,
+  param: string,
+): Record<string, unknown> | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (!isRecord(value)) {
+    throw invalidProtocolRequest(`${param} must be an object.`, param);
+  }
+  return value;
+}
+
+export function stopSequenceValues(
+  value: unknown,
+  param: string,
+  allowBareString: boolean,
+): string | string[] | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === "string" && allowBareString) return value;
+  if (!Array.isArray(value) || value.some((entry) => typeof entry !== "string")) {
+    throw invalidProtocolRequest(
+      allowBareString
+        ? `${param} must be a string or array of strings.`
+        : `${param} must be an array of strings.`,
+      param,
+    );
+  }
+  return value;
+}
+
+export function isAllEmptyText(parts: readonly RouterContent[]): boolean {
+  return parts.every((part) => part.type === "text" && part.text.length === 0);
+}
+
+export function prefixedWireId(value: string, prefix: string): string {
+  return (value.startsWith(prefix) ? value : `${prefix}${value.replace(/[^A-Za-z0-9_-]/g, "_")}`)
+    .slice(0, 64);
+}
+
+export function portableTool(
+  fields: Record<string, unknown>,
+  options: {
+    names: Set<string>;
+    param: string;
+    schemaField: string;
+    schemaRequired: boolean;
+  },
+): RouterTool {
+  const name = requiredString(fields.name, `${options.param}.name`);
+  if (options.names.has(name)) {
+    throw invalidProtocolRequest(`Duplicate tool '${name}'.`, `${options.param}.name`);
+  }
+  options.names.add(name);
+  const schemaParam = `${options.param}.${options.schemaField}`;
+  const schema = fields[options.schemaField];
+  if (schema === undefined) {
+    if (options.schemaRequired) {
+      throw invalidProtocolRequest(`${schemaParam} must be an object.`, schemaParam);
+    }
+  } else if (!isRecord(schema)) {
+    throw invalidProtocolRequest(`${schemaParam} must be an object.`, schemaParam);
+  }
+  const description = optionalString(fields.description, `${options.param}.description`);
+  const strict = optionalBoolean(fields.strict, `${options.param}.strict`);
+  return {
+    name,
+    ...(description === undefined ? {} : { description }),
+    inputSchema: schema ?? { type: "object" },
+    ...(strict === undefined ? {} : { strict }),
+  };
+}

package/src/route.ts

@@ -0,0 +1,490 @@
+// Deterministic route preparation and finalization. These compositions call
+// the same phase functions Dari's hosted runtime executes; hosts with
+// interleaved effects (speculative execution, telemetry) may call the phases
+// directly instead.
+
+import { resolveCompatibleCandidates, type CandidateMetadataLookup } from "./compatibility.js";
+import { conversationBlockCount, conversationMessages } from "./fingerprint.js";
+import {
+  deepestIdentityHit,
+  deriveModelChainHits,
+  estimateCandidateCosts,
+  selectPromptAnchor,
+  type CandidatePromptEstimate,
+  type PricingLookup,
+} from "./cost.js";
+import { warmPrefixHits } from "./cache_behavior.js";
+import type { ReasoningCacheScopeLookup } from "./cache_scope.js";
+import { RouterCoreError } from "./errors.js";
+import {
+  activeLeaseFromHit,
+  compatiblePreviousDecision,
+  pendingLeaseFromHit,
+  previousDecisionFromHit,
+  type ActiveLease,
+  type PendingLease,
+} from "./previous_decision.js";
+import {
+  resolveStrategyCandidates,
+  type StrategyCandidateResolution,
+} from "./candidate_resolution.js";
+import { selectorSafeMessages } from "./selector_input.js";
+import { buildSizedSelectorRequest, type BuiltSelectorRequest } from "./selector_request.js";
+import { parseSelectorDecision, validateSelectorDecisions } from "./selector_parse.js";
+import { routingCandidateKey } from "./types.js";
+import type {
+  CandidateCostEstimate,
+  ChainHits,
+  ChatCompletionRequest,
+  ChatMessage,
+  CustomRouterConfig,
+  HardCapability,
+  PrefixHit,
+  PreviousDecision,
+  ReasoningEffort,
+  RouterEval,
+  RouterModelPrice,
+  RouterPrefixHit,
+  RoutingDecision,
+  RoutingStrategy,
+} from "./types.js";
+
+export type RoutePreparationWarning = {
+  phase: "cost_estimation";
+  error: unknown;
+};
+
+export type CandidatePromptAnchor = {
+  hash: string;
+  depth: number;
+};
+
+// Candidate preparation consumes explicit prompt-accounting facts instead of
+// inferring them from the selector's lossy message projection. Hosts may use
+// provider-visible IR semantics; prepareRoute supplies the legacy Chat
+// accounting behavior for public Chat-shaped callers.
+export type CandidatePromptAccounting = {
+  anchorSemantics: "matched_prefix" | "stored_input";
+  defaultBlockDepth: number;
+  providerBlockDepthFor: (model: string) => number;
+  // Return the full candidate-visible prompt when no anchor is supplied, or
+  // the suffix after a same-model anchor when one is supplied. Foreign-model
+  // token counts are never a valid baseline for this candidate's prompt.
+  promptEstimateFor: (
+    model: string,
+    anchor?: CandidatePromptAnchor,
+  ) => CandidatePromptEstimate;
+};
+
+export type LegacyTailCharsFor = (
+  model: string,
+  hash: string,
+) => number | undefined;
+
+type CandidatePreparationSharedInput = {
+  candidateModels: string[];
+  metadataLookup: CandidateMetadataLookup;
+  requiredCapabilities: readonly HardCapability[];
+  requestedReasoningEffort?: ReasoningEffort;
+  thinkingEnabled?: boolean;
+  toolChoice?: unknown;
+  modelThinkingLevels?: Readonly<Record<string, ReasoningEffort[]>>;
+  strategy: RoutingStrategy;
+  customConfig?: CustomRouterConfig | null;
+  modelPrices?: Record<string, RouterModelPrice>;
+  pricing: PricingLookup;
+  averageOutputTokensByModel?: Readonly<
+    Record<string, Partial<Record<ReasoningEffort, number>> | null>
+  >;
+  // Per-candidate-model prefix-hash chains for the incoming conversation, as
+  // computed by the host's fingerprinting (see fingerprint.ts / prefixChain).
+  chainsByModel: ReadonlyMap<string, string[]>;
+  // Prefix entries resolved by the host's prefix-hit storage: every entry
+  // inside the host's conversation lookback, warm or not. Which of them are
+  // still warm is decided here against nowMs, so a host never has to encode
+  // the provider cache-warmth window itself.
+  prefixHits?: RouterPrefixHit[];
+  // The instant this request arrived, in epoch milliseconds. This package
+  // reads no clock, and prefix warmth is measured from here.
+  nowMs: number;
+  // The request's loose chain (client-durable canonicalization), as computed
+  // by the host's fingerprinting. Identity-only; never used for warmth.
+  looseChain?: readonly string[];
+  toolChoiceFp: string;
+  responseFormatFp: string;
+  previousDecision?: PreviousDecision;
+  cacheScope?: ReasoningCacheScopeLookup;
+};
+
+// Rich hosts provide provider-visible accounting. Existing Chat-shaped hosts
+// provide messages and may override same-model suffix sizing. These modes are
+// mutually exclusive so preparation never silently ignores one representation.
+export type CandidatePreparationInput = CandidatePreparationSharedInput & (
+  | {
+      promptAccounting: CandidatePromptAccounting;
+      messages?: never;
+      tailCharsFor?: never;
+    }
+  | {
+      promptAccounting?: undefined;
+      messages: ChatMessage[];
+      tailCharsFor?: LegacyTailCharsFor;
+    }
+);
+
+export type CandidatePreparation = {
+  blockDepth: number;
+  hits: ChainHits;
+  // Conversation id recovered from the deepest identity hit (strict or
+  // loose tier, warm or merely recent); null for a fresh conversation
+  // (hosts typically substitute a new random id).
+  conversationId: string | null;
+  // Depth of that identity hit, for host reporting. Null when no hit.
+  identityMatchDepth: number | null;
+  // The same matched entry, exposed so hosts can carry synchronized
+  // conversation-level state forward without repeating identity matching.
+  identityHit?: PrefixHit;
+  previousDecision?: PreviousDecision;
+  // Unexpired lease recovered from the identity hit, when its target is still
+  // a compatible candidate. The host may serve it without consulting the
+  // selector.
+  activeLease?: ActiveLease;
+  // Next lease prefetched before expiry; adopted when activeLease is absent.
+  pendingLease?: PendingLease;
+  // Pre-strategy estimates for every compatible candidate, kept for
+  // reporting/audit even when pruning later narrows the candidate set.
+  costEstimates: CandidateCostEstimate[];
+  candidateResolution: StrategyCandidateResolution;
+  warnings: RoutePreparationWarning[];
+};
+
+// Deterministic candidate preparation: eligibility, cache-aware cost
+// estimates, previous-decision resolution, and strategy resolution/pruning.
+// Cost estimation is best-effort: a failure there surfaces as a warning and
+// leaves estimates empty rather than failing the route.
+export function prepareCandidates(input: CandidatePreparationInput): CandidatePreparation {
+  return prepareCandidatesWithAccounting(
+    input,
+    resolvePromptAccounting(input),
+  );
+}
+
+function prepareCandidatesWithAccounting(
+  input: CandidatePreparationSharedInput,
+  promptAccounting: CandidatePromptAccounting,
+): CandidatePreparation {
+  const compatible = resolveCompatibleCandidates({
+    requiredCapabilities: input.requiredCapabilities,
+    requestedReasoningEffort: input.requestedReasoningEffort,
+    thinkingEnabled: input.thinkingEnabled,
+    toolChoice: input.toolChoice,
+    candidateModels: input.candidateModels,
+    metadataLookup: input.metadataLookup,
+    modelThinkingLevels: input.modelThinkingLevels,
+  });
+  const blockDepth = promptAccounting.defaultBlockDepth;
+  const warnings: RoutePreparationWarning[] = [];
+
+  let hits: ChainHits = { perModel: new Map(), perModelBuckets: new Map() };
+  let costEstimates: CandidateCostEstimate[] = [];
+  let previousDecision = compatiblePreviousDecision(
+    input.previousDecision,
+    compatible.candidates,
+  );
+  let conversationId: string | null = null;
+  let identityMatchDepth: number | null = null;
+  let activeLease: ActiveLease | undefined;
+  let pendingLease: PendingLease | undefined;
+  let identityHit: PrefixHit | undefined;
+
+  try {
+    // Warmth: strict chains over hits still inside the warmth window — cost
+    // estimation and the freshness touch must reflect what the provider cache
+    // can actually re-read. Identity: either tier over every recent hit — a
+    // stale or loose-only match still names the same conversation.
+    hits = deriveModelChainHits(
+      input.chainsByModel,
+      warmPrefixHits(input.prefixHits, input.nowMs),
+    );
+    identityHit = deepestIdentityHit(
+      input.chainsByModel,
+      input.looseChain,
+      input.prefixHits,
+    );
+    if (identityHit) {
+      conversationId = identityHit.entry.conversation_id;
+      identityMatchDepth = identityHit.depth;
+      previousDecision ??= previousDecisionFromHit(
+        identityHit.entry,
+        compatible.candidates,
+      );
+      activeLease = activeLeaseFromHit(identityHit.entry, compatible.candidates);
+      // The prefetch write lands on whatever rows existed when the policy
+      // finished, and later turns append rows without it, so the pending
+      // lease is recovered from any recent row of this conversation — but
+      // only when the previous lease ran to completion. The final hold turn
+      // writes a zero countdown; a fallback-served turn writes none, and its
+      // broken commitment must not be resurrected by a stale prefetch.
+      if (identityHit.entry.lease_turns_remaining === 0) {
+        const matchConversationId = identityHit.entry.conversation_id;
+        const conversationHits = (input.prefixHits ?? [])
+          .filter((hit) => hit.conversation_id === matchConversationId)
+          .sort((left, right) => right.updated_at.localeCompare(left.updated_at));
+        for (const hit of conversationHits) {
+          pendingLease = pendingLeaseFromHit(hit, compatible.candidates);
+          if (pendingLease !== undefined) break;
+        }
+      }
+    }
+
+    const promptEstimatesByCandidate = new Map(
+      compatible.candidates.map((candidate) => {
+        const anchor = selectPromptAnchor(
+          hits,
+          candidate.model,
+          candidate.reasoningEffort,
+          input.cacheScope,
+        );
+        const candidateAnchor = promptAnchorFor({
+          accounting: promptAccounting,
+          // Stored prompt tokens include the previous response-format schema.
+          anchor:
+            anchor?.entry.response_format_fp === input.responseFormatFp
+              ? anchor
+              : undefined,
+          chain: input.chainsByModel.get(candidate.model),
+        });
+        return [
+          routingCandidateKey(candidate),
+          promptAccounting.promptEstimateFor(
+            candidate.model,
+            candidateAnchor,
+          ),
+        ];
+      }),
+    );
+    costEstimates = estimateCandidateCosts({
+      candidates: compatible.candidates,
+      hits,
+      incomingBlockCount: blockDepth,
+      incomingProviderBlockCountFor:
+        promptAccounting.providerBlockDepthFor,
+      promptEstimatesByCandidate,
+      toolChoiceFp: input.toolChoiceFp,
+      responseFormatFp: input.responseFormatFp,
+      pricing: input.pricing,
+      averageOutputTokensByModel: input.averageOutputTokensByModel,
+      cacheScope: input.cacheScope,
+    });
+  } catch (error) {
+    warnings.push({ phase: "cost_estimation", error });
+  }
+
+  const candidateResolution = resolveStrategyCandidates({
+    strategy: input.strategy,
+    candidates: compatible.candidates,
+    costEstimates,
+    previousDecision,
+    customConfig: input.customConfig,
+    modelPrices: input.modelPrices ?? {},
+  });
+
+  return {
+    blockDepth,
+    hits,
+    conversationId,
+    identityMatchDepth,
+    ...(identityHit !== undefined ? { identityHit } : {}),
+    ...(previousDecision !== undefined ? { previousDecision } : {}),
+    ...(activeLease !== undefined ? { activeLease } : {}),
+    ...(pendingLease !== undefined ? { pendingLease } : {}),
+    costEstimates,
+    candidateResolution,
+    warnings,
+  };
+}
+
+// Resolved fallback posture for the phased prepareRoute API. Distinct from
+// createRouter's RouterFallbackConfig: here both flags default ON.
+export type RouteFallbackConfig = {
+  enabled: boolean;
+  requiresDifferentProvider: boolean;
+};
+
+type RouteAccountingInput =
+  | {
+      promptAccounting: CandidatePromptAccounting;
+      tailCharsFor?: never;
+    }
+  | {
+      promptAccounting?: undefined;
+      tailCharsFor?: LegacyTailCharsFor;
+    };
+
+export type RouteInput = CandidatePreparationSharedInput & RouteAccountingInput & {
+  // Full request message list, system messages included.
+  messages: ChatMessage[];
+  evals?: RouterEval[];
+  selectorModel: string;
+  // Selector context budget in characters (typically the selector model's
+  // context window in tokens times CHARS_PER_TOKEN).
+  selectorContextWindowChars: number;
+  modelFallbackEnabled?: boolean;
+  fallbackRequiresDifferentProvider?: boolean;
+};
+
+export type PreparedRoute = CandidatePreparation & {
+  fallbackConfig: RouteFallbackConfig;
+  // Null when the custom strategy is selected but no custom rule
+  // configuration resolved; hosts surface their own error for that state.
+  selectorPreparation: BuiltSelectorRequest | null;
+};
+
+export function prepareRoute(input: RouteInput): PreparedRoute {
+  const preparation = prepareCandidatesWithAccounting(
+    input,
+    input.promptAccounting
+      ?? chatPromptAccounting(input.messages, input.tailCharsFor),
+  );
+  const resolution = preparation.candidateResolution;
+  const fallbackConfig: RouteFallbackConfig = {
+    enabled: input.modelFallbackEnabled !== false,
+    requiresDifferentProvider: input.fallbackRequiresDifferentProvider !== false,
+  };
+  const custom = resolution.strategy === "custom" ? resolution.custom : undefined;
+  if (custom === null) {
+    return { ...preparation, fallbackConfig, selectorPreparation: null };
+  }
+  const selectorPreparation = buildSizedSelectorRequest({
+    candidates: resolution.candidates,
+    evals: input.evals ?? [],
+    ...(preparation.previousDecision !== undefined
+      ? { previousDecision: preparation.previousDecision }
+      : {}),
+    costEstimates: resolution.costEstimates,
+    ...(custom ? { customRules: custom.rules, defaultTarget: custom.defaultTarget } : {}),
+    selectorModel: input.selectorModel,
+    contextWindowChars: input.selectorContextWindowChars,
+    messages: selectorSafeMessages(input.messages),
+    modelFallbackEnabled: fallbackConfig.enabled,
+    fallbackRequiresDifferentProvider: fallbackConfig.requiresDifferentProvider,
+  });
+  return { ...preparation, fallbackConfig, selectorPreparation };
+}
+
+export type RouteResult = {
+  decision: RoutingDecision;
+  fallbackDecision?: RoutingDecision;
+  outputText: string;
+};
+
+// Parses and validates the selector's raw output against the prepared
+// candidate set and fallback policy.
+export function finalizeRoute(
+  prepared: Pick<PreparedRoute, "candidateResolution" | "fallbackConfig">,
+  selectorOutputText: string,
+): RouteResult {
+  const parsed = parseSelectorDecision(selectorOutputText);
+  validateSelectorDecisions({
+    decision: parsed.decision,
+    ...(parsed.fallbackDecision !== undefined
+      ? { fallbackDecision: parsed.fallbackDecision }
+      : {}),
+    candidates: prepared.candidateResolution.candidates,
+    modelFallbackEnabled: prepared.fallbackConfig.enabled,
+    fallbackRequiresDifferentProvider: prepared.fallbackConfig.requiresDifferentProvider,
+  });
+  return {
+    decision: parsed.decision,
+    ...(parsed.fallbackDecision !== undefined
+      ? { fallbackDecision: parsed.fallbackDecision }
+      : {}),
+    outputText: selectorOutputText,
+  };
+}
+
+// The only effect in the pipeline: executing the selector request against
+// some model. Implementations receive a complete chat-completions-shaped
+// request and return the model's raw output text. Credentials, transport,
+// and retries are entirely the implementation's concern.
+export type Selector = {
+  select(request: ChatCompletionRequest, signal?: AbortSignal): Promise<string>;
+};
+
+export async function route(
+  input: RouteInput,
+  selector: Selector,
+): Promise<RouteResult & { prepared: PreparedRoute }> {
+  const prepared = prepareRoute(input);
+  if (prepared.selectorPreparation === null) {
+    throw new RouterCoreError(
+      "configuration",
+      "Router custom rule configuration is missing.",
+      "custom_config_missing",
+    );
+  }
+  const outputText = await selector.select(prepared.selectorPreparation.selectorRequest);
+  return { ...finalizeRoute(prepared, outputText), prepared };
+}
+
+export function chatPromptAccounting(
+  messages: ChatMessage[],
+  tailCharsFor?: LegacyTailCharsFor,
+): CandidatePromptAccounting {
+  const conversation = conversationMessages({ messages });
+  const blockDepth = conversationBlockCount({ messages });
+  return {
+    anchorSemantics: "matched_prefix",
+    defaultBlockDepth: blockDepth,
+    providerBlockDepthFor: () => blockDepth,
+    promptEstimateFor: (model, anchor) => {
+      if (anchor) {
+        const exact = tailCharsFor?.(model, anchor.hash);
+        if (exact !== undefined) {
+          return { chars: exact, reusesStoredPromptTokens: true };
+        }
+      }
+      return {
+        chars: JSON.stringify(
+          anchor ? conversation.slice(anchor.depth) : messages,
+        ).length,
+        reusesStoredPromptTokens: anchor !== undefined,
+      };
+    },
+  };
+}
+
+function promptAnchorFor(args: {
+  accounting: CandidatePromptAccounting;
+  anchor: ReturnType<typeof selectPromptAnchor>;
+  chain: readonly string[] | undefined;
+}): CandidatePromptAnchor | undefined {
+  if (!args.anchor) return undefined;
+  const depth =
+    args.accounting.anchorSemantics === "stored_input"
+      ? args.anchor.entry.prompt_anchor_depth
+      : args.anchor.depth;
+  if (
+    depth === undefined
+    || depth === null
+    || depth <= 0
+  ) {
+    return undefined;
+  }
+  const hash = args.chain?.[depth - 1];
+  return hash === undefined ? undefined : { hash, depth };
+}
+
+function resolvePromptAccounting(
+  input: CandidatePreparationInput,
+): CandidatePromptAccounting {
+  if (input.promptAccounting) return input.promptAccounting;
+  if (input.messages) {
+    return chatPromptAccounting(input.messages, input.tailCharsFor);
+  }
+  throw new RouterCoreError(
+    "invalid_request",
+    "Candidate preparation requires promptAccounting or messages",
+    "prompt_accounting_required",
+  );
+}