mirror-mind 0.0.1 → 0.33.0

package/ts/src/observability/inspectLedger.ts

@@ -0,0 +1,329 @@
+// Ledger introspection READS (CV22.DS7.TS4 plateau 2).
+//
+// Port of `inspect llm-calls` and `inspect embedding-provenance` from
+// `src/memory/cli/inspect.py`, over the summary query DS8 already ported
+// (`getLlmCallSummary`) plus the two reads this plateau adds.
+//
+// MEASURED, and none of it is visible from reading the modules:
+//
+//   * these two leaves ARE argparse -- a bad `--limit` exits **2** with usage
+//     on stderr -- while every leaf in the catalog family (plateau 1) exits 1
+//     with usage on stdout. Both classes live under `inspect`;
+//   * `--session` and `--since` are applied by the CLI *after* the store's
+//     `LIMIT`, so `--session X --limit 3` can report "no rows" while
+//     `--session X` alone finds one. Reproduced, not repaired;
+//   * `role` and `model` are NOT NULL in the schema, so the renderer's
+//     `or "?"` fallback is reachable only through an EMPTY STRING;
+//   * the role column is padded to 18 with `{:<18}` and NOT truncated, so
+//     `journal_classification` overflows and misaligns its own row;
+//   * prompts and responses are cut at 200 CODE POINTS after `strip()`, and
+//     printed with `!r`. A UTF-16 cut halves an astral character on the
+//     boundary; the corpus stages exactly that character at index 199.
+
+import type { Database } from "#db/database.ts";
+import { pyRepr, sortByCodePoint } from "#util/pythonText.ts";
+import { getLlmCallSummary, type LlmCallSummary } from "./llmCalls.ts";
+
+export interface LlmCallRow {
+  id: string;
+  role: string;
+  model: string;
+  prompt: string;
+  response: string;
+  promptTokens: number | null;
+  completionTokens: number | null;
+  latencyMs: number | null;
+  costUsd: number | null;
+  conversationId: string | null;
+  sessionId: string | null;
+  calledAt: string;
+}
+
+/** Port of `Store.get_llm_calls`: newest first, filtered in SQL, then LIMIT. */
+export function getLlmCalls(
+  db: Database,
+  options: { conversationId?: string | null; role?: string | null; limit?: number } = {},
+): LlmCallRow[] {
+  const clauses: string[] = [];
+  const params: Array<string | number> = [];
+  if (options.conversationId) {
+    clauses.push("conversation_id = ?");
+    params.push(options.conversationId);
+  }
+  if (options.role) {
+    clauses.push("role = ?");
+    params.push(options.role);
+  }
+  const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+  params.push(options.limit ?? 50);
+  const rows = db
+    .prepare(
+      `SELECT id, role, model, prompt, response,
+              prompt_tokens, completion_tokens, latency_ms, cost_usd,
+              conversation_id, session_id, called_at
+       FROM llm_calls
+       ${where}
+       ORDER BY called_at DESC
+       LIMIT ?`,
+    )
+    .all(...params);
+  return rows.map((row) => ({
+    id: String(row.id ?? ""),
+    role: String(row.role ?? ""),
+    model: String(row.model ?? ""),
+    prompt: String(row.prompt ?? ""),
+    response: String(row.response ?? ""),
+    promptTokens: row.prompt_tokens === null ? null : Number(row.prompt_tokens),
+    completionTokens: row.completion_tokens === null ? null : Number(row.completion_tokens),
+    latencyMs: row.latency_ms === null ? null : Number(row.latency_ms),
+    costUsd: row.cost_usd === null ? null : Number(row.cost_usd),
+    conversationId: row.conversation_id === null ? null : String(row.conversation_id),
+    sessionId: row.session_id === null ? null : String(row.session_id),
+    calledAt: String(row.called_at ?? ""),
+  }));
+}
+
+/**
+ * Port of `Store.count_memories_by_embedding_model`.
+ *
+ * Aggregated in TypeScript rather than in SQL, as Python does and for the same
+ * reason: a legacy or malformed `metadata` degrades into the unknown bucket
+ * instead of raising. Sorted by descending count, then by Python's
+ * `str(model)` -- which renders the unknown bucket as the string `None`, so it
+ * sorts before any lowercase model name on a tie.
+ */
+export function countMemoriesByEmbeddingModel(db: Database): Array<[string | null, number]> {
+  const rows = db.prepare("SELECT metadata FROM memories WHERE embedding IS NOT NULL").all();
+  const counts = new Map<string | null, number>();
+  for (const row of rows) {
+    let model: string | null = null;
+    const metadata = row.metadata;
+    if (metadata) {
+      try {
+        const parsed = JSON.parse(String(metadata));
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+          const value = (parsed as Record<string, unknown>).embedding_model;
+          model = typeof value === "string" ? value : null;
+        }
+      } catch {
+        model = null;
+      }
+    }
+    counts.set(model, (counts.get(model) ?? 0) + 1);
+  }
+  const entries = [...counts.entries()];
+  const keyOf = (model: string | null): string => (model === null ? "None" : model);
+  const order = sortByCodePoint(entries.map(([model]) => keyOf(model)));
+  return entries.sort((left, right) => {
+    if (left[1] !== right[1]) return right[1] - left[1];
+    return order.indexOf(keyOf(left[0])) - order.indexOf(keyOf(right[0]));
+  });
+}
+
+/** Python `f"{cost:.6f}"`. */
+function formatCost(cost: number): string {
+  return cost.toFixed(6);
+}
+
+/** Port of `_fmt_summary_cost`: an em dash for unpriced. */
+export function formatSummaryCost(cost: number | null): string {
+  return cost === null ? "—" : `~$${formatCost(cost)}`;
+}
+
+/** Python `str.ljust`, in code points. */
+function ljust(text: string, width: number): string {
+  const length = Array.from(text).length;
+  return length >= width ? text : text + " ".repeat(width - length);
+}
+
+/** Python `text[:limit]` -- CODE POINTS, not UTF-16 units. */
+function sliceCodePoints(text: string, limit: number): string {
+  return Array.from(text).slice(0, limit).join("");
+}
+
+const NO_ROWS = "(no llm_calls rows match the given filters)\n";
+
+/** Port of the row-listing half of `cmd_inspect_llm_calls`. */
+export function renderLlmCallRows(rows: readonly LlmCallRow[]): string {
+  if (rows.length === 0) return NO_ROWS;
+  const lines = [`=== llm_calls (${rows.length} row${rows.length !== 1 ? "s" : ""}) ===`];
+  for (const row of rows) {
+    const calledAt = sliceCodePoints(row.calledAt, 19).replace("T", " ");
+    const latency = row.latencyMs === null ? "?ms" : `${row.latencyMs}ms`;
+    const conversation = sliceCodePoints(row.conversationId ?? "", 8) || "—";
+    const cost = row.costUsd === null ? "$—" : `~$${formatCost(row.costUsd)}`;
+    lines.push("");
+    lines.push(`[${calledAt}] ${row.role || "?"} | ${row.model || "?"}`);
+    lines.push(
+      `  id:${sliceCodePoints(row.id, 8)}  conv:${conversation}  ` +
+        `${row.promptTokens ?? 0}→${row.completionTokens ?? 0} tokens  ${latency}  ${cost}`,
+    );
+    lines.push(`  prompt:   ${pyRepr(sliceCodePoints(row.prompt.trim(), 200))}`);
+    lines.push(`  response: ${pyRepr(sliceCodePoints(row.response.trim(), 200))}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/** Port of `_print_llm_call_summary`. */
+export function renderLlmCallSummary(summary: LlmCallSummary, since: string | null): string {
+  if (summary.total.calls === 0) return NO_ROWS;
+  const scope = since ? ` since ${since}` : "";
+  const lines = [`=== llm_calls summary${scope} ===`];
+  const block = (title: string, buckets: readonly LlmCallSummary["byRole"][number][]): void => {
+    lines.push("");
+    lines.push(title);
+    for (const bucket of buckets) {
+      const unpriced = bucket.unpriced ? `  (${bucket.unpriced} unpriced)` : "";
+      // `{:<18}` pads but never truncates: a longer role overflows the column.
+      lines.push(
+        `  ${ljust(bucket.bucket, 18)} ${String(bucket.calls).padStart(5)} calls  ` +
+          `${bucket.promptTokens}→${bucket.completionTokens} tokens  ` +
+          `${formatSummaryCost(bucket.costUsd)}${unpriced}`,
+      );
+    }
+  };
+  block("By role:", summary.byRole);
+  block("By week:", summary.byWeek);
+  const unpriced = summary.total.unpriced ? `  (${summary.total.unpriced} unpriced)` : "";
+  lines.push("");
+  lines.push(
+    `TOTAL  ${summary.total.calls} calls  ` +
+      `${summary.total.promptTokens}→${summary.total.completionTokens} tokens  ` +
+      `${formatSummaryCost(summary.total.costUsd)}${unpriced}`,
+  );
+  return `${lines.join("\n")}\n`;
+}
+
+/** Port of `render_embedding_provenance`. */
+export function renderEmbeddingProvenance(
+  distribution: ReadonlyArray<readonly [string | null, number]>,
+): string {
+  const total = distribution.reduce((sum, [, count]) => sum + count, 0);
+  if (total === 0) return "(no stored memory vectors)";
+  const lines = [`=== embedding provenance (${total} memory vector${total !== 1 ? "s" : ""}) ===`];
+  for (const [model, count] of distribution) {
+    lines.push(`  ${String(count).padStart(6)}  ${model ? model : "unknown (pre-provenance)"}`);
+  }
+  return lines.join("\n");
+}
+
+export interface LedgerCommandResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+interface LlmCallOptions {
+  conversationId: string | null;
+  sessionId: string | null;
+  role: string | null;
+  since: string | null;
+  limit: number;
+  summary: boolean;
+}
+
+/**
+ * The argparse-class refusal for these two leaves: exit 2, stderr, and a
+ * one-line TypeScript message rather than argparse's usage block.
+ *
+ * Deliberate, and the same recorded divergence US8 pinned: argparse wraps its
+ * usage to the terminal's `COLUMNS`, so the "byte-identical" text would only
+ * be byte-identical at the width the golden was generated with. The graded
+ * contract is the input set, the stream, and the exit code.
+ */
+function usageError(message: string): LedgerCommandResult {
+  return { stdout: "", stderr: `Mirror TS inspect: ${message}\n`, exitCode: 2 };
+}
+
+const LLM_CALL_VALUE_OPTIONS = new Map<string, keyof LlmCallOptions>([
+  ["--conversation", "conversationId"],
+  ["--session", "sessionId"],
+  ["--role", "role"],
+  ["--since", "since"],
+]);
+
+function parseLlmCallArgv(argv: readonly string[]): LlmCallOptions | LedgerCommandResult {
+  const options: LlmCallOptions = {
+    conversationId: null,
+    sessionId: null,
+    role: null,
+    since: null,
+    limit: 20,
+    summary: false,
+  };
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index] as string;
+    if (token === "--summary") continue;
+    if (token === "--mirror-home") {
+      if (argv[index + 1] === undefined)
+        return usageError("argument --mirror-home: expected one argument");
+      index += 1;
+      continue;
+    }
+    if (token === "--limit") {
+      const value = argv[index + 1];
+      if (value === undefined) return usageError("argument --limit: expected one argument");
+      if (!/^[+-]?\d+$/.test(value.trim())) {
+        return usageError(`argument --limit: invalid int value: ${pyRepr(value)}`);
+      }
+      options.limit = Number.parseInt(value, 10);
+      index += 1;
+      continue;
+    }
+    const field = LLM_CALL_VALUE_OPTIONS.get(token);
+    if (field === undefined) return usageError(`unrecognized arguments: ${token}`);
+    const value = argv[index + 1];
+    if (value === undefined) return usageError(`argument ${token}: expected one argument`);
+    (options[field] as string | null) = value;
+    index += 1;
+  }
+  options.summary = argv.includes("--summary");
+  return options;
+}
+
+/** Port of `cmd_inspect_llm_calls`, both faces. */
+export function runInspectLlmCalls(db: Database, argv: readonly string[]): LedgerCommandResult {
+  const parsed = parseLlmCallArgv(argv);
+  if ("stdout" in parsed) return parsed;
+
+  if (parsed.summary) {
+    const summary = getLlmCallSummary(db, parsed.since ? { since: parsed.since } : {});
+    return { stdout: renderLlmCallSummary(summary, parsed.since), stderr: "", exitCode: 0 };
+  }
+
+  let rows = getLlmCalls(db, {
+    conversationId: parsed.conversationId,
+    role: parsed.role,
+    limit: parsed.limit,
+  });
+  // AFTER the store's LIMIT, exactly as Python does it.
+  if (parsed.sessionId) rows = rows.filter((row) => row.sessionId === parsed.sessionId);
+  if (parsed.since) {
+    const since = parsed.since;
+    rows = rows.filter((row) => (row.calledAt || "") >= since);
+  }
+  return { stdout: renderLlmCallRows(rows), stderr: "", exitCode: 0 };
+}
+
+/** Port of `cmd_inspect_embedding_provenance`. */
+export function runInspectEmbeddingProvenance(
+  db: Database,
+  argv: readonly string[],
+): LedgerCommandResult {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index] as string;
+    if (token === "--mirror-home") {
+      if (argv[index + 1] === undefined) {
+        return usageError("argument --mirror-home: expected one argument");
+      }
+      index += 1;
+      continue;
+    }
+    return usageError(`unrecognized arguments: ${token}`);
+  }
+  return {
+    stdout: `${renderEmbeddingProvenance(countMemoriesByEmbeddingModel(db))}\n`,
+    stderr: "",
+    exitCode: 0,
+  };
+}

package/ts/src/observability/ledgerHooks.ts

@@ -0,0 +1,126 @@
+/**
+ * The two `llm_calls` ledger hooks every provider-crossing leaf wires
+ * (CV22.DS8.US3).
+ *
+ * Python has one authority for this — `build_llm_logger(store, role=...)` —
+ * and every call site passes through it. TypeScript grew three hand-written
+ * copies instead (search, extraction, the close tail), and they did not stay
+ * equal: US1 priced the search embedding row and left extraction's unpriced,
+ * which only surfaced when a live smoke run reported 7 of 10 rows priced. US3
+ * would have added six more copies.
+ *
+ * So: one builder per shape, options for what genuinely differs between call
+ * sites (role, conversation/session attribution, the pipeline's clock, an
+ * explicit env for the model pins), and pricing that cannot be forgotten
+ * because it is not a per-call-site decision any more.
+ *
+ * What every row here shares with Python's logger:
+ *
+ * - **bodies are withheld** unless `MEMORY_LOG_LLM_CALLS=full`, which
+ *   `logLlmCall` already enforces;
+ * - **cost is the static estimate** from the one cost authority. A chat or
+ *   embedding call has no generation id to fetch a real cost for, so the
+ *   estimate IS the cost of record. Consult is the exception and logs
+ *   directly: it fetches a real figure and falls back to the estimate;
+ * - **an unknown model prices to `null`**, never `0`, so unpriced spend stays
+ *   visibly unpriced;
+ * - **a failed round trip still lands a row.** No usage comes back, so it is
+ *   unpriced — but money may already have been spent, and a vanished row
+ *   would hide it.
+ *
+ * Under replay no usage comes back either, so every row this writes is
+ * unpriced and every existing golden is unchanged.
+ */
+
+import type { StatementRunner } from "#db/database.ts";
+import { logLlmCall } from "#observability/llmCalls.ts";
+import {
+  type ModelPinOptions,
+  resolveEmbeddingModel,
+  resolveExtractionModel,
+} from "#providers/config.ts";
+import { computeCost } from "#providers/cost.ts";
+import type { EmbeddingAttemptInfo } from "#providers/embedding.ts";
+import type { LlmResponse } from "#providers/llm.ts";
+
+export interface LedgerContext {
+  /**
+   * The orchestration's clock, not the wall clock: an injected `now` must
+   * stamp every row the pipeline writes, the ledger included.
+   */
+  now?: () => string;
+  conversationId?: string | null;
+  sessionId?: string | null;
+  /** Explicit env for the model pins, when the caller holds one. */
+  env?: Record<string, string | undefined>;
+}
+
+/** What a chat call reports back to the ledger. */
+export type ChatLedgerHook = (response: LlmResponse, prompt: string) => void;
+
+/**
+ * One priced row per successful chat call, as Python's `build_llm_logger`
+ * writes it. `model` echoes the response's model, falling back to the
+ * extraction pin — which is what Python logs.
+ */
+export function chatLedgerHook(
+  db: StatementRunner,
+  role: string,
+  context: LedgerContext = {},
+): ChatLedgerHook {
+  const pins: ModelPinOptions = context.env ? { env: context.env } : {};
+  return (response, prompt) => {
+    const model = response.model ?? resolveExtractionModel(pins);
+    logLlmCall(
+      db,
+      {
+        role,
+        model,
+        prompt,
+        response: response.content,
+        promptTokens: response.promptTokens ?? null,
+        completionTokens: response.completionTokens ?? null,
+        latencyMs: response.latencyMs ?? null,
+        costUsd: computeCost(
+          model,
+          response.promptTokens ?? null,
+          response.completionTokens ?? null,
+        ),
+        conversationId: context.conversationId ?? null,
+        sessionId: context.sessionId ?? null,
+      },
+      context.now ? { now: context.now } : {},
+    );
+  };
+}
+
+/**
+ * One row per embedding ROUND TRIP, wired to `generateEmbeddingSafely`'s
+ * `onAttempt`. "A vector is not text", so `response` is always empty; the
+ * input text rides the same body-withholding rule as every other row.
+ */
+export function embeddingLedgerHook(
+  db: StatementRunner,
+  context: LedgerContext = {},
+): (info: EmbeddingAttemptInfo) => void {
+  const pins: ModelPinOptions = context.env ? { env: context.env } : {};
+  return (info) => {
+    const model = resolveEmbeddingModel(pins);
+    logLlmCall(
+      db,
+      {
+        role: "embedding",
+        model,
+        prompt: info.text,
+        response: "",
+        latencyMs: info.latencyMs,
+        promptTokens: info.promptTokens,
+        // An embedding has no completion side; Python prices it the same way.
+        costUsd: computeCost(model, info.promptTokens, null),
+        conversationId: context.conversationId ?? null,
+        sessionId: context.sessionId ?? null,
+      },
+      context.now ? { now: context.now } : {},
+    );
+  };
+}

package/ts/src/observability/llmCalls.ts

@@ -0,0 +1,154 @@
+/**
+ * LLM call observability logging (AI-09, CV9.E2.S13/S14), scoped to the
+ * consult path only -- see CR040 plan for why the broader Python
+ * `build_llm_logger` six-call-site retrofit (extraction, task-extraction,
+ * consolidation, shadow, journal) is explicitly out of scope here.
+ *
+ * Deliberately does NOT port `compute_cost`/`MODEL_PRICES`: consult always
+ * logs the real fetched generation cost, never a static per-token estimate --
+ * none of consult's models are in Python's 2-entry price table either.
+ */
+
+import type { Database, StatementRunner } from "#db/database.ts";
+import { type LogLlmCallsMode, resolveLogLlmCallsMode } from "#providers/config.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+
+export interface LogLlmCallInput {
+  role: string;
+  model: string;
+  prompt: string;
+  response: string;
+  promptTokens?: number | null;
+  completionTokens?: number | null;
+  latencyMs?: number | null;
+  costUsd?: number | null;
+  conversationId?: string | null;
+  sessionId?: string | null;
+}
+
+export interface LogLlmCallOptions {
+  mode?: LogLlmCallsMode;
+  now?: () => string;
+  id?: () => string;
+}
+
+/**
+ * Insert one row into `llm_calls`, mirroring Python's `log_llm_call` column
+ * order exactly. Fail-soft by design: a logging failure is swallowed, never
+ * propagated -- "observability must never break the pipeline it observes"
+ * (the same principle behind Python's build_llm_logger try/except).
+ *
+ * In `metadata` mode (the default) prompt/response are written as empty
+ * strings, never the real bodies -- consult's prompt carries identity
+ * context, so withholding it by default is a security property, not a
+ * formatting choice. Only explicit `full` mode persists bodies.
+ */
+export function logLlmCall(
+  db: StatementRunner,
+  input: LogLlmCallInput,
+  options: LogLlmCallOptions = {},
+): void {
+  const mode = options.mode ?? resolveLogLlmCallsMode();
+  if (mode === "off") return;
+  const withBodies = mode === "full";
+  try {
+    db.prepare(
+      `INSERT INTO llm_calls (
+        id, role, model, prompt, response,
+        prompt_tokens, completion_tokens, latency_ms, cost_usd,
+        conversation_id, session_id, called_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    ).run(
+      (options.id ?? newId)(),
+      input.role,
+      input.model,
+      withBodies ? input.prompt : "",
+      withBodies ? input.response : "",
+      input.promptTokens ?? null,
+      input.completionTokens ?? null,
+      input.latencyMs ?? null,
+      input.costUsd ?? null,
+      input.conversationId ?? null,
+      input.sessionId ?? null,
+      (options.now ?? nowIso)(),
+    );
+  } catch {
+    // Fail-soft: never let observability break the caller.
+  }
+}
+
+export interface LlmCallSummaryBucket {
+  bucket: string;
+  calls: number;
+  promptTokens: number;
+  completionTokens: number;
+  costUsd: number | null;
+  unpriced: number;
+}
+
+export interface LlmCallSummary {
+  byRole: LlmCallSummaryBucket[];
+  byWeek: LlmCallSummaryBucket[];
+  total: LlmCallSummaryBucket;
+}
+
+/**
+ * Aggregate spend by role and by week, plus an overall total. Mirrors
+ * Python's `get_llm_call_summary`: `SUM(cost_usd)` skips NULLs, so an
+ * all-unpriced bucket reports `costUsd: null` with a non-zero `unpriced`
+ * count -- unpriced spend stays visibly unpriced, never summed as 0.
+ *
+ * Shipped without a CLI renderer (no TS `inspect` command exists -- see
+ * CR040 plan) because it operates on real data once logLlmCall ships, and is
+ * independently tested; an unconsumed but tested query is not dead code.
+ */
+export function getLlmCallSummary(
+  // A READ: widened from `WritableDatabase` at CV22.DS7.TS4 plateau 2, when
+  // `inspect llm-calls --summary` gave it its first caller and that caller
+  // opens the database read-only.
+  db: Database,
+  options: { since?: string } = {},
+): LlmCallSummary {
+  const where = options.since ? "WHERE called_at >= ?" : "";
+  const params = options.since ? [options.since] : [];
+
+  const aggregate = (bucketExpr: string, order: string): LlmCallSummaryBucket[] => {
+    const rows = db
+      .prepare(
+        `SELECT ${bucketExpr} AS bucket,
+                COUNT(*) AS calls,
+                COALESCE(SUM(prompt_tokens), 0) AS prompt_tokens,
+                COALESCE(SUM(completion_tokens), 0) AS completion_tokens,
+                SUM(cost_usd) AS cost_usd,
+                SUM(CASE WHEN cost_usd IS NULL THEN 1 ELSE 0 END) AS unpriced
+         FROM llm_calls
+         ${where}
+         GROUP BY bucket
+         ORDER BY ${order}`,
+      )
+      .all(...params);
+    return rows.map((row) => ({
+      bucket: String(row.bucket),
+      calls: Number(row.calls),
+      promptTokens: Number(row.prompt_tokens),
+      completionTokens: Number(row.completion_tokens),
+      costUsd: row.cost_usd === null ? null : Number(row.cost_usd),
+      unpriced: Number(row.unpriced),
+    }));
+  };
+
+  const byRole = aggregate("role", "bucket");
+  const byWeek = aggregate("strftime('%Y-W%W', called_at)", "bucket DESC");
+
+  const priced = byRole.map((b) => b.costUsd).filter((cost): cost is number => cost !== null);
+  const total: LlmCallSummaryBucket = {
+    bucket: "TOTAL",
+    calls: byRole.reduce((sum, b) => sum + b.calls, 0),
+    promptTokens: byRole.reduce((sum, b) => sum + b.promptTokens, 0),
+    completionTokens: byRole.reduce((sum, b) => sum + b.completionTokens, 0),
+    costUsd: priced.length > 0 ? priced.reduce((sum, cost) => sum + cost, 0) : null,
+    unpriced: byRole.reduce((sum, b) => sum + b.unpriced, 0),
+  };
+
+  return { byRole, byWeek, total };
+}

package/ts/src/persona/detectPersona.ts

@@ -0,0 +1,81 @@
+// `detect-persona` parity port (CV22.DS2.US2).
+//
+// A faithful TypeScript port of Python `IdentityService.detect_persona`
+// (`src/memory/services/identity.py`). The router is pure and deterministic — it
+// reads DB-backed routing metadata only, no clock and no embeddings — so parity
+// is exact behavioral equality, not the ordered-id-with-float-drift metric the
+// hybrid ranker uses.
+//
+// This module scores an already-decoded persona routing table; reading the
+// `persona` identity rows out of the SQLite seam belongs to the caller (the DS3
+// front door and the real-DB-copy harness), keeping this the pure decision core.
+
+/** One persona's routing table, as parsed from `identity.metadata`. */
+export interface PersonaRoutingRow {
+  key: string;
+  routing_keywords: readonly string[];
+}
+
+/** A routing decision: the persona, its hit count, and the match kind. */
+export interface PersonaMatch {
+  key: string;
+  score: number;
+  matchType: string;
+}
+
+/**
+ * Normalize routing text, mirroring Python `_normalize_routing_text`:
+ * lowercase, turn `-`/`_` into spaces, replace any run of non-alphanumeric,
+ * non-whitespace characters with a space, then collapse whitespace and trim.
+ *
+ * JS `\s` and Python `re`'s `\s` both match Unicode whitespace, and ASCII
+ * `[a-z0-9]` is identical across engines, so the synthetic (ASCII) corpus is
+ * reproduced exactly.
+ */
+export function normalizeRoutingText(text: string): string {
+  const lowered = text.toLowerCase().replaceAll("-", " ").replaceAll("_", " ");
+  const normalized = lowered.replace(/[^a-z0-9\s]+/g, " ");
+  return normalized.replace(/\s+/g, " ").trim();
+}
+
+/**
+ * Detect likely personas from routing metadata, reproducing the Python oracle.
+ *
+ * A single-word keyword must match a whole query token (set membership); a
+ * multi-word keyword (including one that becomes multi-word after normalization,
+ * e.g. `savings-plan` -> `savings plan`) matches as a raw substring of the
+ * normalized query — no word boundary, exactly like Python's `in`. Personas with
+ * `hitCount >= threshold` are returned, sorted by score descending then key
+ * ascending, matching `matches.sort(key=lambda i: (-i[1], i[0]))`.
+ */
+export function detectPersona(
+  query: string,
+  personas: readonly PersonaRoutingRow[],
+  threshold = 1.0,
+): PersonaMatch[] {
+  const normalizedQuery = normalizeRoutingText(query);
+  if (!normalizedQuery) return [];
+
+  const queryTokens = new Set(normalizedQuery.split(" ").filter(Boolean));
+  const matches: PersonaMatch[] = [];
+
+  for (const persona of personas) {
+    let hitCount = 0;
+    for (const keyword of persona.routing_keywords) {
+      if (typeof keyword !== "string") continue;
+      const normalizedKeyword = normalizeRoutingText(keyword);
+      if (!normalizedKeyword) continue;
+      if (normalizedKeyword.includes(" ")) {
+        if (normalizedQuery.includes(normalizedKeyword)) hitCount += 1;
+      } else if (queryTokens.has(normalizedKeyword)) {
+        hitCount += 1;
+      }
+    }
+    if (hitCount >= threshold) {
+      matches.push({ key: persona.key, score: hitCount, matchType: "keyword" });
+    }
+  }
+
+  matches.sort((a, b) => b.score - a.score || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  return matches;
+}