plasalid 0.8.2 → 0.9.0

package/dist/cli/ink/ScanDashboard.js

@@ -1,7 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useState } from "react";
-import { Box, Text, useStdout } from "ink";
+import { memo, useEffect, useMemo, useState } from "react";
+import { Box, Text } from "ink";
 import Spinner from "ink-spinner";
+import chalk from "chalk";
+import { padRight, truncateMiddle } from "../helper.js";
+import { ListBrowser } from "./ListBrowser.js";
+import { keyOf } from "./keys.js";
 export function createScanDashboardController() {
     const subscribers = new Set();
     return {
@@ -25,6 +29,7 @@ function classify(input, rules) {
     throw new Error("classify: no rule matched (missing catch-all?)");
 }
 const COL = {
+    marker: 2, // "▸ " or "  "
     status: 14,
     files: 34,
     transactions: 13,
@@ -33,11 +38,36 @@ const COL = {
 export function ScanDashboard(props) {
     const rows = useFileGroups(props.controller, props.files);
     const phase = usePhase(props.controller);
-    const ruleWidth = useRuleWidth();
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Header, { phase: phase }), _jsx(AttachmentLine, { info: props.attachment }), _jsx(Box, { marginTop: 1, children: _jsx(ColumnHeader, {}) }), _jsx(Divider, { width: ruleWidth }), Array.from(rows.entries()).map(([fileId, group]) => (_jsx(FileGroupView, { group: group }, fileId))), _jsx(Divider, { width: ruleWidth }), phase !== "done" && _jsx(Footnote, {})] }));
+    const spinnerFrame = useSpinnerFrame();
+    const items = useMemo(() => Array.from(rows.entries(), ([fileId, group]) => ({ fileId, group })), [rows]);
+    const adapter = useMemo(() => ({
+        headerNode: (_jsxs(Box, { flexDirection: "column", children: [_jsx(Header, { phase: phase }), _jsx(AttachmentLine, { info: props.attachment }), _jsx(ColumnHeader, {})] })),
+        items,
+        getId: (i) => i.fileId,
+        renderRow: (i, ctx) => renderFileRow(i.group, ctx.isCursor, ctx.isExpanded, spinnerFrame, phase),
+        renderExpanded: (i) => (_jsx(ChunkList, { chunks: i.group.chunks, frame: spinnerFrame })),
+        getExpandedHeight: (i) => i.group.chunks.size,
+        matches: (i, needle) => i.group.fileName.toLowerCase().includes(needle),
+        summary: phase !== "done" ? _jsx(Footnote, {}) : null,
+        onKey: (input, key) => {
+            const k = keyOf(input, key);
+            return k === "q" || k === "escape";
+        },
+        emptyMessage: "No files in the scan queue.",
+    }), [phase, items, props.attachment, spinnerFrame]);
+    return _jsx(ListBrowser, { adapter: adapter });
+}
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+function useSpinnerFrame() {
+    const [i, setI] = useState(0);
+    useEffect(() => {
+        const id = setInterval(() => setI((prev) => (prev + 1) % SPINNER_FRAMES.length), 80);
+        return () => clearInterval(id);
+    }, []);
+    return SPINNER_FRAMES[i];
 }
 function Footnote() {
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "output accuracy depends on the model's VL capability." }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "we also provide " }), _jsx(Text, { color: "cyan", children: "clarify" }), _jsx(Text, { dimColor: true, children: ", " }), _jsx(Text, { color: "cyan", children: "record" }), _jsx(Text, { dimColor: true, children: ", and " }), _jsx(Text, { color: "cyan", children: "chat" }), _jsx(Text, { dimColor: true, children: " to rectify the data later." })] })] }));
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Text, { dimColor: true, children: "Output accuracy depends on the model's vision capability." }), _jsxs(Text, { children: [_jsx(Text, { dimColor: true, children: "You can run " }), _jsx(Text, { color: "cyan", children: "clarify" }), _jsx(Text, { dimColor: true, children: ", " }), _jsx(Text, { color: "cyan", children: "record" }), _jsx(Text, { dimColor: true, children: ", and " }), _jsx(Text, { color: "cyan", children: "chat" }), _jsx(Text, { dimColor: true, children: " to correct the data later." })] })] }));
 }
 function AttachmentLine({ info }) {
     const detail = info.format === "pdf" ? "pdf (native)" : "png (rasterized)";
@@ -51,20 +81,6 @@ function usePhase(controller) {
     }), [controller]);
     return phase;
 }
