opencandle 0.3.0 → 0.4.0

package/src/routing/entity-extractor.ts

@@ -0,0 +1,140 @@
+import type { ExtractedEntities } from "./types.js";
+
+const COMMON_WORDS = new Set([
+  "I", "A", "AN", "AM", "AS", "AT", "BE", "BY", "DO", "GO", "IF", "IN", "IS",
+  "IT", "ME", "MY", "NO", "OF", "ON", "OR", "SO", "TO", "UP", "US", "WE",
+  "THE", "AND", "BUT", "FOR", "NOT", "ALL", "ARE", "CAN", "HAD", "HAS", "HER",
+  "HIM", "HIS", "HOW", "ITS", "LET", "MAY", "NEW", "NOW", "OLD", "OUR", "OWN",
+  "SAY", "SHE", "TOO", "USE", "WAY", "WHO", "BOY", "DID", "GET", "HAS", "HIM",
+  "OUT", "PUT", "RUN", "SET", "TOP", "WHY", "BIG", "END", "FAR", "FEW",
+  "GOT", "LOW", "MAN", "OFF", "PAY", "TRY", "TWO", "BUY", "ETF", "ETFS",
+  // Technical analysis acronyms
+  "SMA", "EMA", "RSI", "MACD", "OBV", "ATR", "ADX", "VWAP",
+  // Fundamental analysis acronyms
+  "DCF", "FCF", "ROE", "ROA", "ROI", "EPS", "NAV", "WACC", "EBIT",
+  "BEST", "WHAT", "WITH", "THAT", "THIS", "FROM", "HAVE", "BEEN", "SOME",
+  "THEM", "THAN", "LIKE", "JUST", "OVER", "ALSO", "BACK", "MUCH", "MOST",
+  "ONLY", "VERY", "WHEN", "COME", "MAKE", "FIND", "HERE", "KNOW", "TAKE",
+  "WANT", "GIVE", "GOOD", "CALL", "PUTS", "SAFE", "RISK", "LONG", "TERM",
+  "NEXT", "SHOW", "LAST",
+]);
+
+export function extractEntities(input: string): ExtractedEntities {
+  return {
+    symbols: extractSymbols(input),
+    budget: extractBudget(input),
+    maxPremium: extractMaxPremium(input),
+    direction: extractDirection(input),
+    riskProfile: extractRiskProfile(input),
+    dteHint: extractDteHint(input),
+    timeHorizon: extractTimeHorizon(input),
+  };
+}
+
+export function extractBudget(input: string): number | undefined {
+  // Match $10,000 or $10000 or $10k
+  const dollarSign = input.match(/\$\s*([\d,]+(?:\.\d+)?)\s*([kK])?\b/);
+  if (dollarSign) {
+    const base = parseFloat(dollarSign[1].replace(/,/g, ""));
+    return dollarSign[2] ? base * 1000 : base;
+  }
+
+  // Match "10k" or "10K" standalone
+  const kNotation = input.match(/\b(\d+(?:\.\d+)?)\s*[kK]\b/);
+  if (kNotation) {
+    return parseFloat(kNotation[1]) * 1000;
+  }
+
+  // Match "10000 dollars" or "10,000 dollars"
+  const dollarWord = input.match(/\b([\d,]+(?:\.\d+)?)\s+dollars?\b/i);
+  if (dollarWord) {
+    return parseFloat(dollarWord[1].replace(/,/g, ""));
+  }
+
+  return undefined;
+}
+
+function extractSymbols(input: string): string[] {
+  const symbols: string[] = [];
+
+  // Match $TICKER patterns
+  const dollarTickers = input.matchAll(/\$([A-Za-z]{1,5})\b/g);
+  for (const match of dollarTickers) {
+    symbols.push(match[1].toUpperCase());
+  }
+
+  // Match standalone uppercase tickers (1-5 chars, all caps)
+  const words = input.split(/[\s,]+/);
+  for (const word of words) {
+    const cleaned = word.replace(/[^A-Za-z]/g, "");
+    if (
+      cleaned.length >= 1 &&
+      cleaned.length <= 5 &&
+      cleaned === cleaned.toUpperCase() &&
+      /^[A-Z]+$/.test(cleaned) &&
+      !COMMON_WORDS.has(cleaned) &&
+      !symbols.includes(cleaned)
+    ) {
+      symbols.push(cleaned);
+    }
+  }
+
+  return symbols;
+}
+
+function extractMaxPremium(input: string): number | undefined {
+  const lower = input.toLowerCase();
+  if (!/\bpremium\b/.test(lower)) return undefined;
+
+  const under = input.match(/\b(?:under|below|less\s+than|max(?:imum)?|up\s+to)\s+\$?\s*([\d,]+(?:\.\d+)?)\s*([kK])?\b/i);
+  if (under) {
+    const base = parseFloat(under[1].replace(/,/g, ""));
+    if (isNaN(base)) return undefined;
+    return under[2] ? base * 1000 : base;
+  }
+
+  const trailing = input.match(/\$\s*([\d,]+(?:\.\d+)?)\s*([kK])?\s*(?:premium|max\s*premium)\b/i);
+  if (trailing) {
+    const base = parseFloat(trailing[1].replace(/,/g, ""));
+    if (isNaN(base)) return undefined;
+    return trailing[2] ? base * 1000 : base;
+  }
+
+  return undefined;
+}
+
+function extractDirection(input: string): "bullish" | "bearish" | undefined {
+  const lower = input.toLowerCase();
+  if (/\bcalls?\b/.test(lower) || /\bbullish\b/.test(lower)) return "bullish";
+  if (/\bputs?\b/.test(lower) || /\bbearish\b/.test(lower)) return "bearish";
+  return undefined;
+}
+
+function extractRiskProfile(input: string): string | undefined {
+  const lower = input.toLowerCase();
+  if (/\bconservative\b/.test(lower) || /\brisk\s*averse\b/.test(lower) || /\bsafe[r]?\b/.test(lower)) {
+    return "conservative";
+  }
+  if (/\baggressive\b/.test(lower) || /\bhigh\s*risk\b/.test(lower)) {
+    return "aggressive";
+  }
+  if (/\bbalanced\b/.test(lower) || /\bmoderate\b/.test(lower)) {
+    return "balanced";
+  }
+  return undefined;
+}
+
+function extractDteHint(input: string): string | undefined {
+  const lower = input.toLowerCase();
+  if (/\bleaps?\b/i.test(lower) || /\blong[\s-]*dated\b/.test(lower)) return "leaps";
+  if (/\bmonth\b/.test(lower)) return "month";
+  if (/\bweek(?:ly|s?)?\b/.test(lower)) return "week";
+  return undefined;
+}
+
+function extractTimeHorizon(input: string): string | undefined {
+  const lower = input.toLowerCase();
+  if (/\bshort[\s-]*term\b/.test(lower) || /\bday[\s-]*trad/i.test(lower)) return "short";
+  if (/\blong[\s-]*term\b/.test(lower) || /\bbuy[\s-]*and[\s-]*hold\b/.test(lower)) return "long";
+  return undefined;
+}

