mirror-mind 0.0.1 → 0.32.1

package/ts/src/extensions/migrations.ts

@@ -0,0 +1,350 @@
+// Read side of the extension SQL migration runner (CV22.DS7.TS3 plateau 3a).
+// Port of the read half of `src/memory/extensions/migrations.py`.
+//
+// `runtime status` and `runtime diagnose` need to answer one question per
+// installed command-skill: are this extension's migration files pending,
+// drifted, or clean? That is `inspect_migration_files`, the read-only
+// companion to `run_migrations`. Only the read half is ported here.
+//
+// The WRITE half (`run_migrations`, `_split_statements`,
+// `_extract_table_targets`, `_validate_prefix`) is deliberately absent. It
+// belongs to the extension catalog, which the plan assigns to CV22.DS7.TS4;
+// this module is placed where TS4 extends it rather than moves it.
+//
+// The checksum contract (docs/product/extensions/migrations.md): two files
+// differing only in comments or whitespace hash the same; any structural
+// difference, string literals included, does not. Both cores must agree
+// exactly, or one of them cries drift on a file the other calls clean.
+
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { Database, WritableDatabase } from "#db/database.ts";
+import { PYTHON_WHITESPACE_CLASS, pyStrip, sortByCodePoint } from "#util/pythonText.ts";
+import { ExtensionMigrationError } from "./errors.ts";
+
+/**
+ * Port of `_FILENAME_RE`. Python's `\d` matches the whole Unicode `Nd`
+ * category, not `[0-9]`, so `\p{Nd}` is the faithful class -- a filename
+ * numbered with Arabic-Indic digits is accepted by both cores or by neither.
+ */
+const FILENAME_RE = /^\p{Nd}{3,}_[a-z0-9_]+\.sql$/u;
+
+const STRIP_COMMENTS_RE = /--[^\n]*|\/\*[\s\S]*?\*\//g;
+const COLLAPSE_WHITESPACE_RE = new RegExp(`[${PYTHON_WHITESPACE_CLASS}]+`, "gu");
+const TRIM_AROUND_PUNCT_RE = new RegExp(
+  `[${PYTHON_WHITESPACE_CLASS}]*([(),;])[${PYTHON_WHITESPACE_CLASS}]*`,
+  "gu",
+);
+
+/** Port of `table_prefix_for`: the `ext_<id>_` namespace an extension owns. */
+export function tablePrefixFor(extensionId: string): string {
+  return `ext_${extensionId.replaceAll("-", "_")}_`;
+}
+
+/**
+ * Port of `_normalise_for_checksum`: drop comments, collapse whitespace runs,
+ * and close the gaps around `(),;` so the same statement reformatted across
+ * indented lines hashes identically. String literals survive -- an `INSERT`
+ * value is real SQL content, and editing one must trip the drift guard.
+ */
+export function normaliseForChecksum(sql: string): string {
+  const withoutComments = sql.replace(STRIP_COMMENTS_RE, "");
+  const collapsed = withoutComments.replace(COLLAPSE_WHITESPACE_RE, " ");
+  return pyStrip(collapsed.replace(TRIM_AROUND_PUNCT_RE, "$1"));
+}
+
+/** Port of `_checksum`: SHA-256 over the normalised SQL. */
+export function checksum(content: string): string {
+  return createHash("sha256").update(normaliseForChecksum(content), "utf8").digest("hex");
+}
+
+/**
+ * Port of `_raw_checksum`: SHA-256 over the bytes as written. Backwards
+ * compatibility only -- rows recorded before CV14.E2.S3 carry this hash, and
+ * matching it keeps existing installs from reporting drift on a file nobody
+ * touched.
+ */
+export function rawChecksum(content: string): string {
+  return createHash("sha256").update(content, "utf8").digest("hex");
+}
+
+/**
+ * Port of `_list_migration_files`. Non-`.sql` entries are skipped in silence;
+ * a `.sql` file that breaks the naming contract raises, because a migration
+ * the runner cannot order is a defect, not a file to ignore.
+ */
+export function listMigrationFiles(migrationsDir: string, extensionId: string): string[] {
+  if (!existsSync(migrationsDir)) return [];
+  const names = sortByCodePoint(readdirSync(migrationsDir));
+  const files: string[] = [];
+  for (const name of names) {
+    const full = join(migrationsDir, name);
+    if (!statSync(full).isFile()) continue;
+    // `Path.suffix` is empty for a dotfile with no other dot, so `.sql`
+    // itself is not a `.sql` file to either core.
+    const dot = name.lastIndexOf(".");
+    if (dot <= 0 || name.slice(dot) !== ".sql") continue;
+    if (!FILENAME_RE.test(name)) {
+      throw new ExtensionMigrationError(
+        `invalid migration filename: ${name} (expected ^[0-9]{3,}_[a-z0-9_]+\\.sql$)`,
+        extensionId,
+      );
+    }
+    files.push(name);
+  }
+  return files;
+}
+
+/** What `inspect_migration_files` returns: two ordered filename lists. */
+export interface MigrationInspection {
+  pending: string[];
+  drifted: string[];
+}
+
+/**
+ * Port of `inspect_migration_files`: which files have never been applied, and
+ * which were applied and have since changed. Never writes bookkeeping and
+ * never runs a statement out of a migration file.
+ */
+export function inspectMigrationFiles(
+  db: Database,
+  extensionId: string,
+  migrationsDir: string,
+): MigrationInspection {
+  const files = listMigrationFiles(migrationsDir, extensionId);
+  const applied = db.prepare(
+    "SELECT checksum FROM _ext_migrations WHERE extension_id = ? AND filename = ?",
+  );
+  const pending: string[] = [];
+  const drifted: string[] = [];
+  for (const name of files) {
+    const content = readFileSync(join(migrationsDir, name), "utf8");
+    const row = applied.get(extensionId, name);
+    if (row === undefined) {
+      pending.push(name);
+      continue;
+    }
+    const recorded = row.checksum as string;
+    if (recorded === checksum(content) || recorded === rawChecksum(content)) continue;
+    drifted.push(name);
+  }
+  return { pending, drifted };
+}
+
+// --- the WRITE half (CV22.DS7.TS4 plateau 3) ----------------------------------
+//
+// TS3 ported the read half and said: "The WRITE half (`run_migrations`,
+// `_split_statements`, `_extract_table_targets`, `_validate_prefix`) is
+// deliberately absent. It belongs to the extension catalog, which the plan
+// assigns to CV22.DS7.TS4; this module is placed where TS4 extends it rather
+// than moves it." This is that extension.
+
+const DDL_TABLE_RE = new RegExp(
+  "\\b(?:" +
+    "CREATE\\s+(?:VIRTUAL\\s+)?TABLE|" +
+    "ALTER\\s+TABLE|" +
+    "DROP\\s+TABLE|" +
+    "INSERT\\s+(?:OR\\s+\\w+\\s+)?INTO|" +
+    "UPDATE|" +
+    "DELETE\\s+FROM" +
+    ")" +
+    '\\s+(?:IF\\s+(?:NOT\\s+)?EXISTS\\s+)?"?([A-Za-z_][A-Za-z0-9_]*)"?',
+  "gi",
+);
+
+const INDEX_TABLE_RE = new RegExp(
+  "\\bCREATE\\s+(?:UNIQUE\\s+)?INDEX\\s+" +
+    "(?:IF\\s+NOT\\s+EXISTS\\s+)?" +
+    '(?:"?[A-Za-z_][A-Za-z0-9_]*"?\\s+)?' +
+    'ON\\s+"?([A-Za-z_][A-Za-z0-9_]*)"?',
+  "gi",
+);
+
+const STRIP_STRINGS_RE = /'(?:[^']|'')*'/g;
+
+/** Port of `_strip_noise`: comments out, string literals flattened to `''`. */
+function stripNoise(sql: string): string {
+  return sql.replace(STRIP_COMMENTS_RE, "").replace(STRIP_STRINGS_RE, "''");
+}
+
+/**
+ * Port of `_split_statements`.
+ *
+ * Written as a character walk, exactly as Python's is, because the shape of
+ * the bug it prevents is structural: `executescript` commits any open
+ * transaction, so the runner splits the script itself and feeds statements
+ * through one explicit savepoint. A regex split on `;` would cut inside a
+ * string literal -- the database-architect's plan-stage dissent, and the
+ * reason the corpus stages `INSERT ... VALUES ('a;b')` and `'it''s'`.
+ *
+ * Compound statements (`BEGIN ... END`) are NOT supported, in either core.
+ */
+export function splitStatements(sql: string): string[] {
+  const characters = Array.from(sql);
+  const statements: string[] = [];
+  let buffer = "";
+  let index = 0;
+  while (index < characters.length) {
+    const character = characters[index] as string;
+    if (character === "-" && characters[index + 1] === "-") {
+      const end = characters.indexOf("\n", index);
+      index = end === -1 ? characters.length : end;
+      continue;
+    }
+    if (character === "/" && characters[index + 1] === "*") {
+      const end = sqlIndexOf(characters, "*/", index + 2);
+      index = end === -1 ? characters.length : end + 2;
+      continue;
+    }
+    if (character === "'") {
+      buffer += character;
+      index += 1;
+      while (index < characters.length) {
+        const inner = characters[index] as string;
+        buffer += inner;
+        if (inner === "'") {
+          if (characters[index + 1] === "'") {
+            buffer += characters[index + 1];
+            index += 2;
+            continue;
+          }
+          index += 1;
+          break;
+        }
+        index += 1;
+      }
+      continue;
+    }
+    if (character === ";") {
+      const statement = pyStrip(buffer);
+      if (statement) statements.push(statement);
+      buffer = "";
+      index += 1;
+      continue;
+    }
+    buffer += character;
+    index += 1;
+  }
+  const tail = pyStrip(buffer);
+  if (tail) statements.push(tail);
+  return statements;
+}
+
+/** `str.find(needle, start)` over a code-point array. */
+function sqlIndexOf(characters: readonly string[], needle: string, start: number): number {
+  const parts = Array.from(needle);
+  for (let index = start; index + parts.length <= characters.length; index += 1) {
+    if (parts.every((part, offset) => characters[index + offset] === part)) return index;
+  }
+  return -1;
+}
+
+/** Port of `_extract_table_targets`: every table a statement reads or writes. */
+export function extractTableTargets(sql: string): string[] {
+  const cleaned = stripNoise(sql);
+  const tables: string[] = [];
+  for (const match of cleaned.matchAll(DDL_TABLE_RE))
+    tables.push((match[1] as string).toLowerCase());
+  for (const match of cleaned.matchAll(INDEX_TABLE_RE)) {
+    tables.push((match[1] as string).toLowerCase());
+  }
+  return tables;
+}
+
+/** Port of `_validate_prefix`: an extension may only touch its own namespace. */
+export function validatePrefix(content: string, extensionId: string, filename: string): void {
+  const prefix = tablePrefixFor(extensionId);
+  for (const table of extractTableTargets(content)) {
+    if (!table.startsWith(prefix)) {
+      throw new ExtensionMigrationError(
+        `${filename} targets table '${table}' outside the required prefix '${prefix}*'`,
+        extensionId,
+      );
+    }
+  }
+}
+
+export interface RunMigrationsDeps {
+  /** Python's `_now()`: `datetime.now(timezone.utc).isoformat()`. */
+  readonly nowIso: () => string;
+}
+
+/**
+ * Port of `run_migrations`. Returns the number of newly applied files.
+ *
+ * Atomicity is a SAVEPOINT, not a transaction, and that is deliberate in both
+ * cores: SQLite implicitly commits an open deferred transaction before DDL, so
+ * `BEGIN`/`ROLLBACK` would not undo a half-applied `CREATE TABLE`. A savepoint
+ * does, bookkeeping row included.
+ */
+export function runMigrations(
+  db: WritableDatabase,
+  extensionId: string,
+  migrationsDir: string,
+  deps: RunMigrationsDeps,
+): number {
+  const files = listMigrationFiles(migrationsDir, extensionId);
+  let applied = 0;
+  for (const name of files) {
+    const content = readFileSync(join(migrationsDir, name), "utf8");
+    const current = checksum(content);
+    const row = db
+      .prepare("SELECT checksum FROM _ext_migrations WHERE extension_id = ? AND filename = ?")
+      .get(extensionId, name);
+
+    if (row !== undefined) {
+      const recorded = row.checksum as string;
+      if (recorded === current) continue;
+      if (recorded === rawChecksum(content)) {
+        // A pre-CV14.E2.S3 row that still matches the file as written: upgrade
+        // the stored hash so the next run takes the fast path.
+        db.prepare(
+          "UPDATE _ext_migrations SET checksum = ? WHERE extension_id = ? AND filename = ?",
+        ).run(current, extensionId, name);
+        continue;
+      }
+      throw new ExtensionMigrationError(
+        `${name} has been edited since it was applied ` +
+          `(recorded checksum ${recorded.slice(0, 8)}..., ` +
+          `current checksum ${current.slice(0, 8)}...); never edit an ` +
+          "applied migration in ways that change its SQL semantics " +
+          "— comment and whitespace edits are tolerated, but a " +
+          "structural change requires a new migration file",
+        extensionId,
+      );
+    }
+
+    validatePrefix(content, extensionId, name);
+
+    const savepoint = `ext_migration_${extensionId.replaceAll("-", "_")}`;
+    db.exec(`SAVEPOINT ${savepoint}`);
+    try {
+      for (const statement of splitStatements(content)) db.exec(statement);
+      db.prepare(
+        "INSERT INTO _ext_migrations (extension_id, filename, checksum, applied_at) " +
+          "VALUES (?, ?, ?, ?)",
+      ).run(extensionId, name, current, deps.nowIso());
+    } catch (error) {
+      db.exec(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+      db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+      throw new ExtensionMigrationError(
+        `${name} failed to apply: ${sqliteMessage(error)}`,
+        extensionId,
+      );
+    }
+    db.exec(`RELEASE SAVEPOINT ${savepoint}`);
+    applied += 1;
+  }
+  return applied;
+}
+
+/**
+ * Python renders `sqlite3.Error` as its message alone. `node:sqlite` prefixes
+ * its own errors differently, so the text after `failed to apply:` is a
+ * RECORDED DIVERGENCE: the golden pins the stable prefix and the exit code,
+ * never the driver's sentence.
+ */
+function sqliteMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/ts/src/extraction/conversation.ts

@@ -0,0 +1,304 @@
+import { resolveExtractionModel } from "#providers/config.ts";
+import type { LlmProvider, LlmResponse } from "#providers/llm.ts";
+import {
+  fenceTranscript,
+  MAX_MEMORIES_PER_CONVERSATION,
+  MAX_TASKS_PER_CONVERSATION,
+  type SanitizeDropped,
+  sanitizeExtracted,
+} from "./fencing.ts";
+import { parseJsonResponse } from "./json.ts";
+import { CURATION_PROMPT, EXTRACTION_PROMPT, TASK_EXTRACTION_PROMPT } from "./prompts.ts";
+
+export interface ExtractionMessage {
+  role: string;
+  content: string;
+}
+
+export interface ExtractedMemory {
+  title: string;
+  content: string;
+  context: string | null;
+  memory_type: string;
+  layer: string;
+  tags: string[];
+  journey: string | null;
+  persona: string | null;
+}
+
+export interface ExistingMemoryForCuration {
+  title: string;
+  content: string;
+  memory_type: string;
+  layer: string;
+}
+
+export interface ExtractedTask {
+  title: string;
+  due_date: string | null;
+  journey: string | null;
+  stage: string | null;
+  context: string | null;
+}
+
+export function formatTranscript(
+  messages: readonly ExtractionMessage[],
+  userName = "User",
+): string {
+  return messages
+    .map((message) => {
+      const role = message.role === "user" ? userName : "Mirror";
+      return `**${role}:** ${message.content}`;
+    })
+    .join("\n\n");
+}
+
+export function naiveSummary(messages: readonly ExtractionMessage[]): string {
+  return messages
+    .filter((message) => message.role === "user" || message.role === "assistant")
+    .map((message) => message.content.slice(0, 500))
+    .join(" ")
+    .slice(0, 2000);
+}
+
+export type ExtractionStatusValue = "parse_failed" | "no_signal" | "ok";
+
+export interface ExtractionStatus {
+  status: ExtractionStatusValue;
+  dropped?: SanitizeDropped;
+}
+
+export interface ExtractMemoriesOutcome {
+  memories: ExtractedMemory[];
+  status: ExtractionStatus;
+}
+
+/**
+ * Extracts memories and reports why the result is what it is, mirroring
+ * Python's `extract_memories(status=...)` (AI-10, CV9.E2.S16). A caller can
+ * distinguish unreadable model output (parse_failed) from a genuinely empty
+ * result (no_signal) instead of both looking identical to an empty array.
+ *
+ * `"llm_failed"` is deliberately not part of `ExtractionStatusValue`: this
+ * function cannot structurally report it -- that value only exists when the
+ * call throws, which is the orchestration layer's (`runConversationExtraction`)
+ * concern, not this function's return shape.
+ *
+ * Documented divergence: Python's status dict is left untouched (no key set
+ * at all) for a truly-empty messages call -- a mutate-if-present out-param
+ * behavior this return-based design cannot replicate exactly. This returns
+ * `{ status: "no_signal" }` instead. Zero observable impact:
+ * `runConversationExtraction` already guards `messages.length < 4` before
+ * ever calling this, so the path is unreachable from the real orchestration
+ * call site.
+ */
+/**
+ * The ledger seam Python's `on_llm_call` parameter provides: invoked once per
+ * successful model call with the response and the assembled prompt, before
+ * the response is parsed. Never invoked when the call throws.
+ */
+export type OnLlmCall = (response: LlmResponse, prompt: string) => void;
+
+export async function extractMemoriesWithStatus(
+  provider: LlmProvider,
+  messages: readonly ExtractionMessage[],
+  options: {
+    persona?: string | null;
+    journey?: string | null;
+    userName?: string;
+    onLlmCall?: OnLlmCall;
+  } = {},
+): Promise<ExtractMemoriesOutcome> {
+  if (messages.length === 0) return { memories: [], status: { status: "no_signal" } };
+  const prompt = buildExtractionPrompt(messages, options.userName ?? "User");
+  const response = await provider.complete({
+    role: "extraction",
+    prompt,
+    model: resolveExtractionModel(),
+    temperature: 0.3,
+  });
+  options.onLlmCall?.(response, prompt);
+  const data = parseJsonResponse(response.content);
+  if (!Array.isArray(data)) {
+    return { memories: [], status: { status: "parse_failed" } };
+  }
+  const memories: ExtractedMemory[] = [];
+  for (const item of data) {
+    const memory = toExtractedMemory(item, options);
+    if (memory) memories.push(memory);
+  }
+  const { kept, dropped } = sanitizeExtracted(memories, MAX_MEMORIES_PER_CONVERSATION);
+  return { memories: kept, status: { status: kept.length > 0 ? "ok" : "no_signal", dropped } };
+}
+
+/** Thin, non-breaking wrapper over `extractMemoriesWithStatus`, returning only
+ * the memories array for existing callers -- mirrors Python's `extract_memories`
+ * default (`status=None`) shape. */
+export async function extractMemories(
+  provider: LlmProvider,
+  messages: readonly ExtractionMessage[],
+  options: { persona?: string | null; journey?: string | null; userName?: string } = {},
+): Promise<ExtractedMemory[]> {
+  return (await extractMemoriesWithStatus(provider, messages, options)).memories;
+}
+
+export async function extractTasks(
+  provider: LlmProvider,
+  messages: readonly ExtractionMessage[],
+  options: { journey?: string | null; userName?: string; onLlmCall?: OnLlmCall } = {},
+): Promise<ExtractedTask[]> {
+  if (messages.length === 0) return [];
+  const prompt = buildTaskExtractionPrompt(messages, options.userName ?? "User");
+  const response = await provider.complete({
+    role: "task_extraction",
+    prompt,
+    model: resolveExtractionModel(),
+    temperature: 0.3,
+  });
+  options.onLlmCall?.(response, prompt);
+  const data = parseJsonResponse(response.content);
+  if (!Array.isArray(data)) return [];
+  const tasks: ExtractedTask[] = [];
+  for (const item of data) {
+    const task = toExtractedTask(item, options.journey ?? null);
+    if (task) tasks.push(task);
+  }
+  return tasks.length > MAX_TASKS_PER_CONVERSATION
+    ? tasks.slice(0, MAX_TASKS_PER_CONVERSATION)
+    : tasks;
+}
+
+export async function curateAgainstExisting(
+  provider: LlmProvider,
+  candidates: readonly ExtractedMemory[],
+  existing: readonly ExistingMemoryForCuration[],
+  options: { onLlmCall?: OnLlmCall } = {},
+): Promise<ExtractedMemory[]> {
+  if (candidates.length === 0) return [];
+  if (existing.length === 0) return [...candidates];
+  try {
+    const prompt = buildCurationPrompt(candidates, existing);
+    const response = await provider.complete({
+      role: "curation",
+      prompt,
+      model: resolveExtractionModel(),
+      temperature: 0.2,
+    });
+    options.onLlmCall?.(response, prompt);
+    const data = parseJsonResponse(response.content);
+    if (!Array.isArray(data)) return [...candidates];
+    const curated: ExtractedMemory[] = [];
+    for (const item of data) {
+      const memory = toExtractedMemory(item, {});
+      if (memory) curated.push(memory);
+    }
+    return sanitizeExtracted(curated, MAX_MEMORIES_PER_CONVERSATION).kept;
+  } catch {
+    return [...candidates];
+  }
+}
+
+export function toExtractedMemory(
+  item: unknown,
+  defaults: { persona?: string | null; journey?: string | null },
+): ExtractedMemory | null {
+  if (!isRecord(item)) return null;
+  if (
+    typeof item.title !== "string" ||
+    typeof item.content !== "string" ||
+    typeof item.memory_type !== "string"
+  ) {
+    return null;
+  }
+  return {
+    title: item.title,
+    content: item.content,
+    context: typeof item.context === "string" ? item.context : null,
+    memory_type: item.memory_type,
+    layer: typeof item.layer === "string" ? item.layer : "ego",
+    tags: Array.isArray(item.tags) ? item.tags.map((tag) => String(tag)) : [],
+    journey: typeof item.journey === "string" ? item.journey : (defaults.journey ?? null),
+    persona: typeof item.persona === "string" ? item.persona : (defaults.persona ?? null),
+  };
+}
+
+function toExtractedTask(item: unknown, journey: string | null): ExtractedTask | null {
+  if (!isRecord(item) || typeof item.title !== "string") return null;
+  return {
+    title: item.title,
+    due_date: typeof item.due_date === "string" ? item.due_date : null,
+    journey: typeof item.journey === "string" ? item.journey : journey,
+    stage: typeof item.stage === "string" ? item.stage : null,
+    context: typeof item.context === "string" ? item.context : null,
+  };
+}
+
+/**
+ * Python's `_format_candidates`. Each candidate emits its header line, a
+ * `Content:` line, an optional `Context:` line, and a trailing blank entry, all
+ * joined with newlines -- so the block ends with a newline. The optional
+ * context line and that trailing newline are both part of the prompt bytes.
+ */
+function formatCandidates(candidates: readonly ExtractedMemory[]): string {
+  const lines: string[] = [];
+  candidates.forEach((candidate, index) => {
+    lines.push(
+      `${index + 1}. **${candidate.title}** (${candidate.memory_type}/${candidate.layer})`,
+    );
+    lines.push(`   Content: ${candidate.content}`);
+    if (candidate.context) lines.push(`   Context: ${candidate.context}`);
+    lines.push("");
+  });
+  return lines.join("\n");
+}
+
+/** Python's `_format_existing`: header line, truncated body, trailing blank. */
+function formatExisting(existing: readonly ExistingMemoryForCuration[]): string {
+  const lines: string[] = [];
+  for (const memory of existing) {
+    lines.push(`- **${memory.title}** (${memory.memory_type}/${memory.layer})`);
+    lines.push(`  ${memory.content.slice(0, 200)}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Assemble the exact extraction prompt Python sends.
+ *
+ * Note the asymmetry with the close-tail surfaces: extraction and task
+ * extraction carry no post-fence reminder, while title/tags/summary do. That
+ * is Python's shape, reproduced rather than harmonized.
+ */
+export function buildExtractionPrompt(
+  messages: readonly ExtractionMessage[],
+  userName = "User",
+): string {
+  return EXTRACTION_PROMPT + fenceTranscript(formatTranscript(messages, userName));
+}
+
+/** Assemble the exact task-extraction prompt Python sends. */
+export function buildTaskExtractionPrompt(
+  messages: readonly ExtractionMessage[],
+  userName = "User",
+): string {
+  return TASK_EXTRACTION_PROMPT + fenceTranscript(formatTranscript(messages, userName));
+}
+
+/** Assemble the exact curation prompt Python sends, section headers included. */
+export function buildCurationPrompt(
+  candidates: readonly ExtractedMemory[],
+  existing: readonly ExistingMemoryForCuration[],
+): string {
+  return (
+    CURATION_PROMPT +
+    "## Candidate memories (from this conversation)\n\n" +
+    formatCandidates(candidates) +
+    "\n## Existing similar memories (already stored)\n\n" +
+    formatExisting(existing)
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}