-function useRuleWidth() {
-    const { stdout } = useStdout();
-    const [cols, setCols] = useState(() => stdout?.columns ?? 100);
-    useEffect(() => {
-        if (!stdout)
-            return;
-        const onResize = () => setCols(stdout.columns ?? 100);
-        stdout.on("resize", onResize);
-        return () => {
-            stdout.off("resize", onResize);
-        };
-    }, [stdout]);
-    return Math.min(cols, 120);
-}
 const PHASE_RENDER = {
     pending: (label) => _jsx(Text, { dimColor: true, children: label }),
     running: (label) => (_jsxs(Text, { color: "yellow", children: [_jsx(Spinner, { type: "dots" }), " ", label] })),
@@ -81,28 +97,40 @@ function phaseStateOf(label, current) {
     return "pending";
 }
 function Header({ phase }) {
-    // Cancellation collapses the parse/clarify segments — neither is still
-    // running once the user hits Ctrl+C, and showing them as "pending" would
-    // be misleading. The single "cancelling…" label communicates the wind-down.
     if (phase === "cancelling") {
         return (_jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Scanner" }), _jsx(Text, { dimColor: true, children: "  ·  " }), _jsx(Text, { color: "green", children: "\u2713 decrypt" }), _jsx(Text, { dimColor: true, children: " -> " }), _jsx(Text, { color: "green", children: "\u2713 chunk" }), _jsx(Text, { dimColor: true, children: " -> " }), _jsxs(Text, { color: "red", children: [_jsx(Spinner, { type: "dots" }), " cancelling\u2026"] })] }));
     }
     return (_jsxs(Text, { children: [_jsx(Text, { bold: true, children: "Scanner" }), _jsx(Text, { dimColor: true, children: "  ·  " }), _jsx(Text, { color: "green", children: "\u2713 decrypt" }), _jsx(Text, { dimColor: true, children: " -> " }), _jsx(Text, { color: "green", children: "\u2713 chunk" }), _jsx(Text, { dimColor: true, children: " -> " }), PHASE_RENDER[phaseStateOf("parse", phase)]("parse"), _jsx(Text, { dimColor: true, children: " -> " }), PHASE_RENDER[phaseStateOf("clarify", phase)]("clarify")] }));
 }
 function ColumnHeader() {
-    return (_jsxs(Box, { flexDirection: "row", children: [_jsx(Box, { width: COL.status, children: _jsx(Text, { dimColor: true, children: "status" }) }), _jsx(Box, { width: COL.files, children: _jsx(Text, { dimColor: true, children: "files" }) }), _jsx(Box, { width: COL.transactions, children: _jsx(Text, { dimColor: true, children: "transactions" }) }), _jsx(Box, { width: COL.questions, children: _jsx(Text, { dimColor: true, children: "questions" }) })] }));
-}
-function Divider({ width }) {
-    return _jsx(Text, { dimColor: true, children: "─".repeat(width) });
-}
-const spin = (label) => () => (_jsxs(Text, { color: "yellow", children: [_jsx(Spinner, { type: "dots" }), " ", label] }));
-const STATUS_RENDER = {
-    queued: () => _jsx(Text, { color: "gray", children: "queued" }),
-    running: spin("running"),
-    scanning: spin("scanning"),
-    done: () => _jsx(Text, { color: "green", children: "\u2713 done" }),
-    failed: () => _jsx(Text, { color: "red", children: "failed" }),
-    partial: () => _jsx(Text, { color: "yellow", children: "partial" }),
+    return (_jsxs(Box, { flexDirection: "row", marginTop: 1, children: [_jsx(Box, { width: COL.marker }), _jsx(Box, { width: COL.status, children: _jsx(Text, { dimColor: true, children: "status" }) }), _jsx(Box, { width: COL.files, children: _jsx(Text, { dimColor: true, children: "files" }) }), _jsx(Box, { width: COL.transactions, children: _jsx(Text, { dimColor: true, children: "transactions" }) }), _jsx(Box, { width: COL.questions, children: _jsx(Text, { dimColor: true, children: "questions" }) })] }));
+}
+function statusText(status, frame) {
+    switch (status) {
+        case "queued":
+            return "queued";
+        case "running":
+            return `${frame} running`;
+        case "scanning":
+            return `${frame} scanning`;
+        case "clarify":
+            return `${frame} clarify`;
+        case "done":
+            return "✓ done";
+        case "failed":
+            return "failed";
+        case "partial":
+            return "partial";
+    }
+}
+const STATUS_COLOR = {
+    queued: chalk.gray,
+    running: chalk.yellow,
+    scanning: chalk.yellow,
+    clarify: chalk.yellow,
+    done: chalk.green,
+    failed: chalk.red,
+    partial: chalk.yellow,
 };
 const FILE_STATUS_RULES = [
     { when: ({ finished, total }) => finished < total, state: "scanning" },
@@ -123,40 +151,34 @@ function aggregate(chunks, total) {
     const status = classify({ finished: done + failed, failed, total }, FILE_STATUS_RULES);
     return { totalTx, totalQuestions, status };
 }
-function FileGroupView({ group }) {
-    const chunks = Array.from(group.chunks.values()).sort((a, b) => a.pageNumber - b.pageNumber);
+function renderFileRow(group, isCursor, isExpanded, frame, phase) {
+    const chunks = Array.from(group.chunks.values());
     const agg = aggregate(chunks, group.totalChunks);
-    const fileName = `> ${truncateMiddle(group.fileName, COL.files - 2)}`;
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Row, { status: _jsx(StatusText, { status: agg.status }), files: _jsx(Text, { dimColor: true, children: fileName }), transactions: agg.totalTx, questions: agg.totalQuestions }), chunks.map((c) => (_jsx(ChunkRow, { chunk: c }, c.pageNumber)))] }));
-}
-function ChunkRow({ chunk }) {
-    const connector = "|-";
-    return (_jsx(Row, { status: _jsx(StatusText, { status: chunk.status }), files: _jsx(Text, { dimColor: true, children: `  ${connector} part ${chunk.pageNumber}` }), transactions: chunk.txCount, questions: chunk.questionsCount }));
-}
-function StatusText({ status }) {
-    return STATUS_RENDER[status]();
-}
-function Row({ status, files, transactions, questions, }) {
-    return (_jsxs(Box, { flexDirection: "row", children: [_jsx(Box, { width: COL.status, children: status }), _jsx(Box, { width: COL.files, children: files }), _jsx(Box, { width: COL.transactions, children: _jsx(Numeric, { n: transactions }) }), _jsx(Box, { width: COL.questions, children: _jsx(Numeric, { n: questions }) })] }));
-}
-const NUMERIC_RULES = [
-    { when: (n) => n > 0, state: "present" },
-    { when: () => true, state: "empty" },
-];
-const NUMERIC_RENDER = {
-    present: (n) => _jsx(Text, { children: n }),
-    empty: () => (_jsx(Text, { color: "gray", dimColor: true, children: "-" })),
-};
-function Numeric({ n }) {
-    return NUMERIC_RENDER[classify(n, NUMERIC_RULES)](n);
-}
-function truncateMiddle(s, width) {
-    if (s.length <= width)
-        return s;
-    const keep = width - 1;
-    const left = Math.ceil(keep / 2);
-    const right = Math.floor(keep / 2);
-    return s.slice(0, left) + "..." + s.slice(s.length - right);
+    const effectiveStatus = phase === "clarify" ? "clarify" : agg.status;
+    const marker = isExpanded ? "▾" : isCursor ? "▸" : " ";
+    const status = STATUS_COLOR[effectiveStatus](padRight(statusText(effectiveStatus, frame), COL.status));
+    const nameRaw = truncateMiddle(group.fileName, COL.files - 2);
+    const namePadded = padRight(nameRaw, COL.files);
+    const name = isCursor ? chalk.cyan.bold(namePadded) : chalk.dim(namePadded);
+    const tx = renderCount(agg.totalTx, COL.transactions);
+    const q = renderCount(agg.totalQuestions, COL.questions);
+    return `${marker} ${status}${name}${tx}${q}`;
+}
+function renderCount(n, width) {
+    const raw = n > 0 ? String(n) : "-";
+    const padded = padRight(raw, width);
+    return n > 0 ? padded : chalk.gray(padded);
+}
+const ChunkList = memo(function ChunkList({ chunks, frame, }) {
+    const sorted = Array.from(chunks.values()).sort((a, b) => a.pageNumber - b.pageNumber);
+    return (_jsx(Box, { flexDirection: "column", children: sorted.map((c) => (_jsx(Text, { children: renderChunkLine(c, frame) }, c.pageNumber))) }));
+});
+function renderChunkLine(c, frame) {
+    const status = STATUS_COLOR[c.status](padRight(statusText(c.status, frame), COL.status));
+    const part = chalk.dim(padRight(`  |- part ${c.pageNumber}`, COL.files));
+    const tx = renderCount(c.txCount, COL.transactions);
+    const q = renderCount(c.questionsCount, COL.questions);
+    return `  ${status}${part}${tx}${q}`;
 }
 function useFileGroups(controller, files) {
     const [rows, setRows] = useState(() => seedRows(files));

package/dist/cli/ink/hooks/useFooterText.js

@@ -1,5 +1,7 @@
 import { useEffect, useMemo, useState } from "react";
 import chalk from "chalk";
+import { getActiveModel } from "../../../config.js";
+import { getProvider } from "../../../ai/providers/index.js";
 const HINTS = [
     "try: what's my net worth?",
     "try: how many months of runway do I have?",
@@ -36,33 +38,23 @@ const HINTS = [
 export function useFooterText(db) {
     const [tick, setTick] = useState(0);
     const [hintIdx] = useState(() => Math.floor(Math.random() * HINTS.length));
+    const providerModel = `${getProvider().name}/${getActiveModel()}`;
     useEffect(() => {
         const id = setInterval(() => setTick((t) => t + 1), 60_000);
         return () => clearInterval(id);
     }, []);
     return useMemo(() => {
-        const lastScan = db
-            .prepare(`SELECT MAX(scanned_at) AS ts FROM scanned_files WHERE status = 'scanned'`)
+        const { n: fileCount } = db
+            .prepare(`SELECT COUNT(*) AS n FROM scanned_files WHERE status = 'scanned'`)
             .get();
-        let scanStr = "";
-        if (lastScan?.ts) {
-            const diffMs = Date.now() - new Date(lastScan.ts + "Z").getTime();
-            const mins = Math.floor(diffMs / 60000);
-            if (mins < 1)
-                scanStr = "scanned just now";
-            else if (mins < 60)
-                scanStr = `scanned ${mins}m ago`;
-            else if (mins < 1440)
-                scanStr = `scanned ${Math.floor(mins / 60)}h ago`;
-            else
-                scanStr = `scanned ${Math.floor(mins / 1440)}d ago`;
-        }
         const idx = (hintIdx + tick) % HINTS.length;
-        const parts = [`${chalk.cyan("<°(((><")}`];
-        if (scanStr)
-            parts.push(scanStr);
-        parts.push(HINTS[idx]);
-        parts.push("ctrl+c to exit");
-        return parts.join("  |  ");
-    }, [db, tick, hintIdx]);
+        const parts = [
+            chalk.cyan("<°(((><"),
+            chalk.dim(providerModel),
+            chalk.dim(`${fileCount} file${fileCount === 1 ? "" : "s"}`),
+            chalk.dim(HINTS[idx]),
+            chalk.dim("ctrl+c to exit"),
+        ];
+        return parts.join(chalk.dim("  |  "));
+    }, [db, tick, hintIdx, providerModel]);
 }

package/dist/cli/ink/keys.d.ts

@@ -0,0 +1,2 @@
+import type { Key } from "ink";
+export declare function keyOf(input: string, key: Key): string;

package/dist/cli/ink/keys.js

@@ -0,0 +1,19 @@
+const SPECIAL = [
+    [(k) => k.escape, "escape"],
+    [(k) => k.return, "return"],
+    [(k) => k.backspace, "backspace"],
+    [(k) => k.delete, "delete"],
+    [(k) => k.upArrow, "upArrow"],
+    [(k) => k.downArrow, "downArrow"],
+    [(k) => k.leftArrow, "leftArrow"],
+    [(k) => k.rightArrow, "rightArrow"],
+    [(k) => k.pageUp, "pageUp"],
+    [(k) => k.pageDown, "pageDown"],
+    [(k) => k.tab, "tab"],
+];
+export function keyOf(input, key) {
+    for (const [pred, name] of SPECIAL)
+        if (pred(key))
+            return name;
+    return input;
+}

package/dist/db/queries/files.d.ts

@@ -4,8 +4,37 @@ export interface ScannedFileTotals {
     pending: number;
     failed: number;
 }
+export interface ScannedFileRow {
+    id: string;
+    path: string;
+    file_hash: string;
+    mime: string;
+    status: "pending" | "scanned" | "failed";
+    scanned_at: string | null;
+    provider: string | null;
+    model: string | null;
+    error: string | null;
+    created_at: string;
+}
 /**
  * Bucket the `scanned_files` table by its `status` enum. Missing buckets are
  * filled with 0 so callers can render a stable shape without null checks.
  */
 export declare function countScannedFiles(db: Database.Database): ScannedFileTotals;
+export declare function listScannedFiles(db: Database.Database): ScannedFileRow[];
+export declare function findScannedFileById(db: Database.Database, id: string): ScannedFileRow | null;
+export interface DeleteScannedFileResult {
+    /** The deleted row, or null when no row matched the id. */
+    removed: ScannedFileRow | null;
+    /** Count of transaction rows that cascaded out. */
+    removedTransactions: number;
+    /** Count of question rows that cascaded out. */
+    removedQuestions: number;
+}
+/**
+ * Delete a `scanned_files` row by id. Cascades remove transactions
+ * (`transactions.source_file_id`) and questions (`questions.file_id`) via the
+ * schema's ON DELETE CASCADE. Cascaded counts are gathered before the DELETE
+ * so callers can report what disappeared.
+ */
+export declare function deleteScannedFile(db: Database.Database, id: string): DeleteScannedFileResult;

package/dist/db/queries/files.js

@@ -14,3 +14,37 @@ export function countScannedFiles(db) {
     }
     return totals;
 }
