mirror-mind 0.0.1 → 0.33.0

package/ts/src/planning/promptAssembly.ts

@@ -0,0 +1,111 @@
+/**
+ * Prompt assembly for the CV22.DS7.US11 content & planning tail.
+ *
+ * Each function reproduces, byte for byte, the string Python sends for its
+ * role. US10 established why this matters: replay resolves a fixture by role
+ * alone, so a TS prompt that drifted from the oracle would replay happily and
+ * the divergence would only surface at the DS8 live cutover, against real
+ * users. `ts/test/goldens/prompt-assembly.golden.json` pins a SHA-256 of each
+ * assembled prompt, generated from the Python source.
+ *
+ * Temperatures live here too, unused under replay, because DS8's live mode
+ * must inherit them rather than rediscover them: journal 0.3, week plan 0.2,
+ * descriptor 0.2.
+ */
+
+import {
+  DESCRIPTOR_PROMPT,
+  JOURNAL_CLASSIFICATION_PROMPT,
+  WEEK_PLAN_PROMPT,
+} from "#extraction/prompts.ts";
+import { pyFormat, sliceCodePoints } from "#util/pythonText.ts";
+
+/** Python's `temperature=` per role, carried for the DS8 live cutover. */
+export const JOURNAL_TEMPERATURE = 0.3;
+export const WEEK_PLAN_TEMPERATURE = 0.2;
+export const DESCRIPTOR_TEMPERATURE = 0.2;
+
+/** `JOURNAL_CLASSIFICATION_PROMPT + content` (`classify_journal_entry`). */
+export function buildJournalClassificationPrompt(content: string): string {
+  return JOURNAL_CLASSIFICATION_PROMPT + content;
+}
+
+/** `DESCRIPTOR_PROMPT.format(layer=, key=) + content` (`generate_descriptor`). */
+export function buildDescriptorPrompt(content: string, layer: string, key: string): string {
+  return pyFormat(DESCRIPTOR_PROMPT, { layer, key }) + content;
+}
+
+export interface WeekPlanJourneyContext {
+  /** The journey slug. */
+  slug: string;
+  /**
+   * The journey's identity content, ALREADY truncated to 200 code points by
+   * `TaskService.ingest_week_plan`. This function truncates again to 100, as
+   * `extract_week_plan` does -- the description passes through two different
+   * caps and only the second one reaches the model.
+   */
+  description: string;
+}
+
+/**
+ * Python's `journeys_text`: one `- **slug**: description[:100]` line per
+ * journey, or the literal `(no active journeys)` when the list is empty.
+ *
+ * The slice is by CODE POINT (`sliceCodePoints`), not UTF-16 unit -- the divergence
+ * class US10 found in `generateTitle`. A journey description with an emoji or
+ * a non-BMP character before position 100 would otherwise cut differently in
+ * the two engines and silently change the prompt bytes.
+ */
+export function buildWeekPlanJourneysText(journeys: readonly WeekPlanJourneyContext[]): string {
+  if (journeys.length === 0) return "(no active journeys)";
+  return journeys.map((j) => `- **${j.slug}**: ${sliceCodePoints(j.description, 100)}`).join("\n");
+}
+
+export interface WeekPlanClock {
+  /** `now.strftime("%Y-%m-%d")`. */
+  today: string;
+  /** `["Monday", ... "Sunday"][now.weekday()]` — Monday-first, unlike JS. */
+  weekday: string;
+}
+
+const PY_WEEKDAYS = [
+  "Monday",
+  "Tuesday",
+  "Wednesday",
+  "Thursday",
+  "Friday",
+  "Saturday",
+  "Sunday",
+] as const;
+
+/**
+ * Python's reference date, from an injected clock.
+ *
+ * `datetime.now()` is LOCAL time and `weekday()` is Monday-indexed, while
+ * JavaScript's `getDay()` is Sunday-indexed. Both are reproduced here rather
+ * than approximated, and the clock is injected so the golden can freeze it --
+ * the prompt embeds the date, so an assembly that read the real clock would
+ * fail the digest on any day but the one the corpus was generated.
+ */
+export function weekPlanClock(now: Date): WeekPlanClock {
+  const year = String(now.getFullYear()).padStart(4, "0");
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  const pythonWeekday = (now.getDay() + 6) % 7;
+  return { today: `${year}-${month}-${day}`, weekday: PY_WEEKDAYS[pythonWeekday] };
+}
+
+/** `WEEK_PLAN_PROMPT.format(today=, weekday=, journeys=) + text` (`extract_week_plan`). */
+export function buildWeekPlanPrompt(
+  text: string,
+  journeys: readonly WeekPlanJourneyContext[],
+  clock: WeekPlanClock,
+): string {
+  return (
+    pyFormat(WEEK_PLAN_PROMPT, {
+      today: clock.today,
+      weekday: clock.weekday,
+      journeys: buildWeekPlanJourneysText(journeys),
+    }) + text
+  );
+}

