ndomo 0.1.0

package/src/db/analyses.ts

@@ -0,0 +1,375 @@
+/**
+ * ndomo DB — Analysis CRUD with FTS5 search.
+ *
+ * All functions take a Database instance and return camelCase TS types.
+ * Uses TEXT timestamps (ISO datetime) unlike INTEGER epoch in other tables.
+ */
+
+import type { Database } from "bun:sqlite";
+import { randomUUID } from "node:crypto";
+import { escapeFtsQuery } from "./fts-escape.ts";
+import type { Analysis, InsertAnalysis } from "./types.ts";
+import { analysisFromRow } from "./types.ts";
+
+// ─── Validation helpers ─────────────────────────────────────────────────────
+
+function validateSlug(slug: string): void {
+  if (!slug || slug.trim().length === 0) {
+    throw new Error("ndomo: analysis slug cannot be empty");
+  }
+}
+
+function validateProjectPath(projectPath: string): void {
+  if (!projectPath || projectPath.trim().length === 0) {
+    throw new Error("ndomo: analysis projectPath cannot be empty");
+  }
+}
+
+/**
+ * Agent-aware validation of analysis findings JSON.
+ *
+ * Boundary policy (ndomo agent contract):
+ *  - `ranger` emits observation-only findings (factual, descriptive).
+ *    Rangers MUST NOT include `proposedAction` because they lack decision authority.
+ *  - `foreman` and other decision-capable agents MAY include `proposedAction`.
+ *
+ * Behavior:
+ *  - If findingsJson is undefined → no-op (field not being set).
+ *  - If findingsJson is not valid JSON → no-op (let the existing JSON.parse
+ *    in the tool layer surface the parse error). This helper focuses on the
+ *    semantic boundary check, not syntax.
+ *  - If findingsJson parses to a non-array (or empty array) → no-op.
+ *  - If agent === 'ranger' AND any parsed finding has a `proposedAction` key
+ *    → throw a clear validation error.
+ *
+ * Pure: no DB access. Safe to call from plugin.ts tool handlers before write.
+ */
+export function validateAnalysisFindings(
+  findingsJson: string | undefined,
+  agent: string | undefined,
+): void {
+  if (findingsJson === undefined) return;
+  if (agent !== "ranger") return;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(findingsJson);
+  } catch {
+    // Defer parse errors to the JSON.parse call in the tool handler.
+    return;
+  }
+  if (!Array.isArray(parsed) || parsed.length === 0) return;
+
+  for (const item of parsed) {
+    if (item !== null && typeof item === "object" && "proposedAction" in item) {
+      throw new Error(
+        "ndomo: ranger cannot emit proposedAction on analysis findings (observation-only contract); foreman/decision-capable agents only",
+      );
+    }
+  }
+}
+
+// ─── CRUD ───────────────────────────────────────────────────────────────────
+
+/**
+ * Create a new analysis. Validates slug uniqueness per project_path.
+ * Throws if slug already exists for the same project_path.
+ */
+export function createAnalysis(db: Database, input: InsertAnalysis): Analysis {
+  validateSlug(input.slug);
+  validateProjectPath(input.projectPath);
+
+  const id = randomUUID();
+  const slug = input.slug.trim();
+  const title = input.title.trim();
+  const projectPath = input.projectPath.trim();
+  const summary = input.summary?.trim() ?? "";
+  const findingsJson = input.findingsJson ?? "[]";
+  const agent = input.agent ?? "ranger";
+
+  // Check uniqueness (slug, project_path)
+  const existing = db
+    .query("SELECT id FROM analyses WHERE slug = ? AND project_path = ?")
+    .get(slug, projectPath) as { id: string } | null;
+  if (existing) {
+    throw new Error(
+      `ndomo: analysis with slug '${slug}' already exists for project '${projectPath}'`,
+    );
+  }
+
+  db.query(
+    `INSERT INTO analyses (id, slug, title, project_path, summary, findings_json, source_plan_id, agent, session_id, created_by)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    id,
+    slug,
+    title,
+    projectPath,
+    summary,
+    findingsJson,
+    input.sourcePlanId ?? null,
+    agent,
+    input.sessionId ?? null,
+    input.createdBy ?? null,
+  );
+
+  return getAnalysis(db, id)!;
+}
+
+/**
+ * Get analysis by id. Returns null if not found or archived.
+ * Set includeArchived=true to include soft-deleted.
+ */
+export function getAnalysis(
+  db: Database,
+  id: string,
+  opts?: { includeArchived?: boolean },
+): Analysis | null {
+  const includeArchived = opts?.includeArchived ?? false;
+  const sql = includeArchived
+    ? "SELECT * FROM analyses WHERE id = ?"
+    : "SELECT * FROM analyses WHERE id = ? AND archived_at IS NULL";
+  const row = db.query(sql).get(id);
+  return row ? analysisFromRow(row) : null;
+}
+
+/**
+ * Get analysis by slug + project_path. Returns null if not found.
+ */
+export function getAnalysisBySlug(
+  db: Database,
+  slug: string,
+  projectPath: string,
+  opts?: { includeArchived?: boolean },
+): Analysis | null {
+  const includeArchived = opts?.includeArchived ?? false;
+  const sql = includeArchived
+    ? "SELECT * FROM analyses WHERE slug = ? AND project_path = ?"
+    : "SELECT * FROM analyses WHERE slug = ? AND project_path = ? AND archived_at IS NULL";
+  const row = db.query(sql).get(slug, projectPath);
+  return row ? analysisFromRow(row) : null;
+}
+
+/**
+ * List analyses with optional filters.
+ */
+export function listAnalyses(
+  db: Database,
+  filters?: {
+    sourcePlanId?: string;
+    agent?: string;
+    archived?: boolean;
+    projectPath?: string;
+    limit?: number;
+  },
+): Analysis[] {
+  const clauses: string[] = [];
+  const params: (string | number)[] = [];
+
+  if (filters?.sourcePlanId) {
+    clauses.push("source_plan_id = ?");
+    params.push(filters.sourcePlanId);
+  }
+  if (filters?.agent) {
+    clauses.push("agent = ?");
+    params.push(filters.agent);
+  }
+  if (filters?.projectPath) {
+    clauses.push("project_path = ?");
+    params.push(filters.projectPath);
+  }
+  if (!filters?.archived) {
+    clauses.push("archived_at IS NULL");
+  }
+
+  const where = clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : "";
+  const limit = filters?.limit ?? 50;
+  params.push(limit);
+
+  const rows = db
+    .query(`SELECT * FROM analyses ${where} ORDER BY created_at DESC LIMIT ?`)
+    .all(...params);
+  return (rows as unknown[]).map(analysisFromRow);
+}
+
+/**
+ * FTS5 search over title+summary+findings_json.
+ * Uses escapeFtsQuery to safely wrap query terms.
+ */
+export function searchAnalyses(
+  db: Database,
+  query: string,
+  filters?: {
+    sourcePlanId?: string;
+    agent?: string;
+    archived?: boolean;
+    limit?: number;
+  },
+): Analysis[] {
+  const clauses: string[] = [];
+  const params: (string | number)[] = [];
+
+  if (filters?.sourcePlanId) {
+    clauses.push("a.source_plan_id = ?");
+    params.push(filters.sourcePlanId);
+  }
+  if (filters?.agent) {
+    clauses.push("a.agent = ?");
+    params.push(filters.agent);
+  }
+  if (!filters?.archived) {
+    clauses.push("a.archived_at IS NULL");
+  }
+
+  const extraWhere = clauses.length > 0 ? `AND ${clauses.join(" AND ")}` : "";
+  const limit = filters?.limit ?? 20;
+  params.push(limit);
+
+  const rows = db
+    .query(
+      `SELECT a.* FROM analyses a
+       JOIN analyses_fts fts ON a.rowid = fts.rowid
+       WHERE analyses_fts MATCH ?
+       ${extraWhere}
+       ORDER BY rank
+       LIMIT ?`,
+    )
+    .all(escapeFtsQuery(query), ...params);
+  return (rows as unknown[]).map(analysisFromRow);
+}
+
+/**
+ * Update analysis fields. Returns updated analysis.
+ * Automatically bumps updated_at. Throws if analysis not found.
+ */
+export function updateAnalysis(
+  db: Database,
+  id: string,
+  updates: Partial<InsertAnalysis>,
+): Analysis {
+  const existing = getAnalysis(db, id);
+  if (!existing) {
+    throw new Error(`ndomo: analysis '${id}' not found`);
+  }
+
+  const setClauses: string[] = [];
+  const params: (string | null)[] = [];
+
+  if (updates.slug !== undefined) {
+    validateSlug(updates.slug);
+    setClauses.push("slug = ?");
+    params.push(updates.slug.trim());
+  }
+  if (updates.title !== undefined) {
+    setClauses.push("title = ?");
+    params.push(updates.title.trim());
+  }
+  if (updates.projectPath !== undefined) {
+    validateProjectPath(updates.projectPath);
+    setClauses.push("project_path = ?");
+    params.push(updates.projectPath.trim());
+  }
+  if (updates.summary !== undefined) {
+    setClauses.push("summary = ?");
+    params.push(updates.summary);
+  }
+  if (updates.findingsJson !== undefined) {
+    setClauses.push("findings_json = ?");
+    params.push(updates.findingsJson);
+  }
+  if (updates.sourcePlanId !== undefined) {
+    setClauses.push("source_plan_id = ?");
+    params.push(updates.sourcePlanId ?? null);
+  }
+  if (updates.agent !== undefined) {
+    setClauses.push("agent = ?");
+    params.push(updates.agent);
+  }
+  if (updates.sessionId !== undefined) {
+    setClauses.push("session_id = ?");
+    params.push(updates.sessionId ?? null);
+  }
+  if (updates.createdBy !== undefined) {
+    setClauses.push("created_by = ?");
+    params.push(updates.createdBy ?? null);
+  }
+
+  if (setClauses.length === 0) return existing; // no-op
+
+  // Always bump updated_at
+  setClauses.push("updated_at = datetime('now')");
+  params.push(id);
+
+  db.query(
+    `UPDATE analyses SET ${setClauses.join(", ")} WHERE id = ?`,
+  ).run(...params);
+
+  return getAnalysis(db, id)!;
+}
+
+/**
+ * Soft-delete: set archived_at to current timestamp.
+ */
+export function archiveAnalysis(db: Database, id: string): Analysis {
+  const existing = getAnalysis(db, id, { includeArchived: true });
+  if (!existing) {
+    throw new Error(`ndomo: analysis '${id}' not found`);
+  }
+  // Idempotent: if already archived, just return
+  if (existing.archivedAt) return existing;
+
+  db.query(
+    "UPDATE analyses SET archived_at = datetime('now'), updated_at = datetime('now') WHERE id = ?",
+  ).run(id);
+
+  return getAnalysis(db, id, { includeArchived: true })!;
+}
+
+/**
+ * Link analysis to a plan (set source_plan_id).
+ * Use when analysis is created standalone and later linked to a plan.
+ */
+export function linkAnalysisToPlan(
+  db: Database,
+  id: string,
+  planId: string,
+): Analysis {
+  const existing = getAnalysis(db, id);
+  if (!existing) {
+    throw new Error(`ndomo: analysis '${id}' not found`);
+  }
+
+  // FK enforces plan existence, but validate at app level for better error message
+  const plan = db.query("SELECT id FROM plans WHERE id = ?").get(planId) as
+    | { id: string }
+    | null;
+  if (!plan) {
+    throw new Error(`ndomo: plan '${planId}' not found (FK violation)`);
+  }
+
+  db.query(
+    "UPDATE analyses SET source_plan_id = ?, updated_at = datetime('now') WHERE id = ?",
+  ).run(planId, id);
+
+  return getAnalysis(db, id)!;
+}
+
+/**
+ * Unlink analysis from its source plan (set source_plan_id to NULL).
+ * Idempotent: if already unlinked, just returns the analysis.
+ */
+export function unlinkAnalysisFromPlan(
+  db: Database,
+  id: string,
+): Analysis {
+  const existing = getAnalysis(db, id);
+  if (!existing) {
+    throw new Error(`ndomo: analysis '${id}' not found`);
+  }
+
+  db.query(
+    "UPDATE analyses SET source_plan_id = NULL, updated_at = datetime('now') WHERE id = ?",
+  ).run(id);
+
+  return getAnalysis(db, id)!;
+}

package/src/db/auto-checkpoint.ts

@@ -0,0 +1,131 @@
+/**
+ * ndomo DB — Auto-checkpoint dispatcher.
+ *
+ * Captures orchestrator state into session checkpoints on configurable
+ * triggers (phase_transition, task_batch_complete). Debounced, async,
+ * loop-safe.
+ */
+
+import type { Database } from "bun:sqlite"
+import { getPlan } from "./plans.ts"
+import { checkpointSession, ensureSession } from "./sessions.ts"
+import { listTasksByPlan } from "./tasks.ts"
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface AutoCheckpointConfig {
+  enabled?: boolean
+  triggers?: string[]
+  minIntervalMs?: number
+  captureState?: {
+    completedTasks?: boolean
+    currentPhase?: boolean
+    blockers?: boolean
+  }
+}
+
+export interface AutoCheckpointContext {
+  planId?: string
+  sessionId?: string
+  blockers?: string[] | undefined
+}
+
+// ─── Defaults ───────────────────────────────────────────────────────────────
+
+const DEFAULT_ENABLED = true
+const DEFAULT_TRIGGERS = ["phase_transition", "task_batch_complete"]
+const DEFAULT_MIN_INTERVAL_MS = 30_000
+const DEFAULT_CAPTURE_COMPLETED = true
+const DEFAULT_CAPTURE_PHASE = true
+const DEFAULT_CAPTURE_BLOCKERS = true
+
+// ─── Dispatcher ─────────────────────────────────────────────────────────────
+
+/**
+ * Async, debounced checkpoint dispatcher.
+ *
+ * Instantiate with a Database + optional config. Call `dispatch()` from
+ * tool executors after a successful state mutation. The actual
+ * `checkpointSession` call runs in a microtask (non-blocking) with
+ * error swallowing so it never breaks the caller.
+ *
+ * Loop prevention: an `isAutoCheckpointing` flag prevents re-entrant
+ * dispatch. Since `checkpointSession` only writes to the sessions
+ * table (not plans/tasks), loops are structurally impossible — but the
+ * flag is a safety net.
+ */
+export class AutoCheckpointDispatcher {
+  private lastCheckpointAt = 0
+  private isAutoCheckpointing = false
+
+  private readonly enabled: boolean
+  private readonly triggers: Set<string>
+  private readonly minIntervalMs: number
+  private readonly captureCompleted: boolean
+  private readonly capturePhase: boolean
+  private readonly captureBlockers: boolean
+  private readonly db: Database
+
+  constructor(db: Database, config?: AutoCheckpointConfig) {
+    this.db = db
+    this.enabled = config?.enabled ?? DEFAULT_ENABLED
+    this.triggers = new Set(config?.triggers ?? DEFAULT_TRIGGERS)
+    this.minIntervalMs = config?.minIntervalMs ?? DEFAULT_MIN_INTERVAL_MS
+    this.captureCompleted = config?.captureState?.completedTasks ?? DEFAULT_CAPTURE_COMPLETED
+    this.capturePhase = config?.captureState?.currentPhase ?? DEFAULT_CAPTURE_PHASE
+    this.captureBlockers = config?.captureState?.blockers ?? DEFAULT_CAPTURE_BLOCKERS
+  }
+
+  /**
+   * Fire an auto-checkpoint if conditions are met.
+   *
+   * Checks (in order): loop guard → enabled → trigger allowed → debounce → sessionId present.
+   * If all pass, schedules async checkpoint via microtask.
+   */
+  dispatch(trigger: string, ctx: AutoCheckpointContext): void {
+    if (this.isAutoCheckpointing) return
+    if (!this.enabled) return
+    if (!this.triggers.has(trigger)) return
+
+    const now = Date.now()
+    if (now - this.lastCheckpointAt < this.minIntervalMs) return
+    if (!ctx.sessionId) return
+
+    this.lastCheckpointAt = now
+    this.isAutoCheckpointing = true
+
+    // Async dispatch — does NOT block the caller
+    Promise.resolve().then(() => {
+      try {
+        ensureSession(this.db, ctx.sessionId!, "auto-checkpoint")
+
+        const state: Record<string, unknown> = { trigger }
+
+        if (ctx.planId) {
+          if (this.captureCompleted) {
+            const doneTasks = listTasksByPlan(this.db, ctx.planId, { status: "done" })
+            state.completedTasks = doneTasks.length
+          }
+          if (this.capturePhase) {
+            const plan = getPlan(this.db, ctx.planId)
+            state.currentPhase = plan?.status ?? "unknown"
+          }
+        }
+
+        if (this.captureBlockers && ctx.blockers && ctx.blockers.length > 0) {
+          state.blockers = ctx.blockers
+        }
+
+        checkpointSession(this.db, ctx.sessionId!, state)
+      } catch (err) {
+        // Auto-checkpoint must never break the caller
+        console.error(
+          "[ndomo] auto_checkpoint failed:",
+          err instanceof Error ? err.message : String(err),
+        )
+      } finally {
+        this.isAutoCheckpointing = false
+      }
+    })
+  }
+}

package/src/db/client.test.ts

@@ -0,0 +1,129 @@
+/**
+ * Tests for openDb() input validation — plan 4dc34202.
+ *
+ * Validates that openDb rejects invalid projectDir values (empty, "/",
+ * relative) with a clear Error BEFORE attempting mkdirSync, and that the
+ * happy path (valid absolute path from mkdtempSync) still creates
+ * `.ndomo/state.db` with foreign keys enabled.
+ */
+
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { closeDb, openDb } from "./client.ts";
+
+describe("openDb — input validation", () => {
+  test('openDb("") throws clear Error', () => {
+    expect(() => openDb("")).toThrow(/invalid projectDir/);
+  });
+
+  test('openDb("/") throws clear Error', () => {
+    expect(() => openDb("/")).toThrow(/invalid projectDir/);
+  });
+
+  test('openDb("./relative") throws clear Error', () => {
+    expect(() => openDb("./relative")).toThrow(/invalid projectDir/);
+  });
+
+  test("openDb rejects other relative paths", () => {
+    expect(() => openDb("relative/no-slash")).toThrow(/invalid projectDir/);
+    expect(() => openDb("../parent")).toThrow(/invalid projectDir/);
+  });
+
+  test("error message includes the offending value for debuggability", () => {
+    try {
+      openDb("/");
+      expect.unreachable("should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(Error);
+      expect((err as Error).message).toContain('"/"');
+      expect((err as Error).message).toContain("absolute");
+    }
+  });
+});
+
+describe("openDb — happy path", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "ndomo-client-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("openDb(valid absolute path) creates .ndomo/state.db", () => {
+    const db = openDb(tmpDir);
+    const dbPath = join(tmpDir, ".ndomo", "state.db");
+    expect(existsSync(dbPath)).toBe(true);
+    closeDb(db);
+  });
+
+  test("openDb enables PRAGMA foreign_keys = ON", () => {
+    const db = openDb(tmpDir);
+    const fk = db.query("PRAGMA foreign_keys").get() as Record<string, unknown> | null;
+    expect(fk).not.toBeNull();
+    expect(fk?.foreign_keys).toBe(1);
+    closeDb(db);
+  });
+
+  test("openDb is idempotent — second call reuses existing .ndomo dir", () => {
+    const db1 = openDb(tmpDir);
+    closeDb(db1);
+    // Second call on same dir should not throw (mkdirSync recursive is idempotent)
+    const db2 = openDb(tmpDir);
+    const dbPath = join(tmpDir, ".ndomo", "state.db");
+    expect(existsSync(dbPath)).toBe(true);
+    closeDb(db2);
+  });
+});
+
+describe("openDb — PRAGMA config (plan fcb12dc5 #4)", () => {
+  let tmpDir: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "ndomo-pragma-test-"));
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test("PRAGMA journal_mode = WAL (sticky, applies to file-based DBs)", () => {
+    const db = openDb(tmpDir);
+    const result = db.query("PRAGMA journal_mode").get() as Record<string, unknown> | null;
+    expect(result).not.toBeNull();
+    expect(result?.journal_mode).toBe("wal");
+    closeDb(db);
+  });
+
+  test("PRAGMA synchronous = NORMAL (safe with WAL, faster than FULL)", () => {
+    const db = openDb(tmpDir);
+    const result = db.query("PRAGMA synchronous").get() as Record<string, unknown> | null;
+    expect(result).not.toBeNull();
+    // SQLite reports 0=OFF, 1=NORMAL, 2=FULL
+    expect(Number(result?.synchronous)).toBe(1);
+    closeDb(db);
+  });
+
+  test("PRAGMA auto_vacuum = INCREMENTAL (prevents unbounded growth)", () => {
+    const db = openDb(tmpDir);
+    const result = db.query("PRAGMA auto_vacuum").get() as Record<string, unknown> | null;
+    expect(result).not.toBeNull();
+    // SQLite reports 0=NONE, 1=FULL, 2=INCREMENTAL
+    expect(Number(result?.auto_vacuum)).toBe(2);
+    closeDb(db);
+  });
+
+  test("PRAGMA settings persist across reopen (sticky migration)", () => {
+    const db1 = openDb(tmpDir);
+    closeDb(db1);
+    // Reopen — journal_mode is sticky in DB file
+    const db2 = openDb(tmpDir);
+    const journal = db2.query("PRAGMA journal_mode").get() as Record<string, unknown> | null;
+    expect(journal?.journal_mode).toBe("wal");
+    closeDb(db2);
+  });
+});

package/src/db/client.ts

@@ -0,0 +1,55 @@
+/**
+ * ndomo DB — SQLite client factory.
+ *
+ * Creates a project-level database in `.ndomo/state.db`.
+ * Uses bun:sqlite (built-in, zero deps).
+ *
+ * NOTE on "async" terminology: bun:sqlite ops are SYNCHRONOUS (no async I/O).
+ * In ndomo architecture, "async" refers to inter-agent coordination via DB
+ * state + manual TUI switch between primaries (foreman↔craftsman), NOT to
+ * async database I/O. All db.exec / db.prepare / stmt.run calls are sync.
+ */
+
+import { Database } from "bun:sqlite";
+import { mkdirSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+
+const NDOMO_DIR = ".ndomo";
+const DB_FILE = "state.db";
+
+export function openDb(projectDir: string): Database {
+  // Defensive validation: reject paths that would place .ndomo at the
+  // filesystem root (e.g. projectDir="/" → "/.ndomo" → EACCES) or relative
+  // paths that resolve against CWD unpredictably. See plan
+  // 4dc34202 (harden-open-db-path-validation).
+  if (projectDir === "" || projectDir === "/" || !isAbsolute(projectDir)) {
+    throw new Error(
+      `openDb: invalid projectDir ${JSON.stringify(projectDir)} — must be a non-root absolute path (e.g. /home/user/project). Received "/" or a relative path would create ".ndomo" at the filesystem root or an unpredictable CWD-relative location.`,
+    );
+  }
+  const dir = join(projectDir, NDOMO_DIR);
+  mkdirSync(dir, { recursive: true });
+  const path = join(dir, DB_FILE);
+  const db = new Database(path, { create: true });
+  // Enable foreign key enforcement (OFF by default in SQLite/bun:sqlite)
+  db.exec("PRAGMA foreign_keys = ON");
+  // INCREMENTAL auto_vacuum — reclaims space from deleted rows on demand via
+  // PRAGMA incremental_vacuum (run by `ndomo vacuum` CLI). Prevents unbounded
+  // growth of .ndomo/state.db on long-running installs (audit fcb12dc5 #4).
+  // NOTE: must be set BEFORE journal_mode = WAL — SQLite/bun:sqlite silently
+  // ignores auto_vacuum when set after WAL is enabled on a fresh DB. Empirically
+  // confirmed via /tmp/test-combo.ts (2026-06-23, plan fcb12dc5).
+  db.exec("PRAGMA auto_vacuum = INCREMENTAL");
+  // WAL journal mode — better concurrency, persistent across opens (sticky
+  // in DB file). For long-running installs this prevents the .ndomo/state.db
+  // from blocking readers while a writer is active.
+  db.exec("PRAGMA journal_mode = WAL");
+  // NORMAL synchronous — safe with WAL (durability on checkpoint, not on every
+  // commit). Faster than FULL on write-heavy workloads.
+  db.exec("PRAGMA synchronous = NORMAL");
+  return db;
+}
+
+export function closeDb(db: Database): void {
+  db.close();
+}