mirror-mind 0.0.1 → 0.33.0

package/ts/src/cultivation/propose.ts

@@ -0,0 +1,305 @@
+// Port of `propose_consolidation` (`intelligence/consolidate.py`) and
+// `propose_shadow_observations` (`intelligence/shadow.py`) -- the LLM
+// orchestration half of `consolidate scan` / `shadow scan` (CV22.DS7.US3
+// Slice B; live since CV22.DS8.TS2).
+//
+// The prompt sent to the provider is Python's real template
+// (`CONSOLIDATION_PROMPT` / `SHADOW_SCAN_PROMPT`: task statement, identity or
+// dedup context, the "## Untrusted input" guard, and the JSON output
+// contract), assembled through `pyFormat` around the same fenced block Python
+// fences. The assembled bytes are graded against a golden captured from the
+// real Python builders and digest-pinned, because this file's history is the
+// cautionary tale: from DS7.US3 to DS8.TS2 it sent a fenced memory dump with
+// no instructions, and replay -- which resolves by role and never reads the
+// prompt -- could not tell. Live, the model would have answered prose,
+// `parseJsonResponse` would have failed, and every scan would have reported
+// "no proposals" while the ledger showed paid calls.
+
+import { fenceUntrusted } from "#extraction/fencing.ts";
+import { parseJsonResponse } from "#extraction/json.ts";
+import { CONSOLIDATION_PROMPT, SHADOW_SCAN_PROMPT } from "#extraction/prompts.ts";
+import { classifyProviderError, type OnProviderCallOutcome } from "#observability/callOutcome.ts";
+import type { ChatLedgerHook } from "#observability/ledgerHooks.ts";
+import { resolveExtractionModel } from "#providers/config.ts";
+import type { LlmProvider } from "#providers/llm.ts";
+import { pyFormat } from "#util/pythonText.ts";
+import type { ConsolidationRow, CultivationMemory } from "./consolidationStore.ts";
+
+/** Mirrors Python's action allowlist check in `propose_consolidation`. */
+const CONSOLIDATION_ACTIONS: ReadonlySet<string> = new Set([
+  "merge",
+  "identity_update",
+  "shadow_candidate",
+]);
+
+/** Port of `_format_cluster`: one Markdown section per memory, in input order. */
+export function formatCluster(cluster: readonly CultivationMemory[]): string {
+  const lines: string[] = [];
+  cluster.forEach((memory, index) => {
+    lines.push(`### Memory ${index + 1}`);
+    lines.push(`**Type:** ${memory.memory_type} | **Layer:** ${memory.layer}`);
+    if (memory.journey) lines.push(`**Journey:** ${memory.journey}`);
+    lines.push(`**Created:** ${memory.created_at.slice(0, 10)}`);
+    lines.push(`**Title:** ${memory.title}`);
+    lines.push(`**Content:** ${memory.content}`);
+    if (memory.context) lines.push(`**Context:** ${memory.context}`);
+    lines.push("");
+  });
+  return lines.join("\n");
+}
+
+/** Port of `_format_shadow_memories`. */
+export function formatShadowMemories(memories: readonly CultivationMemory[]): string {
+  if (memories.length === 0) return "(no shadow-candidate memories found)";
+  const lines: string[] = [];
+  for (const memory of memories) {
+    lines.push(`### [${memory.id.slice(0, 8)}] ${memory.title}`);
+    lines.push(
+      `**Type:** ${memory.memory_type} | **Layer:** ${memory.layer} | ` +
+        `**State:** ${memory.readiness_state} | **Date:** ${memory.created_at.slice(0, 10)}`,
+    );
+    lines.push(`**Content:** ${memory.content}`);
+    if (memory.context) lines.push(`**Context:** ${memory.context}`);
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+/** A structural shadow identity entry, the minimal projection `_format_shadow_structure` needs. */
+export interface ShadowStructureEntry {
+  key: string;
+  content: string;
+}
+
+/** Port of `_format_shadow_structure`. */
+export function formatShadowStructure(entries: readonly ShadowStructureEntry[]): string {
+  if (entries.length === 0) return "(no structural shadow content yet)";
+  return entries.map((entry) => `### ${entry.key}\n${entry.content}`).join("\n\n");
+}
+
+/**
+ * Exactly what `propose_consolidation` sends: `CONSOLIDATION_PROMPT.format(...)`
+ * with only the user-derived cluster fenced -- `identity_context` is
+ * system-side. One pass, so a `{placeholder}` literal inside memory content
+ * is never expanded a second time.
+ */
+export function buildConsolidationPrompt(
+  cluster: readonly CultivationMemory[],
+  userName: string,
+  identityContext: string,
+): string {
+  return pyFormat(CONSOLIDATION_PROMPT, {
+    user_name: userName,
+    identity_context: identityContext,
+    cluster_text: fenceUntrusted("cluster", formatCluster(cluster)),
+  });
+}
+
+/**
+ * Exactly what `propose_shadow_observations` sends: `SHADOW_SCAN_PROMPT.format(...)`
+ * with only `shadow_memories` fenced -- `shadow_structure` is structural
+ * identity content, not user-injected, and Python leaves it unfenced.
+ */
+export function buildShadowScanPrompt(
+  memories: readonly CultivationMemory[],
+  shadowEntries: readonly ShadowStructureEntry[],
+  userName: string,
+): string {
+  return pyFormat(SHADOW_SCAN_PROMPT, {
+    user_name: userName,
+    shadow_structure: formatShadowStructure(shadowEntries),
+    shadow_memories: fenceUntrusted("shadow_memories", formatShadowMemories(memories)),
+  });
+}
+
+export interface ProposeConsolidationOptions {
+  id: string;
+  nowIso: string;
+  /** `cmd_scan`'s `_user_name(mem)`; see `promptContext.ts`. Required: the fallback lives in the resolver, as in Python. */
+  userName: string;
+  /** `cmd_scan`'s `_identity_context(mem)`; see `promptContext.ts`. */
+  identityContext: string;
+  /**
+   * Python passes `on_llm_call=build_llm_logger(store, role="consolidation")`
+   * from `consolidate_cmd`. TypeScript logged nothing, which was accurate
+   * while every call was replayed and free, and stops being accurate the
+   * moment this reaches a live provider (CV22.DS8.US3).
+   */
+  onLlmCall?: ChatLedgerHook;
+  /**
+   * What happened on this call, category only. Every `null` below is Python's
+   * swallow, and without this they are indistinguishable from each other and
+   * from an honest "no proposal" (CV22.DS8.US3).
+   */
+  onOutcome?: OnProviderCallOutcome;
+}
+
+/**
+ * Port of `propose_consolidation`: fence the cluster, call the LLM
+ * (role `'consolidation'`), and parse the response into a pending
+ * `ConsolidationRow`, or `null` on any failure (provider rejection, unparsable
+ * JSON, an action outside the allowlist, or empty proposed content) --
+ * mirroring Python's `except Exception: return None` / `return None` branches
+ * exactly. Deliberately does NOT gate `target_layer`/`target_key` here --
+ * this only stores the proposal as `pending`; the identity-write allowlist
+ * gate runs later, at `apply` time (`applyIdentityUpdate`), which is the
+ * adversarial-containment property this story proves.
+ */
+export async function proposeConsolidation(
+  provider: LlmProvider,
+  cluster: readonly CultivationMemory[],
+  options: ProposeConsolidationOptions,
+): Promise<ConsolidationRow | null> {
+  const prompt = buildConsolidationPrompt(cluster, options.userName, options.identityContext);
+  let content: string;
+  try {
+    const response = await provider.complete({
+      role: "consolidation",
+      prompt,
+      model: resolveExtractionModel(),
+      temperature: 0.1,
+    });
+    // Python logs AFTER a successful call and BEFORE parsing, so a response
+    // the parser rejects still leaves a row: the call was made and paid for.
+    options.onLlmCall?.(response, prompt);
+    content = response.content;
+  } catch (error) {
+    options.onOutcome?.({ outcome: "transport_failed", kind: classifyProviderError(error) });
+    return null;
+  }
+
+  const data = parseJsonResponse(content);
+  // A response the parser cannot use is a PROMPT-layer signal, not a transport
+  // one: the call succeeded and was paid for.
+  if (!isRecord(data)) {
+    options.onOutcome?.({ outcome: "parse_failed" });
+    return null;
+  }
+
+  // The model answered and was understood; we rejected what it proposed. That
+  // is "nothing to do", not a failure.
+  const action = typeof data.action === "string" ? data.action.toLowerCase() : "";
+  if (!CONSOLIDATION_ACTIONS.has(action)) {
+    options.onOutcome?.({ outcome: "empty" });
+    return null;
+  }
+
+  const proposedContent =
+    typeof data.proposed_content === "string" ? data.proposed_content.trim() : "";
+  if (!proposedContent) {
+    options.onOutcome?.({ outcome: "empty" });
+    return null;
+  }
+
+  options.onOutcome?.({ outcome: "answered" });
+
+  const targetLayer =
+    typeof data.target_layer === "string" && data.target_layer ? data.target_layer : null;
+  const targetKey = typeof data.target_key === "string" && data.target_key ? data.target_key : null;
+  const rationaleRaw = typeof data.rationale === "string" ? data.rationale.trim() : "";
+
+  return {
+    id: options.id,
+    action,
+    proposal: proposedContent,
+    result: null,
+    source_memory_ids: JSON.stringify(cluster.map((memory) => memory.id)),
+    target_layer: targetLayer,
+    target_key: targetKey,
+    rationale: rationaleRaw || null,
+    status: "pending",
+    created_at: options.nowIso,
+    reviewed_at: null,
+  };
+}
+
+export interface ProposeShadowObservationsOptions {
+  /** Called once per emitted observation, matching Python's per-item `_uuid()`/`_now()`. */
+  id: () => string;
+  nowIso: () => string;
+  /** `cmd_scan`'s `_user_name(mem)`; see `promptContext.ts`. */
+  userName: string;
+  /** Python's `build_llm_logger(store, role="shadow_scan")`; see above. */
+  onLlmCall?: ChatLedgerHook;
+  /** What happened on the one call, category only; see `ProposeConsolidationOptions`. */
+  onOutcome?: OnProviderCallOutcome;
+}
+
+/**
+ * Port of `propose_shadow_observations`: a single LLM call over the FULL
+ * candidate pool (not per-cluster) so cross-cluster patterns can surface,
+ * fenced under `'shadow_memories'`. Returns `[]` on any failure (no
+ * memories, provider rejection, unparsable JSON, or a non-array response) --
+ * mirroring Python's early-return branches exactly. Each valid item becomes
+ * its own pending `Consolidation` with `action: 'shadow_observation'`,
+ * `target_layer: 'shadow'`, `target_key: 'profile'` -- ALWAYS this pair,
+ * never read from the LLM response (Python's `Consolidation(...,
+ * target_layer="shadow", target_key="profile", ...)` is a hardcoded literal,
+ * not derived from `item`).
+ */
+export async function proposeShadowObservations(
+  provider: LlmProvider,
+  memories: readonly CultivationMemory[],
+  shadowEntries: readonly ShadowStructureEntry[],
+  options: ProposeShadowObservationsOptions,
+): Promise<ConsolidationRow[]> {
+  if (memories.length === 0) return [];
+
+  const prompt = buildShadowScanPrompt(memories, shadowEntries, options.userName);
+
+  let content: string;
+  try {
+    const response = await provider.complete({
+      role: "shadow_scan",
+      prompt,
+      model: resolveExtractionModel(),
+      temperature: 0.1,
+    });
+    options.onLlmCall?.(response, prompt);
+    content = response.content;
+  } catch (error) {
+    options.onOutcome?.({ outcome: "transport_failed", kind: classifyProviderError(error) });
+    return [];
+  }
+
+  const data = parseJsonResponse(content);
+  if (!Array.isArray(data)) {
+    options.onOutcome?.({ outcome: "parse_failed" });
+    return [];
+  }
+
+  const results: ConsolidationRow[] = [];
+  for (const item of data) {
+    if (!isRecord(item)) continue;
+    const observation = typeof item.observation === "string" ? item.observation.trim() : "";
+    if (!observation) continue;
+    const title = typeof item.title === "string" ? item.title.trim() : "Shadow observation";
+    const memoryIds = Array.isArray(item.memory_ids)
+      ? item.memory_ids.map((value) => String(value))
+      : [];
+    const evidenceNote = typeof item.evidence_note === "string" ? item.evidence_note.trim() : "";
+
+    const parts = [`**${title}**\n\n${observation}`];
+    if (evidenceNote) parts.push(`*Evidence: ${evidenceNote}*`);
+
+    results.push({
+      id: options.id(),
+      action: "shadow_observation",
+      proposal: parts.join("\n\n"),
+      result: null,
+      source_memory_ids: JSON.stringify(memoryIds),
+      target_layer: "shadow",
+      target_key: "profile",
+      rationale: title,
+      status: "pending",
+      created_at: options.nowIso(),
+      reviewed_at: null,
+    });
+  }
+  options.onOutcome?.({ outcome: results.length > 0 ? "answered" : "empty" });
+  return results;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/ts/src/cultivation/scan.ts

@@ -0,0 +1,155 @@
+// `consolidate scan` / `shadow scan` orchestration (CV22.DS7.US3 Slice B):
+// cluster (deterministic) -> propose (LLM call, replay-gated) -> store.
+// Ports `cli/consolidate_cmd.py:cmd_scan` and `cli/shadow_cmd.py:cmd_scan`'s
+// non-printing logic -- rendering is the front door's concern.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { listIdentityByLayer } from "#identity/identityRead.ts";
+import type { OnProviderCallOutcome } from "#observability/callOutcome.ts";
+import type { ChatLedgerHook } from "#observability/ledgerHooks.ts";
+import type { LlmProvider } from "#providers/llm.ts";
+import { clusterMemories, DEFAULT_CLUSTER_THRESHOLD } from "./cluster.ts";
+import {
+  type ConsolidationRow,
+  type CultivationMemoryWithEmbedding,
+  createConsolidation,
+  getMemoriesWithEmbeddingsForCultivation,
+  getShadowCandidateMemories,
+} from "./consolidationStore.ts";
+import { consolidationIdentityContext, cultivationUserName } from "./promptContext.ts";
+import { proposeConsolidation, proposeShadowObservations } from "./propose.ts";
+
+/** Mirrors `consolidate scan`'s `--limit` default (max proposals per run). */
+export const DEFAULT_CONSOLIDATE_SCAN_LIMIT = 5;
+
+/** Mirrors `shadow scan`'s `--limit` default (max shadow-candidate memories considered). */
+export const DEFAULT_SHADOW_SCAN_LIMIT = 50;
+
+export interface ConsolidateScanOptions {
+  journey?: string | null;
+  layer?: string | null;
+  /** Max proposals to generate (caps the cluster list before proposing, matching Python). */
+  limit?: number;
+  threshold?: number;
+  provider: LlmProvider;
+  /** Called once per cluster considered, matching Python's per-Consolidation `_uuid()`/`_now()`. */
+  id: () => string;
+  nowIso: () => string;
+  /** Ledger hook for the one `consolidation` call per cluster. */
+  onLlmCall?: ChatLedgerHook;
+  /** Per-cluster outcome, category only; see `observability/callOutcome.ts`. */
+  onOutcome?: OnProviderCallOutcome;
+}
+
+/** One attempted cluster's outcome, in scan order -- `proposal: null` is
+ * Python's "LLM returned no valid proposal for cluster of N memories" branch. */
+export interface ConsolidateScanClusterOutcome {
+  cluster: CultivationMemoryWithEmbedding[];
+  proposal: ConsolidationRow | null;
+}
+
+export interface ConsolidateScanResult {
+  memoriesScanned: number;
+  /** Capped at `limit` (Python slices `clusters[:limit]` BEFORE proposing), in order. */
+  results: ConsolidateScanClusterOutcome[];
+}
+
+/** Convenience projection: only the clusters that actually produced a stored proposal. */
+export function createdProposals(result: ConsolidateScanResult): ConsolidationRow[] {
+  return result.results.flatMap((r) => (r.proposal ? [r.proposal] : []));
+}
+
+/**
+ * Port of `consolidate_cmd.cmd_scan`'s non-printing logic: read
+ * embedded memories (filtered), cluster them, cap at `limit`, propose one
+ * Consolidation per cluster, and persist every non-null proposal. A cluster
+ * whose proposal comes back `null` (LLM failure, unparsable JSON, disallowed
+ * action, or empty content) is reported as `proposal: null` -- exactly like
+ * Python's "LLM returned no valid proposal" branch, which does not store
+ * anything for that cluster and moves on, but still renders a line for it.
+ */
+export async function consolidateScan(
+  db: WritableDatabase,
+  options: ConsolidateScanOptions,
+): Promise<ConsolidateScanResult> {
+  const memories = getMemoriesWithEmbeddingsForCultivation(db, {
+    journey: options.journey,
+    layer: options.layer,
+  });
+  if (memories.length === 0) {
+    return { memoriesScanned: 0, results: [] };
+  }
+
+  const allClusters = clusterMemories(memories, options.threshold ?? DEFAULT_CLUSTER_THRESHOLD);
+  const clusters = allClusters.slice(0, options.limit ?? DEFAULT_CONSOLIDATE_SCAN_LIMIT);
+
+  // Resolved once per scan, after the cluster cap and before the loop --
+  // where `cmd_scan` resolves them (CV22.DS8.TS2).
+  const userName = cultivationUserName(db);
+  const identityContext = consolidationIdentityContext(db);
+
+  const results: ConsolidateScanClusterOutcome[] = [];
+  for (const cluster of clusters) {
+    const proposal = await proposeConsolidation(options.provider, cluster, {
+      id: options.id(),
+      nowIso: options.nowIso(),
+      userName,
+      identityContext,
+      onLlmCall: options.onLlmCall,
+      onOutcome: options.onOutcome,
+    });
+    if (proposal === null) {
+      results.push({ cluster, proposal: null });
+      continue;
+    }
+    results.push({ cluster, proposal: createConsolidation(db, proposal) });
+  }
+
+  return { memoriesScanned: memories.length, results };
+}
+
+export interface ShadowScanOptions {
+  limit?: number;
+  provider: LlmProvider;
+  /** Ledger hook for the one `shadow_scan` call; Python always passes one. */
+  onLlmCall?: ChatLedgerHook;
+  /** Outcome of the one call, category only. */
+  onOutcome?: OnProviderCallOutcome;
+  /** Called once per emitted observation, matching Python's per-item `_uuid()`/`_now()`. */
+  id: () => string;
+  nowIso: () => string;
+}
+
+export interface ShadowScanResult {
+  candidatesConsidered: number;
+  proposalsCreated: ConsolidationRow[];
+}
+
+/**
+ * Port of `shadow_cmd.cmd_scan`'s non-printing logic: read shadow-candidate
+ * memories and the current structural shadow layer, propose observations over
+ * the FULL pool in one call, and persist every emitted proposal.
+ */
+export async function shadowScan(
+  db: WritableDatabase,
+  options: ShadowScanOptions,
+): Promise<ShadowScanResult> {
+  const memories = getShadowCandidateMemories(db, {
+    limit: options.limit ?? DEFAULT_SHADOW_SCAN_LIMIT,
+  });
+  const shadowEntries = listIdentityByLayer(db, "shadow").map((row) => ({
+    key: row.key,
+    content: row.content,
+  }));
+
+  const proposals = await proposeShadowObservations(options.provider, memories, shadowEntries, {
+    id: options.id,
+    nowIso: options.nowIso,
+    userName: cultivationUserName(db),
+    onLlmCall: options.onLlmCall,
+    onOutcome: options.onOutcome,
+  });
+
+  const proposalsCreated = proposals.map((proposal) => createConsolidation(db, proposal));
+  return { candidatesConsidered: memories.length, proposalsCreated };
+}

package/ts/src/db/backupGate.ts

@@ -0,0 +1,47 @@
+// Backup gate for destructive write-parity runs.
+//
+// The copy-only guard (`copyGuard.ts`) keeps writes off the live database; this
+// gate adds the second half of the discipline: a hash-verified backup of the
+// source must exist before any destructive apply. The harness refuses to run if
+// the recorded backup is missing or its bytes have changed, so a parity run is
+// always recoverable.
+
+import { createHash } from "node:crypto";
+import { lstatSync, readFileSync } from "node:fs";
+
+/** Raised when the required pre-write backup is missing or altered. */
+export class BackupGateError extends Error {}
+
+/** A recorded backup: a file path and the sha256 of its bytes when recorded. */
+export interface BackupRecord {
+  path: string;
+  sha256: string;
+}
+
+/** Hash a file's bytes as lowercase-hex sha256. */
+export function sha256File(path: string): string {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+/**
+ * Require a present, hash-verified backup before any destructive apply. The
+ * recorded path must be a regular file — a symlinked backup could be
+ * redirected after verification, so indirection is refused (CR030).
+ */
+export function requireBackup(backup: BackupRecord | undefined): void {
+  if (!backup?.path) {
+    throw new BackupGateError("no backup recorded before a destructive write");
+  }
+  let isRegularFile: boolean;
+  try {
+    isRegularFile = lstatSync(backup.path).isFile();
+  } catch {
+    throw new BackupGateError(`recorded backup is missing: ${backup.path}`);
+  }
+  if (!isRegularFile) {
+    throw new BackupGateError(`recorded backup is not a regular file: ${backup.path}`);
+  }
+  if (sha256File(backup.path) !== backup.sha256) {
+    throw new BackupGateError("recorded backup hash does not match the backup file");
+  }
+}

package/ts/src/db/bootstrap.ts

@@ -0,0 +1,108 @@
+// Bootstrap authority — CV22.DS6.TS3.
+//
+// TS equivalent of Python's `src/memory/db/connection.py::get_connection`.
+// Composes TS1's `createSchema` and TS2's `runMigrations` behind the
+// cross-process bootstrap lock (`bootstrapLock.ts`) and Python's exact pragma
+// ordering, so a TS-only process can create and migrate `memory.db` safely —
+// including under concurrent bootstrap attempts from multiple processes.
+//
+// Pragma ordering matches Python precisely and is load-bearing:
+//   connect -> busy_timeout -> foreign_keys -> WAL -> run_migrations -> SCHEMA
+// `journal_mode=WAL` must be set outside any transaction and before
+// migrations run (each migration commits via `withTransaction`; switching
+// journal mode inside a transaction is refused by SQLite).
+
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+import { acquireBootstrapLock, type BootstrapLockOptions } from "./bootstrapLock.ts";
+import { type OpenOptions, openDatabaseForBootstrap, type WritableDatabase } from "./database.ts";
+import { runMigrations } from "./migrations.ts";
+import { createSchema } from "./schema.ts";
+
+export interface BootstrapOptions extends OpenOptions, BootstrapLockOptions {}
+
+function ensureWalMode(db: WritableDatabase): void {
+  const row = db.prepare("PRAGMA journal_mode").get() as { journal_mode?: string } | undefined;
+  const current = (row?.journal_mode ?? "").toLowerCase();
+  if (current !== "wal") {
+    db.exec("PRAGMA journal_mode=WAL");
+  }
+}
+
+/** Owner-only posture (0600) for the database file and its WAL sidecars. A
+ * missing sidecar (e.g. no writes have happened yet) is not an error. */
+function chmodOwnerOnly(dbPath: string): void {
+  for (const path of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+    try {
+      chmodSync(path, 0o600);
+    } catch {
+      // Sidecar absent, or filesystem does not support POSIX modes — Python's
+      // own posture is best-effort here too (`contextlib.suppress(OSError)`).
+    }
+  }
+}
+
+/**
+ * Bootstrap `dbPath`: create the parent directory (owner-only if we create
+ * it — an existing directory is never mutated, matching Python), acquire the
+ * cross-process lock, apply pragma discipline, run migrations, and create any
+ * missing schema. Idempotent and safe to call repeatedly — every step it
+ * composes (pragmas, `runMigrations`, `createSchema`) is a no-op against an
+ * already-current database.
+ *
+ * Returns the open, bootstrapped connection — callers should use it directly
+ * rather than reopening, exactly as Python's `get_connection` returns the
+ * connection it just bootstrapped.
+ */
+export function bootstrapDatabase(
+  dbPath: string,
+  options: BootstrapOptions = {},
+): WritableDatabase {
+  const parentDir = dirname(dbPath);
+  const parentPreexisting = existsSync(parentDir);
+  mkdirSync(parentDir, { recursive: true });
+  if (!parentPreexisting) {
+    try {
+      chmodSync(parentDir, 0o700);
+    } catch {
+      // Best-effort, matching Python's `contextlib.suppress(OSError)`.
+    }
+  }
+
+  const lock = acquireBootstrapLock(dbPath, options);
+  let db: WritableDatabase;
+  try {
+    db = openDatabaseForBootstrap(dbPath, options);
+    // busy_timeout + foreign_keys are already applied by openDatabaseForBootstrap
+    // (shared `applyConnectionPragmas`); WAL is bootstrap-specific because it
+    // must run outside a transaction and only needs setting once per file.
+    ensureWalMode(db);
+    runMigrations(db);
+    createSchema(db);
+  } finally {
+    lock.release();
+  }
+
+  chmodOwnerOnly(dbPath);
+  return db;
+}
+
+/**
+ * Ensure a bootstrapped database exists at `dbPath` (CV22.DS6.TS4). When the
+ * file is absent, create and migrate it through {@link bootstrapDatabase} under
+ * the cross-process lock, then close the connection so the caller can reopen in
+ * the exact mode it needs — read-only serving, or the backup-gated live-write
+ * seam. When the file already exists this is a cheap `existsSync` no-op, so the
+ * per-command hot path never pays for a lock acquire.
+ *
+ * This is the front door's first-run seam: it replaces the DS2/DS3 stopgap that
+ * delegated a missing database to Python to bootstrap. Concurrency-safe by
+ * construction — the underlying bootstrap is lock-guarded and idempotent, so
+ * even if the file appears between the check here and the call, the work is a
+ * safe no-op rather than a double-apply.
+ */
+export function bootstrapDatabaseIfMissing(dbPath: string, options: BootstrapOptions = {}): void {
+  if (existsSync(dbPath)) return;
+  bootstrapDatabase(dbPath, options).close();
+}