package/ts/src/planning/weekPending.ts

@@ -0,0 +1,81 @@
+/**
+ * The `week plan` → `week save` pending-file contract (CV22.DS7.US11).
+ *
+ * Python writes proposed weekly items to a fixed path in the system temp
+ * directory and `week save` consumes them. During the transition either engine
+ * may write the file and the other may read it, so the shape here is the
+ * contract, not an implementation detail — `ts/parity/week_pending_cross_engine.py`
+ * proves both directions on a copy.
+ *
+ * Parity notes:
+ *   - Python: `Path(tempfile.gettempdir()) / "mm_week_pending.json"`, resolved
+ *     at import time. Node's `os.tmpdir()` resolves the same TMPDIR on macOS
+ *     and Linux; the smoke sets TMPDIR explicitly so both engines agree.
+ *   - Python writes `json.dumps(pending, ensure_ascii=False, indent=2)` with NO
+ *     trailing newline. `writePendingItems` matches, because the cross-engine
+ *     proof compares bytes.
+ *   - Every field except `title` and `due_date` is optional and defaults to
+ *     null, mirroring `ExtractedWeekItem`.
+ */
+
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface WeekPendingItem {
+  title: string;
+  due_date: string;
+  scheduled_at: string | null;
+  time_hint: string | null;
+  journey: string | null;
+  context: string | null;
+}
+
+/** Python's module-level `PENDING_FILE`, resolved the same way. */
+export function defaultPendingPath(): string {
+  return join(tmpdir(), "mm_week_pending.json");
+}
+
+function optionalString(value: unknown): string | null {
+  return typeof value === "string" ? value : null;
+}
+
+/**
+ * Read the pending file, or `null` when it does not exist.
+ *
+ * Python distinguishes "no file" (prints `No pending items to save.`) from "an
+ * empty list" (prints `✅ 0 items saved:` and still unlinks), so the absent
+ * case must stay distinguishable from the empty one.
+ */
+export function readPendingItems(path: string): WeekPendingItem[] | null {
+  let raw: string;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+  const parsed: unknown = JSON.parse(raw);
+  if (!Array.isArray(parsed)) return [];
+  return parsed.map((entry) => {
+    const record = (entry ?? {}) as Record<string, unknown>;
+    return {
+      title: typeof record.title === "string" ? record.title : "",
+      due_date: typeof record.due_date === "string" ? record.due_date : "",
+      scheduled_at: optionalString(record.scheduled_at),
+      time_hint: optionalString(record.time_hint),
+      journey: optionalString(record.journey),
+      context: optionalString(record.context),
+    };
+  });
+}
+
+/** Write the pending file in Python's exact serialization (no trailing newline). */
+export function writePendingItems(path: string, items: WeekPendingItem[]): void {
+  writeFileSync(path, JSON.stringify(items, null, 2), "utf8");
+}
+
+/** Python's `PENDING_FILE.unlink(missing_ok=True)`. */
+export function removePendingFile(path: string): void {
+  rmSync(path, { force: true });
+}

package/ts/src/planning/weekPlan.ts

