@mupt-ai/dari-router 0.1.0

package/src/dari_policy.ts

@@ -0,0 +1,360 @@
+import type { CandidateModelMetadata } from "./compatibility.js";
+import type { PricingLookup } from "./cost.js";
+import { RouterCoreError } from "./errors.js";
+import { RouterFrameworkError } from "./framework_error.js";
+import type {
+  RouterCandidate,
+  RouterContent,
+  RouterRequest,
+  RoutingPolicy,
+  RoutingPolicyInput,
+} from "./framework_types.js";
+import { optionsFingerprints } from "./fingerprint.js";
+import {
+  finalizeRoute,
+  prepareRoute,
+  type PreparedRoute,
+  type RouteInput,
+  type RouteResult,
+  type Selector,
+} from "./route.js";
+import type {
+  ChatCompletionRequest,
+  ChatMessage,
+  CustomRouterConfig,
+  RouterEval,
+  RouterModelPrice,
+  RouterPrefixHit,
+} from "./types.js";
+
+export type DariPolicyState = {
+  chainsByModel?: ReadonlyMap<string, string[]>;
+  prefixHits?: RouterPrefixHit[];
+  looseChain?: readonly string[];
+  nowMs?: number;
+  toolChoiceFingerprint?: string;
+  responseFormatFingerprint?: string;
+};
+
+export type DariRoutingPolicyOptions<Metadata = unknown> = {
+  selector?: Selector | ((request: ChatCompletionRequest, signal: AbortSignal) => Promise<string>);
+  runtime?: {
+    select(request: ChatCompletionRequest, signal?: AbortSignal): Promise<string>;
+  };
+  selectorModel: string;
+  selectorContextWindowChars: number;
+  metadata?: (model: RouterCandidate<Metadata>) => CandidateModelMetadata;
+  pricing?: PricingLookup;
+  evals?: RouterEval[] | ((input: RoutingPolicyInput<Metadata>) => RouterEval[] | Promise<RouterEval[]>);
+  state?: (
+    input: RoutingPolicyInput<Metadata>,
+  ) => DariPolicyState | Promise<DariPolicyState>;
+  strategy?: "slm" | "custom";
+  customConfig?: CustomRouterConfig | null;
+  modelPrices?: Record<string, RouterModelPrice>;
+  averageOutputTokensByModel?: RouteInput["averageOutputTokensByModel"];
+};
+
+export type DariPolicyDetails = {
+  prepared: PreparedRoute;
+  selectorOutput: string;
+};
+
+export function createDariRoutingPolicy<Metadata = unknown>(
+  options: DariRoutingPolicyOptions<Metadata>,
+): RoutingPolicy<Metadata> {
+  const selector = options.selector ?? options.runtime;
+  if (selector === undefined) {
+    throw new RouterFrameworkError(
+      "configuration",
+      "Dari routing requires a selector or Pi runtime.",
+      "selector_missing",
+    );
+  }
+  return async (input) => {
+    const chatRequest = routerRequestToChat(input.request);
+    const state = await options.state?.(input) ?? {};
+    const evals = typeof options.evals === "function"
+      ? await options.evals(input)
+      : options.evals ?? [];
+    const fingerprints = optionsFingerprints(chatRequest);
+    const candidateModels = input.candidates.map((candidate) => candidate.id);
+    const metadataByModel = new Map(
+      input.candidates.map((candidate) => [
+        candidate.id,
+        options.metadata?.(candidate) ?? defaultDariMetadata(candidate),
+      ]),
+    );
+    let prepared: PreparedRoute;
+    try {
+      prepared = prepareRoute({
+        candidateModels,
+        metadataLookup: (model) => metadataByModel.get(model)!,
+        requiredCapabilities: [],
+        ...(input.request.reasoning?.effort === undefined
+          ? {}
+          : { requestedReasoningEffort: input.request.reasoning.effort }),
+        ...(input.request.reasoning?.enabled === undefined
+          ? {}
+          : { thinkingEnabled: input.request.reasoning.enabled }),
+        ...(chatRequest.tool_choice === undefined ? {} : { toolChoice: chatRequest.tool_choice }),
+        modelThinkingLevels: Object.fromEntries(
+          input.candidates.map((candidate) => [candidate.id, [...candidate.reasoningEfforts]]),
+        ),
+        strategy: options.strategy ?? "slm",
+        ...(options.customConfig === undefined ? {} : { customConfig: options.customConfig }),
+        modelPrices: options.modelPrices ?? {},
+        pricing: options.pricing ?? (() => null),
+        ...(options.averageOutputTokensByModel === undefined
+          ? {}
+          : { averageOutputTokensByModel: options.averageOutputTokensByModel }),
+        messages: chatRequest.messages ?? [],
+        chainsByModel: state.chainsByModel ?? new Map(
+          candidateModels.map((model) => [model, []]),
+        ),
+        prefixHits: state.prefixHits ?? [],
+        nowMs: state.nowMs ?? Date.now(),
+        ...(state.looseChain === undefined ? {} : { looseChain: state.looseChain }),
+        toolChoiceFp: state.toolChoiceFingerprint ?? fingerprints.tool_choice_fp,
+        responseFormatFp: state.responseFormatFingerprint ?? fingerprints.response_format_fp,
+        evals,
+        selectorModel: options.selectorModel,
+        selectorContextWindowChars: options.selectorContextWindowChars,
+        // Selection fallback is deliberately not provider retry. The framework
+        // dispatches one chosen candidate and leaves retries to its executor.
+        modelFallbackEnabled: false,
+      });
+    } catch (error) {
+      throw mapDariPolicyError(error);
+    }
+    if (prepared.selectorPreparation === null) {
+      throw new RouterFrameworkError(
+        "configuration",
+        "Dari custom routing requires a non-empty customConfig.",
+        "custom_config_missing",
+      );
+    }
+
+    const selectorRequest = prepared.selectorPreparation.selectorRequest;
+    let selectorOutput: string;
+    try {
+      selectorOutput = typeof selector === "function"
+        ? await selector(selectorRequest, input.signal)
+        : await selector.select(selectorRequest, input.signal);
+    } catch (error) {
+      throw mapSelectorError(error);
+    }
+    let result: RouteResult;
+    try {
+      result = finalizeRoute(prepared, selectorOutput);
+    } catch (error) {
+      throw mapDariPolicyError(error);
+    }
+    return {
+      model: result.decision.selectedModel,
+      reasoningEffort: result.decision.reasoningEffort,
+      reason: result.decision.reason,
+      ...(result.decision.leaseTurnsRemaining === undefined
+        ? {}
+        : { leaseTurnsRemaining: result.decision.leaseTurnsRemaining }),
+      details: { prepared, selectorOutput } satisfies DariPolicyDetails,
+    };
+  };
+}
+
+function mapSelectorError(error: unknown): unknown {
+  if (!(error instanceof RouterFrameworkError) || error.kind !== "executor") return error;
+  return new RouterFrameworkError(
+    "policy",
+    error.message,
+    error.code,
+    error.param,
+    { cause: error },
+  );
+}
+
+function mapDariPolicyError(error: unknown): unknown {
+  if (!(error instanceof RouterCoreError)) return error;
+  const kind = error.kind === "invalid_request"
+    ? "invalid_request"
+    : error.kind === "configuration"
+      ? "configuration"
+      : "policy";
+  return new RouterFrameworkError(
+    kind,
+    error.message,
+    error.code,
+    error.param,
+    { cause: error },
+  );
+}
+
+function defaultDariMetadata<Metadata>(
+  candidate: RouterCandidate<Metadata>,
+): CandidateModelMetadata {
+  return {
+    provider: candidate.provider,
+    api: candidate.api,
+    supportsImageInput: candidate.capabilities.imageInput,
+    supportsHostedWebSearch: false,
+    supportsStructuredOutput: candidate.capabilities.structuredOutput,
+    supportedThinkingLevels: [...candidate.reasoningEfforts],
+  };
+}
+
+function routerRequestToChat(request: RouterRequest): ChatCompletionRequest {
+  const messages: ChatMessage[] = [];
+  for (const item of request.items) {
+    if (item.type === "message") {
+      const content = chatContent(item.content);
+      const previous = messages.at(-1);
+      if (item.role === "assistant" && previous?.role === "assistant") {
+        const previousContent = previous.content;
+        previous.content = Array.isArray(previousContent)
+          ? [...previousContent, ...content]
+          : content;
+      } else {
+        messages.push({ role: item.role, content });
+      }
+      continue;
+    }
+    if (item.type === "reasoning") {
+      const readable = [...(item.summary ?? []), ...item.content].join("\n");
+      let assistant = messages.at(-1);
+      if (!assistant || assistant.role !== "assistant" || hasAssistantContent(assistant)) {
+        assistant = { role: "assistant", content: null };
+        messages.push(assistant);
+      }
+      if (readable) {
+        assistant.reasoning_content = appendReasoningText(assistant.reasoning_content, readable);
+      }
+      continue;
+    }
+    if (item.type === "tool_result") {
+      messages.push({
+        role: "tool",
+        tool_call_id: item.toolCallId,
+        content: chatContent(item.content),
+      });
+      continue;
+    }
+
+    let assistant = messages.at(-1);
+    if (assistant?.role !== "assistant") {
+      assistant = { role: "assistant", content: null, tool_calls: [] };
+      messages.push(assistant);
+    }
+    assistant.tool_calls ??= [];
+    if (item.type === "hosted_tool_call") {
+      const payload: Record<string, unknown> = {
+        ...item.payload,
+        type: item.providerType,
+        id: item.id,
+      };
+      if (item.status) payload.status = item.status;
+      else delete payload.status;
+      assistant.tool_calls.push({
+        id: item.id,
+        type: "function",
+        function: { name: item.tool, arguments: JSON.stringify(payload) },
+      });
+      continue;
+    }
+    assistant.tool_calls.push({
+      id: item.id,
+      type: "function",
+      function: {
+        name: item.name,
+        arguments: typeof item.arguments === "string"
+          ? item.arguments
+          : JSON.stringify(item.arguments),
+      },
+    });
+  }
+
+  return {
+    model: request.requestedModel,
+    messages,
+    stream: request.stream,
+    source_protocol: request.protocol === "anthropic_messages"
+      ? "anthropic_messages"
+      : "openai_chat",
+    ...(request.cacheKey === undefined ? {} : { prompt_cache_key: request.cacheKey }),
+    ...(request.generation.temperature === undefined
+      ? {}
+      : { temperature: request.generation.temperature }),
+    ...(request.generation.topP === undefined ? {} : { top_p: request.generation.topP }),
+    ...(request.generation.maxOutputTokens === undefined
+      ? {}
+      : { max_completion_tokens: request.generation.maxOutputTokens }),
+    ...(request.generation.stop === undefined ? {} : { stop: request.generation.stop }),
+    ...(request.tools.length === 0 ? {} : { tools: request.tools.map(chatTool) }),
+    ...(request.toolChoice === undefined ? {} : { tool_choice: chatToolChoice(request.toolChoice) }),
+    ...(request.parallelToolCalls === undefined
+      ? {}
+      : { parallel_tool_calls: request.parallelToolCalls }),
+    ...(request.responseFormat === undefined
+      ? {}
+      : { response_format: chatResponseFormat(request.responseFormat) }),
+    ...(request.reasoning?.effort === undefined
+      ? {}
+      : { reasoning_effort: request.reasoning.effort }),
+    ...(request.metadata === undefined ? {} : { metadata: request.metadata }),
+    ...(request.user === undefined ? {} : { user: request.user }),
+  };
+}
+
+function chatContent(content: readonly RouterContent[]): Array<Record<string, unknown>> {
+  return content.map((part) =>
+    part.type === "text"
+      ? { type: "text", text: part.text }
+      : {
+          type: "image_url",
+          image_url: {
+            url: part.url,
+            ...(part.detail === undefined ? {} : { detail: part.detail }),
+          },
+        }
+  );
+}
+
+function hasAssistantContent(message: ChatMessage): boolean {
+  if (message.content !== undefined && message.content !== null) return true;
+  return (message.tool_calls?.length ?? 0) > 0;
+}
+
+function appendReasoningText(existing: string | undefined, text: string): string {
+  return existing ? `${existing}\n${text}` : text;
+}
+
+function chatTool(tool: RouterRequest["tools"][number]): Record<string, unknown> {
+  return {
+    type: "function",
+    function: {
+      name: tool.name,
+      ...(tool.description === undefined ? {} : { description: tool.description }),
+      parameters: tool.inputSchema,
+      ...(tool.strict === undefined ? {} : { strict: tool.strict }),
+    },
+  };
+}
+
+function chatToolChoice(choice: NonNullable<RouterRequest["toolChoice"]>): string | Record<string, unknown> {
+  if (typeof choice === "string") return choice;
+  return { type: "function", function: { name: choice.name } };
+}
+
+function chatResponseFormat(
+  format: NonNullable<RouterRequest["responseFormat"]>,
+): NonNullable<ChatCompletionRequest["response_format"]> {
+  if (format.type !== "json_schema") return format;
+  return {
+    type: "json_schema",
+    json_schema: {
+      name: format.name,
+      schema: format.schema,
+      ...(format.description === undefined ? {} : { description: format.description }),
+      ...(format.strict === undefined ? {} : { strict: format.strict }),
+    },
+  };
+}