package/src/routing/index.ts

@@ -0,0 +1,26 @@
+export { classifyIntent } from "./classify-intent.js";
+export { extractEntities, extractBudget } from "./entity-extractor.js";
+export { resolvePortfolioSlots, resolveOptionsScreenerSlots } from "./slot-resolver.js";
+export { PORTFOLIO_DEFAULTS, OPTIONS_SCREENER_DEFAULTS, parseDteTarget } from "./defaults.js";
+export { route, validateRouterOutput } from "./router.js";
+export { createPiAiRouterClient } from "./router-llm-client.js";
+export { buildRouterPrompt } from "./router-prompt.js";
+export type {
+  WorkflowType,
+  ClassificationResult,
+  ExtractedEntities,
+  PortfolioSlots,
+  OptionsScreenerSlots,
+  CompareAssetsSlots,
+  SlotResolution,
+  SlotSource,
+} from "./types.js";
+export type {
+  RouterOutput,
+  RouterRoute,
+  RouterSlot,
+  RouterConfidence,
+  RouterPreferenceUpdate,
+  RouterInputContext,
+  RouterLlmClient,
+} from "./router-types.js";

package/src/routing/router-llm-client.ts

@@ -0,0 +1,51 @@
+import { completeSimple, type Model } from "@earendil-works/pi-ai";
+import type { RouterLlmClient } from "./router-types.js";
+
+/**
+ * Build a router LLM client backed by pi-ai's `completeSimple`. The client
+ * is intentionally thin: prompt in, raw text out. Schema validation and
+ * retry logic live in `router.ts`.
+ *
+ * Zero tools are passed — the router operates on text alone. Temperature
+ * is pinned low for structured-output stability.
+ */
+export function createPiAiRouterClient(model: Model<"anthropic-messages"> | Model<any>): RouterLlmClient {
+  return {
+    async complete(prompt: string): Promise<string> {
+      const response = await completeSimple(
+        model,
+        {
+          messages: [
+            {
+              role: "user",
+              content: prompt,
+              timestamp: Date.now(),
+            },
+          ],
+          // Explicitly no tools — spec requirement.
+          tools: [],
+        },
+        {
+          temperature: 0,
+          maxTokens: 2000,
+          reasoning: "minimal",
+        },
+      );
+
+      if (response.stopReason === "error" || response.stopReason === "aborted") {
+        throw new Error(
+          `router LLM call failed: ${response.errorMessage ?? response.stopReason}`,
+        );
+      }
+
+      const text = response.content
+        .filter((c): c is { type: "text"; text: string } => c.type === "text")
+        .map((c) => c.text)
+        .join("");
+      if (!text) {
+        throw new Error("router LLM call returned no text content");
+      }
+      return text;
+    },
+  };
+}