@@ -0,0 +1,183 @@
+/**
+ * `week plan` — CV22.DS7.US11 plateau 4.
+ *
+ * Extracts temporal items from free text through the model, warns about
+ * near-duplicates already in `tasks`, writes the pending file `week save`
+ * consumes, and prints a JSON report.
+ *
+ * Graded by `ts/test/goldens/week-plan.golden.json`. Three Python behaviours
+ * the corpus pins, each of which a tidier implementation would get wrong:
+ *
+ *   - **The similarity query is `LIKE '%fragment%'`** — a CONTAINS match over
+ *     the first 20 code points of the title, with NO wildcard escaping and the
+ *     journey argument NOT passed. A `%` or `_` in a title is therefore a live
+ *     wildcard that over-matches. The US11 Plan review corrected an earlier
+ *     description of this as a prefix query; the SQL is ported as written.
+ *   - **A malformed item is skipped, not fatal.** Python wraps
+ *     `ExtractedWeekItem(**item_data)` in `try/except Exception: continue`, so
+ *     one bad entry does not lose its siblings.
+ *   - **The report and the pending file are different shapes.** The report may
+ *     carry a `warning` key; the pending file never does, and its bytes are
+ *     `json.dumps(..., ensure_ascii=False, indent=2)` with no trailing newline.
+ */
+
+import type { Database, WritableDatabase } from "#db/database.ts";
+import {
+  buildWeekPlanPrompt,
+  type WeekPlanClock,
+  type WeekPlanJourneyContext,
+} from "#planning/promptAssembly.ts";
+import { type WeekPendingItem, writePendingItems } from "#planning/weekPending.ts";
+import { sliceCodePoints } from "#util/pythonText.ts";
+
+export interface ExtractedWeekItem {
+  title: string;
+  due_date: string;
+  scheduled_at: string | null;
+  time_hint: string | null;
+  journey: string | null;
+  context: string | null;
+}
+
+/** Python's `ExtractedWeekItem(**item_data)` inside `try/except: continue`. */
+export function parseExtractedWeekItems(parsed: unknown): ExtractedWeekItem[] {
+  if (!Array.isArray(parsed)) return [];
+  const items: ExtractedWeekItem[] = [];
+  for (const entry of parsed) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) continue;
+    const record = entry as Record<string, unknown>;
+    // `title` and `due_date` have no defaults on the dataclass, so their
+    // absence raises and the item is skipped. Every other field defaults to
+    // None. An UNKNOWN key also raises (unexpected keyword argument).
+    const known = new Set(["title", "due_date", "scheduled_at", "time_hint", "journey", "context"]);
+    if (Object.keys(record).some((key) => !known.has(key))) continue;
+    if (typeof record.title !== "string" || typeof record.due_date !== "string") continue;
+    // `ExtractedWeekItem` is a pydantic model with `extra="forbid"` and no
+    // str coercion, so a PRESENT optional field of the wrong type raises and
+    // the whole item is skipped -- it does not fall back to null.
+    const optionalKeys = ["scheduled_at", "time_hint", "journey", "context"] as const;
+    const badOptional = optionalKeys.some(
+      (key) =>
+        key in record &&
+        record[key] !== null &&
+        record[key] !== undefined &&
+        typeof record[key] !== "string",
+    );
+    if (badOptional) continue;
+    const optional = (value: unknown): string | null => (typeof value === "string" ? value : null);
+    items.push({
+      title: record.title,
+      due_date: record.due_date,
+      scheduled_at: optional(record.scheduled_at),
+      time_hint: optional(record.time_hint),
+      journey: optional(record.journey),
+      context: optional(record.context),
+    });
+  }
+  return items;
+}
+
+export interface ExistingTask {
+  id: string;
+  title: string;
+  due_date: string | null;
+  status: string;
+}
+
+/**
+ * Python `find_tasks_by_title(title_fragment)` — `LIKE '%fragment%'`, ordered
+ * by `created_at DESC`, journey filter unused by this caller.
+ *
+ * The fragment is NOT escaped, so `%` and `_` inside a title behave as SQL
+ * wildcards. Reproduced exactly: this is the query the oracle runs, and the
+ * golden pins its over-matching.
+ */
+export function findTasksByTitle(db: Database, fragment: string): ExistingTask[] {
+  return db
+    .prepare(
+      "SELECT id, title, due_date, status FROM tasks WHERE title LIKE ? ORDER BY created_at DESC",
+    )
+    .all(`%${fragment}%`) as unknown as ExistingTask[];
+}
+
+/** Python: same `due_date`, status not `done`. The FIRST match names the warning. */
+export function similarExistingTasks(db: Database, item: ExtractedWeekItem): ExistingTask[] {
+  const fragment = sliceCodePoints(item.title, 20);
+  return findTasksByTitle(db, fragment).filter(
+    (task) => task.due_date === item.due_date && task.status !== "done",
+  );
+}
+
+export interface WeekPlanDeps {
+  /** Returns the model's raw response body for the assembled prompt. */
+  complete: (prompt: string) => string;
+  /** Python's `_parse_json_response`. */
+  parseJson: (raw: string) => unknown;
+  clock: WeekPlanClock;
+  pendingPath: string;
+  print?: (text: string) => void;
+}
+
+/** Journey context exactly as `ingest_week_plan` builds it: `content[:200]`. */
+export function buildJourneyContext(db: Database): WeekPlanJourneyContext[] {
+  const rows = db
+    .prepare("SELECT key, content FROM identity WHERE layer = 'journey' ORDER BY rowid")
+    .all() as unknown as { key: string; content: string | null }[];
+  return rows.map((row) => ({
+    slug: row.key,
+    description: row.content ? sliceCodePoints(row.content, 200) : "",
+  }));
+}
+
+export interface WeekPlanResult {
+  itemCount: number;
+  wrotePendingFile: boolean;
+}
+
+export function runWeekPlan(
+  db: WritableDatabase,
+  text: string,
+  deps: WeekPlanDeps,
+): WeekPlanResult {
+  const print = deps.print ?? ((value: string) => process.stdout.write(value));
+
+  const journeys = buildJourneyContext(db);
+  const prompt = buildWeekPlanPrompt(text, journeys, deps.clock);
+  const items = parseExtractedWeekItems(deps.parseJson(deps.complete(prompt)));
+
+  if (items.length === 0) {
+    print("No temporal items found in the text.\n");
+    return { itemCount: 0, wrotePendingFile: false };
+  }
+
+  const pending: WeekPendingItem[] = [];
+  const reportItems: Record<string, unknown>[] = [];
+
+  for (const item of items) {
+    const payload: WeekPendingItem = {
+      title: item.title,
+      due_date: item.due_date,
+      scheduled_at: item.scheduled_at,
+      time_hint: item.time_hint,
+      journey: item.journey,
+      context: item.context,
+    };
+    pending.push(payload);
+
+    const reportItem: Record<string, unknown> = { ...payload };
+    const similar = similarExistingTasks(db, item);
+    if (similar.length > 0) {
+      reportItem.warning = `Similar item already exists: '${similar[0].title}'`;
+    }
+    reportItems.push(reportItem);
+  }
+
+  writePendingItems(deps.pendingPath, pending);
+  // Python: `json.dumps(output, ensure_ascii=False, indent=2)` -- NO
+  // sort_keys, so insertion order is the contract, and non-ASCII stays raw.
+  // `pythonJsonDumpsIndented` sorts keys and escapes non-ASCII, so it is the
+  // wrong helper here despite the name.
+  print(`${JSON.stringify({ items: reportItems, pending_file: deps.pendingPath }, null, 2)}\n`);
+
+  return { itemCount: items.length, wrotePendingFile: true };
+}

