akm-cli 0.9.0-beta.53 → 0.9.0-beta.55

package/dist/core/state-db.js

@@ -4,11 +4,17 @@
 /**
  * state.db — Durable SQLite database for non-regenerable akm state.
  *
- * This module owns THREE tables that replace flat-file storage:
- *
- *   events      — replaces events.jsonl (append-only event bus)
- *   proposals   — replaces per-uuid JSON directories under .akm/proposals/
- *   task_history — replaces per-task JSONL files under <cacheDir>/tasks/history/
+ * This module OWNS the state database's shared infrastructure: path resolution,
+ * the managed-db open/loan wrappers, the `BEGIN IMMEDIATE` transaction helper,
+ * and schema introspection. The table-specific query helpers live by domain in
+ * `src/storage/repositories/*-repository.ts` (events, proposals, task-history,
+ * improve-runs, extract-sessions, consolidation, recombine, embeddings,
+ * canaries); importers reference those modules directly. The migration engine
+ * lives in `./state/migrations`.
+ *
+ * The state DB replaces flat-file storage for data that is NON-REGENERABLE —
+ * events (events.jsonl), proposals (per-uuid JSON directories), task history
+ * (per-task JSONL), and the improve-pipeline ledgers.
  *
  * ## Why a separate database from index.db
  *
@@ -51,9 +57,7 @@
  */
 import path from "node:path";
 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";
 // ── Path helper ──────────────────────────────────────────────────────────────
 /**
  * Default path: `<dataDir>/state.db`.
@@ -116,350 +120,9 @@ export function withStateDbAsync(fn, opts) {
 //
 // 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.
+// openStateDatabase.
 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.
- */
-export function eventRowToEnvelope(row) {
-    let metadata;
-    try {
-        const parsed = JSON.parse(row.metadata_json);
-        // Only attach metadata when the JSON blob is non-empty so downstream
-        // consumers that check `envelope.metadata !== undefined` keep working.
-        if (Object.keys(parsed).length > 0) {
-            metadata = parsed;
-        }
-    }
-    catch {
-        // Corrupt JSON in the DB — treat as no metadata.
-    }
-    return {
-        schemaVersion: 1,
-        id: row.id,
-        ts: row.ts,
-        eventType: row.event_type,
-        ...(row.ref !== null ? { ref: row.ref } : {}),
-        ...(metadata !== undefined ? { metadata } : {}),
-    };
-}
-/**
- * Convert a raw `ProposalRow` to the public `Proposal` shape.
- */
-export function proposalRowToProposal(row) {
-    let frontmatter;
-    if (row.frontmatter_json) {
-        try {
-            frontmatter = JSON.parse(row.frontmatter_json);
-        }
-        catch {
-            /* ignore corrupt frontmatter JSON */
-        }
-    }
-    let meta = {};
-    try {
-        meta = JSON.parse(row.metadata_json);
-    }
-    catch {
-        /* ignore */
-    }
-    return {
-        id: row.id,
-        ref: row.ref,
-        status: row.status,
-        source: row.source,
-        ...(typeof meta.sourceRun === "string" ? { sourceRun: meta.sourceRun } : {}),
-        createdAt: row.created_at,
-        updatedAt: row.updated_at,
-        payload: {
-            content: row.content,
-            ...(frontmatter !== undefined ? { frontmatter } : {}),
-        },
-        ...(meta.review !== undefined ? { review: meta.review } : {}),
-        ...(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 }
-            : {}),
-    };
-}
-/**
- * Convert a public `Proposal` to column values ready for an INSERT/UPDATE.
- * The `stash_dir` comes from the call site (proposals.ts has it in scope).
- */
-export function proposalToRowValues(proposal, stashDir) {
-    // Fields that have no dedicated column live in metadata_json.
-    const metaObj = {};
-    if (proposal.sourceRun !== undefined)
-        metaObj.sourceRun = proposal.sourceRun;
-    if (proposal.review !== undefined)
-        metaObj.review = proposal.review;
-    if (proposal.confidence !== undefined)
-        metaObj.confidence = proposal.confidence;
-    if (proposal.gateDecision !== undefined)
-        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,
-        ref: proposal.ref,
-        status: proposal.status,
-        source: proposal.source,
-        created_at: proposal.createdAt,
-        updated_at: proposal.updatedAt,
-        content: proposal.payload.content,
-        frontmatter_json: proposal.payload.frontmatter ? JSON.stringify(proposal.payload.frontmatter) : null,
-        metadata_json: JSON.stringify(metaObj),
-    };
-}
-// ── events table helpers ─────────────────────────────────────────────────────
-/**
- * Insert a single event. Returns the auto-assigned monotonic rowid, which
- * callers can store as a "sinceId" cursor for future `readEventsSince` calls.
- *
- * Best-effort: mirrors the behaviour of the old `appendEvent` — errors are
- * caught and logged to stderr rather than propagated so observability never
- * breaks mutation.
- */
-export function insertEvent(db, input) {
-    try {
-        const result = db
-            .prepare(`INSERT INTO events (event_type, ts, ref, metadata_json)
-         VALUES (?, ?, ?, ?)
-         RETURNING id`)
-            .get(input.eventType, input.ts, input.ref ?? null, JSON.stringify(input.metadata ?? {}));
-        return result?.id;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        error(`akm: state.db event insert failed (${message})`);
-        return undefined;
-    }
-}
-/**
- * Read events from the database matching the filter. Returns events in
- * ascending id order so consumers can process them in emission order.
- *
- * The returned `nextId` is the maximum id seen (or `sinceId` when no rows
- * match), suitable as the next `sinceId` cursor value.
- */
-export function readStateEvents(db, options = {}) {
-    const conditions = [];
-    const params = [];
-    if (options.sinceId !== undefined && options.sinceId > 0) {
-        conditions.push("id > ?");
-        params.push(options.sinceId);
-    }
-    if (options.since) {
-        conditions.push("ts >= ?");
-        params.push(options.since);
-    }
-    if (options.type) {
-        conditions.push("event_type = ?");
-        params.push(options.type);
-    }
-    if (options.ref) {
-        conditions.push("ref = ?");
-        params.push(options.ref);
-    }
-    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-    const rows = db
-        .prepare(`SELECT id, event_type, ts, ref, metadata_json FROM events ${where} ORDER BY id ASC`)
-        .all(...params);
-    const events = rows.map(eventRowToEnvelope);
-    const nextId = events.length > 0 ? events[events.length - 1].id : (options.sinceId ?? 0);
-    return { events, nextId };
-}
-/**
- * Delete events older than `retentionDays` (default: 90). Safe to call from
- * a maintenance cron; uses a single DELETE with an index-covered ts predicate.
- *
- * Returns the number of rows actually deleted so callers can emit an
- * `events_purged` observability event. A non-positive or non-finite
- * `retentionDays` is treated as "disabled" and returns 0 without scanning.
- */
-export function purgeOldEvents(db, retentionDays = 90) {
-    if (!Number.isFinite(retentionDays) || retentionDays <= 0)
-        return 0;
-    const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
-    const result = db.prepare("DELETE FROM events WHERE ts < ?").run(cutoff);
-    // bun:sqlite's run() returns { changes, lastInsertRowid }. `changes` may be
-    // a number or bigint depending on the underlying lib; coerce to number for
-    // the metadata payload.
-    const changes = result.changes ?? 0;
-    return typeof changes === "bigint" ? Number(changes) : changes;
-}
-// ── proposals table helpers ──────────────────────────────────────────────────
-/**
- * Upsert a proposal row. Called by the proposal write path when state.db is
- * the active backend.
- */
-export function upsertProposal(db, proposal, stashDir) {
-    const v = proposalToRowValues(proposal, stashDir);
-    db.prepare(`
-    INSERT INTO proposals
-      (id, stash_dir, ref, status, source, created_at, updated_at, content, frontmatter_json, metadata_json)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    ON CONFLICT(id) DO UPDATE SET
-      stash_dir        = excluded.stash_dir,
-      ref              = excluded.ref,
-      status           = excluded.status,
-      source           = excluded.source,
-      updated_at       = excluded.updated_at,
-      content          = excluded.content,
-      frontmatter_json = excluded.frontmatter_json,
-      metadata_json    = excluded.metadata_json
-  `).run(v.id, v.stash_dir, v.ref, v.status, v.source, v.created_at, v.updated_at, v.content, v.frontmatter_json, v.metadata_json);
-}
-/**
- * List proposals, optionally filtered by stashDir, status, and/or ref.
- *
- * Results are ordered by `created_at ASC` (matching the historical
- * `listProposals()` sort), with `rowid` as a deterministic tiebreak so two
- * proposals created in the same millisecond list in insertion order.
- */
-export function listStateProposals(db, options = {}) {
-    const conditions = [];
-    const params = [];
-    if (options.stashDir) {
-        conditions.push("stash_dir = ?");
-        params.push(options.stashDir);
-    }
-    if (options.status) {
-        conditions.push("status = ?");
-        params.push(options.status);
-    }
-    if (options.ref) {
-        conditions.push("ref = ?");
-        params.push(options.ref);
-    }
-    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-    const rows = db
-        .prepare(`SELECT id, stash_dir, ref, status, source, created_at, updated_at,
-              content, frontmatter_json, metadata_json
-       FROM proposals ${where} ORDER BY created_at ASC, rowid ASC`)
-        .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.
- */
-export function getStateProposal(db, id, stashDir) {
-    const sql = `SELECT id, stash_dir, ref, status, source, created_at, updated_at,
-              content, frontmatter_json, metadata_json
-       FROM proposals WHERE id = ?${stashDir ? " AND stash_dir = ?" : ""}`;
-    const row = (stashDir ? db.prepare(sql).get(id, stashDir) : db.prepare(sql).get(id));
-    return row ? proposalRowToProposal(row) : undefined;
-}
-/**
- * Find PENDING proposal ids in one stash whose id starts with `idPrefix`.
- * Backs the UUID-prefix form of `akm proposal show/accept/... <prefix>` —
- * prefix resolution is deliberately scoped to the live (pending) queue,
- * mirroring the historical behaviour of scanning only the live directory.
- *
- * `%` / `_` / `\` in the prefix are escaped so the LIKE pattern is literal.
- */
-export function listStateProposalIdsByPrefix(db, stashDir, idPrefix) {
-    const escaped = idPrefix.replace(/[\\%_]/g, (ch) => `\\${ch}`);
-    const rows = db
-        .prepare(`SELECT id FROM proposals
-       WHERE stash_dir = ? AND status = 'pending' AND id LIKE ? ESCAPE '\\'
-       ORDER BY id ASC`)
-        .all(stashDir, `${escaped}%`);
-    return rows.map((r) => r.id);
-}
-/**
- * Whether the legacy filesystem proposal import has already run for `stashDir`.
- * See migration 005 (`proposal_fs_imports`).
- */
-export function hasImportedFsProposals(db, stashDir) {
-    // Drivers disagree on the no-row sentinel (bun:sqlite → null,
-    // better-sqlite3 → undefined) — Boolean() covers both.
-    return Boolean(db.prepare("SELECT 1 FROM proposal_fs_imports WHERE stash_dir = ?").get(stashDir));
-}
-/**
- * Record that the legacy filesystem proposal import completed for `stashDir`
- * so subsequent invocations skip the directory walk. INSERT OR REPLACE keeps
- * the call idempotent.
- */
-export function recordFsProposalsImport(db, stashDir, importedCount) {
-    db.prepare("INSERT OR REPLACE INTO proposal_fs_imports (stash_dir, imported_at, imported_count) VALUES (?, ?, ?)").run(stashDir, new Date().toISOString(), importedCount);
-}
-/**
- * Insert a proposal row ONLY when the id is not already present (used by the
- * legacy filesystem import so re-runs never clobber rows that have since been
- * mutated through the canonical store). Returns true when a row was inserted.
- */
-export function insertProposalIfAbsent(db, proposal, stashDir) {
-    const v = proposalToRowValues(proposal, stashDir);
-    const result = db
-        .prepare(`
-      INSERT OR IGNORE INTO proposals
-        (id, stash_dir, ref, status, source, created_at, updated_at, content, frontmatter_json, metadata_json)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `)
-        .run(v.id, v.stash_dir, v.ref, v.status, v.source, v.created_at, v.updated_at, v.content, v.frontmatter_json, v.metadata_json);
-    const changes = result.changes ?? 0;
-    return Number(changes) > 0;
-}
+// ── BEGIN IMMEDIATE transaction helper ───────────────────────────────────────
 /**
  * Run `fn` inside a `BEGIN IMMEDIATE` transaction.
  *
@@ -569,97 +232,6 @@ export function withImmediateTransaction(db, fn) {
     // Exhausted retries on transient begin failures.
     throw lastBeginErr;
 }
-// ── task_history table helpers ───────────────────────────────────────────────
-/**
- * Upsert a task history row.
- */
-export function upsertTaskHistory(db, row) {
-    // INSERT OR IGNORE: if a run with the same (task_id, started_at) was already
-    // imported (e.g. by the migration script), skip it silently.
-    db.prepare(`
-    INSERT OR IGNORE INTO task_history
-      (task_id, status, started_at, completed_at, failed_at, log_path,
-       target_kind, target_ref, metadata_json)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(row.task_id, row.status, row.started_at, row.completed_at ?? null, row.failed_at ?? null, row.log_path ?? null, row.target_kind ?? null, row.target_ref ?? null, row.metadata_json);
-}
-/**
- * Look up a task history row by task_id. Returns undefined when not found.
- */
-/**
- * Return the most recent run for a given task_id, or undefined if no runs exist.
- */
-export function getTaskHistory(db, taskId) {
-    return db
-        .prepare(`SELECT id, task_id, status, started_at, completed_at, failed_at, log_path,
-              target_kind, target_ref, metadata_json
-       FROM task_history WHERE task_id = ? ORDER BY started_at DESC LIMIT 1`)
-        .get(taskId);
-}
-/**
- * Return all runs for a given task_id, newest first.
- */
-export function getTaskHistoryRuns(db, taskId, limit = 50) {
-    return db
-        .prepare(`SELECT id, task_id, status, started_at, completed_at, failed_at, log_path,
-              target_kind, target_ref, metadata_json
-       FROM task_history WHERE task_id = ? ORDER BY started_at DESC LIMIT ?`)
-        .all(taskId, limit);
-}
-/**
- * Query task history rows by started_at range and/or status.
- */
-export function queryTaskHistory(db, options = {}) {
-    const conditions = [];
-    const params = [];
-    if (options.since) {
-        conditions.push("started_at >= ?");
-        params.push(options.since);
-    }
-    if (options.until) {
-        conditions.push("started_at <= ?");
-        params.push(options.until);
-    }
-    if (options.status) {
-        conditions.push("status = ?");
-        params.push(options.status);
-    }
-    if (options.targetKind) {
-        conditions.push("target_kind = ?");
-        params.push(options.targetKind);
-    }
-    if (options.targetRef) {
-        conditions.push("target_ref = ?");
-        params.push(options.targetRef);
-    }
-    const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
-    return db
-        .prepare(`SELECT task_id, status, started_at, completed_at, failed_at, log_path,
-              target_kind, target_ref, metadata_json
-       FROM task_history ${where} ORDER BY started_at DESC`)
-        .all(...params);
-}
-/**
- * Read COMPLETED `akm-improve` task_history runs whose `started_at` falls in
- * `[since, until)` (or `started_at >= since` when `until` is omitted), ordered
- * oldest-first by `started_at`. Only rows with a non-null `completed_at` are
- * returned (in-flight runs are excluded). The `task_id = 'akm-improve'`
- * predicate is fixed because the only caller (commands/health.ts
- * `loadTaskIntervals`) builds wall-time intervals for the improve cron task.
- *
- * Owns the SQL formerly inlined in commands/health.ts. Note the bound is
- * EXCLUSIVE on the upper end (`started_at < ?`) — callers pass an already
- * widened window; this helper does not widen.
- *
- * Connection-lifetime rule (WS5): `.all()` materializes a plain array before
- * returning.
- */
-export function queryCompletedTaskIntervals(db, since, until) {
-    const sql = until
-        ? "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND started_at < ? AND completed_at IS NOT NULL ORDER BY started_at"
-        : "SELECT started_at, completed_at FROM task_history WHERE task_id = 'akm-improve' AND started_at >= ? AND completed_at IS NOT NULL ORDER BY started_at";
-    return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
-}
 // ── schema introspection ─────────────────────────────────────────────────────
 /**
  * Return the subset of `names` that exist as TABLEs in this database, ordered
@@ -680,702 +252,3 @@ export function listExistingTableNames(db, names) {
         .prepare(`SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${placeholders}) ORDER BY name`)
         .all(...names);
 }
-// ── events.jsonl import ──────────────────────────────────────────────────────
-/**
- * Import all events from an `events.jsonl` file into the `events` table.
- *
- * The old byte-offset `id` is NOT preserved — the database assigns new
- * monotonic integer ids. Callers that persisted a byte-offset cursor must
- * discard it after migration and use the returned `maxId` as the new cursor.
- *
- * **Idempotency**: each line is pre-checked against the `events` table using
- * `(event_type, ts, ref, metadata_json)` as the duplicate key. Lines whose
- * exact tuple is already present are skipped and reported as `skipped` in the
- * return value. This makes the migration safe to re-run (the v0.7→v0.8
- * migration guide recommends re-running the script as a recovery path; without
- * this guard, every re-run would double-import the entire event log).
- *
- * Duplicate detection is per-import-tuple, not a table-wide UNIQUE constraint:
- * the events table has no UNIQUE constraint at runtime so that
- * `appendEvent` can write multiple events with the same ts (sub-millisecond
- * bursts produce identical `(event_type, ts, ref)` triples in practice). The
- * SELECT-first check is scoped to the import path only.
- *
- * The import is wrapped in a single transaction for atomicity.
- *
- * @param db       - Open state.db connection.
- * @param jsonlPath - Absolute path to the events.jsonl file to import.
- * @returns         Number of rows inserted, the max id assigned, and the
- *                  count of rows skipped because an identical event already
- *                  existed in the table.
- */
-export async function importEventsJsonl(db, jsonlPath) {
-    const { readFileSync, existsSync } = await import("node:fs");
-    if (!existsSync(jsonlPath)) {
-        return { imported: 0, maxId: 0, skipped: 0 };
-    }
-    const text = readFileSync(jsonlPath, "utf8");
-    const lines = text.split("\n").filter((l) => l.trim().length > 0);
-    let imported = 0;
-    let maxId = 0;
-    let skipped = 0;
-    const insertStmt = db.prepare(`INSERT INTO events (event_type, ts, ref, metadata_json)
-     VALUES (?, ?, ?, ?)
-     RETURNING id`);
-    // Dedup pre-check: matches by the full tuple including metadata_json so an
-    // import is idempotent over identical rows but does not collide with two
-    // genuinely different events that happen to share (event_type, ts, ref).
-    //
-    // Uses IS for ref so two NULL refs compare equal (a plain `=` would treat
-    // NULL = NULL as NULL and the row would be re-inserted on every run).
-    const existsStmt = db.prepare(`SELECT 1 FROM events
-     WHERE event_type = ?
-       AND ts = ?
-       AND ref IS ?
-       AND metadata_json = ?
-     LIMIT 1`);
-    db.transaction(() => {
-        for (const line of lines) {
-            let parsed;
-            try {
-                parsed = JSON.parse(line);
-            }
-            catch {
-                continue; // skip malformed lines — same behaviour as readEvents()
-            }
-            const eventType = typeof parsed.eventType === "string" ? parsed.eventType : "unknown";
-            const ts = typeof parsed.ts === "string" ? parsed.ts : new Date().toISOString();
-            const ref = typeof parsed.ref === "string" ? parsed.ref : null;
-            const metadata = parsed.metadata !== undefined && typeof parsed.metadata === "object" ? JSON.stringify(parsed.metadata) : "{}";
-            const duplicate = existsStmt.get(eventType, ts, ref, metadata);
-            if (duplicate) {
-                skipped++;
-                continue;
-            }
-            const result = insertStmt.get(eventType, ts, ref, metadata);
-            if (result) {
-                imported++;
-                if (result.id > maxId)
-                    maxId = result.id;
-            }
-        }
-    })();
-    return { imported, maxId, skipped };
-}
-/**
- * Compute the cheap aggregate metrics blob from a full improve result.
- *
- * Pure function — no I/O. Used by {@link recordImproveRun} to populate
- * `metrics_json`. Exposed for tests and for any future call site that wants
- * the same aggregation logic without hitting state.db.
- */
-export function computeImproveRunMetrics(result) {
-    const plannedCount = Array.isArray(result.plannedRefs) ? result.plannedRefs.length : 0;
-    const actions = Array.isArray(result.actions) ? result.actions : [];
-    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. 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++;
-                break;
-            case "rejected":
-                rejectedCount++;
-                break;
-            case "skipped":
-                skippedCount++;
-                break;
-            case "error":
-                errorCount++;
-                break;
-            case "noop":
-                break;
-        }
-        // Legacy: pre-gate action results may carry autoAccepted: true (reflect path).
-        const r = action.result;
-        if (r && r.autoAccepted === true)
-            autoAcceptedCount++;
-    }
-    // Add gate-promoted count from the unified PostPhaseAutoAcceptGate (all phases).
-    autoAcceptedCount += result.gateAutoAcceptedCount ?? 0;
-    return { plannedCount, actionsCount, acceptedCount, rejectedCount, skippedCount, autoAcceptedCount, errorCount };
-}
-/**
- * Insert a single improve-run row into `improve_runs`. Uses parameterised SQL.
- *
- * Idempotency: the table's PRIMARY KEY is `id`, so re-running with the same
- * runId would error. Callers mint a fresh runId per invocation via
- * {@link buildImproveRunId} so this is not a concern in practice — but the
- * default behaviour is INSERT (not REPLACE) so accidental dupes surface as
- * a SQLite constraint error rather than silently overwriting a prior record.
- *
- * The `metrics` parameter defaults to the output of
- * {@link computeImproveRunMetrics} when not supplied. Pass an explicit
- * `metrics` object to override the derivation (e.g. tests).
- */
-export function recordImproveRun(db, input) {
-    const metricsObj = input.metrics ?? computeImproveRunMetrics(input.result);
-    db.prepare(`
-    INSERT INTO improve_runs
-      (id, started_at, completed_at, stash_dir, dry_run, profile,
-       scope_mode, scope_value, guidance, ok, result_json, metrics_json, metadata_json)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(input.id, input.startedAt, input.completedAt, input.stashDir, input.dryRun ? 1 : 0, input.profile, input.scopeMode, input.scopeValue, input.guidance, input.ok ? 1 : 0, JSON.stringify(input.result), JSON.stringify(metricsObj), JSON.stringify(input.metadata ?? {}));
-}
-/**
- * Read real (non-dry-run) improve_runs rows whose `started_at` falls in the
- * window `[since, until)`. When `until` is omitted the window is open-ended
- * (`started_at >= since`). Rows are returned newest-first (`ORDER BY
- * started_at DESC`).
- *
- * Owns the SQL formerly inlined in commands/health.ts (`loadImproveRunRows`).
- * The `dry_run = 0` filter is first-class so dry-run probes never pollute
- * productivity audits.
- *
- * Connection-lifetime rule (WS5): `.all()` fully materializes the result set
- * into a plain array before returning — no live cursor escapes the caller's
- * `openStateDatabase` scope.
- */
-export function queryImproveRuns(db, since, until) {
-    const sql = until
-        ? "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND started_at < ? AND dry_run = 0 ORDER BY started_at DESC"
-        : "SELECT id, started_at, completed_at, ok, scope_mode, scope_value, result_json FROM improve_runs WHERE started_at >= ? AND dry_run = 0 ORDER BY started_at DESC";
-    return (until ? db.prepare(sql).all(since, until) : db.prepare(sql).all(since));
-}
-/**
- * Delete improve_runs rows older than `retentionDays` (default: 90). Mirrors
- * {@link purgeOldEvents} — same default, same return shape (number of rows
- * actually deleted), same disabled-when-non-finite semantics.
- *
- * Safe to call from the improve post-loop maintenance pass alongside
- * `purgeOldEvents(db, retentionDays)`.
- */
-export function purgeOldImproveRuns(db, retentionDays = 90) {
-    if (!Number.isFinite(retentionDays) || retentionDays <= 0)
-        return 0;
-    const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
-    const result = db.prepare("DELETE FROM improve_runs WHERE started_at < ?").run(cutoff);
-    const changes = result.changes ?? 0;
-    return typeof changes === "bigint" ? Number(changes) : changes;
-}
-/**
- * Record (or update) one session's extract outcome. INSERT-OR-REPLACE so the
- * 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)
-        ? new Date(input.sessionEndedAt).toISOString()
-        : null;
-    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,
-       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
- * session has never been processed.
- */
-export function getExtractedSession(db, harness, sessionId) {
-    // bun:sqlite returns null (not undefined) when no row matches — normalize so
-    // callers can rely on `if (!row)` and `toBeUndefined()` equivalently.
-    const row = db
-        .prepare("SELECT * FROM extract_sessions_seen WHERE harness = ? AND session_id = ?")
-        .get(harness, sessionId);
-    return row ?? undefined;
-}
-/**
- * Bulk-fetch session-extract status for a list of sessionIds in one harness.
- * Returns a Map keyed by sessionId so callers can do O(1) lookups while
- * iterating the discovery list.
- */
-export function getExtractedSessionsMap(db, harness, sessionIds) {
-    const out = new Map();
-    if (sessionIds.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 < sessionIds.length; i += CHUNK) {
-        const chunk = sessionIds.slice(i, i + CHUNK);
-        const placeholders = chunk.map(() => "?").join(",");
-        const rows = db
-            .prepare(`SELECT * FROM extract_sessions_seen
-         WHERE harness = ? AND session_id IN (${placeholders})`)
-            .all(harness, ...chunk);
-        for (const row of rows)
-            out.set(row.session_id, row);
-    }
-    return out;
-}
-/**
- * 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.
- *
- * 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, currentContentHash) {
-    if (!prior)
-        return false;
-    if (prior.content_hash == null)
-        return false;
-    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;
-}
-/**
- * #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.
- *
- * 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.
- *
- * 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.
- *
- * @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.
- *
- * #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.
- *
- * 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).
- *
- * 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 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);
-        }
-    })();
-}
-/** Insert a freshly minted canary set (all rows active, one shared set id). */
-export function insertCanaries(db, canarySetId, canaries, now) {
-    if (canaries.length === 0)
-        return;
-    const ts = now ?? new Date().toISOString();
-    const stmt = db.prepare(`
-    INSERT INTO canary_queries (canary_set_id, anchor_ref, query, source, active, created_at)
-    VALUES (?, ?, ?, ?, 1, ?)
-  `);
-    db.transaction(() => {
-        for (const c of canaries) {
-            stmt.run(canarySetId, c.anchorRef, c.query, c.source ?? "auto", ts);
-        }
-    })();
-}
-/** Load the active canary set (empty array = never minted). */
-export function getActiveCanaries(db) {
-    // Scope to the NEWEST active set: if an interrupted refresh (or a bug) ever
-    // leaves two sets active, mixing their rows would silently corrupt the
-    // recall/entropy trend baselines. The newest set wins; stale-active rows are
-    // simply never returned.
-    return db
-        .prepare(`SELECT * FROM canary_queries
-       WHERE active = 1 AND canary_set_id = (
-         SELECT canary_set_id FROM canary_queries WHERE active = 1
-         ORDER BY created_at DESC, id DESC LIMIT 1
-       )
-       ORDER BY id`)
-        .all();
-}
-/** Load one canary set's rows by its exact set id (any active state), insertion order. */
-export function getCanariesBySetId(db, canarySetId) {
-    return db
-        .prepare(`SELECT * FROM canary_queries WHERE canary_set_id = ? ORDER BY id`)
-        .all(canarySetId);
-}
-/** List every distinct canary_set_id that still has active rows. */
-export function listActiveCanarySetIds(db) {
-    const rows = db.prepare(`SELECT DISTINCT canary_set_id FROM canary_queries WHERE active = 1`).all();
-    return rows.map((r) => r.canary_set_id);
-}
-/**
- * Deactivate every canary row in a set. Rows are RETAINED (active = 0) so
- * historical improve_cycle_metrics rows keyed on the old canary_set_id stay
- * interpretable; only `akm improve canary --refresh` calls this.
- */
-export function deactivateCanarySet(db, canarySetId) {
-    const result = db
-        .prepare(`UPDATE canary_queries SET active = 0 WHERE canary_set_id = ? AND active = 1`)
-        .run(canarySetId);
-    const changes = result.changes ?? 0;
-    return typeof changes === "bigint" ? Number(changes) : changes;
-}
-/** Persist one qualifying cycle's store-health snapshot. */
-export function insertCycleMetrics(db, row) {
-    db.prepare(`
-    INSERT INTO improve_cycle_metrics
-      (run_id, ts, pass, canary_set_id, mean_recall, mean_ndcg, mean_mrr,
-       canary_ranks_json, store_total, store_by_type_json, distinct_content_ratio,
-       mean_bigram_diversity, over_generation_count, accepted_actions,
-       merge_floor_violations, alerts_json)
-    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(row.run_id, row.ts, row.pass, row.canary_set_id, row.mean_recall, row.mean_ndcg, row.mean_mrr, row.canary_ranks_json, row.store_total, row.store_by_type_json, row.distinct_content_ratio, row.mean_bigram_diversity, row.over_generation_count, row.accepted_actions, row.merge_floor_violations, row.alerts_json);
-}
-/**
- * Load the most recent cycle rows for one canary set, OLDEST-first (the alert
- * evaluator's window order). Scoped by canary_set_id so trends never compare
- * across canary re-mints.
- */
-export function queryRecentCycleMetrics(db, canarySetId, limit) {
-    const rows = db
-        .prepare(`SELECT run_id, ts, pass, canary_set_id, mean_recall, mean_ndcg, mean_mrr,
-              canary_ranks_json, store_total, store_by_type_json, distinct_content_ratio,
-              mean_bigram_diversity, over_generation_count, accepted_actions,
-              merge_floor_violations, alerts_json
-       FROM improve_cycle_metrics WHERE canary_set_id = ?
-       ORDER BY ts DESC, id DESC LIMIT ?`)
-        .all(canarySetId, Math.max(0, limit));
-    return rows.reverse();
-}
-/** Load the single most recent cycle row across all canary sets (health surface). */
-export function getLatestCycleMetrics(db) {
-    const row = db
-        .prepare(`SELECT run_id, ts, pass, canary_set_id, mean_recall, mean_ndcg, mean_mrr,
-              canary_ranks_json, store_total, store_by_type_json, distinct_content_ratio,
-              mean_bigram_diversity, over_generation_count, accepted_actions,
-              merge_floor_violations, alerts_json
-       FROM improve_cycle_metrics ORDER BY ts DESC, id DESC LIMIT 1`)
-        .get();
-    return row == null ? undefined : row;
-}
-/**
- * Delete cycle rows older than `retentionDays` (default 365 — owner-approved;
- * a slow collapse needs a longer trend window than the 90-day events log).
- * Returns the purged row count. canary_queries rows are never purged.
- */
-export function purgeOldCycleMetrics(db, retentionDays = 365) {
-    if (!Number.isFinite(retentionDays) || retentionDays <= 0)
-        return 0;
-    const cutoff = new Date(Date.now() - retentionDays * 86_400_000).toISOString();
-    const result = db.prepare("DELETE FROM improve_cycle_metrics WHERE ts < ?").run(cutoff);
-    const changes = result.changes ?? 0;
-    return typeof changes === "bigint" ? Number(changes) : changes;
-}