akm-cli 0.9.0-beta.45 → 0.9.0-beta.47

package/dist/core/state-db.js

@@ -12,12 +12,12 @@
  *
  * ## Why a separate database from index.db
  *
- * index.db uses a single DB_VERSION integer: when the version changes it drops
- * ALL tables and recreates them. That is acceptable for the search index because
- * every entry is fully regenerable from the stash on disk. Events, proposals, and
- * task history are NON-REGENERABLE — losing them is data loss. They must live in
- * a database whose schema evolves via incremental, additive migrations that never
- * drop rows.
+ * index.db is a derived cache built by an idempotent baseline schema; it is fully
+ * regenerable from the stash on disk, so a corrupt index is recovered by deleting
+ * it and re-running `akm index` (no destructive version-bump rebuild). Events,
+ * proposals, and task history are NON-REGENERABLE — losing them is data loss. They
+ * must live in a database whose schema evolves via incremental, additive migrations
+ * that never drop rows.
  *
  * ## Migration-safety contract
  *
@@ -49,11 +49,8 @@
  *
  * @module state-db
  */
-import fs from "node:fs";
 import path from "node:path";
-import { openDatabase } from "../storage/database.js";
-import { runMigrations as runSqliteMigrations } from "../storage/engines/sqlite-migrations.js";
-import { applyStandardPragmas } from "../storage/sqlite-pragmas.js";
+import { openManagedDatabase, withManagedDb, withManagedDbAsync } from "../storage/managed-db.js";
 import { classifyImproveAction } from "./improve-types.js";
 import { getDataDir } from "./paths.js";
 import { error } from "./warn.js";