package/ts/src/planning/weekSave.ts

@@ -0,0 +1,117 @@
+/**
+ * `week save` — CV22.DS7.US11 plateau 1.
+ *
+ * Reads the pending file `week plan` wrote, creates one task per item with
+ * `source="week_plan"`, unlinks the file, and prints Python's receipt.
+ *
+ * This leaf crosses NO provider seam. CR068 found it recorded in `routing.ts`
+ * as "LLM-gated and reassigned to US5", which is false: `save_week_items`
+ * reads the file and calls `add_task`, already ported in DS7.US2. It therefore
+ * flips ungated, unlike its `week plan` sibling.
+ *
+ * Parity notes (pinned by `ts/test/goldens/week-save.golden.json`):
+ *   - the time suffix is `" at HH:MM"` from `scheduled_at`, ELSE
+ *     `" (time_hint)"`, else empty — `scheduled_at` wins when both are set;
+ *   - an unparseable `scheduled_at` hits Python's `except ValueError` and
+ *     yields NO suffix, while the row still stores the unparseable string;
+ *   - the file is unlinked AFTER the loop, so a mid-loop failure leaves
+ *     partial tasks and the file in place. Preserved deliberately;
+ *   - `✅ {n} items saved:` is printed even when n is 0 (empty list), but the
+ *     absent file prints `No pending items to save.` and writes nothing.
+ */
+
+import type { WritableDatabase } from "#db/database.ts";
+import {
+  defaultPendingPath,
+  readPendingItems,
+  removePendingFile,
+  type WeekPendingItem,
+} from "#planning/weekPending.ts";
+import { createTask } from "#tasks/taskStore.ts";
+import { newId, nowIso } from "#util/pyGenerators.ts";
+
+export interface WeekSaveOptions {
+  pendingPath?: string;
+  print?: (line: string) => void;
+}
+
+export interface WeekSaveResult {
+  savedCount: number;
+  hadPendingFile: boolean;
+}
+
+/**
+ * Python's `datetime.fromisoformat(scheduled_at).strftime("%H:%M")`, guarded by
+ * `except ValueError`. Node's Date parser is more permissive than
+ * `fromisoformat`, so this validates the shape explicitly rather than trusting
+ * `new Date(...)` — otherwise TS would render a time where Python renders none.
+ */
+function timeSuffix(item: WeekPendingItem): string {
+  if (item.scheduled_at) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d+)?)?$/.exec(
+      item.scheduled_at,
+    );
+    if (match) {
+      const [, year, month, day, hour, minute, second] = match;
+      const y = Number(year);
+      const mo = Number(month);
+      const d = Number(day);
+      const h = Number(hour);
+      const mi = Number(minute);
+      const sec = second === undefined ? 0 : Number(second);
+      const valid =
+        mo >= 1 &&
+        mo <= 12 &&
+        d >= 1 &&
+        d <= new Date(Date.UTC(y, mo, 0)).getUTCDate() &&
+        h <= 23 &&
+        mi <= 59 &&
+        sec <= 59;
+      if (valid) return ` at ${hour}:${minute}`;
+    }
+    return "";
+  }
+  if (item.time_hint) return ` (${item.time_hint})`;
+  return "";
+}
+
+export function runWeekSave(db: WritableDatabase, options: WeekSaveOptions = {}): WeekSaveResult {
+  const pendingPath = options.pendingPath ?? defaultPendingPath();
+  const print = options.print ?? ((line: string) => console.log(line));
+
+  const pending = readPendingItems(pendingPath);
+  if (pending === null) {
+    print("No pending items to save.");
+    return { savedCount: 0, hadPendingFile: false };
+  }
+
+  const created = pending.map((item) =>
+    createTask(
+      db,
+      {
+        title: item.title,
+        journey: item.journey ?? undefined,
+        dueDate: item.due_date ?? undefined,
+        scheduledAt: item.scheduled_at ?? undefined,
+        timeHint: item.time_hint ?? undefined,
+        context: item.context ?? undefined,
+        source: "week_plan",
+      },
+      newId(),
+      nowIso(),
+    ),
+  );
+
+  removePendingFile(pendingPath);
+
+  print(`✅ ${created.length} items saved:`);
+  created.forEach((task, index) => {
+    const item = pending[index];
+    const journey = task.journey ? ` [${task.journey}]` : "";
+    print(
+      `  ○ \`${task.id.slice(0, 8)}\` ${task.title} - ${task.due_date}${timeSuffix(item)}${journey}`,
+    );
+  });
+
+  return { savedCount: created.length, hadPendingFile: true };
+}

