mirror-mind 0.0.1 → 0.32.1

package/ts/src/conversation/journeyRepair.ts

@@ -0,0 +1,114 @@
+// Journey association diagnosis and repair (CV22.DS7.US10 slice E).
+//
+// Ports `diagnose_journey_associations` and
+// `_print_journey_association_findings` from
+// `src/memory/cli/conversation_logger.py`.
+//
+// `diagnose-journeys` is read-only. `repair-journeys --apply` is the one
+// genuinely MUTATING repair in this story: it rewrites the `journey` column of
+// conversations the user never explicitly assigned. Python gates it behind a
+// database backup and refuses to proceed if the backup fails, which is a safety
+// property, not an implementation detail -- it is ported as a hard refusal.
+
+import {
+  firstUserMessage,
+  inferJourneyForConversation,
+  journeyAliases,
+} from "#conversation/journeyInference.ts";
+import type { WritableDatabase } from "#db/database.ts";
+
+export interface JourneyFinding {
+  conversation_id: string;
+  journey: string;
+  reason: string;
+  title: string;
+  started_at: string;
+  message_count: number;
+}
+
+export interface DiagnoseOptions {
+  limit?: number | null;
+  apply?: boolean;
+  /**
+   * Create a database backup and return its path, or null on failure. Required
+   * whenever `apply` is set; a null return refuses the repair.
+   */
+  backup?: () => string | null;
+}
+
+/**
+ * Find, and optionally repair, journeyless conversations with a high-confidence
+ * match.
+ *
+ * The findings list is identical in both modes: `apply` changes whether they are
+ * written, never which conversations qualify. That is what makes the dry run a
+ * trustworthy preview of the mutation.
+ */
+export function diagnoseJourneyAssociations(
+  db: WritableDatabase,
+  options: DiagnoseOptions = {},
+): JourneyFinding[] {
+  const aliases = journeyAliases(db);
+  const limit = options.limit ?? null;
+  const baseSql =
+    "SELECT id, title, started_at FROM conversations WHERE journey IS NULL ORDER BY started_at DESC";
+  const rows = (
+    limit === null ? db.prepare(baseSql).all() : db.prepare(`${baseSql} LIMIT ?`).all(limit)
+  ) as Record<string, unknown>[];
+
+  const findings: JourneyFinding[] = [];
+  for (const row of rows) {
+    const conversationId = String(row.id);
+    const title = typeof row.title === "string" ? row.title : null;
+    const { journey, reason } = inferJourneyForConversation(
+      title,
+      firstUserMessage(db, conversationId),
+      aliases,
+    );
+    if (!journey) continue;
+
+    const countRow = db
+      .prepare("SELECT COUNT(*) AS count FROM messages WHERE conversation_id = ?")
+      .get(conversationId) as Record<string, unknown>;
+    findings.push({
+      conversation_id: conversationId,
+      journey,
+      reason: reason ?? "high-confidence match",
+      title: title ?? "",
+      started_at: String(row.started_at),
+      message_count: Number(countRow.count ?? 0),
+    });
+  }
+
+  if (options.apply && findings.length > 0) {
+    if (!options.backup) {
+      throw new Error("Database backup failed; refusing to repair conversations.");
+    }
+    const backupPath = options.backup();
+    if (backupPath === null) {
+      throw new Error("Database backup failed; refusing to repair conversations.");
+    }
+    for (const finding of findings) {
+      db.prepare("UPDATE conversations SET journey = ? WHERE id = ?").run(
+        finding.journey,
+        finding.conversation_id,
+      );
+    }
+  }
+
+  return findings;
+}
+
+/** Python's `_print_journey_association_findings`. */
+export function renderJourneyFindings(findings: JourneyFinding[], applied: boolean): string {
+  const label = applied ? "Repaired" : "Repair candidates";
+  const lines = [`${label}: ${findings.length}`];
+  for (const finding of findings) {
+    lines.push(
+      `- ${finding.conversation_id} -> ${finding.journey} ` +
+        `(${finding.reason}; ${finding.message_count} messages; ` +
+        `${finding.started_at}; ${finding.title})`,
+    );
+  }
+  return `${lines.join("\n")}\n`;
+}