@@ -95,739 +92,33 @@ export function getStateDbPath() {
  *     narrow when a post-inference reindex overlapped a parallel event write.
  */
 export function openStateDatabase(dbPath) {
-    const resolvedPath = dbPath ?? getStateDbPath();
-    const dir = path.dirname(resolvedPath);
-    if (!fs.existsSync(dir)) {
-        fs.mkdirSync(dir, { recursive: true });
-    }
-    const db = openDatabase(resolvedPath);
-    // PRAGMAs must run before any DDL or DML.
-    applyStandardPragmas(db, { dataDir: dir });
-    runMigrations(db);
-    return db;
+    return openManagedDatabase({ path: dbPath ?? getStateDbPath(), init: runMigrations });
 }
-// ── Migration engine ─────────────────────────────────────────────────────────
-//
-// The runner itself (ensureMigrationsTable + runMigrations) lives in the shared
-// engine at src/storage/engines/sqlite-migrations.ts. This module owns only its
-// own MIGRATIONS array and delegates application to that shared runner. The
-// {@link Migration} interface is imported from there.
 /**
- * All migrations in application order. New migrations are APPENDED to this
- * array — never inserted in the middle or reordered.
- *
- * @see Migration
+ * Run `fn` against state.db, owning the handle unless one is borrowed. The loan
+ * helper for state.db, mirroring `withIndexDb` / `withWorkflowRunsRepo`. Pass
+ * `{ borrowed: ctx?.db }` to reuse an already-open run-scoped handle rather than
+ * opening + closing a fresh one — this replaces the hand-rolled
+ * `ctx?.db ?? open()` + `ownsDb` flag + `finally`/close idiom at call sites.
  */
-const MIGRATIONS = [
-    // ── Migration 001 — initial schema ──────────────────────────────────────────
-    {
-        id: "001-initial-schema",
-        up: `
-      -- ── events ──────────────────────────────────────────────────────────────
-      --
-      -- Replaces events.jsonl. Indexed (query) columns:
-      --   id          INTEGER PK — monotonic rowid; replaces byte-offset cursor.
-      --                            Callers store this as "sinceId" for resume.
-      --   event_type  TEXT        — indexed; replaces the type filter in readEvents().
-      --   ts          TEXT        — ISO-8601 UTC ms; indexed for range queries.
-      --   ref         TEXT        — nullable asset ref; indexed for ref-scoped queries.
-      --
-      -- Extensible (metadata_json) columns:
-      --   metadata_json TEXT      — JSON object storing all non-indexed payload
-      --                             fields (tags, any future structured fields).
-      --                             Maps directly to EventEnvelope.metadata.
-      --
-      -- schema_version mirrors EventEnvelope.schemaVersion — always 1 for v1
-      -- rows. Stored as a column (not in the JSON blob) so future schema
-      -- changes can be detected and migrated row-by-row if ever needed.
-      --
-      -- TTL: rows where ts < NOW() - 90 days can be deleted by a maintenance job.
-      -- No automatic deletion occurs here — callers call purgeOldEvents().
-      --
-      -- ADD COLUMN extension points (future migrations):
-      --   ALTER TABLE events ADD COLUMN stash_dir TEXT DEFAULT NULL;
-      --   ALTER TABLE events ADD COLUMN correlation_id TEXT DEFAULT NULL;
-      --   ALTER TABLE events ADD COLUMN schema_version INTEGER NOT NULL DEFAULT 1;
-      --
-      CREATE TABLE IF NOT EXISTS events (
-        id             INTEGER PRIMARY KEY AUTOINCREMENT,
-        event_type     TEXT    NOT NULL,
-        ts             TEXT    NOT NULL,
-        ref            TEXT,
-        metadata_json  TEXT    NOT NULL DEFAULT '{}'
-      );
-
-      -- Query patterns supported by these indexes:
-      --   SELECT … WHERE event_type = ?                 → idx_events_type
-      --   SELECT … WHERE ref = ?                        → idx_events_ref
-      --   SELECT … WHERE ts >= ? AND ts <= ?            → idx_events_ts
-      --   SELECT … WHERE event_type = ? AND ref = ?     → idx_events_type (prefix scan) + filter
-      --   SELECT … WHERE id > ?                         → PK (rowid) — no extra index needed
-      CREATE INDEX IF NOT EXISTS idx_events_type ON events(event_type);
-      CREATE INDEX IF NOT EXISTS idx_events_ref  ON events(ref);
-      CREATE INDEX IF NOT EXISTS idx_events_ts   ON events(ts);
-
-      -- ── proposals ────────────────────────────────────────────────────────────
-      --
-      -- Replaces per-uuid JSON directories under <stashDir>/.akm/proposals/.
-      --
-      -- Indexed (query) columns:
-      --   id          TEXT PK     — UUID (crypto.randomUUID()); stable directory name.
-      --   stash_dir   TEXT        — absolute stash root; multi-stash installs need
-      --                             this to partition proposal lists per stash.
-      --   ref         TEXT        — target asset ref (e.g. "lesson:alpha");
-      --                             indexed for ref-scoped queue views.
-      --   status      TEXT        — "pending" | "accepted" | "rejected"; indexed
-      --                             so pending-queue queries are fast.
-      --   source      TEXT        — human-readable origin tag (e.g. "reflect").
-      --   created_at  TEXT        — ISO-8601; used for ORDER BY created_at ASC.
-      --   updated_at  TEXT        — ISO-8601; updated on accept/reject.
-      --
-      -- Large payload columns (NOT indexed):
-      --   content     TEXT        — full markdown text; the proposal payload body.
-      --   frontmatter_json TEXT   — JSON of parsed frontmatter (may be NULL when
-      --                             the content has no frontmatter block).
-      --
-      -- Extensible (metadata_json) columns:
-      --   metadata_json TEXT      — JSON object for future proposal fields.
-      --                             Current fields stored here: sourceRun,
-      --                             review, confidence, gateDecision (#577),
-      --                             backupContent, eligibilitySource.
-      --
-      -- ADD COLUMN extension points (future migrations):
-      --   ALTER TABLE proposals ADD COLUMN source_run TEXT DEFAULT NULL;
-      --   ALTER TABLE proposals ADD COLUMN review_outcome TEXT DEFAULT NULL;
-      --   ALTER TABLE proposals ADD COLUMN review_reason TEXT DEFAULT NULL;
-      --   ALTER TABLE proposals ADD COLUMN review_decided_at TEXT DEFAULT NULL;
-      --   ALTER TABLE proposals ADD COLUMN archived INTEGER NOT NULL DEFAULT 0;
-      --
-      CREATE TABLE IF NOT EXISTS proposals (
-        id               TEXT    PRIMARY KEY,
-        stash_dir        TEXT    NOT NULL,
-        ref              TEXT    NOT NULL,
-        status           TEXT    NOT NULL DEFAULT 'pending',
-        source           TEXT    NOT NULL,
-        created_at       TEXT    NOT NULL,
-        updated_at       TEXT    NOT NULL,
-        content          TEXT    NOT NULL DEFAULT '',
-        frontmatter_json TEXT,
-        metadata_json    TEXT    NOT NULL DEFAULT '{}'
-      );
-
-      -- Query patterns:
-      --   SELECT … WHERE stash_dir = ? AND status = ?   → idx_proposals_stash_status
-      --   SELECT … WHERE ref = ? AND status = ?         → idx_proposals_ref_status
-      --   SELECT … WHERE id = ?                         → PK
-      CREATE INDEX IF NOT EXISTS idx_proposals_stash_status
-        ON proposals(stash_dir, status);
-      CREATE INDEX IF NOT EXISTS idx_proposals_ref_status
-        ON proposals(ref, status);
-
-      -- ── task_history ─────────────────────────────────────────────────────────
-      --
-      -- Replaces per-task JSONL files under <cacheDir>/tasks/history/.
-      --
-      -- Indexed (query) columns:
-      --   task_id     TEXT PK     — stable task identifier string.
-      --   status      TEXT        — terminal status (e.g. "completed", "failed",
-      --                             "cancelled"); indexed for status-scoped queries.
-      --   started_at  TEXT        — ISO-8601; indexed for time-range queries.
-      --   target_kind TEXT        — kind of the target entity (e.g. "issue",
-      --                             "workflow", "agent"); indexed for kind-scoped queries.
-      --   target_ref  TEXT        — stable ref of the target entity; indexed for
-      --                             per-target history lookups.
-      --
-      -- Non-indexed time columns:
-      --   completed_at TEXT       — ISO-8601 or NULL if still running.
-      --   failed_at    TEXT       — ISO-8601 or NULL.
-      --
-      -- Non-indexed diagnostic columns:
-      --   log_path     TEXT       — absolute path to the task log file, if any.
-      --
-      -- Extensible (metadata_json) columns:
-      --   metadata_json TEXT      — JSON object for future task fields (exit_code,
-      --                             runner, priority, parent_task_id, …).
-      --
-      -- ADD COLUMN extension points (future migrations):
-      --   ALTER TABLE task_history ADD COLUMN exit_code INTEGER DEFAULT NULL;
-      --   ALTER TABLE task_history ADD COLUMN runner TEXT DEFAULT NULL;
-      --   ALTER TABLE task_history ADD COLUMN parent_task_id TEXT DEFAULT NULL;
-      --   ALTER TABLE task_history ADD COLUMN priority INTEGER NOT NULL DEFAULT 0;
-      --
-      CREATE TABLE IF NOT EXISTS task_history (
-        task_id       TEXT    PRIMARY KEY,
-        status        TEXT    NOT NULL,
-        started_at    TEXT    NOT NULL,
-        completed_at  TEXT,
-        failed_at     TEXT,
-        log_path      TEXT,
-        target_kind   TEXT,
-        target_ref    TEXT,
-        metadata_json TEXT    NOT NULL DEFAULT '{}'
-      );
-
-      -- Query patterns:
-      --   SELECT … WHERE task_id = ?                    → PK
-      --   SELECT … WHERE started_at >= ? AND started_at <= ? → idx_task_history_started
-      --   SELECT … WHERE target_kind = ? AND target_ref = ?  → idx_task_history_target
-      --   SELECT … WHERE status = ?                     → idx_task_history_status
-      CREATE INDEX IF NOT EXISTS idx_task_history_started
-        ON task_history(started_at);
-      CREATE INDEX IF NOT EXISTS idx_task_history_target
-        ON task_history(target_kind, target_ref);
-      CREATE INDEX IF NOT EXISTS idx_task_history_status
-        ON task_history(status);
-    `,
-    },
-    // Migration 002 — fix task_history to be a true per-run log.
-    //
-    // Migration 001 used task_id as PRIMARY KEY, meaning each task had exactly
-    // one row and every new run overwrote the previous one. This silently
-    // discarded all historical runs — the opposite of a history table.
-    //
-    // This migration recreates the table with an AUTOINCREMENT id so each run
-    // appends a new row. The old single-row table is renamed to _old, the new
-    // table is created, data is copied, and the old table is dropped.
-    {
-        id: "002-task-history-per-run",
-        up: `
-      ALTER TABLE task_history RENAME TO task_history_v1;
-
-      CREATE TABLE task_history (
-        id            INTEGER PRIMARY KEY AUTOINCREMENT,
-        task_id       TEXT    NOT NULL,
-        status        TEXT    NOT NULL,
-        started_at    TEXT    NOT NULL,
-        completed_at  TEXT,
-        failed_at     TEXT,
-        log_path      TEXT,
-        target_kind   TEXT,
-        target_ref    TEXT,
-        metadata_json TEXT    NOT NULL DEFAULT '{}'
-      );
-
-      INSERT INTO task_history
-        (task_id, status, started_at, completed_at, failed_at,
-         log_path, target_kind, target_ref, metadata_json)
-      SELECT task_id, status, started_at, completed_at, failed_at,
-             log_path, target_kind, target_ref, metadata_json
-      FROM task_history_v1;
-
-      DROP TABLE task_history_v1;
-
-      -- Unique constraint: same task cannot have two runs with the same start time.
-      CREATE UNIQUE INDEX IF NOT EXISTS idx_task_history_run
-        ON task_history(task_id, started_at);
-      CREATE INDEX IF NOT EXISTS idx_task_history_task_id
-        ON task_history(task_id);
-      CREATE INDEX IF NOT EXISTS idx_task_history_started
-        ON task_history(started_at);
-      CREATE INDEX IF NOT EXISTS idx_task_history_target
-        ON task_history(target_kind, target_ref);
-      CREATE INDEX IF NOT EXISTS idx_task_history_status
-        ON task_history(status);
-    `,
-    },
-    // ── Migration 003 — improve_runs ────────────────────────────────────────────
-    //
-    // Records every `akm improve` invocation as a durable row, replacing the
-    // legacy `<stash>/.akm/runs/<runId>/improve-result.json` artifact files.
-    //
-    // The `dry_run` column is FIRST-CLASS and indexed so productivity audits can
-    // cleanly filter dry-run probes out of real-run analyses without parsing
-    // `result_json`. The dry-run/real-run artifact-trap (recorded in
-    // feedback_akm_dryrun_artifact_trap) was the specific motivating bug.
-    //
-    // Indexed (query) columns:
-    //   id            TEXT PK   — runId (`buildImproveRunId()` output).
-    //   started_at    TEXT      — ISO-8601; indexed for time-range queries.
-    //   stash_dir     TEXT      — absolute stash root; multi-stash scoping.
-    //   dry_run       INTEGER   — 0/1; indexed for productivity audits.
-    //   scope_mode    TEXT      — "all" | "type" | "ref"; indexed via composite
-    //                              with stash_dir for stash-scoped scope queries.
-    //
-    // Non-indexed payload:
-    //   completed_at  TEXT      — ISO-8601 or NULL if interrupted.
-    //   profile       TEXT      — improve profile name (nullable).
-    //   scope_value   TEXT      — type name or asset ref (nullable).
-    //   guidance      TEXT      — user-provided guidance text, if any.
-    //   ok            INTEGER   — 0/1; whether the run produced ok=true.
-    //   result_json   TEXT      — full AkmImproveResult JSON.
-    //   metrics_json  TEXT      — aggregate counts extracted from result, cheap
-    //                              to query without parsing result_json.
-    //
-    // Extensible (metadata_json) columns:
-    //   metadata_json TEXT      — JSON object for future improve-run fields.
-    //
-    // ADD COLUMN extension points (future migrations):
-    //   ALTER TABLE improve_runs ADD COLUMN duration_ms INTEGER DEFAULT NULL;
-    //   ALTER TABLE improve_runs ADD COLUMN host TEXT DEFAULT NULL;
-    //
-    // TTL: rows where started_at < NOW() - 90 days can be deleted by
-    // `purgeOldImproveRuns()`. No automatic deletion occurs here.
-    {
-        id: "003-improve-runs",
-        up: `
-      CREATE TABLE IF NOT EXISTS improve_runs (
-        id            TEXT    PRIMARY KEY,
-        started_at    TEXT    NOT NULL,
-        completed_at  TEXT,
-        stash_dir     TEXT    NOT NULL,
-        dry_run       INTEGER NOT NULL DEFAULT 0,
-        profile       TEXT,
-        scope_mode    TEXT    NOT NULL,
-        scope_value   TEXT,
-        guidance      TEXT,
-        ok            INTEGER NOT NULL,
-        result_json   TEXT    NOT NULL,
-        metrics_json  TEXT,
-        metadata_json TEXT    NOT NULL DEFAULT '{}'
-      );
-
-      -- Query patterns supported:
-      --   SELECT … WHERE started_at >= ? AND started_at <= ?
-      --     → idx_improve_runs_started
-      --   SELECT … WHERE dry_run = 0
-      --     → idx_improve_runs_dry_run (productivity audits filter trap)
-      --   SELECT … WHERE stash_dir = ? AND scope_mode = ?
-      --     → idx_improve_runs_stash_scope
-      CREATE INDEX IF NOT EXISTS idx_improve_runs_started
-        ON improve_runs(started_at);
-      CREATE INDEX IF NOT EXISTS idx_improve_runs_dry_run
-        ON improve_runs(dry_run);
-      CREATE INDEX IF NOT EXISTS idx_improve_runs_stash_scope
-        ON improve_runs(stash_dir, scope_mode);
-    `,
-    },
-    // ── Migration 004 — extract_sessions_seen ───────────────────────────────────
-    //
-    // Tracks which platform sessions the extractor has processed, so the discovery
-    // pass in `akm extract --since <window>` skips sessions whose content hasn't
-    // changed since the last successful run. Replaces the akm-plugin
-    // session-checkpoint hook's implicit "write-once" memory of what's been
-    // captured — but persistent and queryable.
-    //
-    // Indexed (query) columns:
-    //   harness          TEXT     — harness name (claude-code, opencode, ...).
-    //   session_id       TEXT     — platform-native session identifier.
-    //   processed_at     TEXT     — ISO-8601 UTC; when extract last ran on this session.
-    //   session_ended_at TEXT     — session.endedAt at processing time. When a
-    //                                later listSessions reports a *newer* endedAt
-    //                                for the same session_id, the extractor
-    //                                re-processes the appended events.
-    //   outcome          TEXT     — "candidates_queued" | "no_candidates" |
-    //                                "skipped" | "failed".
-    //
-    // Non-indexed columns:
-    //   candidate_count  INTEGER  — number of candidates the LLM produced.
-    //   proposal_count   INTEGER  — number of proposals actually queued
-    //                                (candidates may fail downstream validation).
-    //   rationale        TEXT     — for "no_candidates", the LLM's explanation.
-    //   source_run       TEXT     — sourceRun id for PROV-DM traceability.
-    //   metadata_json    TEXT     — future-proofing (pre-filter stats, LLM
-    //                                model+version, prompt token count, etc.).
-    //
-    // PK: (harness, session_id) — one row per session per harness. A re-extract
-    // updates the row in place via INSERT OR REPLACE.
-    //
-    // TTL: no automatic deletion. Sessions stay tracked as long as the source
-    // session files exist on disk. Operator can `DELETE FROM extract_sessions_seen
-    // WHERE processed_at < ?` for cleanup if desired.
-    {
-        id: "004-extract-sessions-seen",
-        up: `
-      CREATE TABLE IF NOT EXISTS extract_sessions_seen (
-        harness          TEXT    NOT NULL,
-        session_id       TEXT    NOT NULL,
-        processed_at     TEXT    NOT NULL,
-        session_ended_at TEXT,
-        outcome          TEXT    NOT NULL,
-        candidate_count  INTEGER NOT NULL DEFAULT 0,
-        proposal_count   INTEGER NOT NULL DEFAULT 0,
-        rationale        TEXT,
-        source_run       TEXT,
-        metadata_json    TEXT    NOT NULL DEFAULT '{}',
-        PRIMARY KEY (harness, session_id)
-      );
-
-      -- Query patterns:
-      --   SELECT … WHERE harness = ?                       → idx_extract_sessions_harness
-      --   SELECT … WHERE processed_at >= ?                 → idx_extract_sessions_processed
-      --   SELECT … WHERE harness = ? AND session_id = ?    → PK
-      CREATE INDEX IF NOT EXISTS idx_extract_sessions_harness
-        ON extract_sessions_seen(harness);
-      CREATE INDEX IF NOT EXISTS idx_extract_sessions_processed
-        ON extract_sessions_seen(processed_at);
-    `,
-    },
-    // ── Migration 005 — proposal_fs_imports ─────────────────────────────────────
-    //
-    // One-shot ledger for the legacy filesystem→SQLite proposal import (#578).
-    //
-    // Before 0.9.0 the proposal queue lived as per-uuid JSON directories under
-    // `<stashDir>/.akm/proposals/` and the `proposals` table (created in 001) was
-    // dead weight. 0.9.0 makes the table canonical; the first proposal operation
-    // against a stash imports any legacy `proposal.json` files it finds (INSERT
-    // OR IGNORE, so re-runs never duplicate) and records the stash here so later
-    // invocations skip the directory walk entirely.
-    //
-    // Indexed (query) columns:
-    //   stash_dir    TEXT PK  — absolute stash root the import ran against.
-    //
-    // Non-indexed columns:
-    //   imported_at    TEXT     — ISO-8601 UTC; when the import completed.
-    //   imported_count INTEGER  — rows actually inserted by the import.
-    {
-        id: "005-proposal-fs-imports",
-        up: `
-      CREATE TABLE IF NOT EXISTS proposal_fs_imports (
-        stash_dir      TEXT    PRIMARY KEY,
-        imported_at    TEXT    NOT NULL,
-        imported_count INTEGER NOT NULL DEFAULT 0
-      );
-    `,
-    },
-    // ── Migration 006 — pending proposal lookup index ──────────────────────────
-    //
-    // Supports the transaction-scoped dedup / queue-mutation hardening added in
-    // 0.9.x. The queue now acquires an IMMEDIATE write transaction before it
-    // reads pending proposals, so the hot path is a stash-scoped `status='pending'
-    // AND ref=?` probe followed by an update/insert. This composite index keeps
-    // that lookup index-covered under contention.
-    {
-        id: "006-proposals-pending-ref-source",
-        up: `
-      CREATE INDEX IF NOT EXISTS idx_proposals_stash_status_ref_source
-        ON proposals(stash_dir, status, ref, source);
-    `,
-    },
-    // ── Migration 007 — consolidation_judged ────────────────────────────────────
-    //
-    // Judged-state cache for nightly consolidation (#581). Lets one consolidation
-    // run cover the FULL memory corpus cheaply by SKIPPING memories already judged
-    // with unchanged content, instead of narrowing to a recent time-window slice
-    // (which leaves a near-duplicate backlog the corpus can never clear).
-    //
-    // The consolidate LLM judging loop UPSERTs a row for every memory it saw in a
-    // successfully-judged chunk; the next run hashes each candidate's current
-    // content and skips it when the hash equals the cached `content_hash`
-    // (judged-unchanged → no re-judge). A memory whose content changed produces a
-    // new hash and is re-judged. This converts coverage from O(window) to
-    // O(changed/new). DEFAULT OFF — gated behind
-    // `processes.consolidate.judgedCache.enabled`; when the feature is off this
-    // table is never read or written and behaviour is byte-identical to today.
-    //
-    // Indexed (query) columns:
-    //   entry_key    TEXT PK   — `memory:<name>` ref; one row per judged memory.
-    //
-    // Non-indexed columns:
-    //   content_hash TEXT      — sha256 of the frontmatter-stripped, trimmed body.
-    //   judged_at    TEXT      — ISO-8601 UTC; when the memory was last judged.
-    //   outcome      TEXT      — coarse outcome of the last judge ("actioned" |
-    //                            "no_action"); observability only, never gates.
-    //
-    // TTL: no automatic deletion. Rows for memories deleted on disk become
-    // harmless dead entries (their entry_key never recurs); operators can prune
-    // with `DELETE FROM consolidation_judged WHERE judged_at < ?` if desired.
-    {
-        id: "007-consolidation-judged",
-        up: `
-      CREATE TABLE IF NOT EXISTS consolidation_judged (
-        entry_key    TEXT    PRIMARY KEY,
-        content_hash TEXT    NOT NULL,
-        judged_at    TEXT    NOT NULL,
-        outcome      TEXT    NOT NULL
-      );
-    `,
-    },
-    // ── Migration 008 — body_embeddings ─────────────────────────────────────────
-    //
-    // cacheHash-keyed body-embedding cache (WS-3a). Stores the embedding of the
-    // case-preserving stripped body so the dedup pre-pass and the consolidation
-    // clustering step share one computed vector per unique body, eliminating
-    // redundant embedding calls across runs.
-    //
-    // Design:
-    //   - PK is the `cacheHash` (sha256 of the stripped, case-preserving body).
-    //   - `embedding` is a raw BLOB storing a Float32 array (384 floats × 4 B =
-    //     1 536 B per entry for the default bge-small-en-v1.5 model; ~20 MB at
-    //     13 k memories). This matches the native wire format and avoids JSON
-    //     round-trip overhead.
-    //   - `model_id` is MANDATORY. On mismatch (model changed) the entire table
-    //     is dropped and rebuilt — stale vectors from the wrong metric space would
-    //     produce silent cosine errors.
-    //   - `created_at` is an INTEGER Unix ms timestamp for lazy orphan purges.
-    //
-    // Writes: one bulk `WHERE content_hash IN (…)` lookup → embed only misses →
-    // upsert all results in one transaction per run.
-    //
-    // TTL: no automatic row deletion. Orphaned rows for bodies no longer in the
-    // stash stay until an operator prunes them. The table is ~1.5 KB per row
-    // (~20 MB at 13 k memories — acceptable).
-    {
-        id: "008-body-embeddings",
-        up: `
-      CREATE TABLE IF NOT EXISTS body_embeddings (
-        content_hash TEXT    PRIMARY KEY,
-        embedding    BLOB    NOT NULL,
-        model_id     TEXT    NOT NULL,
-        created_at   INTEGER NOT NULL
-      );
-    `,
-    },
-    // ── Migration 009 — asset_salience (WS-1 salience vector) ───────────────────
-    //
-    // Per-asset salience vector persisted in state.db (canonical store).
-    //
-    // Three independently-stored, independently-decayable sub-scores:
-    //   encoding_salience  — intrinsic importance (Gap 1; v1 = type-weight stub).
-    //   outcome_salience   — differential usefulness (WS-2; 0 until that lands).
-    //   retrieval_salience — frequency × recency (the decayable term).
-    //
-    // Plus the scalar projection for ranking:
-    //   rank_score = (w_e·encoding + w_o·outcome + w_r·retrieval) × sizePenalty,
-    //   normalized [0,1]. Every selector reads rank_score; individual sub-scores
-    //   are available for telemetry and per-dimension thresholding.
-    //
-    // Plasticity column:
-    //   consecutive_no_ops INTEGER — number of consecutive improve cycles where
-    //     this asset produced a no-op (reflect/distill produced no change).
-    //     Dampens CONSOLIDATION-SELECTION only — intentionally NOT applied to
-    //     rank_score (stable assets stay retrievable but skip LLM merge passes).
-    //
-    // updated_at is an INTEGER Unix-ms timestamp for recency queries.
-    //
-    // The canonical store is state.db, not frontmatter.  An optional frontmatter
-    // mirror of the stable encodingSalience is allowed for portability (#608).
-    //
-    // TTL: rows are overwritten on every run; orphaned rows for deleted assets
-    // accumulate harmlessly until an operator prunes them.
-    {
-        id: "009-asset-salience",
-        up: `
-      CREATE TABLE IF NOT EXISTS asset_salience (
-        asset_ref          TEXT    PRIMARY KEY,
-        encoding_salience  REAL    NOT NULL DEFAULT 0.5,
-        outcome_salience   REAL    NOT NULL DEFAULT 0.0,
-        retrieval_salience REAL    NOT NULL DEFAULT 0.0,
-        rank_score         REAL    NOT NULL DEFAULT 0.0,
-        consecutive_no_ops INTEGER NOT NULL DEFAULT 0,
-        updated_at         INTEGER NOT NULL DEFAULT 0
-      );
-
-      -- Hot path: sort / filter by rank_score for selector queries.
-      CREATE INDEX IF NOT EXISTS idx_asset_salience_rank
-        ON asset_salience(rank_score DESC);
-    `,
-    },
-    // ── Migration 010 — asset_outcome (WS-2 outcome loop) ───────────────────────
-    //
-    // Per-asset outcome loop persisted in state.db (S2 seam, WS-2).
-    //
-    // Stores the differential "was this retrieval useful" signal so the salience
-    // vector's `outcomeSalience` sub-score (WS-1 `W_OUTCOME` term) is non-zero.
-    //
-    // Columns:
-    //   asset_ref TEXT PK             — `type:name` asset ref (FK to asset_salience).
-    //   last_retrieved_at INTEGER     — Unix-ms of the most recent retrieval.
-    //   retrieval_count INTEGER       — total retrieval count from the index DB.
-    //   expected_retrieval_rate REAL  — EMA-smoothed expected count per cycle.
-    //   negative_feedback_count INTEGER — cumulative negative-feedback events.
-    //   accepted_change_count INTEGER — cumulative accepted proposals.
-    //   review_pressure INTEGER       — #613 pressure counter: repeated low-satisfaction
-    //                                   retrievals increment it; feeds outcomeSalience.
-    //   outcome_score REAL            — differential outcome signal (can be negative).
-    //   updated_at INTEGER            — Unix-ms timestamp of last update.
-    //
-    // Design:
-    //   - outcome_score is differential (prediction-error shaped), NOT a raw count,
-    //     so it rewards assets that are retrieved MORE than their rolling mean AND
-    //     accepted for change when retrieved. See outcome-loop.ts for the formula.
-    //   - review_pressure (#613): repeated negative-feedback retrievals raise it,
-    //     non-negative cycles decay it. Never mutates asset content directly.
-    //   - warm_start: seeded from utility EMA at row creation, clipped to [0, 0.3]
-    //     so the first negative delta does not cause a spurious rank inversion.
-    //   - Orphaned rows (deleted assets) accumulate harmlessly; operators can prune
-    //     with `DELETE FROM asset_outcome WHERE updated_at < ?` if desired.
-    {
-        id: "010-asset-outcome",
-        up: `
-      CREATE TABLE IF NOT EXISTS asset_outcome (
-        asset_ref                TEXT    PRIMARY KEY,
-        last_retrieved_at        INTEGER NOT NULL DEFAULT 0,
-        retrieval_count          INTEGER NOT NULL DEFAULT 0,
-        expected_retrieval_rate  REAL    NOT NULL DEFAULT 0.0,
-        negative_feedback_count  INTEGER NOT NULL DEFAULT 0,
-        accepted_change_count    INTEGER NOT NULL DEFAULT 0,
-        review_pressure          INTEGER NOT NULL DEFAULT 0,
-        outcome_score            REAL    NOT NULL DEFAULT 0.0,
-        updated_at               INTEGER NOT NULL DEFAULT 0
-      );
-
-      -- Hot path: sort assets by review_pressure DESC for #613 admission.
-      CREATE INDEX IF NOT EXISTS idx_asset_outcome_review_pressure
-        ON asset_outcome(review_pressure DESC);
-
-      -- Secondary: sort by outcome_score DESC for outcomeSalience reads.
-      CREATE INDEX IF NOT EXISTS idx_asset_outcome_score
-        ON asset_outcome(outcome_score DESC);
-    `,
-    },
-    // ── Migration 011 — asset_salience: homeostatic_demoted_at column ─────────────
-    //
-    // WS-3b step 0a (homeostatic demotion). Records the last time `retrievalSalience`
-    // was demoted for this asset so:
-    //   (a) Each run can identify assets that have been demoted but not yet
-    //       re-retrieved (they stay in the demoted state until a retrieval
-    //       re-promotes them via `upsertAssetSalience`).
-    //   (b) The homeostatic pass can log "N assets demoted this run".
-    //
-    // NULL = never demoted (or was re-promoted after last demotion, since a fresh
-    // `upsertAssetSalience` call clears the flag by updating retrieval_salience
-    // from live data rather than the demoted value — the column is informational,
-    // not the canonical source of the salience value).
-    {
-        id: "011-asset-salience-homeostatic-demoted-at",
-        up: `
-      ALTER TABLE asset_salience ADD COLUMN homeostatic_demoted_at INTEGER DEFAULT NULL;
-    `,
-    },
-    // ── Migration 012 — improve_gate_thresholds (WS-4 per-phase threshold store) ─
-    //
-    // Persists the auto-tuned accept-gate threshold PER PHASE so that each phase
-    // (reflect, distill, extract, consolidate) maintains its own calibrated
-    // threshold rather than sharing a single global `options.autoAccept`.
-    //
-    // Schema:
-    //   phase TEXT PK        — phase label, e.g. "reflect", "distill", "extract",
-    //                          "consolidate".
-    //   threshold INTEGER    — tuned threshold (0-100), matches the integer
-    //                          scale used everywhere else in the gate pipeline.
-    //   updated_at INTEGER   — Unix milliseconds of the last update.
-    //
-    // `makeGateConfig` reads the stored threshold for its phase (falling back to
-    // the caller-supplied `globalThreshold` when no row exists yet). WS-4's
-    // `persistPhaseThreshold` writes it after each auto-tune step.
-    {
-        id: "012-improve-gate-thresholds",
-        up: `
-      CREATE TABLE IF NOT EXISTS improve_gate_thresholds (
-        phase       TEXT    NOT NULL PRIMARY KEY,
-        threshold   INTEGER NOT NULL,
-        updated_at  INTEGER NOT NULL
-      );
-    `,
-    },
-    // ── Migration 013 — extract_sessions_seen: content_hash column (#602) ────────
-    //
-    // Replaces the brittle timestamp-based incrementality (`session_ended_at`,
-    // compared against the live session metadata) with a content hash. The old
-    // clock/timestamp logic caused the Jun 11-12 double-extract + over-throttle
-    // incident (clock skew / out-of-order endedAt both double-processed AND
-    // over-suppressed sessions). The hash makes the skip decision byte-exact and
-    // clock-independent.
-    //
-    // Additive ADD COLUMN (migration-safe; mirrors migration 011's style). All
-    // pre-existing rows read back `content_hash = NULL`, which the skip logic
-    // treats as "seen before content-hash tracking existed → process once to
-    // backfill", after which the row gets a real hash and becomes hash-stable.
-    // Never mutate migration 004 (the original table) — this column is appended.
-    {
-        id: "013-extract-sessions-content-hash",
-        up: `
-      ALTER TABLE extract_sessions_seen ADD COLUMN content_hash TEXT DEFAULT NULL;
-    `,
-    },
-    // ── Migration 014 — recombine_hypotheses (#625 confirmation count) ───────────
-    //
-    // Second-pass promotion ledger for the recombine pass. The first pass (#609)
-    // only ever emits `type: hypothesis` proposals; this table tracks how many
-    // CONSECUTIVE runs re-induced the SAME generalization (keyed by the
-    // deterministic `deriveRecombineLessonRef` value — a hash of the sorted
-    // member entryKeys). Once `consecutive_count >= confirmThreshold`, the run
-    // promotes the generalization to a `type: lesson` proposal (through the same
-    // proposal queue + quality gate). A hypothesis NOT re-induced in a run has its
-    // consecutive streak reset (decay-to-zero), so confirmation is per exact
-    // member-set and conservative.
-    //
-    // Indexed columns:
-    //   hypothesis_ref TEXT PK — the `lesson:recombined/<slug>-<hash>` ref; one
-    //                            row per re-inducible generalization. The ref is
-    //                            the promotion TARGET (a lesson in both the
-    //                            hypothesis and promoted states), so the ref never
-    //                            encodes the proposal type.
-    //   last_seen_at   TEXT (idx) — for forensic / pruning queries.
-    //
-    // Non-indexed columns:
-    //   signature          TEXT — the cluster's shared relatedness signal (tag /
-    //                             entity) at induction time; forensics only.
-    //   member_key         TEXT — sorted member entryKeys joined; the membership
-    //                             fingerprint behind the ref hash. Stored so a
-    //                             membership change (which yields a DIFFERENT ref)
-    //                             is auditable.
-    //   consecutive_count  INTEGER — current confirmation streak (reset on decay
-    //                                and on promotion).
-    //   first_seen_at      TEXT — ISO-8601 UTC of the first induction.
-    //   last_run           TEXT — sourceRun token of the last induction; the
-    //                             same-run idempotency guard.
-    //   promoted_at        TEXT — non-null once promoted; guards against
-    //                             double-promoting on every subsequent run.
-    //   metadata_json      TEXT — reserved for future forensics; defaults to '{}'.
-    {
-        id: "014-recombine-hypotheses",
-        up: `
-      CREATE TABLE IF NOT EXISTS recombine_hypotheses (
-        hypothesis_ref    TEXT PRIMARY KEY,
-        signature         TEXT NOT NULL,
-        member_key        TEXT NOT NULL,
-        consecutive_count INTEGER NOT NULL DEFAULT 0,
-        first_seen_at     TEXT NOT NULL,
-        last_seen_at      TEXT NOT NULL,
-        last_run          TEXT,
-        promoted_at       TEXT,
-        metadata_json     TEXT NOT NULL DEFAULT '{}'
-      );
-      CREATE INDEX IF NOT EXISTS idx_recombine_hypotheses_last_seen
-        ON recombine_hypotheses(last_seen_at);
-    `,
-    },
-    // ── Migration 015 — asset_salience: encoding_source provenance column (#644) ──
-    //
-    // Records HOW the stored `encoding_salience` was derived so an improve run's
-    // type-weight fallback can no longer clobber a real content-derived score:
-    //
-    //   "content"   — written by the distill path from `scoreEncodingSalience`
-    //                 (novelty·0.40 + magnitude·0.35 + predictionError·0.25).
-    //   "type-stub" — written by `computeSalience`'s `DEFAULT_TYPE_ENCODING_WEIGHTS`
-    //                 fallback (no content-based score available for this ref yet).
-    //   NULL        — legacy row written before this migration; provenance unknown.
-    //                 Treated as a stub by readers UNLESS its stored value differs
-    //                 from the pure type-weight (best-effort heuristic for old data).
-    //
-    // Why a column rather than inference: before #644, every improve run overwrote
-    // the distill-written content score with the type-weight stub, so the stored
-    // value alone cannot distinguish a real score from a stub. The provenance flag
-    // is the single source of truth going forward; `upsertAssetSalience` refuses to
-    // lower a "content" row to a "type-stub" so the high-salience gate (#608) keys
-    // on genuine novelty/magnitude/prediction-error, not the asset type.
-    {
-        id: "015-asset-salience-encoding-source",
-        up: `
-      ALTER TABLE asset_salience ADD COLUMN encoding_source TEXT DEFAULT NULL;
-    `,
-    },
-];
+export function withStateDb(fn, opts) {
+    return withManagedDb(() => openStateDatabase(opts?.path), fn, opts);
+}
 /**
- * Apply every pending migration in a single transaction per migration.
- *
- * Delegates to the shared SQLite migration engine; state.db has no
- * pre-versioning bootstrap step, so no `bootstrap` hook is passed.
- *
- * Called automatically by `openStateDatabase()`.
+ * Async sibling of {@link withStateDb} — for `fn`s that hold the handle across
+ * an `await` (the sync version would close it too early). Same borrow/own +
+ * optional `path` override semantics.
  */
-export function runMigrations(db) {
-    runSqliteMigrations(db, MIGRATIONS);
+export function withStateDbAsync(fn, opts) {
+    return withManagedDbAsync(() => openStateDatabase(opts?.path), fn, opts);
 }
+// ── Migration engine ─────────────────────────────────────────────────────────
+//
+// The MIGRATIONS registry + runMigrations live in ./state/migrations (the single
+// append-only ordered source of truth). Imported for internal use by
+// openStateDatabase + re-exported so existing importers keep resolving.
+import { runMigrations } from "./state/migrations.js";
+export { runMigrations } from "./state/migrations.js";
 /**
  * Convert a raw `EventRow` from the database to the public `EventEnvelope`
  * interface used throughout the events module.
@@ -1897,45 +1188,3 @@ export function upsertBodyEmbeddings(db, entries) {
         }
     })();
 }
-// ── registry_index_cache (goes in index.db, not state.db) ───────────────────
-/**
- * DDL for the `registry_index_cache` table that lives in the EXISTING index.db
- * (managed by src/indexer/db/db.ts).
- *
- * Design: uses the same migration-safe ADD COLUMN approach. The table is
- * created with CREATE TABLE IF NOT EXISTS so it is safe to call inside
- * ensureSchema() or as a standalone migration.
- *
- * Purpose: caches the result of resolving and fetching remote registry stash
- * indexes so `akm search` does not hit the network on every invocation.
- *
- * Indexed (query) columns:
- *   registry_url  TEXT PK   — canonical URL of the registry; cache key.
- *   fetched_at    TEXT      — ISO-8601; used to detect stale entries (TTL).
- *   etag          TEXT      — HTTP ETag for conditional GET (If-None-Match).
- *   last_modified TEXT      — HTTP Last-Modified for conditional GET.
- *
- * Non-indexed payload:
- *   index_json    TEXT      — JSON blob of the fetched registry index document.
- *
- * ADD COLUMN extension points (future migrations in db.ts):
- *   ALTER TABLE registry_index_cache ADD COLUMN schema_version INTEGER DEFAULT 1;
- *   ALTER TABLE registry_index_cache ADD COLUMN kit_count INTEGER DEFAULT NULL;
- *   ALTER TABLE registry_index_cache ADD COLUMN error_message TEXT DEFAULT NULL;
- *
- * To add this table to index.db, call ensureRegistryIndexCacheSchema(db) from
- * within ensureSchema() in src/indexer/db/db.ts, or add it as a new CREATE TABLE
- * IF NOT EXISTS block inside the existing ensureSchema() call.
- */
-export const REGISTRY_INDEX_CACHE_DDL = `
-  CREATE TABLE IF NOT EXISTS registry_index_cache (
-    registry_url  TEXT    PRIMARY KEY,
-    fetched_at    TEXT    NOT NULL,
-    etag          TEXT,
-    last_modified TEXT,
-    index_json    TEXT    NOT NULL DEFAULT '{}'
-  );
-
-  CREATE INDEX IF NOT EXISTS idx_registry_cache_fetched
-    ON registry_index_cache(fetched_at);
-`;