package/src/routing/router-prompt.ts

@@ -0,0 +1,159 @@
+import type { RouterInputContext } from "./router-types.js";
+
+/**
+ * Privacy note — priorTurns rendering:
+ * Conversational text rendered into the router prompt via `priorTurns` is NOT
+ * filtered by `src/memory/types.ts::NEVER_TRUST_FROM_MEMORY` (which governs
+ * structured market-sensitive memory keys such as `stock_price` and
+ * `target_price`). A future `/forget` command is the designated scrubbing
+ * primitive for removing or masking matching entries from the session branch
+ * so they no longer reach the router. See
+ * `openspec/changes/router-context-and-observability/` for the follow-up.
+ */
+
+/**
+ * List of workflows the router may emit. Keep this in sync with
+ * `WorkflowType` in `src/routing/types.ts` minus the `unclassified` sentinel.
+ */
+const WORKFLOW_CATALOG = [
+  {
+    name: "portfolio_builder",
+    when: "user asks to build/allocate a portfolio, invest a budget across positions",
+    required: ["budget"],
+  },
+  {
+    name: "options_screener",
+    when: "user asks for options trades / calls / puts on a specific ticker",
+    required: ["symbol"],
+  },
+  {
+    name: "compare_assets",
+    when: "user asks to compare two or more symbols (vs / versus / which is better)",
+    required: ["symbols (>=2)"],
+  },
+  {
+    name: "single_asset_analysis",
+    when: "user asks for a full analysis / deep dive / 'is X attractive' on ONE symbol",
+    required: ["symbol"],
+  },
+  {
+    name: "watchlist_or_tracking",
+    when: "user manages or asks about their saved watchlist / prediction history",
+    required: [],
+  },
+  {
+    name: "general_finance_qa",
+    when: "definitional / conceptual 'what is X', 'explain Y' questions",
+    required: [],
+  },
+];
+
+function renderCatalog(): string {
+  return WORKFLOW_CATALOG.map(
+    (w) =>
+      `- "${w.name}": ${w.when}${w.required.length > 0 ? ` [required: ${w.required.join(", ")}]` : ""}`,
+  ).join("\n");
+}
+
+function renderProfile(profile: Record<string, unknown>): string {
+  const entries = Object.entries(profile);
+  if (entries.length === 0) return "(empty)";
+  return entries.map(([k, v]) => `- ${k}: ${JSON.stringify(v)}`).join("\n");
+}
+
+function renderPriorTurns(
+  turns: Array<{ role: "user" | "assistant"; text: string }>,
+): string {
+  if (turns.length === 0) return "(none)";
+  return turns
+    .map((t) => `[${t.role}] ${t.text.replace(/\n+/g, " ").slice(0, 400)}`)
+    .join("\n");
+}
+
+function renderRecentRuns(
+  runs: Array<{
+    workflowType: string;
+    turnType: string;
+    resolvedSlots?: Record<string, unknown>;
+    createdAt: string;
+  }>,
+): string {
+  if (runs.length === 0) return "(none)";
+  return runs
+    .map(
+      (r) =>
+        `- ${r.createdAt} ${r.turnType}/${r.workflowType} ${r.resolvedSlots ? JSON.stringify(r.resolvedSlots) : ""}`,
+    )
+    .join("\n");
+}
+
+const SCHEMA_SPEC = `You MUST respond with a SINGLE JSON object and nothing else (no markdown fences, no prose outside the JSON). The object MUST conform to this TypeScript interface exactly:
+
+interface RouterOutput {
+  route: "workflow" | "fallback";
+  workflow?: "portfolio_builder" | "options_screener" | "compare_assets" | "single_asset_analysis" | "watchlist_or_tracking" | "general_finance_qa";
+  entities: {
+    symbols: string[];               // UPPERCASE tickers the user mentioned or implied
+    budget?: number;                 // dollar amount if user stated one
+    maxPremium?: number;
+    timeHorizon?: string;            // e.g. "6mo", "1y_plus", "short", "long"
+    riskProfile?: string;            // "conservative" | "balanced" | "aggressive"
+    direction?: "bullish" | "bearish";
+    dteHint?: string;
+  };
+  slots: Record<string, {
+    value: unknown;
+    source: "user" | "preference" | "default"; // user = stated this turn; preference = from profileSnapshot; default = workflow fallback
+    confidence: "high" | "medium" | "low";
+  }>;
+  preference_updates: Array<{
+    key: string;                      // e.g. "risk_profile", "time_horizon", "asset_scope", "options_liquidity"
+    value: string;
+    confidence: "high" | "medium" | "low";
+    source: "inferred";
+  }>;
+  missing_required: string[];         // required slot names the turn/profile/defaults did not fill
+  reasoning: string;                  // one or two short sentences; used for debugging only
+}`;
+
+const ROUTING_RULES = `Routing rules:
+- Choose route = "workflow" ONLY when the turn clearly matches one of the workflows below AND required slots are filled (from the turn OR the profile snapshot).
+- Choose route = "fallback" for anything else — including simple data fetches like "AAPL quote", open-ended questions like "entry levels on ASTS for 6 months", or cases where required slots are missing.
+- DO NOT invent a "direct_tool" or "needs_clarification" route. Only "workflow" or "fallback" are valid.
+- If required slots are missing (e.g. options workflow needs a symbol, portfolio needs a budget), still pick the closest route but list the missing slot names in missing_required. The main agent will use ask_user to collect them.
+- Source attribution rules (per-slot source field):
+  - source = "user": the value came from THIS turn's text.
+  - source = "preference": the value came from profileSnapshot (not this turn).
+  - source = "default": a sensible default was applied (workflow fallback).
+- Preference updates:
+  - Emit preference_updates ONLY for stable user-dispositions stated (or very strongly implied) in the current turn. E.g. "I'm aggressive" → risk_profile=aggressive, high.
+  - Do NOT emit preference_updates that merely echo profileSnapshot.
+  - Only confidence="high" updates will be persisted; medium/low are logged but dropped.
+- You have NO tools. Do not request tool execution. Classify on text alone.`;
+
+export function buildRouterPrompt(input: RouterInputContext): string {
+  return `You are OpenCandle's routing agent. Your job is to classify the user's turn into one of the known workflows (or fallback), extract entities + per-slot provenance, and surface any stable preferences the user expressed. Your output feeds the main analyst agent — it does NOT go to the user.
+
+WORKFLOW CATALOG:
+${renderCatalog()}
+
+${SCHEMA_SPEC}
+
+${ROUTING_RULES}
+
+--- CONTEXT ---
+
+Profile snapshot (persisted preferences from prior sessions):
+${renderProfile(input.profileSnapshot)}
+
+Recent workflow runs (most recent last):
+${renderRecentRuns(input.recentWorkflowRuns)}
+
+Prior conversation turns (most recent last):
+${renderPriorTurns(input.priorTurns)}
+
+--- CURRENT TURN ---
+${input.text}
+
+Respond with the JSON object. Nothing else.`;
+}

