akm-cli 0.9.0-beta.5 → 0.9.0-beta.51

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,10 +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 { openManagedDatabase, withManagedDb, withManagedDbAsync } from "../storage/managed-db.js";
 import { classifyImproveAction } from "./improve-types.js";
 import { getDataDir } from "./paths.js";
 import { error } from "./warn.js";
@@ -94,412 +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.
-    db.exec("PRAGMA journal_mode = WAL");
-    db.exec("PRAGMA foreign_keys = ON");
-    db.exec("PRAGMA busy_timeout = 30000");
-    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.
-      --
-      -- 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
-      );
-    `,
-    },
-];
+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.
@@ -562,6 +181,9 @@ export function proposalRowToProposal(row) {
         ...(typeof meta.confidence === "number" ? { confidence: meta.confidence } : {}),
         ...(meta.gateDecision !== undefined ? { gateDecision: meta.gateDecision } : {}),
         ...(typeof meta.backupContent === "string" ? { backupContent: meta.backupContent } : {}),
+        ...(typeof meta.eligibilitySource === "string"
+            ? { eligibilitySource: meta.eligibilitySource }
+            : {}),
     };
 }
 /**
@@ -581,6 +203,8 @@ export function proposalToRowValues(proposal, stashDir) {
         metaObj.gateDecision = proposal.gateDecision;
     if (proposal.backupContent !== undefined)
         metaObj.backupContent = proposal.backupContent;
+    if (proposal.eligibilitySource !== undefined)
+        metaObj.eligibilitySource = proposal.eligibilitySource;
     return {
         id: proposal.id,
         stash_dir: stashDir,
@@ -723,6 +347,57 @@ export function listStateProposals(db, options = {}) {
         .all(...params);
     return rows.map(proposalRowToProposal);
 }
+/**
+ * Read every proposal's `gateDecision` record across all stashes (#612).
+ *
+ * Calibration reads the auto-accept gate's per-proposal decisions regardless of
+ * the proposal's current lifecycle status — a proposal that was auto-accepted
+ * is now `accepted`, an auto-rejected one stays `pending`, so filtering by
+ * status would drop half the join. Rows without a `gateDecision` (created
+ * before #577, or never gated) are skipped. The result is ordered by
+ * `decidedAt ASC` for deterministic downstream aggregation, falling back to
+ * `created_at` ordering from the SQL layer for rows with equal/missing
+ * timestamps.
+ */
+export function listProposalGateDecisions(db) {
+    const rows = db.prepare("SELECT metadata_json FROM proposals ORDER BY created_at ASC, rowid ASC").all();
+    const decisions = [];
+    for (const row of rows) {
+        let meta;
+        try {
+            meta = JSON.parse(row.metadata_json);
+        }
+        catch {
+            continue;
+        }
+        const decision = meta.gateDecision;
+        if (decision && typeof decision === "object" && typeof decision.outcome === "string") {
+            decisions.push(decision);
+        }
+    }
+    decisions.sort((a, b) => new Date(a.decidedAt).getTime() - new Date(b.decidedAt).getTime());
+    return decisions;
+}
+// ── WS-4: Per-phase gate threshold store (Migration 012) ─────────────────────
+/**
+ * Read the persisted auto-tuned threshold for a gate phase.
+ *
+ * Returns `undefined` when no row exists yet (first run, or the phase has
+ * never been tuned). The caller falls back to the global `options.autoAccept`
+ * in that case.
+ */
+export function getPhaseThreshold(db, phase) {
+    const row = db.prepare("SELECT threshold FROM improve_gate_thresholds WHERE phase = ?").get(phase);
+    return row?.threshold;
+}
+/**
+ * Persist the auto-tuned threshold for a gate phase.
+ * Uses INSERT OR REPLACE so the call is idempotent (upsert semantics).
+ */
+export function persistPhaseThreshold(db, phase, threshold) {
+    db.prepare(`INSERT OR REPLACE INTO improve_gate_thresholds (phase, threshold, updated_at)
+     VALUES (?, ?, ?)`).run(phase, Math.round(threshold), Date.now());
+}
 /**
  * Look up a single proposal by id, optionally scoped to one stash root.
  * Returns undefined when not found.
@@ -785,6 +460,92 @@ export function insertProposalIfAbsent(db, proposal, stashDir) {
     const changes = result.changes ?? 0;
     return Number(changes) > 0;
 }
+/**
+ * Run `fn` inside a `BEGIN IMMEDIATE` transaction.
+ *
+ * `db.transaction()` is DEFERRED by default on both Bun and better-sqlite3,
+ * which means two writers can both perform stale preflight reads and only race
+ * when they finally attempt the write. Proposal creation and queue mutation
+ * need the write lock BEFORE those reads so concurrent processes serialize on
+ * the live queue state rather than clobbering each other.
+ */
+/**
+ * Errors `BEGIN IMMEDIATE` can throw under concurrent-writer contention that are
+ * transient (the statement did NOT start a usable transaction) and safe to
+ * retry after clearing any phantom transaction state:
+ *   - "database is locked" / SQLITE_BUSY — another writer holds the lock.
+ *   - "cannot start a transaction within a transaction" — bun:sqlite can leave
+ *     the connection reporting an open transaction after a contended busy-wait
+ *     on BEGIN IMMEDIATE (observed only under heavy parallel load, e.g. the
+ *     proposal-queue worker race). A ROLLBACK clears that phantom state.
+ * These are start-of-transaction failures only; an error thrown by `fn` is a
+ * real failure and is NEVER retried.
+ */
+function isRetryableBeginError(err) {
+    const msg = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return (msg.includes("within a transaction") ||
+        msg.includes("database is locked") ||
+        msg.includes("database table is locked") ||
+        // Phantom BEGIN (see below) — synthesized when BEGIN IMMEDIATE returns
+        // without opening a transaction. Safe to retry: fn() has not run.
+        msg.includes("did not open a transaction"));
+}
+const WITH_IMMEDIATE_TX_MAX_ATTEMPTS = 5;
+/** Portable synchronous sleep (works under both Bun and Node). */
+function sleepSyncMs(ms) {
+    if (ms <= 0)
+        return;
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+export function withImmediateTransaction(db, fn) {
+    let lastBeginErr;
+    for (let attempt = 1; attempt <= WITH_IMMEDIATE_TX_MAX_ATTEMPTS; attempt++) {
+        try {
+            db.exec("BEGIN IMMEDIATE");
+            // bun:sqlite can return from BEGIN IMMEDIATE under writer contention WITHOUT
+            // actually opening a transaction (no throw). That phantom state otherwise
+            // surfaces as "cannot commit - no transaction is active" at COMMIT — AFTER
+            // fn() has already run in autocommit, so its writes escaped the intended
+            // serialization (the concurrent proposal-queue race). Detect it here, before
+            // fn(), and route it through the same retry path as a contended BEGIN.
+            if (!db.inTransaction) {
+                throw new Error("BEGIN IMMEDIATE did not open a transaction (phantom contention state)");
+            }
+        }
+        catch (err) {
+            lastBeginErr = err;
+            if (isRetryableBeginError(err) && attempt < WITH_IMMEDIATE_TX_MAX_ATTEMPTS) {
+                // Clear any phantom/stale transaction left by the contended BEGIN, then
+                // retry with a small backoff so concurrent writers serialize cleanly.
+                try {
+                    db.exec("ROLLBACK");
+                }
+                catch {
+                    // No active transaction to roll back — fine.
+                }
+                sleepSyncMs(2 ** (attempt - 1));
+                continue;
+            }
+            throw err;
+        }
+        try {
+            const result = fn();
+            db.exec("COMMIT");
+            return result;
+        }
+        catch (err) {
+            try {
+                db.exec("ROLLBACK");
+            }
+            catch {
+                // Ignore rollback failures so the original error is preserved.
+            }
+            throw err; // a real error inside the transaction body — never retried.
+        }
+    }
+    // Exhausted retries on transient begin failures.
+    throw lastBeginErr;
+}
 // ── task_history table helpers ───────────────────────────────────────────────
 /**
  * Upsert a task history row.
@@ -991,15 +752,16 @@ export function computeImproveRunMetrics(result) {
     const actionsCount = actions.length;
     let acceptedCount = 0;
     let rejectedCount = 0;
+    let skippedCount = 0;
     let autoAcceptedCount = 0;
     let errorCount = 0;
     for (const action of actions) {
         // Bucketing delegated to the shared classifyImproveAction so this aggregate
         // and the improve_completed event in improve.ts can never disagree, and so a
-        // new union variant is a compile error rather than a silent drop. Note:
-        // `reflect-guard-rejected` now counts as "rejected" (previously this switch
-        // omitted it entirely — a data-integrity miscount). "noop" (memory-prune) is
-        // intentionally counted in none of the three numeric buckets.
+        // new union variant is a compile error rather than a silent drop. Gated skips
+        // (cooldown / signal-delta / distill pool-delta) bucket to "skipped", NOT
+        // "rejected" — only a guard-rejected produced change is a true rejection.
+        // "noop" (memory-prune) is intentionally counted in none of the buckets.
         switch (classifyImproveAction(action.mode)) {
             case "accepted":
                 acceptedCount++;
@@ -1007,6 +769,9 @@ export function computeImproveRunMetrics(result) {
             case "rejected":
                 rejectedCount++;
                 break;
+            case "skipped":
+                skippedCount++;
+                break;
             case "error":
                 errorCount++;
                 break;
@@ -1020,7 +785,7 @@ export function computeImproveRunMetrics(result) {
     }
     // Add gate-promoted count from the unified PostPhaseAutoAcceptGate (all phases).
     autoAcceptedCount += result.gateAutoAcceptedCount ?? 0;
-    return { plannedCount, actionsCount, acceptedCount, rejectedCount, autoAcceptedCount, errorCount };
+    return { plannedCount, actionsCount, acceptedCount, rejectedCount, skippedCount, autoAcceptedCount, errorCount };
 }
 /**
  * Insert a single improve-run row into `improve_runs`. Uses parameterised SQL.
@@ -1082,9 +847,11 @@ export function purgeOldImproveRuns(db, retentionDays = 90) {
 }
 /**
  * Record (or update) one session's extract outcome. INSERT-OR-REPLACE so the
- * row reflects the most recent run; downstream skip-logic compares
- * `session_ended_at` against the live session metadata to decide if anything
- * new arrived since `processed_at`.
+ * row reflects the most recent run. The `content_hash` persisted here is what
+ * the NEXT run compares against (#602): a byte-identical session is skipped, a
+ * changed session is re-processed, and a NULL-backfill row becomes hash-stable
+ * after its one reprocess. `session_ended_at` is still written for
+ * telemetry/forensics but is no longer the skip authority.
  */
 export function upsertExtractedSession(db, input) {
     const endedAtIso = typeof input.sessionEndedAt === "number" && Number.isFinite(input.sessionEndedAt)
@@ -1093,9 +860,10 @@ export function upsertExtractedSession(db, input) {
     db.prepare(`
     INSERT OR REPLACE INTO extract_sessions_seen
       (harness, session_id, processed_at, session_ended_at, outcome,
-       candidate_count, proposal_count, rationale, source_run, metadata_json)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(input.harness, input.sessionId, input.processedAt, endedAtIso, input.outcome, input.candidateCount, input.proposalCount, input.rationale ?? null, input.sourceRun ?? null, JSON.stringify(input.metadata ?? {}));
+       candidate_count, proposal_count, rationale, source_run, metadata_json,
+       content_hash)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(input.harness, input.sessionId, input.processedAt, endedAtIso, input.outcome, input.candidateCount, input.proposalCount, input.rationale ?? null, input.sourceRun ?? null, JSON.stringify(input.metadata ?? {}), input.contentHash);
 }
 /**
  * Fetch a single session's last extract record, or `undefined` when the
@@ -1133,71 +901,354 @@ export function getExtractedSessionsMap(db, harness, sessionIds) {
     return out;
 }
 /**
- * Decide whether a session should be skipped because the extractor has
- * already processed it AND nothing has changed since. The "anything new since
- * last extract?" rule is: the live `sessionEndedAtMs` is strictly later than
- * the recorded `session_ended_at`. Same-or-earlier endedAt means we'd be
- * re-processing the exact same content for no gain.
+ * The most recent extract-run time for a harness — `MAX(processed_at)` across
+ * its ledger rows, as ms epoch — or `null` when the harness has never been
+ * extracted. Used to default the discovery window to "since the last run" so an
+ * intermittently-online host that was off for days still rediscovers sessions
+ * that ended during the gap (the content-hash ledger keeps the widened window
+ * free of redundant LLM cost).
+ */
+export function getLastExtractRunAt(db, harness) {
+    const row = db
+        .prepare("SELECT MAX(processed_at) AS last FROM extract_sessions_seen WHERE harness = ?")
+        .get(harness);
+    if (!row?.last)
+        return null;
+    const ms = Date.parse(row.last);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Decide whether a session should be skipped because the extractor has already
+ * processed BYTE-IDENTICAL content (#602). The skip authority is the content
+ * hash, NOT `session_ended_at` — this is clock-independent, so it is immune to
+ * the clock-skew / out-of-order-endedAt problems that caused the Jun 11-12
+ * double-extract + over-throttle incident.
  *
- * Returns:
- *   - `false` — no prior row, or session has new content since last extract.
- *     The caller should process it.
- *   - `true`  — the session was already processed and hasn't been updated.
- *     The caller should skip.
+ * Rules:
+ *   - no prior row              → `false` (never seen → process; AC3).
+ *   - prior.content_hash == null → `false` (legacy / hash-less row → process
+ *     exactly once to backfill the hash, then it becomes hash-stable; AC4).
+ *   - hashes equal              → `true`  (unchanged content → skip; AC1).
+ *   - hashes differ             → `false` (changed content → re-process; AC2).
  */
-export function shouldSkipAlreadyExtractedSession(prior, liveSessionEndedAtMs) {
+export function shouldSkipAlreadyExtractedSession(prior, currentContentHash) {
     if (!prior)
         return false;
-    // No live timestamp → can't tell if anything's new. Be conservative and
-    // skip — the operator can pass --force later if we add it.
-    if (typeof liveSessionEndedAtMs !== "number" || !Number.isFinite(liveSessionEndedAtMs)) {
-        return true;
-    }
-    const priorMs = prior.session_ended_at ? Date.parse(prior.session_ended_at) : Number.NaN;
-    if (!Number.isFinite(priorMs))
+    if (prior.content_hash == null)
         return false;
-    // Re-process when there's new content; skip when the session is unchanged.
-    return liveSessionEndedAtMs <= priorMs;
+    return prior.content_hash === currentContentHash;
+}
+/**
+ * Bulk-fetch the judged-state cache for a set of entry keys in one query.
+ * Returns a Map keyed by entry_key so the consolidate pool-selection loop can
+ * do O(1) "has this memory been judged at this content hash?" lookups.
+ * Empty input → empty map (no query issued).
+ */
+export function getConsolidationJudgedMap(db, entryKeys) {
+    const out = new Map();
+    if (entryKeys.length === 0)
+        return out;
+    // SQLite has a ~999 param ceiling; chunk if a caller ever exceeds that.
+    const CHUNK = 500;
+    for (let i = 0; i < entryKeys.length; i += CHUNK) {
+        const chunk = entryKeys.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT * FROM consolidation_judged WHERE entry_key IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows)
+            out.set(row.entry_key, row);
+    }
+    return out;
+}
+/**
+ * Record (or update) the judged state for one memory. INSERT-OR-REPLACE so the
+ * row always reflects the most recent judge of that entry_key. Called once per
+ * memory the consolidate LLM saw in a successfully-judged chunk.
+ */
+export function upsertConsolidationJudged(db, input) {
+    db.prepare(`
+    INSERT OR REPLACE INTO consolidation_judged
+      (entry_key, content_hash, judged_at, outcome)
+    VALUES (?, ?, ?, ?)
+  `).run(input.entryKey, input.contentHash, input.judgedAt, input.outcome);
+}
+/**
+ * Record an induction of a recombine hypothesis and return the new consecutive
+ * count. INSERT … ON CONFLICT increments the streak, but the `last_run` guard
+ * makes a repeated call within the SAME run idempotent (no double-increment if
+ * the same ref appears twice in one run). On insert the streak starts at 1.
+ */
+export function recordRecombineInduction(db, input) {
+    const row = db
+        .prepare(`
+      INSERT INTO recombine_hypotheses
+        (hypothesis_ref, signature, member_key, consecutive_count, first_seen_at, last_seen_at, last_run)
+      VALUES (?, ?, ?, 1, ?, ?, ?)
+      ON CONFLICT(hypothesis_ref) DO UPDATE SET
+        consecutive_count = consecutive_count + (CASE WHEN last_run IS excluded.last_run THEN 0 ELSE 1 END),
+        last_seen_at = excluded.last_seen_at,
+        last_run = excluded.last_run,
+        signature = excluded.signature,
+        member_key = excluded.member_key
+      RETURNING consecutive_count
+    `)
+        .get(input.hypothesisRef, input.signature, input.memberKey, input.seenAt, input.seenAt, input.run);
+    return row?.consecutive_count ?? 0;
 }
-// ── 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).
+ * #633 — find an existing pending (non-promoted) hypothesis row whose cluster
+ * is the SAME generalization as a newly-induced one, matched by SIGNATURE plus
+ * a Jaccard membership-overlap test, rather than an exact member-set hash.
  *
- * 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.
+ * In a growing stash any added/removed memory changes the exact member set, so
+ * the ref hash (and member_key) shift every run → a fresh row at count=1 → the
+ * streak never reaches `confirmThreshold` and nothing ever promotes. Matching
+ * on overlap lets a drifting-but-stable cluster keep accumulating under one row.
  *
- * Purpose: caches the result of resolving and fetching remote registry stash
- * indexes so `akm search` does not hit the network on every invocation.
+ * Returns the matched row with the HIGHEST overlap (ties broken by most-recent
+ * `last_seen_at`), or `undefined` when none clears `minOverlap`. Already-promoted
+ * rows are ignored so a confirmed lesson is not reopened by a later induction.
  *
- * 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.
+ * @param memberKey  the candidate cluster's membership fingerprint
+ *                   (sorted member entryKeys joined by `|`).
+ * @param minOverlap Jaccard threshold in [0,1]; a candidate matches when
+ *                   |A∩B| / |A∪B| >= minOverlap.
+ */
+export function findMatchingRecombineHypothesis(db, input) {
+    const candidateMembers = new Set(input.memberKey.split("|").filter((m) => m.length > 0));
+    if (candidateMembers.size === 0)
+        return undefined;
+    const rows = db
+        .prepare("SELECT * FROM recombine_hypotheses WHERE signature = ? AND promoted_at IS NULL ORDER BY last_seen_at DESC")
+        .all(input.signature);
+    let best;
+    let bestOverlap = -1;
+    for (const row of rows) {
+        const rowMembers = row.member_key.split("|").filter((m) => m.length > 0);
+        if (rowMembers.length === 0)
+            continue;
+        let intersection = 0;
+        for (const m of rowMembers) {
+            if (candidateMembers.has(m))
+                intersection += 1;
+        }
+        const union = candidateMembers.size + rowMembers.length - intersection;
+        const overlap = union === 0 ? 0 : intersection / union;
+        // rows are ordered last_seen_at DESC, so a strict `>` keeps the most-recent
+        // row on ties.
+        if (overlap >= input.minOverlap && overlap > bestOverlap) {
+            best = row;
+            bestOverlap = overlap;
+        }
+    }
+    return best;
+}
+/**
+ * Fetch a single recombine hypothesis row, or `undefined` when the ref has
+ * never been induced. Normalizes bun:sqlite null → undefined like
+ * {@link getExtractedSession}.
+ */
+export function getRecombineHypothesis(db, hypothesisRef) {
+    const row = db
+        .prepare("SELECT * FROM recombine_hypotheses WHERE hypothesis_ref = ?")
+        .get(hypothesisRef);
+    return row ?? undefined;
+}
+/**
+ * Mark a hypothesis promoted: stamp `promoted_at` and reset the consecutive
+ * count to 0, so it must re-accumulate a full confirmation streak before it can
+ * promote again. The `promoted_at` non-null state is the double-promotion guard.
+ */
+export function markRecombineHypothesisPromoted(db, hypothesisRef, promotedAt) {
+    db.prepare("UPDATE recombine_hypotheses SET promoted_at = ?, consecutive_count = 0 WHERE hypothesis_ref = ?").run(promotedAt, hypothesisRef);
+}
+/**
+ * #658 — does any current-run cluster match this hypothesis row under the SAME
+ * signature + Jaccard-overlap rule used for re-induction? A match means the
+ * cluster genuinely re-formed this run (it was merely cap-displaced out of the
+ * processed top-`maxClustersPerRun` slice), so its streak must NOT be reset.
+ */
+function hypothesisMatchesAnyPresentCluster(row, presentClusters, minOverlap) {
+    const rowMembers = row.member_key.split("|").filter((m) => m.length > 0);
+    if (rowMembers.length === 0)
+        return false;
+    const rowSet = new Set(rowMembers);
+    for (const cluster of presentClusters) {
+        if (cluster.signature !== row.signature)
+            continue;
+        const clusterMembers = cluster.memberKey.split("|").filter((m) => m.length > 0);
+        if (clusterMembers.length === 0)
+            continue;
+        let intersection = 0;
+        for (const m of clusterMembers) {
+            if (rowSet.has(m))
+                intersection += 1;
+        }
+        const union = rowSet.size + clusterMembers.length - intersection;
+        const overlap = union === 0 ? 0 : intersection / union;
+        if (overlap >= minOverlap)
+            return true;
+    }
+    return false;
+}
+/**
+ * Decay-to-zero every NON-promoted hypothesis NOT re-induced in the current run.
+ *
+ * A generalization that stops being supported by the corpus has lost its
+ * confirmation streak, so we hard-reset `consecutive_count` to 0 (the
+ * alternative — `count - 1` floored at 0 — tolerates a single noisy run but
+ * blurs the "consecutive" semantics; hard-reset is the conservative choice).
+ *
+ * Only rows whose `hypothesis_ref` is NOT in `seenRefs` AND whose `last_run` is
+ * NOT the current run are decayed. Already-promoted rows are left alone.
  *
- * Non-indexed payload:
- *   index_json    TEXT      — JSON blob of the fetched registry index document.
+ * #658 — CAP-AWARE decay. The recombine pass only re-inducts (and thus marks
+ * `seen`) the top-`maxClustersPerRun` clusters, but a cluster genuinely
+ * re-forms every run even when it is displaced below that cap. Resetting such a
+ * row treats a SCHEDULING miss as a SUBSTANCE miss and traps the hypothesis
+ * below `confirmThreshold` forever. When `opts.presentClusters` is supplied, a
+ * row is SPARED from decay if it Jaccard-matches any present cluster (same
+ * signature, overlap >= `opts.minOverlap`) — i.e. its cluster re-formed this run
+ * but was cap-displaced. This does NOT advance the streak (only re-induction in
+ * the processed slice does that, via {@link recordRecombineInduction}), so the
+ * recurrence bar for promotion is unchanged; it only stops the cap from
+ * manufacturing artificial misses. Omitting `presentClusters` preserves the
+ * pre-#658 hard-reset-after-one-miss behaviour exactly.
  *
- * 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;
+ * Returns the number of rows reset.
+ */
+export function decayUnseenRecombineHypotheses(db, currentRun, seenRefs, opts) {
+    // #658 — when cap-aware sparing is requested, fold the cap-displaced rows into
+    // the "seen" exclusion set: the underlying reset SQL already protects every
+    // ref it is given, so sparing == treating a spared row exactly like a seen
+    // row for this sweep (its count is left untouched, never advanced).
+    let effectiveSeen = seenRefs;
+    if (opts && opts.presentClusters.length > 0) {
+        const candidates = db
+            .prepare("SELECT hypothesis_ref, signature, member_key FROM recombine_hypotheses WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")
+            .all(currentRun);
+        const seenSet = new Set(seenRefs);
+        for (const row of candidates) {
+            if (seenSet.has(row.hypothesis_ref))
+                continue;
+            if (hypothesisMatchesAnyPresentCluster(row, opts.presentClusters, opts.minOverlap)) {
+                seenSet.add(row.hypothesis_ref);
+            }
+        }
+        effectiveSeen = [...seenSet];
+    }
+    return decayUnseenRecombineHypothesesInner(db, currentRun, effectiveSeen);
+}
+/**
+ * The raw reset sweep shared by the cap-aware wrapper above. Resets every
+ * non-promoted row from a prior run whose ref is NOT in `seenRefs`. Kept private
+ * so the param-ceiling chunking logic lives in one place.
+ */
+function decayUnseenRecombineHypothesesInner(db, currentRun, seenRefs) {
+    // Reset every eligible row, then exclude the seen refs in chunks to respect
+    // the ~999 SQLite param ceiling. With no seen refs we reset all non-promoted
+    // rows from prior runs in a single statement.
+    if (seenRefs.length === 0) {
+        const res = db
+            .prepare("UPDATE recombine_hypotheses SET consecutive_count = 0 WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")
+            .run(currentRun);
+        return Number(res.changes);
+    }
+    // A single NOT IN keeps the exclusion atomic (a chunked NOT IN would let a ref
+    // excluded by one chunk still be reset by another chunk's statement). The
+    // recombine pass caps RE-INDUCED clusters at `maxClustersPerRun` (a handful) —
+    // but with #658 cap-aware sparing the caller folds every cap-displaced
+    // (present-but-unprocessed) hypothesis into `effectiveSeen` too, so on a large
+    // stash `seenRefs` here can carry MANY spared refs, not just the handful that
+    // were processed. We cap defensively at ~900 (under SQLite's ~999 param
+    // ceiling): if `effectiveSeen` somehow exceeds it we fall back to resetting all
+    // eligible rows — which re-introduces the cap-displacement trap for THAT run
+    // (spared rows get decayed because the NOT IN protection is dropped). That is a
+    // rare, bounded degradation; a stash with >900 simultaneously-spared
+    // hypotheses is far beyond current scale.
+    if (seenRefs.length > 900) {
+        const res = db
+            .prepare("UPDATE recombine_hypotheses SET consecutive_count = 0 WHERE promoted_at IS NULL AND (last_run IS NULL OR last_run != ?) AND consecutive_count != 0")
+            .run(currentRun);
+        return Number(res.changes);
+    }
+    const placeholders = seenRefs.map(() => "?").join(",");
+    const res = db
+        .prepare(`UPDATE recombine_hypotheses SET consecutive_count = 0
+       WHERE promoted_at IS NULL
+         AND (last_run IS NULL OR last_run != ?)
+         AND consecutive_count != 0
+         AND hypothesis_ref NOT IN (${placeholders})`)
+        .run(currentRun, ...seenRefs);
+    return Number(res.changes);
+}
+/**
+ * Convert a `number[]` embedding vector to the `Float32Array` byte
+ * representation stored in the `body_embeddings.embedding` BLOB column.
+ */
+export function embeddingToBlob(vec) {
+    const f32 = new Float32Array(vec);
+    return new Uint8Array(f32.buffer);
+}
+/**
+ * Convert the raw `Uint8Array` bytes from the `body_embeddings.embedding`
+ * BLOB column back to a `number[]` embedding vector.
+ */
+export function blobToEmbedding(blob) {
+    // SQLite BLOB columns are returned as Uint8Array; re-interpret as Float32.
+    const f32 = new Float32Array(blob.buffer, blob.byteOffset, blob.byteLength / 4);
+    return Array.from(f32);
+}
+/**
+ * Bulk-fetch cached body embeddings for a set of content hashes.
+ * Returns a Map keyed by `content_hash` (embedding decoded to `number[]`).
+ * Empty input → empty map (no query issued).
  *
- * 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.
+ * If the stored `model_id` does not match `expectedModelId` the entire table
+ * is cleared (drop-all on model mismatch) and an empty map is returned so
+ * callers re-embed everything on this run.
  */
-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);
-`;
+export function getBodyEmbeddings(db, contentHashes, expectedModelId) {
+    const out = new Map();
+    if (contentHashes.length === 0)
+        return out;
+    // Model-id mismatch: vectors are in the wrong metric space — drop all rows.
+    const firstRow = db.prepare("SELECT model_id FROM body_embeddings LIMIT 1").get();
+    if (firstRow && firstRow.model_id !== expectedModelId) {
+        db.exec("DELETE FROM body_embeddings");
+        return out;
+    }
+    // SQLite has a ~999 param ceiling; chunk if needed.
+    const CHUNK = 500;
+    for (let i = 0; i < contentHashes.length; i += CHUNK) {
+        const chunk = contentHashes.slice(i, i + CHUNK);
+        const placeholders = chunk.map(() => "?").join(",");
+        const rows = db
+            .prepare(`SELECT content_hash, embedding FROM body_embeddings WHERE content_hash IN (${placeholders})`)
+            .all(...chunk);
+        for (const row of rows) {
+            out.set(row.content_hash, blobToEmbedding(row.embedding));
+        }
+    }
+    return out;
+}
+/**
+ * Upsert body-embedding rows in a single transaction.
+ * Each entry maps a `cacheHash` → `number[]` vector. `model_id` is stored
+ * so a future model change can trigger a drop-all purge.
+ */
+export function upsertBodyEmbeddings(db, entries) {
+    if (entries.length === 0)
+        return;
+    const now = Date.now();
+    const stmt = db.prepare(`
+    INSERT OR REPLACE INTO body_embeddings (content_hash, embedding, model_id, created_at)
+    VALUES (?, ?, ?, ?)
+  `);
+    db.transaction(() => {
+        for (const { contentHash, embedding, modelId } of entries) {
+            stmt.run(contentHash, embeddingToBlob(embedding), modelId, now);
+        }
+    })();
+}