package/ts/src/providers/config.ts

@@ -0,0 +1,189 @@
+export type ProviderName = "openrouter";
+
+export interface ProviderConfig {
+  provider: ProviderName;
+  apiKey: string;
+  baseUrl: string;
+}
+
+export interface ProviderConfigOptions {
+  env?: Record<string, string | undefined>;
+  argv?: readonly string[];
+}
+
+const OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+const ARG_SECRET_PATTERN =
+  /^(?:--)?(?:api[-_]?key|openrouter[-_]?api[-_]?key|token|secret)(?:=|$)/i;
+
+// Model pins (AI-06, CV9.E2.S12): a deprecated pinned model would fail every
+// extraction/embedding call, and those paths fail soft -- so the pins must be
+// env-overridable to repoint a deployed instance without a release.
+export const DEFAULT_EXTRACTION_MODEL = "google/gemini-2.5-flash-lite";
+export const DEFAULT_EMBEDDING_MODEL = "openai/text-embedding-3-small";
+
+export interface ModelPinOptions {
+  env?: Record<string, string | undefined>;
+}
+
+/**
+ * Mirrors Python's `EXTRACTION_MODEL = os.getenv("MEMORY_EXTRACTION_MODEL", ...)`.
+ * Every extraction-family LLM call (extract, task-extract, curate, summary)
+ * uses this single pin -- Python has no per-role model, so TS does not invent one.
+ *
+ * Uses `??`, not `||`: matches `os.getenv(name, default)` precisely -- only
+ * absence triggers the default, an empty-string override is a real value.
+ */
+export function resolveExtractionModel(options: ModelPinOptions = {}): string {
+  const env = options.env ?? process.env;
+  return env.MEMORY_EXTRACTION_MODEL ?? DEFAULT_EXTRACTION_MODEL;
+}
+
+/**
+ * Mirrors Python's `EMBEDDING_MODEL = os.getenv("MEMORY_EMBEDDING_MODEL", ...)`.
+ * CR039 deliberately shipped no resolver here -- EmbeddingProvider.embed(text)
+ * had no model parameter to wire it into, and an unconsumed function would
+ * have been dead code. CR043 gives it a real consumer: embedding provenance
+ * (recording which model produced a stored vector) needs the *configured*
+ * embedding pin, not the extraction pin -- a different constant entirely.
+ */
+export function resolveEmbeddingModel(options: ModelPinOptions = {}): string {
+  const env = options.env ?? process.env;
+  return env.MEMORY_EMBEDDING_MODEL ?? DEFAULT_EMBEDDING_MODEL;
+}
+
+// Observability (AI-09, CV9.E2.S13): mirrors Python's MEMORY_LOG_LLM_CALLS
+// resolution exactly -- off | metadata | full, default metadata (never a
+// silent full -- bodies are opt-in only). Legacy "1" maps to "full" for
+// back-compat with Python's original boolean-flag meaning.
+export type LogLlmCallsMode = "off" | "metadata" | "full";
+
+export function resolveLogLlmCallsMode(options: ModelPinOptions = {}): LogLlmCallsMode {
+  const env = options.env ?? process.env;
+  const raw = (env.MEMORY_LOG_LLM_CALLS ?? "").trim().toLowerCase();
+  if (raw === "" || raw === "metadata") return "metadata";
+  if (raw === "1" || raw === "full") return "full";
+  return "off";
+}
+
+export class ProviderConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProviderConfigError";
+  }
+}
+
+export function resolveProviderConfig(
+  provider: ProviderName,
+  options: ProviderConfigOptions = {},
+): ProviderConfig {
+  rejectArgvSecrets(options.argv ?? []);
+  const env = options.env ?? process.env;
+  const apiKey = env.OPENROUTER_API_KEY?.trim();
+  if (!apiKey) {
+    throw new ProviderConfigError("OPENROUTER_API_KEY is not configured.");
+  }
+  return { provider, apiKey, baseUrl: OPENROUTER_BASE_URL };
+}
+
+function rejectArgvSecrets(argv: readonly string[]): void {
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index] ?? "";
+    if (ARG_SECRET_PATTERN.test(arg)) {
+      throw new ProviderConfigError("API keys must come from env/config, not argv-like inputs.");
+    }
+    const previous = argv[index - 1] ?? "";
+    if (ARG_SECRET_PATTERN.test(previous) && arg.trim().length > 0) {
+      throw new ProviderConfigError("API keys must come from env/config, not argv-like inputs.");
+    }
+  }
+}
+
+// Extraction-pipeline switches (CV22.DS7.US10 slice F). Python reads each once
+// at import; the front door resolves them per invocation from the same names
+// so a session-end under TypeScript makes the same calls Python would.
+
+/** Python `SUMMARIZE_ENABLED = os.getenv("MEMORY_SUMMARIZE", "") == "1"`. */
+export function resolveSummarizeEnabled(options: ModelPinOptions = {}): boolean {
+  const env = options.env ?? process.env;
+  return env.MEMORY_SUMMARIZE === "1";
+}
+
+/** Python `TWO_PASS_ENABLED = os.getenv("MEMORY_TWO_PASS", "") == "1"`. */
+export function resolveTwoPassEnabled(options: ModelPinOptions = {}): boolean {
+  const env = options.env ?? process.env;
+  return env.MEMORY_TWO_PASS === "1";
+}
+
+/** Python `int(os.getenv("MEMORY_MAINTENANCE_MAX_EXTRACTIONS", "10"))` (AI-05). */
+export function resolveMaintenanceMaxExtractions(options: ModelPinOptions = {}): number {
+  const env = options.env ?? process.env;
+  return parsePythonInt(env.MEMORY_MAINTENANCE_MAX_EXTRACTIONS, 10);
+}
+
+/** Python `int(os.getenv("MEMORY_EXTRACTION_MAX_ATTEMPTS", "3"))` (CV9.E2.S7). */
+export function resolveExtractionMaxAttempts(options: ModelPinOptions = {}): number {
+  const env = options.env ?? process.env;
+  return parsePythonInt(env.MEMORY_EXTRACTION_MAX_ATTEMPTS, 3);
+}
+
+/**
+ * Python `int(os.getenv(name, default))`: absence yields the default; a
+ * present value that is not an integer makes Python's import fail, so the
+ * front door fails the same way rather than silently substituting.
+ */
+function parsePythonInt(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) return fallback;
+  if (!/^\s*[+-]?\d+\s*$/.test(raw)) {
+    throw new Error(`invalid literal for int() with base 10: '${raw}'`);
+  }
+  return Number.parseInt(raw, 10);
+}
+
+/**
+ * Python `float(os.getenv(name, default))`. Same contract as `parsePythonInt`:
+ * only absence takes the default, and a present non-numeric value fails loudly
+ * instead of silently reverting to a value the operator did not ask for.
+ */
+function parsePythonFloat(raw: string | undefined, fallback: number): number {
+  if (raw === undefined) return fallback;
+  const parsed = Number(raw);
+  if (raw.trim() === "" || Number.isNaN(parsed)) {
+    throw new Error(`could not convert string to float: '${raw}'`);
+  }
+  return parsed;
+}
+
+// Per-role call bounds (AI-18, CV22.DS8.US1). Python bounds every model call at
+// client construction (`config.py` LLM_TIMEOUT_*, LLM_MAX_RETRIES) so a hung
+// provider connection cannot stall a session hook or the interactive path --
+// the OpenAI SDK default is 600s. The TS live transport carries the same bounds
+// under the same env names; only the unit changes (Python seconds -> ms for
+// AbortSignal.timeout).
+
+/** The three call classes Python bounds separately. */
+export type LlmTimeoutRole = "extraction" | "reception" | "embedding";
+
+const LLM_TIMEOUT_ENV: Readonly<Record<LlmTimeoutRole, { name: string; defaultSeconds: number }>> =
+  {
+    extraction: { name: "MEMORY_LLM_TIMEOUT_EXTRACTION", defaultSeconds: 60 },
+    reception: { name: "MEMORY_LLM_TIMEOUT_RECEPTION", defaultSeconds: 10 },
+    embedding: { name: "MEMORY_LLM_TIMEOUT_EMBEDDING", defaultSeconds: 15 },
+  };
+
+/**
+ * Milliseconds to bound one provider call of `role`, from Python's per-role
+ * second-valued pins. All three ship together even though CV22.DS8.US1 only
+ * uses `embedding`: the config surface is the same shape for US2/US3, and a
+ * half-ported timeout table is how per-role bounds quietly become one bound.
+ */
+export function resolveLlmTimeoutMs(role: LlmTimeoutRole, options: ModelPinOptions = {}): number {
+  const env = options.env ?? process.env;
+  const { name, defaultSeconds } = LLM_TIMEOUT_ENV[role];
+  return parsePythonFloat(env[name], defaultSeconds) * 1000;
+}
+
+/** Python `LLM_MAX_RETRIES = int(os.getenv("MEMORY_LLM_MAX_RETRIES", "2"))`. */
+export function resolveLlmMaxRetries(options: ModelPinOptions = {}): number {
+  const env = options.env ?? process.env;
+  return parsePythonInt(env.MEMORY_LLM_MAX_RETRIES, 2);
+}