package/src/routing/router-types.ts

@@ -0,0 +1,66 @@
+import type { ExtractedEntities, SlotSource, WorkflowType } from "./types.js";
+
+export type RouterRoute = "workflow" | "fallback";
+
+export type RouterConfidence = "high" | "medium" | "low";
+
+export interface RouterSlot {
+  value: unknown;
+  source: SlotSource;
+  confidence: RouterConfidence;
+}
+
+export interface RouterPreferenceUpdate {
+  key: string;
+  value: string;
+  confidence: RouterConfidence;
+  source: "inferred";
+}
+
+/**
+ * Structured output from the LLM router. Mirrors existing types
+ * (`ClassificationResult`, `ExtractedEntities`, `SlotSource`) so downstream
+ * consumers can branch without a new vocabulary.
+ *
+ * `workflow` is only meaningful when `route === "workflow"`. For `fallback`
+ * routes, `workflow_type` at the storage layer is the sentinel `"fallback"`.
+ */
+export interface RouterOutput {
+  route: RouterRoute;
+  workflow?: Exclude<WorkflowType, "unclassified">;
+  entities: ExtractedEntities;
+  slots: Record<string, RouterSlot>;
+  preference_updates: RouterPreferenceUpdate[];
+  missing_required: string[];
+  reasoning: string;
+}
+
+/** Context passed into the router on each turn. */
+export interface RouterInputContext {
+  /** Raw user text from `pi.on("input")`. */
+  text: string;
+  /** Last 5 user/assistant turns (most recent last). */
+  priorTurns: Array<{ role: "user" | "assistant"; text: string }>;
+  /** Current investor_profile snapshot retrieved from preferences storage. */
+  profileSnapshot: Record<string, unknown>;
+  /** Last 3 workflow_runs, compact summaries. */
+  recentWorkflowRuns: Array<{
+    workflowType: string;
+    turnType: string;
+    resolvedSlots?: Record<string, unknown>;
+    createdAt: string;
+  }>;
+}
+
+/**
+ * Abstract LLM client used by the router. Injected by callers so unit tests
+ * can supply a deterministic mock. The real implementation (see
+ * `src/routing/router-llm-client.ts`) wraps pi-ai's `completeSimple`.
+ */
+export interface RouterLlmClient {
+  /**
+   * Run a single prompt → text completion. Router parses the returned text
+   * as JSON; the client is not responsible for structured-output parsing.
+   */
+  complete(prompt: string): Promise<string>;
+}