+export function listScannedFiles(db) {
+    return db
+        .prepare(`SELECT id, path, file_hash, mime, status, scanned_at, provider, model, error, created_at
+       FROM scanned_files
+       ORDER BY scanned_at DESC, created_at DESC`)
+        .all();
+}
+export function findScannedFileById(db, id) {
+    const row = db
+        .prepare(`SELECT id, path, file_hash, mime, status, scanned_at, provider, model, error, created_at
+       FROM scanned_files WHERE id = ?`)
+        .get(id);
+    return row ?? null;
+}
+/**
+ * Delete a `scanned_files` row by id. Cascades remove transactions
+ * (`transactions.source_file_id`) and questions (`questions.file_id`) via the
+ * schema's ON DELETE CASCADE. Cascaded counts are gathered before the DELETE
+ * so callers can report what disappeared.
+ */
+export function deleteScannedFile(db, id) {
+    const removed = findScannedFileById(db, id);
+    if (!removed) {
+        return { removed: null, removedTransactions: 0, removedQuestions: 0 };
+    }
+    const removedTransactions = db
+        .prepare(`SELECT COUNT(*) AS n FROM transactions WHERE source_file_id = ?`)
+        .get(id).n;
+    const removedQuestions = db
+        .prepare(`SELECT COUNT(*) AS n FROM questions WHERE file_id = ?`)
+        .get(id).n;
+    db.prepare(`DELETE FROM scanned_files WHERE id = ?`).run(id);
+    return { removed, removedTransactions, removedQuestions };
+}

