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

package/dist/storage/repositories/canaries-repository.js

@@ -0,0 +1,107 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/** 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;
+}

package/dist/storage/repositories/consolidation-repository.js

@@ -0,0 +1,38 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * 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);
+}

package/dist/storage/repositories/embeddings-repository.js

@@ -0,0 +1,72 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * 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);
+        }
+    })();
+}

package/dist/storage/repositories/events-repository.js

@@ -0,0 +1,187 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { error } from "../../core/warn.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 } : {}),
+    };
+}
+/**
+ * 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;
+}
+/**
+ * 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 };
+}

package/dist/storage/repositories/extract-sessions-repository.js

@@ -0,0 +1,96 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * 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;
+}

package/dist/storage/repositories/improve-runs-repository.js

@@ -0,0 +1,130 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { classifyImproveAction } from "../../core/improve-types.js";
+// ── 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());
+}
+/**
+ * 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;
+}

package/dist/storage/repositories/index-db.js

@@ -1,8 +1,9 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-import { closeDatabase, openExistingDatabase } from "../../indexer/db/db.js";
+import { openExistingDatabase } from "../../indexer/db/db.js";
 import { resolveStorageLocations } from "../locations.js";
+import { withManagedDb } from "../managed-db.js";
 /**
  * Busy-timeout (ms) for read-path telemetry writers. Small on purpose: a
  * usage-event insert contending with a background reindex should be dropped,
@@ -39,14 +40,10 @@ export const TELEMETRY_BUSY_TIMEOUT_MS = 250;
  * @returns Whatever `fn` returns.
  */
 export function withIndexDb(fn, opts) {
-    const db = openExistingDatabase(resolveStorageLocations().indexDb);
-    try {
+    return withManagedDb(() => openExistingDatabase(resolveStorageLocations().indexDb), (db) => {
         if (opts?.busyTimeoutMs !== undefined) {
             db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(opts.busyTimeoutMs))}`);
         }
         return fn(db);
-    }
-    finally {
-        closeDatabase(db);
-    }
+    });
 }