@avocadostudio-ai/orchestrator-core 0.3.2 → 0.3.3

package/dist/durable/sqlite-durable-store.js

@@ -0,0 +1,631 @@
+import { randomUUID } from "node:crypto";
+import { IMPACT_FALLBACK_SQL, fallbackImpact } from "./finding-impact.js";
+/*
+ * SQLite implementation of `DurableStore`.
+ *
+ * It takes an already-open database rather than a file path, so it shares the
+ * single `.data/orchestrator.db` connection `SqliteStore` owns. Two writers on
+ * one file is a WAL problem nobody needs, and these tables want to be in the
+ * same backup and the same `VACUUM INTO` snapshot as everything else.
+ *
+ * Every statement here is row-addressed. Nothing truncates a table to write one
+ * record — which is the entire difference between this store and the snapshot
+ * path it sits beside, and the reason a network-backed implementation of the
+ * same interface is viable later.
+ *
+ * The schema is `CREATE TABLE IF NOT EXISTS` only. There is no migration runner
+ * in this repo (`ensureSchemaVersion` writes a version and does nothing else),
+ * so a new table is safe and a changed one is not. The single exception is
+ * `ensureColumns()` below, which adds a *nullable* column to a table that
+ * already exists — the one migration shape that needs no runner. A column added
+ * to the CREATE TABLE text alone would never reach an existing database, so any
+ * addition has to appear in both places.
+ */
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS findings (
+  id            TEXT PRIMARY KEY,
+  fingerprint   TEXT NOT NULL,
+  scope_key     TEXT NOT NULL,
+  slug          TEXT NOT NULL,
+  rule_id       TEXT NOT NULL,
+  agent         TEXT NOT NULL,
+  severity      TEXT NOT NULL CHECK (severity IN ('error','warning','info')),
+  impact        REAL,
+  status        TEXT NOT NULL CHECK (status IN ('open','snoozed','dismissed','fixed')),
+  title         TEXT NOT NULL,
+  detail        TEXT,
+  evidence      TEXT,
+  proposed_ops  TEXT,
+  last_run_id   TEXT NOT NULL,
+  first_seen_at INTEGER NOT NULL,
+  last_seen_at  INTEGER NOT NULL,
+  resolved_at   INTEGER,
+  snoozed_until INTEGER
+);
+-- Per scope, not global. A natural fingerprint such as seo.description-missing::/
+-- is identical across sites; a global unique index makes one tenant's finding
+-- overwrite another's, and the second site then sees nothing at all.
+CREATE UNIQUE INDEX IF NOT EXISTS findings_by_scope_fingerprint ON findings(scope_key, fingerprint);
+CREATE INDEX IF NOT EXISTS findings_by_scope ON findings(scope_key, status);
+CREATE INDEX IF NOT EXISTS findings_by_slug ON findings(scope_key, slug);
+
+CREATE TABLE IF NOT EXISTS check_runs (
+  id              TEXT PRIMARY KEY,
+  scope_key       TEXT NOT NULL,
+  agent           TEXT NOT NULL,
+  trigger_kind    TEXT NOT NULL,
+  started_at      INTEGER NOT NULL,
+  finished_at     INTEGER,
+  pages_scanned   INTEGER NOT NULL DEFAULT 0,
+  findings_opened INTEGER NOT NULL DEFAULT 0,
+  findings_closed INTEGER NOT NULL DEFAULT 0,
+  cost_usd        REAL NOT NULL DEFAULT 0,
+  error           TEXT
+);
+CREATE INDEX IF NOT EXISTS check_runs_by_scope ON check_runs(scope_key, started_at DESC);
+
+CREATE TABLE IF NOT EXISTS memory_records (
+  id            TEXT PRIMARY KEY,
+  scope         TEXT NOT NULL CHECK (scope IN ('site','session','page')),
+  scope_key     TEXT NOT NULL,
+  kind          TEXT NOT NULL CHECK (kind IN ('fact','preference','decision','glossary')),
+  key           TEXT NOT NULL,
+  value         TEXT NOT NULL,
+  source        TEXT NOT NULL CHECK (source IN ('user','inferred','agent','import')),
+  source_ref    TEXT,
+  confidence    REAL NOT NULL DEFAULT 1,
+  status        TEXT NOT NULL CHECK (status IN ('active','superseded','rejected')),
+  supersedes_id TEXT,
+  created_at    INTEGER NOT NULL,
+  last_used_at  INTEGER,
+  use_count     INTEGER NOT NULL DEFAULT 0
+);
+CREATE INDEX IF NOT EXISTS memory_by_scope ON memory_records(scope_key, status, kind);
+-- One active record per key. A new value supersedes rather than appends;
+-- memory that only grows is memory that contradicts itself.
+CREATE UNIQUE INDEX IF NOT EXISTS memory_active_key
+  ON memory_records(scope, scope_key, kind, key) WHERE status = 'active';
+
+CREATE TABLE IF NOT EXISTS corrections (
+  id        TEXT PRIMARY KEY,
+  trace_id  TEXT NOT NULL,
+  scope_key TEXT NOT NULL,
+  slug      TEXT,
+  request   TEXT NOT NULL,
+  proposed  TEXT NOT NULL,
+  outcome   TEXT NOT NULL CHECK (outcome IN ('accepted','edited','rejected','undone')),
+  applied   TEXT,
+  at        INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS corrections_by_scope ON corrections(scope_key, at DESC);
+
+CREATE TABLE IF NOT EXISTS proposals (
+  id         TEXT PRIMARY KEY,
+  scope_key  TEXT NOT NULL,
+  origin     TEXT NOT NULL,
+  summary    TEXT NOT NULL,
+  ops        TEXT NOT NULL,
+  slugs      TEXT NOT NULL,
+  finding_id TEXT,
+  payload    TEXT,
+  status     TEXT NOT NULL CHECK (status IN ('pending','approved','discarded','expired')),
+  created_at INTEGER NOT NULL,
+  expires_at INTEGER,
+  resolved_at INTEGER
+);
+CREATE INDEX IF NOT EXISTS proposals_by_scope ON proposals(scope_key, status, created_at DESC);
+`;
+/*
+ * Retention. Every other collection in this repo is capped — `HISTORY_DEPTH_CAP`,
+ * `VERSION_LOG_CAP`, `CHAT_HISTORY_CAP` — and these were not. A `plan_ready`
+ * turn writes a whole `PendingApprovalPlan` as a `payload` blob, and the file it
+ * lands in is copied entire into up to 14 rolling `VACUUM INTO` backups, so an
+ * unbounded proposals table is paid for fifteen times over.
+ *
+ * Findings are deliberately not capped: they are reconciled, so the table's size
+ * tracks the number of real problems rather than the number of runs.
+ */
+export const PROPOSAL_CAP = 200;
+export const CORRECTION_CAP = 500;
+export const CHECK_RUN_CAP = 200;
+/**
+ * How long a snooze lasts.
+ *
+ * Seven days, because the button competes with Dismiss and has to mean
+ * something different from it: long enough to clear a finding out of the way
+ * for the week somebody is shipping a campaign, short enough that "I'll get to
+ * it" does not quietly become "never". Exported so both implementations, and
+ * the tests that hold them to the same behaviour, derive it from one number.
+ */
+export const SNOOZE_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+function parseJson(raw, fallback) {
+    if (!raw)
+        return fallback;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+function toFinding(row) {
+    const evidence = parseJson(row.evidence, null);
+    const proposedOps = parseJson(row.proposed_ops, null);
+    return {
+        id: row.id,
+        fingerprint: row.fingerprint,
+        scopeKey: row.scope_key,
+        slug: row.slug,
+        ruleId: row.rule_id,
+        agent: row.agent,
+        severity: row.severity,
+        impact: row.impact ?? fallbackImpact(row.severity),
+        status: row.status,
+        title: row.title,
+        ...(row.detail ? { detail: row.detail } : {}),
+        ...(evidence ? { evidence } : {}),
+        ...(proposedOps ? { proposedOps } : {}),
+        lastRunId: row.last_run_id,
+        firstSeenAt: row.first_seen_at,
+        lastSeenAt: row.last_seen_at,
+        ...(row.resolved_at != null ? { resolvedAt: row.resolved_at } : {}),
+        ...(row.snoozed_until != null ? { snoozedUntil: row.snoozed_until } : {})
+    };
+}
+function toCheckRun(row) {
+    return {
+        id: row.id,
+        scopeKey: row.scope_key,
+        agent: row.agent,
+        trigger: row.trigger_kind,
+        startedAt: row.started_at,
+        ...(row.finished_at != null ? { finishedAt: row.finished_at } : {}),
+        pagesScanned: row.pages_scanned,
+        findingsOpened: row.findings_opened,
+        findingsClosed: row.findings_closed,
+        costUsd: row.cost_usd,
+        ...(row.error ? { error: row.error } : {})
+    };
+}
+function toMemory(row) {
+    return {
+        id: row.id,
+        scope: row.scope,
+        scopeKey: row.scope_key,
+        kind: row.kind,
+        key: row.key,
+        value: row.value,
+        source: row.source,
+        ...(row.source_ref ? { sourceRef: row.source_ref } : {}),
+        confidence: row.confidence,
+        status: row.status,
+        ...(row.supersedes_id ? { supersedesId: row.supersedes_id } : {}),
+        createdAt: row.created_at,
+        ...(row.last_used_at != null ? { lastUsedAt: row.last_used_at } : {}),
+        useCount: row.use_count
+    };
+}
+function toCorrection(row) {
+    const applied = parseJson(row.applied, null);
+    return {
+        id: row.id,
+        traceId: row.trace_id,
+        scopeKey: row.scope_key,
+        ...(row.slug ? { slug: row.slug } : {}),
+        request: row.request,
+        proposed: parseJson(row.proposed, []),
+        outcome: row.outcome,
+        ...(applied ? { applied } : {}),
+        at: row.at
+    };
+}
+function toProposal(row) {
+    return {
+        id: row.id,
+        scopeKey: row.scope_key,
+        origin: row.origin,
+        summary: row.summary,
+        ops: parseJson(row.ops, []),
+        slugs: parseJson(row.slugs, []),
+        ...(row.finding_id ? { findingId: row.finding_id } : {}),
+        ...(row.payload ? { payload: parseJson(row.payload, {}) } : {}),
+        status: row.status,
+        createdAt: row.created_at,
+        ...(row.expires_at != null ? { expiresAt: row.expires_at } : {}),
+        ...(row.resolved_at != null ? { resolvedAt: row.resolved_at } : {})
+    };
+}
+export class SqliteDurableStore {
+    db;
+    now;
+    constructor(db, options = {}) {
+        this.db = db;
+        this.now = options.now ?? Date.now;
+        this.db.exec(SCHEMA);
+        this.ensureColumns();
+    }
+    /*
+     * The one thing `CREATE TABLE IF NOT EXISTS` cannot do: reach a table that
+     * already exists without a column this build needs. There is no migration
+     * runner in the repo, and a `payload` column added to `proposals` after the
+     * table shipped would make every insert fail with "no such column" — swallowed
+     * by a best-effort caller and surfaced as something unrelated.
+     *
+     * `ALTER TABLE ... ADD COLUMN` is cheap, idempotent once guarded, and the only
+     * migration shape this store needs. Anything beyond adding a nullable column
+     * still requires a real runner.
+     */
+    ensureColumns() {
+        const expected = [
+            { table: "proposals", column: "payload", type: "TEXT" },
+            { table: "findings", column: "snoozed_until", type: "INTEGER" },
+            // Nullable on purpose: rows written before impact existed keep NULL and
+            // are read through `IMPACT_FALLBACK_SQL` until the next run scores them.
+            { table: "findings", column: "impact", type: "REAL" }
+        ];
+        for (const { table, column, type } of expected) {
+            const columns = this.db
+                .prepare(`PRAGMA table_info(${table})`)
+                .all()
+                .map((c) => c.name);
+            if (columns.length === 0 || columns.includes(column))
+                continue;
+            this.db.exec(`ALTER TABLE ${table} ADD COLUMN ${column} ${type}`);
+        }
+    }
+    trim(table, scopeKey, cap) {
+        const orderColumn = table === "corrections" ? "at" : table === "proposals" ? "created_at" : "started_at";
+        this.db
+            .prepare(`DELETE FROM ${table} WHERE id IN (
+           SELECT id FROM ${table} WHERE scope_key = ?
+            ORDER BY ${orderColumn} DESC LIMIT -1 OFFSET ?
+         )`)
+            .run(scopeKey, cap);
+    }
+    // Findings ---------------------------------------------------------------
+    async recordFindings(runId, findings) {
+        if (findings.length === 0)
+            return { opened: 0, updated: 0 };
+        const at = this.now();
+        const selectByFingerprint = this.db.prepare("SELECT * FROM findings WHERE scope_key = ? AND fingerprint = ?");
+        const insert = this.db.prepare(`INSERT INTO findings
+         (id, fingerprint, scope_key, slug, rule_id, agent, severity, impact, status, title, detail,
+          evidence, proposed_ops, last_run_id, first_seen_at, last_seen_at, resolved_at)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'open', ?, ?, ?, ?, ?, ?, ?, NULL)`);
+        // Note what this UPDATE does not touch: `status` and `first_seen_at`. A
+        // dismissal has to survive every subsequent run, and "how long has this been
+        // wrong" is the only interesting thing about a finding that keeps recurring.
+        //
+        // `impact` *is* touched, and has to be: it derives from the site's link
+        // graph and nav, so a page that joins the nav today must lift the findings
+        // that have been sitting on it since Tuesday.
+        const update = this.db.prepare(`UPDATE findings
+          SET slug = ?, rule_id = ?, agent = ?, severity = ?, impact = ?, title = ?, detail = ?,
+              evidence = ?, proposed_ops = ?, last_run_id = ?, last_seen_at = ?
+        WHERE id = ?`);
+        const reopen = this.db.prepare("UPDATE findings SET status = 'open', resolved_at = NULL WHERE id = ?");
+        let opened = 0;
+        let updated = 0;
+        this.db.transaction(() => {
+            for (const f of findings) {
+                const existing = selectByFingerprint.get(f.scopeKey, f.fingerprint);
+                const evidence = f.evidence ? JSON.stringify(f.evidence) : null;
+                const ops = f.proposedOps ? JSON.stringify(f.proposedOps) : null;
+                if (!existing) {
+                    insert.run(randomUUID(), f.fingerprint, f.scopeKey, f.slug, f.ruleId, f.agent, f.severity, f.impact ?? null, f.title, f.detail ?? null, evidence, ops, runId, at, at);
+                    opened += 1;
+                    continue;
+                }
+                update.run(f.slug, f.ruleId, f.agent, f.severity, f.impact ?? null, f.title, f.detail ?? null, evidence, ops, runId, at, existing.id);
+                if (existing.status === "fixed") {
+                    reopen.run(existing.id);
+                    opened += 1;
+                }
+                else {
+                    updated += 1;
+                }
+            }
+        })();
+        return { opened, updated };
+    }
+    async reconcileFindings(args) {
+        // A run over two pages must not close findings on the other forty-three.
+        if (args.slugs.length === 0)
+            return { closed: 0 };
+        const at = args.at ?? this.now();
+        const placeholders = args.slugs.map(() => "?").join(", ");
+        const agentClause = args.agent ? " AND agent = ?" : "";
+        // `snoozed` closes too: a snooze defers the report, not the problem, so a
+        // finding deferred on Monday and fixed on Tuesday must not resurface on
+        // Friday as an open finding about a page that is fine.
+        const stmt = this.db.prepare(`UPDATE findings
+          SET status = 'fixed', resolved_at = ?, snoozed_until = NULL
+        WHERE scope_key = ?
+          AND status IN ('open', 'snoozed')
+          AND last_run_id != ?
+          AND slug IN (${placeholders})${agentClause}`);
+        const params = [at, args.scopeKey, args.runId, ...args.slugs];
+        if (args.agent)
+            params.push(args.agent);
+        const result = stmt.run(...params);
+        return { closed: result.changes };
+    }
+    async listFindings(query) {
+        const clauses = ["scope_key = ?"];
+        const params = [query.scopeKey];
+        if (query.slug) {
+            clauses.push("slug = ?");
+            params.push(query.slug);
+        }
+        if (query.agent) {
+            clauses.push("agent = ?");
+            params.push(query.agent);
+        }
+        if (query.severity) {
+            clauses.push("severity = ?");
+            params.push(query.severity);
+        }
+        if (query.status) {
+            const statuses = Array.isArray(query.status) ? query.status : [query.status];
+            if (statuses.length === 0)
+                return [];
+            clauses.push(`status IN (${statuses.map(() => "?").join(", ")})`);
+            params.push(...statuses);
+        }
+        const limit = Math.max(1, Math.min(query.limit ?? 500, 5000));
+        const rows = this.db
+            .prepare(
+        // Impact leads, severity breaks its ties. Ordering by severity first
+        // put every info finding below every warning wherever it sat, which is
+        // how a list whose largest single source was a test page came to be
+        // sorted the way it was.
+        `SELECT * FROM findings WHERE ${clauses.join(" AND ")}
+          ORDER BY
+            ${IMPACT_FALLBACK_SQL} DESC,
+            CASE severity WHEN 'error' THEN 0 WHEN 'warning' THEN 1 ELSE 2 END,
+            last_seen_at DESC
+          LIMIT ?`)
+            .all(...params, limit);
+        return rows.map(toFinding);
+    }
+    async getFinding(id) {
+        const row = this.db.prepare("SELECT * FROM findings WHERE id = ?").get(id);
+        return row ? toFinding(row) : null;
+    }
+    async setFindingStatus(id, status, at) {
+        const when = at ?? this.now();
+        // A snoozed finding is deferred, not resolved — `resolvedAt` on one would
+        // read as "this was dealt with" in every ledger that looks at the column.
+        const resolved = status === "open" || status === "snoozed" ? null : when;
+        const snoozedUntil = status === "snoozed" ? when + SNOOZE_WINDOW_MS : null;
+        this.db
+            .prepare("UPDATE findings SET status = ?, resolved_at = ?, snoozed_until = ? WHERE id = ?")
+            .run(status, resolved, snoozedUntil, id);
+    }
+    async wakeSnoozedFindings(scopeKey, now) {
+        const at = now ?? this.now();
+        const result = this.db
+            .prepare(`UPDATE findings SET status = 'open', snoozed_until = NULL, resolved_at = NULL
+          WHERE scope_key = ? AND status = 'snoozed'
+            AND snoozed_until IS NOT NULL AND snoozed_until <= ?`)
+            .run(scopeKey, at);
+        return { woken: result.changes };
+    }
+    // Check runs -------------------------------------------------------------
+    async startCheckRun(run) {
+        this.db
+            .prepare(`INSERT INTO check_runs (id, scope_key, agent, trigger_kind, started_at)
+         VALUES (?, ?, ?, ?, ?)`)
+            .run(run.id, run.scopeKey, run.agent, run.trigger, run.startedAt);
+        this.trim("check_runs", run.scopeKey, CHECK_RUN_CAP);
+        return {
+            ...run,
+            pagesScanned: 0,
+            findingsOpened: 0,
+            findingsClosed: 0,
+            costUsd: 0
+        };
+    }
+    async finishCheckRun(id, patch) {
+        const sets = [];
+        const params = [];
+        const map = [
+            ["finishedAt", "finished_at"],
+            ["pagesScanned", "pages_scanned"],
+            ["findingsOpened", "findings_opened"],
+            ["findingsClosed", "findings_closed"],
+            ["costUsd", "cost_usd"],
+            ["error", "error"]
+        ];
+        for (const [key, column] of map) {
+            const value = patch[key];
+            if (value === undefined)
+                continue;
+            sets.push(`${column} = ?`);
+            params.push(value);
+        }
+        if (sets.length === 0)
+            return;
+        params.push(id);
+        this.db.prepare(`UPDATE check_runs SET ${sets.join(", ")} WHERE id = ?`).run(...params);
+    }
+    async listCheckRuns(scopeKey, limit = 50) {
+        const rows = this.db
+            .prepare("SELECT * FROM check_runs WHERE scope_key = ? ORDER BY started_at DESC LIMIT ?")
+            .all(scopeKey, Math.max(1, Math.min(limit, 1000)));
+        return rows.map(toCheckRun);
+    }
+    // Memory -----------------------------------------------------------------
+    async putMemory(input, at) {
+        const createdAt = at ?? this.now();
+        const id = randomUUID();
+        const confidence = input.confidence ?? 1;
+        const record = this.db.transaction(() => {
+            const previous = this.db
+                .prepare(`SELECT * FROM memory_records
+            WHERE scope = ? AND scope_key = ? AND kind = ? AND key = ? AND status = 'active'`)
+                .get(input.scope, input.scopeKey, input.kind, input.key);
+            if (previous) {
+                this.db.prepare("UPDATE memory_records SET status = 'superseded' WHERE id = ?").run(previous.id);
+            }
+            this.db
+                .prepare(`INSERT INTO memory_records
+             (id, scope, scope_key, kind, key, value, source, source_ref, confidence,
+              status, supersedes_id, created_at, last_used_at, use_count)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?, NULL, 0)`)
+                .run(id, input.scope, input.scopeKey, input.kind, input.key, input.value, input.source, input.sourceRef ?? null, confidence, previous?.id ?? null, createdAt);
+            return this.db
+                .prepare("SELECT * FROM memory_records WHERE id = ?")
+                .get(id);
+        })();
+        if (!record)
+            throw new Error("putMemory: insert did not produce a row");
+        return toMemory(record);
+    }
+    async listMemory(query = {}) {
+        const clauses = [];
+        const params = [];
+        if (query.scopeKey) {
+            clauses.push("scope_key = ?");
+            params.push(query.scopeKey);
+        }
+        if (query.scope) {
+            clauses.push("scope = ?");
+            params.push(query.scope);
+        }
+        if (query.kind) {
+            const kinds = Array.isArray(query.kind) ? query.kind : [query.kind];
+            if (kinds.length === 0)
+                return [];
+            clauses.push(`kind IN (${kinds.map(() => "?").join(", ")})`);
+            params.push(...kinds);
+        }
+        // Default to active only: a superseded record exists for the audit trail,
+        // not to be handed back to a planner as though it were still true.
+        clauses.push("status = ?");
+        params.push(query.status ?? "active");
+        const limit = Math.max(1, Math.min(query.limit ?? 500, 5000));
+        const rows = this.db
+            .prepare(`SELECT * FROM memory_records
+          ${clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : ""}
+          ORDER BY created_at DESC LIMIT ?`)
+            .all(...params, limit);
+        return rows.map(toMemory);
+    }
+    async touchMemory(ids, at) {
+        if (ids.length === 0)
+            return;
+        const when = at ?? this.now();
+        const placeholders = ids.map(() => "?").join(", ");
+        this.db
+            .prepare(`UPDATE memory_records
+            SET last_used_at = ?, use_count = use_count + 1
+          WHERE id IN (${placeholders})`)
+            .run(when, ...ids);
+    }
+    async setMemoryStatus(id, status) {
+        // Reactivating has to demote whatever is active for that key. Writing
+        // `status` blind hits the `memory_active_key` partial unique index and
+        // throws from a setter no caller expects to throw — and the in-memory
+        // store, with no index to stop it, would instead end up handing a planner
+        // two contradicting facts for one key.
+        this.db.transaction(() => {
+            if (status === "active") {
+                const target = this.db
+                    .prepare("SELECT * FROM memory_records WHERE id = ?")
+                    .get(id);
+                if (!target)
+                    return;
+                this.db
+                    .prepare(`UPDATE memory_records SET status = 'superseded'
+              WHERE scope = ? AND scope_key = ? AND kind = ? AND key = ?
+                AND status = 'active' AND id != ?`)
+                    .run(target.scope, target.scope_key, target.kind, target.key, id);
+            }
+            this.db.prepare("UPDATE memory_records SET status = ? WHERE id = ?").run(status, id);
+        })();
+    }
+    // Corrections ------------------------------------------------------------
+    async recordCorrection(input, at) {
+        const record = { ...input, id: randomUUID(), at: at ?? this.now() };
+        this.db
+            .prepare(`INSERT INTO corrections (id, trace_id, scope_key, slug, request, proposed, outcome, applied, at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`)
+            .run(record.id, record.traceId, record.scopeKey, record.slug ?? null, record.request, JSON.stringify(record.proposed), record.outcome, record.applied ? JSON.stringify(record.applied) : null, record.at);
+        this.trim("corrections", record.scopeKey, CORRECTION_CAP);
+        return record;
+    }
+    async listCorrections(query = {}) {
+        const clauses = [];
+        const params = [];
+        if (query.scopeKey) {
+            clauses.push("scope_key = ?");
+            params.push(query.scopeKey);
+        }
+        if (query.outcome) {
+            clauses.push("outcome = ?");
+            params.push(query.outcome);
+        }
+        if (query.since != null) {
+            clauses.push("at >= ?");
+            params.push(query.since);
+        }
+        const limit = Math.max(1, Math.min(query.limit ?? 200, 5000));
+        const rows = this.db
+            .prepare(`SELECT * FROM corrections
+          ${clauses.length > 0 ? `WHERE ${clauses.join(" AND ")}` : ""}
+          ORDER BY at DESC LIMIT ?`)
+            .all(...params, limit);
+        return rows.map(toCorrection);
+    }
+    // Proposals --------------------------------------------------------------
+    async putProposal(input) {
+        this.db
+            .prepare(`INSERT INTO proposals
+           (id, scope_key, origin, summary, ops, slugs, finding_id, payload, status, created_at, expires_at, resolved_at)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?, NULL)
+         ON CONFLICT(id) DO UPDATE SET
+           origin = excluded.origin,
+           summary = excluded.summary,
+           ops = excluded.ops,
+           slugs = excluded.slugs,
+           finding_id = excluded.finding_id,
+           payload = excluded.payload,
+           expires_at = excluded.expires_at`)
+            .run(input.id, input.scopeKey, input.origin, input.summary, JSON.stringify(input.ops), JSON.stringify(input.slugs), input.findingId ?? null, input.payload ? JSON.stringify(input.payload) : null, input.createdAt, input.expiresAt ?? null);
+        this.trim("proposals", input.scopeKey, PROPOSAL_CAP);
+        const record = await this.getProposal(input.id);
+        if (!record)
+            throw new Error("putProposal: insert did not produce a row");
+        return record;
+    }
+    async getProposal(id) {
+        const row = this.db.prepare("SELECT * FROM proposals WHERE id = ?").get(id);
+        return row ? toProposal(row) : null;
+    }
+    async listProposals(query) {
+        const clauses = ["scope_key = ?"];
+        const params = [query.scopeKey];
+        if (query.status) {
+            clauses.push("status = ?");
+            params.push(query.status);
+        }
+        const limit = Math.max(1, Math.min(query.limit ?? 100, 1000));
+        const rows = this.db
+            .prepare(`SELECT * FROM proposals WHERE ${clauses.join(" AND ")} ORDER BY created_at DESC LIMIT ?`)
+            .all(...params, limit);
+        return rows.map(toProposal);
+    }
+    async setProposalStatus(id, status, at) {
+        const resolved = status === "pending" ? null : (at ?? this.now());
+        this.db.prepare("UPDATE proposals SET status = ?, resolved_at = ? WHERE id = ?").run(status, resolved, id);
+    }
+    async expireProposals(now) {
+        const at = now ?? this.now();
+        const result = this.db
+            .prepare(`UPDATE proposals SET status = 'expired', resolved_at = ?
+          WHERE status = 'pending' AND expires_at IS NOT NULL AND expires_at <= ?`)
+            .run(at, at);
+        return { expired: result.changes };
+    }
+}