package/dist/db/queries/questions.d.ts

@@ -22,12 +22,17 @@ export interface QuestionRow {
     prompt: string;
     options_json: string | null;
     context_json: string | null;
+    deferred_until: string | null;
     created_at: string;
 }
 export interface ClosedQuestion {
     prompt: string;
     kind: string | null;
     answer: string;
+    /** Stable signature pulled from the question's context_json. When set, the
+     * rule synthesizer keys the learned rule on this (so future questions with
+     * different prose but the same key match). When null, no rule is learned. */
+    rule_key: string | null;
 }
 /**
  * Insert a new questions row and flip the `has_question` boolean on whichever
@@ -53,10 +58,22 @@ export interface CountQuestionsScope {
     account_id?: string;
     kind?: string;
     scan_id?: string;
+    /** When true, count deferred rows too (default false — defer hides). */
+    includeDeferred?: boolean;
 }
 export declare function countQuestions(db: Database.Database, scope?: CountQuestionsScope): number;
 export interface ListQuestionsOptions {
     limit?: number;
     scanId?: string;
+    /** When true, include deferred rows in the result (default false). */
+    includeDeferred?: boolean;
 }
 export declare function listQuestions(db: Database.Database, opts?: ListQuestionsOptions): QuestionRow[];
+/**
+ * Mark a question as deferred for `days` days from now. The default
+ * `listQuestions` / `countQuestions` filter hides deferred rows until the
+ * timestamp passes, so the clarifier won't re-encounter the question on the
+ * next run. Pass `includeDeferred: true` to those functions for an
+ * unfiltered view (e.g. for the rules / files browsers).
+ */
+export declare function deferQuestion(db: Database.Database, id: string, days: number): boolean;