package/src/routing/router.ts

@@ -0,0 +1,213 @@
+import { extractEntities } from "./entity-extractor.js";
+import { buildRouterPrompt } from "./router-prompt.js";
+import type {
+  RouterInputContext,
+  RouterLlmClient,
+  RouterOutput,
+  RouterPreferenceUpdate,
+  RouterRoute,
+  RouterSlot,
+} from "./router-types.js";
+import type { ExtractedEntities, WorkflowType } from "./types.js";
+
+const VALID_ROUTES: readonly RouterRoute[] = ["workflow", "fallback"];
+const VALID_WORKFLOWS: ReadonlyArray<Exclude<WorkflowType, "unclassified">> = [
+  "portfolio_builder",
+  "options_screener",
+  "compare_assets",
+  "single_asset_analysis",
+  "watchlist_or_tracking",
+  "general_finance_qa",
+];
+const VALID_SOURCES = new Set(["user", "preference", "default"]);
+const VALID_CONFIDENCE = new Set(["high", "medium", "low"]);
+
+/**
+ * Run the LLM router against the given input context. Retries once on
+ * validation failure with a corrective message. Falls back to a minimal
+ * `route: "fallback"` output on persistent failure.
+ *
+ * The LLM client is injected so unit tests can supply deterministic responses.
+ */
+export async function route(
+  input: RouterInputContext,
+  client: RouterLlmClient,
+): Promise<RouterOutput> {
+  const prompt = buildRouterPrompt(input);
+
+  let firstError: string | undefined;
+  try {
+    const raw = await client.complete(prompt);
+    return validateRouterOutput(raw);
+  } catch (err) {
+    firstError = err instanceof Error ? err.message : String(err);
+  }
+
+  // Retry once with error feedback.
+  try {
+    const retryPrompt = `${prompt}\n\n(Your previous response failed validation: ${firstError}. Return a valid JSON object conforming to RouterOutput. Nothing else.)`;
+    const raw = await client.complete(retryPrompt);
+    return validateRouterOutput(raw);
+  } catch {
+    // Persistent failure — return a minimal fallback with regex-extracted symbols.
+    return minimalFallback(input.text);
+  }
+}
+
+export function validateRouterOutput(raw: string): RouterOutput {
+  const parsed = parseJsonPayload(raw);
+
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("router output was not a JSON object");
+  }
+  const obj = parsed as Record<string, unknown>;
+
+  const route = obj.route;
+  if (typeof route !== "string" || !VALID_ROUTES.includes(route as RouterRoute)) {
+    throw new Error(`invalid route: ${JSON.stringify(route)}`);
+  }
+
+  let workflow: RouterOutput["workflow"];
+  if (route === "workflow") {
+    if (typeof obj.workflow !== "string" || !VALID_WORKFLOWS.includes(obj.workflow as Exclude<WorkflowType, "unclassified">)) {
+      throw new Error(`workflow route requires a valid workflow; got ${JSON.stringify(obj.workflow)}`);
+    }
+    workflow = obj.workflow as Exclude<WorkflowType, "unclassified">;
+  }
+
+  const entities = validateEntities(obj.entities);
+  const slots = validateSlots(obj.slots);
+  const preference_updates = validatePreferenceUpdates(obj.preference_updates);
+  const missing_required = validateStringArray(obj.missing_required, "missing_required");
+  const reasoning =
+    typeof obj.reasoning === "string" ? obj.reasoning : "";
+
+  return {
+    route: route as RouterRoute,
+    workflow,
+    entities,
+    slots,
+    preference_updates,
+    missing_required,
+    reasoning,
+  };
+}
+
+function parseJsonPayload(raw: string): unknown {
+  const trimmed = raw.trim();
+  // Tolerate ```json ... ``` fences even though the prompt forbids them.
+  const stripped = trimmed
+    .replace(/^```(?:json)?\s*/i, "")
+    .replace(/\s*```$/i, "")
+    .trim();
+  try {
+    return JSON.parse(stripped);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`router output was not valid JSON: ${msg}`);
+  }
+}
+
+function validateEntities(raw: unknown): ExtractedEntities {
+  if (!raw || typeof raw !== "object") {
+    throw new Error("entities must be an object");
+  }
+  const e = raw as Record<string, unknown>;
+  const symbols = validateStringArray(e.symbols, "entities.symbols").map((s) =>
+    s.toUpperCase(),
+  );
+
+  const out: ExtractedEntities = { symbols };
+  if (typeof e.budget === "number") out.budget = e.budget;
+  if (typeof e.maxPremium === "number") out.maxPremium = e.maxPremium;
+  if (typeof e.timeHorizon === "string") out.timeHorizon = e.timeHorizon;
+  if (typeof e.riskProfile === "string") out.riskProfile = e.riskProfile;
+  if (e.direction === "bullish" || e.direction === "bearish") out.direction = e.direction;
+  if (typeof e.dteHint === "string") out.dteHint = e.dteHint;
+  return out;
+}
+
+function validateSlots(raw: unknown): Record<string, RouterSlot> {
+  if (raw === undefined || raw === null) return {};
+  if (typeof raw !== "object") {
+    throw new Error("slots must be an object");
+  }
+  const out: Record<string, RouterSlot> = {};
+  for (const [key, val] of Object.entries(raw as Record<string, unknown>)) {
+    if (!val || typeof val !== "object") {
+      throw new Error(`slot ${key} must be an object`);
+    }
+    const s = val as Record<string, unknown>;
+    if (!VALID_SOURCES.has(s.source as string)) {
+      throw new Error(`slot ${key} has invalid source: ${JSON.stringify(s.source)}`);
+    }
+    if (!VALID_CONFIDENCE.has(s.confidence as string)) {
+      throw new Error(`slot ${key} has invalid confidence: ${JSON.stringify(s.confidence)}`);
+    }
+    out[key] = {
+      value: s.value,
+      source: s.source as RouterSlot["source"],
+      confidence: s.confidence as RouterSlot["confidence"],
+    };
+  }
+  return out;
+}
+
+function validatePreferenceUpdates(raw: unknown): RouterPreferenceUpdate[] {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    throw new Error("preference_updates must be an array");
+  }
+  return raw.map((item, idx) => {
+    if (!item || typeof item !== "object") {
+      throw new Error(`preference_updates[${idx}] must be an object`);
+    }
+    const p = item as Record<string, unknown>;
+    if (typeof p.key !== "string" || p.key.length === 0) {
+      throw new Error(`preference_updates[${idx}].key must be a non-empty string`);
+    }
+    if (typeof p.value !== "string") {
+      throw new Error(`preference_updates[${idx}].value must be a string`);
+    }
+    if (!VALID_CONFIDENCE.has(p.confidence as string)) {
+      throw new Error(`preference_updates[${idx}].confidence is invalid`);
+    }
+    // Router-emitted preferences are always inferred — absent is accepted
+    // (normalized), but any explicit non-"inferred" value is an invariant
+    // violation the caller should see rather than silently lose.
+    if (p.source !== undefined && p.source !== "inferred") {
+      throw new Error(`preference_updates[${idx}].source must be "inferred" (got ${JSON.stringify(p.source)})`);
+    }
+    return {
+      key: p.key,
+      value: p.value,
+      confidence: p.confidence as RouterPreferenceUpdate["confidence"],
+      source: "inferred",
+    };
+  });
+}
+
+function validateStringArray(raw: unknown, field: string): string[] {
+  if (raw === undefined || raw === null) return [];
+  if (!Array.isArray(raw)) {
+    throw new Error(`${field} must be an array`);
+  }
+  return raw.map((item, idx) => {
+    if (typeof item !== "string") {
+      throw new Error(`${field}[${idx}] must be a string`);
+    }
+    return item;
+  });
+}
+
+function minimalFallback(text: string): RouterOutput {
+  const entities = extractEntities(text);
+  return {
+    route: "fallback",
+    entities: { symbols: entities.symbols },
+    slots: {},
+    preference_updates: [],
+    missing_required: [],
+    reasoning: "router validation failed; emitted minimal fallback",
+  };
+}