package/src/errors.ts

@@ -0,0 +1,27 @@
+// Typed errors for the deterministic routing core. The core never speaks
+// HTTP; hosts map `kind` to their own transport semantics (Dari's hosted
+// runtime maps invalid_request -> 400, selector_output -> 502, and
+// configuration -> 500 while preserving `code`, `param`, and the message).
+export type RouterCoreErrorKind =
+  | "invalid_request"
+  | "selector_output"
+  | "configuration";
+
+export class RouterCoreError extends Error {
+  readonly kind: RouterCoreErrorKind;
+  readonly code: string;
+  readonly param?: string;
+
+  constructor(
+    kind: RouterCoreErrorKind,
+    message: string,
+    code: string,
+    param?: string,
+  ) {
+    super(message);
+    this.name = "RouterCoreError";
+    this.kind = kind;
+    this.code = code;
+    if (param !== undefined) this.param = param;
+  }
+}

package/src/fingerprint.ts

@@ -0,0 +1,148 @@
+import { createHash } from "node:crypto";
+
+import type { ChatCompletionRequest, ChatMessage } from "./types.js";
+
+const FP_VERSION = "v1";
+
+/**
+ * Conversation identity is an exact-prefix match over what providers actually
+ * cache: system prompt, tools, and the message sequence. Sampling parameters
+ * (temperature, top_p, max_tokens, ...) never enter provider cache keys and
+ * are deliberately excluded. tool_choice and response_format are also kept
+ * out of the chain — folding them in would break conversation identity over
+ * a one-turn knob flip — and are tracked via optionsFingerprints instead.
+ */
+
+function sha256(text: string): string {
+  return createHash("sha256").update(text, "utf8").digest("hex");
+}
+
+// JSON with recursively sorted object keys so semantically identical payloads
+// hash identically regardless of client key ordering. Provider caches match
+// tokenized content, not raw JSON byte order.
+export function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "null";
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).sort();
+  return `{${keys.map((key) => `${JSON.stringify(key)}:${stableStringify(record[key])}`).join(",")}}`;
+}
+
+function canonicalToolCalls(toolCalls: Array<Record<string, unknown>> | undefined): unknown {
+  if (!toolCalls?.length) return null;
+  return toolCalls.map((call) => {
+    const fn = isRecord(call.function) ? call.function : {};
+    return {
+      id: typeof call.id === "string" ? call.id : "",
+      name: typeof fn.name === "string" ? fn.name : "",
+      // Keep string arguments byte-exact; never parse-and-restringify, the
+      // provider saw (and cached) exactly these bytes inside its prompt.
+      arguments: typeof fn.arguments === "string" ? fn.arguments : stableStringify(fn.arguments ?? null),
+    };
+  });
+}
+
+export function canonicalMessage(message: ChatMessage): string {
+  return stableStringify({
+    role: message.role,
+    content: message.content ?? null,
+    tool_calls: canonicalToolCalls(message.tool_calls),
+    tool_call_id: message.tool_call_id ?? null,
+  });
+}
+
+function isSystemRole(role: string): boolean {
+  return role === "system" || role === "developer";
+}
+
+export function conversationMessages(request: ChatCompletionRequest): ChatMessage[] {
+  return (request.messages ?? []).filter((message) => !isSystemRole(message.role));
+}
+
+// Approximates how many Anthropic content blocks a message renders to: one
+// per content part (or one for string content), plus one per tool call; tool
+// results are a single tool_result block. Used only for the Anthropic
+// breakpoint-lookback gate, where blocks — not messages — are the unit.
+export function messageBlockCount(message: ChatMessage): number {
+  if (message.role === "tool") return 1;
+  let blocks = 0;
+  if (typeof message.content === "string") {
+    if (message.content.length > 0) blocks += 1;
+  } else if (Array.isArray(message.content)) {
+    blocks += message.content.length;
+  }
+  blocks += message.tool_calls?.length ?? 0;
+  return Math.max(1, blocks);
+}
+
+// Content-block position of this request's cache breakpoint (its last user
+// message): total blocks across the non-system messages.
+export function conversationBlockCount(request: ChatCompletionRequest): number {
+  return conversationMessages(request).reduce(
+    (total, message) => total + messageBlockCount(message),
+    0
+  );
+}
+
+// Anchors and scopes the chain. routerId is a pure namespace so two routers
+// receiving identical conversations never share entries; system/tools changes
+// bust provider caches, so they bust ours too.
+// System/developer messages are folded in here regardless of their position in
+// the message list, so a request that moves one mid-conversation hashes the
+// same as system-first. Clients virtually always send system first; if they
+// don't, the warmth estimate is merely optimistic — estimates never bill.
+// NUL is the component delimiter throughout: JSON.stringify always escapes
+// control characters, so canonical output can never contain a raw NUL and
+// component boundaries are unambiguous.
+export function headHash(routerId: string, request: ChatCompletionRequest): string {
+  const systemMessages = (request.messages ?? [])
+    .filter((message) => isSystemRole(message.role))
+    .map((message) => canonicalMessage(message));
+  return sha256(
+    [FP_VERSION, routerId, `[${systemMessages.join(",")}]`, stableStringify(request.tools ?? [])].join("\u0000")
+  );
+}
+
+// h[i] = sha256(h[i-1] ‖ canonical(message_i)) over non-system messages.
+// Returns [h1 ... hn]; chain[i] identifies the conversation prefix ending at
+// non-system message i+1. System messages live in the head hash only.
+export function prefixChain(routerId: string, request: ChatCompletionRequest): string[] {
+  let hash = headHash(routerId, request);
+  const chain: string[] = [];
+  for (const message of conversationMessages(request)) {
+    hash = sha256(`${hash}\u0000${canonicalMessage(message)}`);
+    chain.push(hash);
+  }
+  return chain;
+}
+
+// Chain extended with the assistant reply we are about to return, in the
+// exact OpenAI shape the client will echo back next turn.
+export function extendChain(lastHash: string, assistantMessage: Record<string, unknown>): string {
+  const canonical = canonicalMessage({
+    role: "assistant",
+    content: (assistantMessage.content as ChatMessage["content"]) ?? null,
+    tool_calls: Array.isArray(assistantMessage.tool_calls)
+      ? (assistantMessage.tool_calls as Array<Record<string, unknown>>)
+      : undefined,
+  });
+  return sha256(`${lastHash}\u0000${canonical}`);
+}
+
+// NOT part of the chain (see the module comment): compared against the
+// matched entry's stored values to downgrade cache-warmth estimates when
+// these knobs flip mid-conversation. Do not "fix" this by folding them into
+// headHash — that would break conversation identity over a one-turn change.
+export function optionsFingerprints(request: ChatCompletionRequest): {
+  tool_choice_fp: string;
+  response_format_fp: string;
+} {
+  return {
+    tool_choice_fp: sha256(stableStringify(request.tool_choice ?? null)),
+    response_format_fp: sha256(stableStringify(request.response_format ?? null)),
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/fixed_turn_cost_config.ts

@@ -0,0 +1,24 @@
+// Loop horizons every candidate is projected at, ascending. These match the
+// lease lengths the selector can commit to, so every option is priced at
+// exactly the horizon its action would hold for — the longer horizons are
+// where cache behavior and output pricing separate models that look alike on
+// a single turn.
+export const FIXED_TURN_COST_PROJECTED_TURNS = [5, 10, 30] as const;
+
+// Turn commitments the selector may choose between: how many turns the routed
+// model keeps serving before the router reconsiders. Committing amortizes the
+// cold start it pays on the first turn across the warm turns that follow.
+export const SELECTOR_LEASE_TURNS = [5, 10, 30] as const;
+
+// The horizon used wherever a single scalar cost is needed rather than the
+// whole curve, notably warm-incumbent pruning.
+export const FIXED_TURN_COST_COMPARISON_TURNS = 10;
+
+export const FIXED_TURN_CACHE_HIT_PROBABILITY = {
+  openai: 0.95,
+  anthropic: 0.99,
+  fireworks: 0.88,
+  // 48/50 follow-up requests hit in the July 2026 25-agent Pi benchmark.
+  // First turns are excluded because fixed-turn turn one uses live warmth.
+  meta: 0.96,
+} as const;

package/src/framework_error.ts

@@ -0,0 +1,38 @@
+export type RouterFrameworkErrorKind =
+  | "invalid_request"
+  | "not_found"
+  | "configuration"
+  | "cancelled"
+  | "policy"
+  | "executor";
+
+const STATUS_BY_KIND: Record<RouterFrameworkErrorKind, number> = {
+  invalid_request: 400,
+  not_found: 404,
+  configuration: 500,
+  cancelled: 499,
+  policy: 502,
+  executor: 502,
+};
+
+export class RouterFrameworkError extends Error {
+  readonly kind: RouterFrameworkErrorKind;
+  readonly code: string;
+  readonly param?: string;
+  readonly status: number;
+
+  constructor(
+    kind: RouterFrameworkErrorKind,
+    message: string,
+    code: string,
+    param?: string,
+    options?: ErrorOptions,
+  ) {
+    super(message, options);
+    this.name = "RouterFrameworkError";
+    this.kind = kind;
+    this.code = code;
+    this.status = STATUS_BY_KIND[kind];
+    if (param !== undefined) this.param = param;
+  }
+}

package/src/framework_lifecycle.ts

@@ -0,0 +1,74 @@
+import { RouterFrameworkError } from "./framework_error.js";
+
+export function executorStartError(error: unknown, executor: string): RouterFrameworkError {
+  if (error instanceof RouterFrameworkError) return error;
+  return new RouterFrameworkError(
+    "executor",
+    errorMessage(error, `Executor '${executor}' failed to start.`),
+    "executor_setup_failed",
+    undefined,
+    { cause: error },
+  );
+}
+
+export function safeHook(run: () => void): void {
+  try {
+    run();
+  } catch {
+    // Hooks are fire-and-forget; a throwing hook must never affect the
+    // request or stream.
+  }
+}
+
+export function normalizeError(error: unknown): RouterFrameworkError {
+  if (error instanceof RouterFrameworkError) return error;
+  return new RouterFrameworkError(
+    "configuration",
+    errorMessage(error, "Internal router error."),
+    "internal_error",
+    undefined,
+    { cause: error },
+  );
+}
+
+export function completionContract(message: string): RouterFrameworkError {
+  return new RouterFrameworkError("executor", message, "executor_output_invalid");
+}
+
+export function streamContract(message: string): RouterFrameworkError {
+  return new RouterFrameworkError("executor", message, "stream_invalid");
+}
+
+export function cancelled(reason: unknown): RouterFrameworkError {
+  return new RouterFrameworkError(
+    "cancelled",
+    errorMessage(reason, "Request cancelled."),
+    "request_cancelled",
+  );
+}
+
+export function throwIfAborted(signal: AbortSignal): void {
+  if (signal.aborted) throw cancelled(signal.reason);
+}
+
+export async function closeAsyncIterable(iterable: AsyncIterable<unknown>): Promise<void> {
+  try {
+    await closeAsyncIterator(iterable[Symbol.asyncIterator]());
+  } catch {
+    // Cleanup errors must not replace the mode mismatch.
+  }
+}
+
+export async function closeAsyncIterator(iterator: AsyncIterator<unknown>): Promise<void> {
+  try {
+    await iterator.return?.();
+  } catch {
+    // Cleanup errors must not replace the request or provider failure.
+  }
+}
+
+export function errorMessage(error: unknown, fallback: string): string {
+  if (error instanceof Error && error.message.trim()) return error.message;
+  if (typeof error === "string" && error.trim()) return error;
+  return fallback;
+}