package/dist/db/queries/questions.js

@@ -24,7 +24,7 @@ export function recordQuestion(db, input) {
  */
 export function closeQuestion(db, id, answer) {
     const row = db
-        .prepare(`SELECT prompt, kind, transaction_id, account_id FROM questions WHERE id = ?`)
+        .prepare(`SELECT prompt, kind, transaction_id, account_id, context_json FROM questions WHERE id = ?`)
         .get(id);
     if (!row)
         return null;
@@ -33,7 +33,23 @@ export function closeQuestion(db, id, answer) {
         transaction_id: row.transaction_id,
         account_id: row.account_id,
     });
-    return { prompt: row.prompt, kind: row.kind, answer };
+    return {
+        prompt: row.prompt,
+        kind: row.kind,
+        answer,
+        rule_key: extractRuleKey(row.context_json),
+    };
+}
+function extractRuleKey(contextJson) {
+    if (!contextJson)
+        return null;
+    try {
+        const parsed = JSON.parse(contextJson);
+        return typeof parsed?.rule_key === "string" ? parsed.rule_key : null;
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Look up the transaction/account a question is attached to. Returns null when
@@ -65,6 +81,7 @@ function maybeClearHasQuestionFlags(db, target) {
             db.prepare(`UPDATE accounts SET has_question = 0 WHERE id = ?`).run(target.account_id);
     }
 }
+const ACTIVE_DEFERRED_CLAUSE = "(deferred_until IS NULL OR deferred_until <= datetime('now'))";
 export function countQuestions(db, scope = {}) {
     const conditions = [];
     const params = [];
@@ -88,23 +105,44 @@ export function countQuestions(db, scope = {}) {
         conditions.push("scan_id = ?");
         params.push(scope.scan_id);
     }
+    if (!scope.includeDeferred)
+        conditions.push(ACTIVE_DEFERRED_CLAUSE);
     const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
     const row = db
         .prepare(`SELECT COUNT(*) AS n FROM questions ${where}`)
         .get(...params);
     return row.n;
 }
+const ROW_COLUMNS = "id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, deferred_until, created_at";
 export function listQuestions(db, opts = {}) {
     const capped = Math.min(Math.max(opts.limit ?? 200, 1), 1000);
+    const conditions = [];
+    const params = [];
     if (opts.scanId) {
-        return db.prepare(`SELECT id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
-       FROM questions
-       WHERE scan_id = ?
-       ORDER BY created_at ASC
-       LIMIT ?`).all(opts.scanId, capped);
+        conditions.push("scan_id = ?");
+        params.push(opts.scanId);
     }
-    return db.prepare(`SELECT id, scan_id, file_id, transaction_id, account_id, kind, prompt, options_json, context_json, created_at
+    if (!opts.includeDeferred)
+        conditions.push(ACTIVE_DEFERRED_CLAUSE);
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    params.push(capped);
+    return db.prepare(`SELECT ${ROW_COLUMNS}
      FROM questions
+     ${where}
      ORDER BY created_at ASC
-     LIMIT ?`).all(capped);
+     LIMIT ?`).all(...params);
+}
+/**
+ * Mark a question as deferred for `days` days from now. The default
+ * `listQuestions` / `countQuestions` filter hides deferred rows until the
+ * timestamp passes, so the clarifier won't re-encounter the question on the
+ * next run. Pass `includeDeferred: true` to those functions for an
+ * unfiltered view (e.g. for the rules / files browsers).
+ */
+export function deferQuestion(db, id, days) {
+    const safeDays = Math.max(1, Math.floor(days));
+    const result = db
+        .prepare(`UPDATE questions SET deferred_until = datetime('now', ?) WHERE id = ?`)
+        .run(`+${safeDays} days`, id);
+    return result.changes > 0;
 }

package/dist/db/queries/rules.d.ts

@@ -0,0 +1,31 @@
+import type Database from "libsql";
+export interface Rule {
+    id: number;
+    kind: string;
+    key: string;
+    target: string;
+    evidence_count: number;
+    last_seen_at: string;
+    created_at: string;
+}
+export interface UpsertRuleInput {
+    kind: string;
+    key: string;
+    target: string;
+}
+/**
+ * Insert a rule keyed on (kind, key), or — if one already exists — bump
+ * `evidence_count`, refresh `last_seen_at`, and overwrite `target` with the
+ * latest answer. The deterministic clarifier pass looks rules up via the
+ * UNIQUE(kind, key) index, so this is the only write path that keeps the
+ * rule store sparse and indexed.
+ */
+export declare function upsertRule(db: Database.Database, input: UpsertRuleInput): Rule;
+export declare function findRule(db: Database.Database, kind: string, key: string): Rule | null;
+export interface ListRulesOptions {
+    kind?: string;
+    limit?: number;
+}
+export declare function listRules(db: Database.Database, opts?: ListRulesOptions): Rule[];
+export declare function countRules(db: Database.Database): number;
+export declare function deleteRule(db: Database.Database, id: number): Rule | null;

package/dist/db/queries/rules.js

@@ -0,0 +1,55 @@
+/**
+ * Insert a rule keyed on (kind, key), or — if one already exists — bump
+ * `evidence_count`, refresh `last_seen_at`, and overwrite `target` with the
+ * latest answer. The deterministic clarifier pass looks rules up via the
+ * UNIQUE(kind, key) index, so this is the only write path that keeps the
+ * rule store sparse and indexed.
+ */
+export function upsertRule(db, input) {
+    db.prepare(`INSERT INTO rules (kind, key, target)
+     VALUES (?, ?, ?)
+     ON CONFLICT(kind, key) DO UPDATE SET
+       target = excluded.target,
+       evidence_count = evidence_count + 1,
+       last_seen_at = datetime('now')`).run(input.kind, input.key, input.target);
+    const row = findRule(db, input.kind, input.key);
+    if (!row)
+        throw new Error(`upsertRule: row vanished after upsert (${input.kind}, ${input.key})`);
+    return row;
+}
+export function findRule(db, kind, key) {
+    const row = db
+        .prepare(`SELECT id, kind, key, target, evidence_count, last_seen_at, created_at
+       FROM rules WHERE kind = ? AND key = ?`)
+        .get(kind, key);
+    return row ?? null;
+}
+export function listRules(db, opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 500, 1), 5000);
+    if (opts.kind) {
+        return db
+            .prepare(`SELECT id, kind, key, target, evidence_count, last_seen_at, created_at
+         FROM rules WHERE kind = ?
+         ORDER BY last_seen_at DESC LIMIT ?`)
+            .all(opts.kind, limit);
+    }
+    return db
+        .prepare(`SELECT id, kind, key, target, evidence_count, last_seen_at, created_at
+       FROM rules
+       ORDER BY last_seen_at DESC LIMIT ?`)
+        .all(limit);
+}
+export function countRules(db) {
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM rules`).get();
+    return row.n;
+}
+export function deleteRule(db, id) {
+    const row = db
+        .prepare(`SELECT id, kind, key, target, evidence_count, last_seen_at, created_at
+       FROM rules WHERE id = ?`)
+        .get(id);
+    if (!row)
+        return null;
+    db.prepare(`DELETE FROM rules WHERE id = ?`).run(id);
+    return row;
+}

package/dist/db/queries/transactions.d.ts

@@ -89,6 +89,39 @@ export declare function updatePosting(db: Database.Database, postingId: string,
  * the postings automatically.
  */
 export declare function deleteTransaction(db: Database.Database, transactionId: string): number;
+export interface BulkUpdatePostingsFilter {
+    account_id?: string;
+    /** Case-insensitive substring match against `transactions.description`.
+     *  Use multiple bulk calls for descriptor variants — there is no regex. */
+    description_contains?: string;
+    currency?: string;
+    from?: string;
+    to?: string;
+    merchant_id?: string;
+}
+export interface BulkUpdatePostingsSet {
+    account_id?: string;
+    memo?: string | null;
+}
+export interface BulkUpdatePostingsResult {
+    affected: number;
+    sample_posting_ids: string[];
+}
+/**
+ * Backfill primitive. Update every posting matching the filter in one SQL
+ * UPDATE, return the affected count plus a sample of ids so the caller (often
+ * an AI tool) can quote evidence back to the user.
+ *
+ * Refuses to run without at least one filter field (no "update everything"
+ * escape hatch) and without at least one set field. Also refuses a no-op
+ * recategorization where `set.account_id` equals `filter.account_id` —
+ * agents shouldn't waste tool calls on identity transforms.
+ *
+ * Safe-field policy mirrors `updatePosting`: account_id + memo only.
+ * Amount/currency corrections must go through delete + re-record to keep
+ * the transaction's debit=credit invariant intact.
+ */
+export declare function bulkUpdatePostings(db: Database.Database, filter: BulkUpdatePostingsFilter, set: BulkUpdatePostingsSet): BulkUpdatePostingsResult;
 export interface DuplicateGroupTransaction {
     id: string;
     date: string;
@@ -170,3 +203,4 @@ export interface TransactionTotals {
     postings: number;
 }
 export declare function countTransactions(db: Database.Database): TransactionTotals;
+export declare function countTransactionsBySourceFile(db: Database.Database, fileId: string): number;