akm-cli 0.9.0-beta.9 → 0.9.0-rc.0

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,146 @@
+// 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;
+    // C1 (13-bus-factor): distill-skipped rows are folded into the bounded
+    // `distillSkipped` aggregate and no longer live in `actions`. Add the
+    // aggregate total to the skipped + total-actions counters so metrics_json
+    // reports the same numbers as before the fold. (Legacy rows that still carry
+    // per-ref distill-skipped in `actions` have no aggregate, so they are counted
+    // by the classify loop above — never double-counted.)
+    const distillSkippedTotal = result.distillSkipped?.total ?? 0;
+    skippedCount += distillSkippedTotal;
+    return {
+        plannedCount,
+        actionsCount: actionsCount + distillSkippedTotal,
+        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,15 @@
 // 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,
+ * not waited on for the default 30s.
+ */
+export const TELEMETRY_BUSY_TIMEOUT_MS = 250;
 /**
  * Scoped-resource (loan pattern) helper for the index database (`index.db`).
  *
@@ -32,12 +39,11 @@ import { resolveStorageLocations } from "../locations.js";
  * @param fn Receives the open index database; must finish all DB work before returning.
  * @returns Whatever `fn` returns.
  */
-export function withIndexDb(fn) {
-    const db = openExistingDatabase(resolveStorageLocations().indexDb);
-    try {
+export function withIndexDb(fn, opts) {
+    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);
-    }
+    });
 }

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

@@ -0,0 +1,220 @@
+// 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 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),
+    };
+}
+/**
+ * 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;
+}
+/**
+ * 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;
+}