package/ts/src/conversation/lifecycleFaces.ts

@@ -0,0 +1,197 @@
+/**
+ * The ES-001 metadata-lifecycle READ faces — CV22.DS7.US11 plateau 5b.
+ *
+ * `conversations --metadata-lifecycle-dry-run <conversation-id>` and
+ * `--metadata-lifecycle-preview-at-message <message-id>`: two pure reads over
+ * the engine DS7.US10 already ported. CR068 found the whole ES-001 flag family
+ * unowned — US1 called it "own slice", no slice claimed it.
+ *
+ * **Scope boundary, Navigator decision 2026-09-09 (option B).** The sibling
+ * faces `--metadata-lifecycle-apply` and `--metadata-lifecycle-demo` are NOT
+ * ported here and are refused BY NAME in `routing.ts`. Both need
+ * `apply_metadata_lifecycle`: ~80 lines of unported decision logic with a write
+ * path, which `closeTail.ts` already refuses for the same reason, and `demo`
+ * calls `apply`. The US11 plan recorded all four as "wiring over the ported
+ * engine", which was true of the reads and false of the writes. DS7.TS4 owns
+ * them; the two historical metadata-backfill flags were retired outright by
+ * CV22.DS10.TS4.
+ */
+
+import {
+  type ConversationLike,
+  dryRunMetadataLifecycle,
+  type MessageLike,
+  type MetadataLifecycleReport,
+  titleNeedsImprovement,
+} from "#conversation/metadataLifecycle.ts";
+import type { Database } from "#db/database.ts";
+
+/** Python raises `ValueError`; the CLI renders its text. */
+export class LifecycleFaceError extends Error {}
+
+/**
+ * Every column the ENGINE reads, not just the ones the title decision reads.
+ *
+ * The first version of this face selected `id, title, metadata`, and the
+ * summary and tags decisions silently answered as if the conversation had
+ * neither: a conversation with a stored summary reported `summary: defer` where
+ * Python reports `keep`, and the title decision moved with it, because
+ * refinement evidence is drawn from the summary. Measured at CV22.DS7.TS4
+ * plateau 6 against the real CLI; the US11 corpus could not see it because no
+ * seeded conversation had a summary or tags to lose.
+ */
+interface ConversationRow {
+  id: string;
+  title: string | null;
+  summary: string | null;
+  tags: string | null;
+  metadata: string | null;
+}
+
+/**
+ * Python `_get_conversation_for_title_operation`: exact id, then an id-prefix
+ * lookup, then a ValueError naming the value the caller passed.
+ */
+export function resolveConversation(db: Database, conversationId: string): ConversationRow {
+  if (typeof conversationId !== "string" || conversationId.trim() === "") {
+    throw new LifecycleFaceError("conversationId is required");
+  }
+  const exact = db
+    .prepare("SELECT id, title, summary, tags, metadata FROM conversations WHERE id = ?")
+    .get(conversationId) as unknown as ConversationRow | undefined;
+  if (exact) return exact;
+  const prefixed = db
+    .prepare(
+      "SELECT id, title, summary, tags, metadata FROM conversations WHERE id LIKE ? " +
+        "ORDER BY started_at LIMIT 1",
+    )
+    .get(`${conversationId}%`) as unknown as ConversationRow | undefined;
+  if (prefixed) return prefixed;
+  throw new LifecycleFaceError(`Conversation '${conversationId}' not found`);
+}
+
+/**
+ * The engine's `MessageLike` declares only what the policy READS (role,
+ * content). The boundary walk needs the id as well, so it is declared here
+ * rather than widening the engine's interface for a caller's convenience.
+ */
+interface MessageRow extends MessageLike {
+  id: string;
+}
+
+function loadMessages(db: Database, conversationId: string): MessageRow[] {
+  return db
+    .prepare(
+      "SELECT id, role, content, created_at FROM messages WHERE conversation_id = ? ORDER BY created_at",
+    )
+    .all(conversationId) as unknown as MessageRow[];
+}
+
+/** Python `_metadata_dict`: a non-object or malformed metadata becomes `{}`. */
+export function metadataDict(conversation: ConversationRow): Record<string, unknown> {
+  if (!conversation.metadata) return {};
+  try {
+    const parsed: unknown = JSON.parse(conversation.metadata);
+    if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return {};
+    return parsed as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * `titleNeedsImprovement` reads `metadata` — `title_status: "provisional"` is
+ * what makes a title repairable — so the WHOLE row crosses, not just id and
+ * title. An earlier draft passed `{ id, title }` behind an `as ConversationLike`
+ * cast, which compiled fine and silently turned every `repair` into `keep`.
+ * The cast is gone: the row already satisfies the interface structurally.
+ */
+function asConversationLike(row: ConversationRow): ConversationLike {
+  return {
+    id: row.id,
+    title: row.title,
+    summary: row.summary,
+    tags: row.tags,
+    metadata: row.metadata,
+  };
+}
+
+/** `conversations --metadata-lifecycle-dry-run <conversation-id>`. */
+export function runLifecycleDryRun(db: Database, conversationId: string): MetadataLifecycleReport {
+  const conversation = resolveConversation(db, conversationId);
+  const messages = loadMessages(db, conversation.id);
+  return dryRunMetadataLifecycle(
+    asConversationLike(conversation),
+    messages,
+    metadataDict(conversation),
+    {
+      titleNeedsImprovement,
+    },
+  );
+}
+
+export interface PreviewAtMessageReport {
+  conversation_id: string;
+  message_id: string;
+  mode: "debug_preview_at_message";
+  mutated: false;
+  included_message_count: number;
+  excluded_message_count: number;
+  dry_run: MetadataLifecycleReport;
+}
+
+/**
+ * `conversations --metadata-lifecycle-preview-at-message <message-id>`.
+ *
+ * Python resolves the boundary message by exact id OR id prefix, taking the
+ * MOST RECENT match (`ORDER BY created_at DESC LIMIT 1`) — the opposite
+ * direction from the conversation lookup beside it, reproduced as written.
+ */
+export function runLifecyclePreviewAtMessage(
+  db: Database,
+  messageId: string,
+): PreviewAtMessageReport {
+  if (typeof messageId !== "string" || messageId.trim() === "") {
+    throw new LifecycleFaceError("messageId is required");
+  }
+  const boundary = db
+    .prepare(
+      "SELECT id, conversation_id FROM messages WHERE id = ? OR id LIKE ? ORDER BY created_at DESC LIMIT 1",
+    )
+    .get(messageId, `${messageId}%`) as unknown as
+    | { id: string; conversation_id: string }
+    | undefined;
+  if (!boundary) throw new LifecycleFaceError(`Message '${messageId}' not found`);
+
+  const conversation = resolveConversation(db, boundary.conversation_id);
+  const allMessages = loadMessages(db, conversation.id);
+
+  const selected: MessageRow[] = [];
+  let foundBoundary = false;
+  for (const message of allMessages) {
+    selected.push(message);
+    if (message.id === boundary.id) {
+      foundBoundary = true;
+      break;
+    }
+  }
+  if (!foundBoundary) {
+    throw new LifecycleFaceError(`Message '${messageId}' not found in conversation`);
+  }
+
+  const dryRun = dryRunMetadataLifecycle(
+    asConversationLike(conversation),
+    selected,
+    metadataDict(conversation),
+    { titleNeedsImprovement },
+  );
+  return {
+    conversation_id: conversation.id,
+    message_id: boundary.id,
+    mode: "debug_preview_at_message",
+    mutated: false,
+    included_message_count: selected.length,
+    excluded_message_count: Math.max(0, allMessages.length - selected.length),
+    dry_run: dryRun,
+  };
+}

package/ts/src/conversation/lifecycleWrites.ts

@@ -0,0 +1,313 @@
+/**
+ * The ES-001 metadata-lifecycle WRITE faces — CV22.DS7.TS4 plateau 6.
+ *
+ * `conversations --metadata-lifecycle-apply <id> [--title/--summary/--tag]` and
+ * `--metadata-lifecycle-demo`, the two faces US11 refused by name and handed
+ * here (Navigator decision 2026-09-09, option B).
+ *
+ * This is the WRITE half of an engine already ported: every decision comes from
+ * `dryRunMetadataLifecycle`, and what lands here is the bounded application of
+ * those decisions. Three rules the corpus pinned and a reading of the code
+ * would not give:
+ *
+ *   1. **A decision is not a permission.** `create` and `repair` apply a title;
+ *      `preserve` and `refine_candidate` each skip with their OWN reason, and
+ *      any other decision skips as `decision_<name>_not_applied` — but only
+ *      when a value was actually offered. With no value the reason is
+ *      `no_value_provided`, which is a different fact and is reported as one.
+ *   2. **Tags ride the summary.** A `defer` tags decision still applies when a
+ *      summary changed in the SAME call, because the deferral was waiting for
+ *      exactly that substance. Alone, the same call skips.
+ *   3. **The flag is `--tag`, singular and repeatable.** There is no `--tags`;
+ *      the parser appends into `dest="tags"`. A port written from the parameter
+ *      name would expose an option Python refuses.
+ */
+
+import type { ConversationLike, MetadataLifecycleReport } from "#conversation/metadataLifecycle.ts";
+import type { WritableDatabase } from "#db/database.ts";
+import { pythonJsonDumps } from "#util/pyGenerators.ts";
+import { sliceCodePoints } from "#util/pythonText.ts";
+import {
+  LifecycleFaceError,
+  metadataDict,
+  resolveConversation,
+  runLifecycleDryRun,
+} from "./lifecycleFaces.ts";
+
+export interface ApplyMetadataLifecycleInput {
+  title?: string | null;
+  summary?: string | null;
+  /** The repeated `--tag` values, or a pre-encoded string. */
+  tags?: readonly string[] | string | null;
+  source?: string;
+}
+
+export interface ApplyMetadataLifecycleReport {
+  conversation_id: string;
+  mode: "apply";
+  mutated: boolean;
+  changed: Record<string, unknown>;
+  skipped: Record<string, string>;
+  dry_run: MetadataLifecycleReport;
+}
+
+/** Port of `ConversationService._clean_title`. */
+export function cleanTitle(title: string): string {
+  const clean = title.trim().split(/\s+/u).filter(Boolean).join(" ");
+  if (!clean) throw new LifecycleFaceError("title is required");
+  if (clean.length > 160) throw new LifecycleFaceError("title must be at most 160 characters");
+  return clean;
+}
+
+/**
+ * Port of `ConversationService._title_metadata`.
+ *
+ * `previous_title` is recorded only when it differs from the one already
+ * stored, so repeated applies do not overwrite the ORIGINAL title with the one
+ * the previous apply wrote.
+ */
+export function titleMetadata(
+  metadata: Record<string, unknown>,
+  options: { source: string; status: string; previousTitle: string | null },
+): Record<string, unknown> {
+  const next = { ...metadata };
+  if (options.previousTitle && options.previousTitle !== next.previous_title) {
+    next.previous_title = options.previousTitle;
+  }
+  next.title_source = options.source;
+  next.title_status = options.status;
+  return next;
+}
+
+/** Port of `ConversationService.apply_metadata_lifecycle`. */
+export function applyMetadataLifecycle(
+  db: WritableDatabase,
+  conversationId: string,
+  input: ApplyMetadataLifecycleInput = {},
+): ApplyMetadataLifecycleReport {
+  const source = input.source ?? "metadata_lifecycle_apply";
+  const conversation = resolveConversation(db, conversationId);
+  const dryRun = runLifecycleDryRun(db, conversation.id);
+  let metadata = metadataDict(conversation);
+  const updates: Record<string, string> = {};
+  const changed: Record<string, unknown> = {};
+  const skipped: Record<string, string> = {};
+
+  const title = input.title ?? null;
+  const titleDecision = String(dryRun.fields.title.decision);
+  if (titleDecision === "preserve") {
+    skipped.title = "manual_lock_preserved";
+  } else if (titleDecision === "refine_candidate") {
+    skipped.title = "candidate_decision_requires_explicit_review";
+  } else if ((titleDecision === "create" || titleDecision === "repair") && title !== null) {
+    const clean = cleanTitle(title);
+    updates.title = clean;
+    metadata = titleMetadata(metadata, {
+      source,
+      status: "generated",
+      previousTitle: conversation.title,
+    });
+    changed.title = clean;
+  } else if (title !== null) {
+    skipped.title = `decision_${titleDecision}_not_applied`;
+  } else {
+    skipped.title = "no_value_provided";
+  }
+
+  const summary = input.summary ?? null;
+  const summaryDecision = String(dryRun.fields.summary.decision);
+  if (summaryDecision === "create" && summary !== null) {
+    const clean = summary.trim();
+    if (clean) {
+      // Python truncates with a slice, which counts CODE POINTS. A UTF-16
+      // slice would cut an astral character in half at the boundary.
+      updates.summary = sliceCodePoints(clean, 1000);
+      metadata.summary_status = "generated";
+      changed.summary = updates.summary;
+    } else {
+      skipped.summary = "blank_value";
+    }
+  } else if (summary !== null) {
+    skipped.summary = `decision_${summaryDecision}_not_applied`;
+  } else {
+    skipped.summary = "no_value_provided";
+  }
+
+  const tags = input.tags ?? null;
+  const tagsDecision = String(dryRun.fields.tags.decision);
+  // Rule 2: a deferral waits for substance, and a summary landing in this same
+  // call IS that substance.
+  const tagsReadyAfterSummary = tagsDecision === "defer" && "summary" in changed;
+  if ((tagsDecision === "create" || tagsReadyAfterSummary) && tags !== null) {
+    updates.tags = typeof tags === "string" ? tags : pythonJsonDumps([...tags]);
+    metadata.tags_status = "generated";
+    changed.tags = tags;
+  } else if (tags !== null) {
+    skipped.tags = `decision_${tagsDecision}_not_applied`;
+  } else {
+    skipped.tags = "no_value_provided";
+  }
+
+  if (Object.keys(changed).length > 0) {
+    metadata.metadata_lifecycle_version = 1;
+    metadata.last_metadata_update_source = source;
+    updates.metadata = pythonJsonDumps(metadata);
+    updateConversation(db, conversation.id, updates);
+  }
+
+  return {
+    conversation_id: conversation.id,
+    mode: "apply",
+    mutated: Object.keys(changed).length > 0,
+    changed,
+    skipped,
+    dry_run: dryRun,
+  };
+}
+
+/** Port of `ConversationStore.update_conversation`: the given columns, nothing else. */
+export function updateConversation(
+  db: WritableDatabase,
+  conversationId: string,
+  updates: Record<string, string>,
+): void {
+  const columns = Object.keys(updates);
+  if (columns.length === 0) return;
+  const assignments = columns.map((column) => `${column} = ?`).join(", ");
+  db.prepare(`UPDATE conversations SET ${assignments} WHERE id = ?`).run(
+    ...columns.map((column) => updates[column] as string),
+    conversationId,
+  );
+}
+
+/** The conversation columns the demo reports after applying. */
+export interface ConversationAfter {
+  title: string | null;
+  summary: string | null;
+  tags: string | null;
+}
+
+export interface MetadataLifecycleDemoReport {
+  mode: "metadata_lifecycle_demo";
+  uses_production_data: false;
+  passed: boolean;
+  checks: Record<string, boolean>;
+  scenarios: Record<string, unknown>;
+}
+
+/**
+ * Port of `_metadata_lifecycle_demo_report`.
+ *
+ * A controlled scenario over a throwaway database: it proves the three
+ * decisions a reader most needs to trust — a provisional title is repaired, a
+ * manual lock is preserved, and a refine candidate is refused — and it touches
+ * no production data, which is the claim `uses_production_data: false` makes.
+ *
+ * The caller supplies the empty database, so the demo never decides where to
+ * write. Python's is `sqlite3.connect(":memory:")`.
+ */
+export function metadataLifecycleDemoReport(
+  db: WritableDatabase,
+  seed: DemoSeed,
+): MetadataLifecycleDemoReport {
+  const repair = seed.startConversation("cli");
+  seed.setProvisionalTitle(repair, "vamos trabalhar no maestro");
+  seed.addMessage(repair, "user", "Vamos validar checkpoint visibility");
+  seed.addMessage(repair, "assistant", "Vamos revisar o handoff");
+  const preview = runLifecycleDryRun(db, repair);
+  const apply = applyMetadataLifecycle(db, repair, {
+    title: "Maestro checkpoint visibility validation",
+    summary: "Conversation metadata lifecycle validation.",
+    tags: ["metadata", "conversation"],
+  });
+  const afterApply = readConversation(db, repair);
+
+  const manual = seed.startConversation("cli", "Initial title");
+  seed.addMessage(manual, "user", "Quero corrigir títulos");
+  seed.addMessage(manual, "assistant", "Vamos desenhar a correção");
+  seed.updateTitle(manual, "Manual conversation title");
+  const manualApply = applyMetadataLifecycle(db, manual, {
+    title: "Generated replacement title",
+  });
+
+  const refine = seed.startConversation("cli", "Initial editorial session");
+  seed.addMessage(refine, "user", "Let's begin");
+  seed.addMessage(refine, "assistant", "Ready");
+  updateConversation(db, refine, {
+    summary:
+      "Editorial workflow for Raphael Albino manuscript. Scrivener import, " +
+      "cover briefing, Kindle export, EPUB validation, chapter cleanup, raw text hygiene.",
+  });
+  const refineApply = applyMetadataLifecycle(db, refine, {
+    title: "Better editorial workflow title",
+  });
+
+  const checks = {
+    preview_non_mutating: preview.mutated === false,
+    apply_changed_title: apply.changed.title === "Maestro checkpoint visibility validation",
+    manual_lock_preserved: manualApply.skipped.title === "manual_lock_preserved",
+    refine_candidate_skipped:
+      refineApply.skipped.title === "candidate_decision_requires_explicit_review",
+  };
+  return {
+    mode: "metadata_lifecycle_demo",
+    uses_production_data: false,
+    passed: Object.values(checks).every(Boolean),
+    checks,
+    scenarios: {
+      preview,
+      apply: {
+        report: apply,
+        after: {
+          title: afterApply?.title ?? null,
+          summary: afterApply?.summary ?? null,
+          tags: afterApply?.tags ?? null,
+        },
+      },
+      manual_lock: manualApply,
+      refine_candidate: refineApply,
+    },
+  };
+}
+
+/** What the demo needs from the conversation writer, injected rather than reached for. */
+export interface DemoSeed {
+  startConversation: (interfaceName: string, title?: string) => string;
+  addMessage: (conversationId: string, role: string, content: string) => void;
+  setProvisionalTitle: (conversationId: string, title: string) => void;
+  updateTitle: (conversationId: string, title: string) => void;
+}
+
+function readConversation(db: WritableDatabase, conversationId: string): ConversationAfter | null {
+  const row = db
+    .prepare("SELECT title, summary, tags FROM conversations WHERE id = ?")
+    .get(conversationId) as unknown as ConversationAfter | undefined;
+  return row ?? null;
+}
+
+/**
+ * The two title writes the demo scripts, ported from `set_provisional_title`
+ * and `update_title`. Both go through `_title_metadata`, which is why a
+ * provisional title is later REPAIRABLE and a manual one is locked: the only
+ * difference on disk is `title_status`.
+ */
+export function writeTitle(
+  db: WritableDatabase,
+  conversationId: string,
+  title: string,
+  kind: "provisional" | "manual",
+): void {
+  const conversation = resolveConversation(db, conversationId);
+  const clean = cleanTitle(title);
+  const metadata = titleMetadata(metadataDict(conversation), {
+    source: kind === "manual" ? "manual" : "first_user",
+    status: kind === "manual" ? "manual" : "provisional",
+    previousTitle: conversation.title,
+  });
+  updateConversation(db, conversation.id, {
+    title: clean,
+    metadata: pythonJsonDumps(metadata),
+  });
+}
+
+export type { ConversationLike };

package/ts/src/conversation/listing.ts

@@ -0,0 +1,77 @@
+// `conversations` listing read — the port of Store.list_recent_conversation_summaries
+// (memory.cli.conversations, the plain-listing path only). The metadata-lifecycle
+// and backfill preview/apply flags on the same Python CLI are stateful writes
+// (ES-001); routing.ts falls back to Python whenever any of those flags are
+// present, so this module only ever serves the plain listing.
+//
+// Query-builder + row-mapper, ordering pushed down to SQLite, per the same
+// database-seam philosophy as memory/listing.ts.
+
+import type { Database, SqlValue } from "#db/database.ts";
+import { optionalString, requireString } from "#db/rowDecode.ts";
+
+export interface ConversationSummary {
+  id: string;
+  title: string | null;
+  started_at: string | null;
+  persona: string | null;
+  journey: string | null;
+  message_count: number;
+}
+
+export interface ListRecentConversationsFilters {
+  limit?: number;
+  journey?: string | null;
+  persona?: string | null;
+}
+
+/**
+ * Build the parameterized recent-conversations query, mirroring the Python
+ * builder exactly: a `1=1` seed, `journey = ?` then `persona = ?` when
+ * provided (in that order), `ORDER BY started_at DESC`, trailing `LIMIT ?`.
+ */
+export function buildListRecentConversationsQuery(filters: ListRecentConversationsFilters = {}): {
+  sql: string;
+  params: SqlValue[];
+} {
+  const { limit = 20, journey = null, persona = null } = filters;
+  const conditions = ["1=1"];
+  const params: SqlValue[] = [];
+  if (journey) {
+    conditions.push("journey = ?");
+    params.push(journey);
+  }
+  if (persona) {
+    conditions.push("persona = ?");
+    params.push(persona);
+  }
+  params.push(limit);
+  const sql =
+    "SELECT id, title, started_at, persona, journey, " +
+    "(SELECT COUNT(*) FROM messages WHERE conversation_id = c.id) as message_count " +
+    `FROM conversations c WHERE ${conditions.join(" AND ")} ORDER BY started_at DESC LIMIT ?`;
+  return { sql, params };
+}
+
+function toSummary(row: Record<string, unknown>): ConversationSummary {
+  return {
+    id: requireString(row, "id"),
+    title: optionalString(row, "title"),
+    started_at: optionalString(row, "started_at"),
+    persona: optionalString(row, "persona"),
+    journey: optionalString(row, "journey"),
+    message_count: Number(row.message_count),
+  };
+}
+
+/** Return recent conversation summaries with optional equality filters, newest first. */
+export function listRecentConversationSummaries(
+  db: Database,
+  filters: ListRecentConversationsFilters = {},
+): ConversationSummary[] {
+  const { sql, params } = buildListRecentConversationsQuery(filters);
+  return db
+    .prepare(sql)
+    .all(...params)
+    .map(toSummary);
+}