plasalid 0.7.1 → 0.7.3

package/dist/scanner/phases/commit.js

@@ -0,0 +1,140 @@
+import { randomUUID } from "crypto";
+import { validateTransaction, insertTransactionRows, } from "../../db/queries/transactions.js";
+import { recordUnknown } from "../../db/queries/unknowns.js";
+import { appendAction } from "../../db/queries/action-log.js";
+import { tryExecute } from "../result.js";
+const SERIALIZE = {
+    record_transaction: (t) => ({
+        transaction: {
+            date: t.date,
+            description: t.description,
+            source_page: t.source_page ?? null,
+            raw_descriptor: t.raw_descriptor ?? null,
+        },
+        postings: t.postings,
+    }),
+};
+/**
+ * Commit ONE buffered transaction in its own DB transaction so a FK violation
+ * drops only this row. The audit_log row pairs with the insert so revert can
+ * undo this exact entry.
+ */
+async function commitOneTransaction(db, scanId, bt, fileIdByChunkId) {
+    const sourceFileId = fileIdByChunkId.get(bt.chunkId);
+    const result = await tryExecute(() => {
+        const validated = validateTransaction({
+            ...bt.input,
+            id: bt.transaction_id,
+            source_file_id: sourceFileId,
+        });
+        db.transaction(() => {
+            insertTransactionRows(db, validated);
+            appendAction(db, {
+                correlation_id: scanId,
+                command: "scan",
+                action_type: "record_transaction",
+                target_id: validated.id,
+                payload: SERIALIZE.record_transaction(validated),
+            });
+        })();
+        return validated.id;
+    });
+    if (result.ok)
+        return { kind: "ok", transactionId: result.value };
+    return {
+        kind: "failed",
+        description: bt.input.description,
+        date: bt.input.date,
+        error: result.error,
+    };
+}
+function bootstrapScannedFiles(db, decrypted) {
+    const ids = [];
+    const fileIdByPath = new Map();
+    for (const file of decrypted) {
+        if (file.replacesPriorScannedFileId) {
+            db.prepare(`DELETE FROM scanned_files WHERE id = ?`).run(file.replacesPriorScannedFileId);
+        }
+        const sfId = `sf:${randomUUID()}`;
+        db.prepare(`INSERT INTO scanned_files (id, path, file_hash, mime, status) VALUES (?, ?, ?, ?, 'pending')`).run(sfId, file.path, file.hash, file.mime);
+        ids.push(sfId);
+        fileIdByPath.set(file.path, sfId);
+    }
+    return { ids, fileIdByPath };
+}
+function buildChunkLookup(chunks, fileIdByPath) {
+    const out = new Map();
+    for (const c of chunks) {
+        const sfId = fileIdByPath.get(c.fileId);
+        if (sfId)
+            out.set(c.chunkId, sfId);
+    }
+    return out;
+}
+function failuresToUnknowns(failures) {
+    return failures.map(f => ({
+        unknown_id: `bu:${randomUUID()}`,
+        chunkId: null,
+        transaction_id: null,
+        account_id: null,
+        kind: "scan_commit_failure",
+        prompt: `Could not record "${f.description}" on ${f.date}: ${f.error}. Review the source statement and re-enter via the record flow.`,
+        answer: null,
+    }));
+}
+function writeUnknowns(db, unknowns, fileIdByChunkId) {
+    const op = db.transaction(() => {
+        for (const u of unknowns) {
+            // Closed unknowns: their resolution side-effects already landed via other
+            // buffer mutations (update_posting / delete_transaction / etc.) during
+            // the audit pass. Skip persisting — leaving them out keeps the DB free
+            // of orphan rows masquerading as open work.
+            if (u.answer !== null)
+                continue;
+            const sfId = u.chunkId ? fileIdByChunkId.get(u.chunkId) ?? null : null;
+            recordUnknown(db, {
+                file_id: sfId,
+                transaction_id: u.transaction_id,
+                account_id: u.account_id,
+                kind: u.kind ?? null,
+                prompt: u.prompt,
+                options: u.options,
+            });
+        }
+    });
+    op();
+}
+/**
+ * Phase 5 — flush the shared buffer to the DB. Per-row transactions so one
+ * bad row drops only itself (lands as a scan_commit_failure unknown). Every
+ * successful mutation appends an action_log row keyed to scanId so the run
+ * can be reverted as a unit.
+ */
+export async function commitPhase(db, state, hooks) {
+    if (state.review !== "commit")
+        return;
+    await hooks.beforeCommit?.(state);
+    const snapshot = state.buffer.snapshot();
+    const { ids: scannedFileIds, fileIdByPath } = bootstrapScannedFiles(db, state.decrypted);
+    const fileIdByChunkId = buildChunkLookup(state.chunks, fileIdByPath);
+    const outcomes = await Promise.all(snapshot.transactions.map(bt => commitOneTransaction(db, state.scanId, bt, fileIdByChunkId)));
+    const insertedTx = outcomes.filter(o => o.kind === "ok").length;
+    const failures = outcomes.filter((o) => o.kind === "failed");
+    const failureUnknowns = failuresToUnknowns(failures);
+    writeUnknowns(db, [...snapshot.unknowns, ...failureUnknowns], fileIdByChunkId);
+    for (const sfId of scannedFileIds) {
+        db.prepare(`UPDATE scanned_files SET status = 'scanned', scanned_at = datetime('now') WHERE id = ?`).run(sfId);
+    }
+    const unknownsResolved = snapshot.unknowns.filter(u => u.answer !== null).length;
+    const unknownsOpen = snapshot.unknowns.length - unknownsResolved + failureUnknowns.length;
+    const outcome = {
+        transactions: insertedTx,
+        accounts: snapshot.accountsCreated.length,
+        merchants: snapshot.merchantsCreated.length,
+        unknownsOpen,
+        unknownsResolved,
+        scannedFileIds,
+    };
+    state.committed = outcome;
+    await hooks.afterCommit?.(state, outcome);
+}

package/dist/scanner/phases/decrypt.d.ts

@@ -0,0 +1,10 @@
+import type Database from "libsql";
+import type { ScanState } from "../engine.js";
+import type { ScanHooks } from "../hooks.js";
+/**
+ * Phase 1 — walk the data dir, optionally filter by regex, decrypt each file
+ * sequentially (password prompts can't share a TTY). Output partitions into
+ * decrypted / skipped / failed via a kind-keyed dispatch map. Bootstrapped
+ * scanned_files rows are tagged onto each DecryptedFile.
+ */
+export declare function decryptPhase(db: Database.Database, state: ScanState, hooks: ScanHooks): Promise<void>;

package/dist/scanner/phases/decrypt.js

@@ -0,0 +1,80 @@
+import { randomUUID } from "crypto";
+import { readPdf } from "../pdf.js";
+import { unlockIfNeeded, persistUnlockOutcome } from "../unlock.js";
+import { scanDataDir } from "../walker.js";
+import { tryExecute } from "../result.js";
+function findScannedByHash(db, hash) {
+    return db
+        .prepare(`SELECT id FROM scanned_files WHERE file_hash = ?`)
+        .get(hash) ?? null;
+}
+async function decryptOne(db, file, opts) {
+    const read = await tryExecute(() => readPdf(file.path));
+    if (!read.ok)
+        return { kind: "failed", error: `read failed: ${read.error}` };
+    const pdf = read.value;
+    const existing = findScannedByHash(db, pdf.hash);
+    if (existing && !opts.force) {
+        return { kind: "skipped", existingScannedFileId: existing.id };
+    }
+    const unlock = await tryExecute(() => unlockIfNeeded({
+        db,
+        filePath: file.path,
+        bytes: pdf.bytes,
+        interactive: opts.interactive,
+    }));
+    if (!unlock.ok)
+        return { kind: "failed", error: unlock.error || "unlock failed" };
+    persistUnlockOutcome(db, file.path, unlock.value.outcome);
+    return {
+        kind: "decrypted",
+        file: {
+            path: file.path,
+            fileName: file.name,
+            relPath: file.relPath,
+            hash: pdf.hash,
+            mime: pdf.mime,
+            decryptedBytes: unlock.value.decrypted,
+            replacesPriorScannedFileId: existing?.id,
+        },
+    };
+}
+const APPLY = {
+    decrypted: (state, _file, o) => { state.decrypted.push(o.file); },
+    skipped: (state, file, o) => { state.skipped.push({ file, existingScannedFileId: o.existingScannedFileId }); },
+    failed: (state, file, o) => { state.failed.push({ file, error: o.error }); },
+};
+/**
+ * Bootstrap one scanned_files row per decrypted file. Chunk workers later
+ * stamp transactions with source_file_id, so the row must exist before any
+ * tool writes hit the DB. Status flips to 'scanned' after parse completes.
+ */
+function bootstrapScannedFiles(db, state) {
+    for (const file of state.decrypted) {
+        if (file.replacesPriorScannedFileId) {
+            db.prepare(`DELETE FROM scanned_files WHERE id = ?`).run(file.replacesPriorScannedFileId);
+        }
+        const sfId = `sf:${randomUUID()}`;
+        db.prepare(`INSERT INTO scanned_files (id, path, file_hash, mime, status) VALUES (?, ?, ?, ?, 'pending')`).run(sfId, file.path, file.hash, file.mime);
+        file.scannedFileId = sfId;
+    }
+}
+/**
+ * Phase 1 — walk the data dir, optionally filter by regex, decrypt each file
+ * sequentially (password prompts can't share a TTY). Output partitions into
+ * decrypted / skipped / failed via a kind-keyed dispatch map. Bootstrapped
+ * scanned_files rows are tagged onto each DecryptedFile.
+ */
+export async function decryptPhase(db, state, hooks) {
+    await hooks.beforeDecrypt?.(state);
+    const matcher = state.options.regex ? new RegExp(state.options.regex, "i") : null;
+    state.files = scanDataDir().filter(f => (matcher ? matcher.test(f.relPath) : true));
+    const interactive = state.options.interactive ?? true;
+    const force = !!state.options.force;
+    for (const file of state.files) {
+        const outcome = await decryptOne(db, file, { force, interactive });
+        APPLY[outcome.kind](state, file, outcome);
+    }
+    bootstrapScannedFiles(db, state);
+    await hooks.afterDecrypt?.(state);
+}

package/dist/scanner/phases/parse.d.ts

@@ -0,0 +1,10 @@
+import type Database from "libsql";
+import type { ScanState } from "../engine.js";
+import type { ScanHooks } from "../hooks.js";
+/**
+ * Phase 3 — fan out FileWorkers in parallel. Each FileWorker fans out its
+ * file's chunks in parallel internally. The scanId + progress sink are
+ * threaded through ScanState; chunk-worker tools write to the DB directly
+ * and tick the progress sink as they go.
+ */
+export declare function parsePhase(db: Database.Database, state: ScanState, hooks: ScanHooks): Promise<void>;

package/dist/scanner/phases/parse.js

@@ -0,0 +1,46 @@
+import { runWithConcurrency } from "../concurrency.js";
+import { runFileWorker } from "../file-worker.js";
+import { errorMessage } from "../result.js";
+const DEFAULT_MAX_FILE_WORKERS = 5;
+const DEFAULT_MAX_CHUNK_WORKERS_PER_FILE = 5;
+const HARD_CAP = 8;
+const clamp = (n, fallback) => Math.min(HARD_CAP, Math.max(1, n ?? fallback));
+/**
+ * Phase 3 — fan out FileWorkers in parallel. Each FileWorker fans out its
+ * file's chunks in parallel internally. The scanId + progress sink are
+ * threaded through ScanState; chunk-worker tools write to the DB directly
+ * and tick the progress sink as they go.
+ */
+export async function parsePhase(db, state, hooks) {
+    await hooks.beforeParse?.(state);
+    const maxFile = clamp(state.options.maxFileWorkers, DEFAULT_MAX_FILE_WORKERS);
+    const maxChunk = clamp(state.options.maxChunkWorkersPerFile, DEFAULT_MAX_CHUNK_WORKERS_PER_FILE);
+    const fileGroups = state.decrypted
+        .map(file => ({
+        fileId: file.path,
+        scannedFileId: file.scannedFileId,
+        chunks: state.chunks.filter(c => c.fileId === file.path),
+    }))
+        .filter(g => g.chunks.length > 0);
+    const tasks = fileGroups.map(group => () => runFileWorker({
+        db,
+        scanId: state.scanId,
+        scannedFileId: group.scannedFileId,
+        progress: state.progress,
+        fileId: group.fileId,
+        chunks: group.chunks,
+        maxChunkWorkers: maxChunk,
+    }, hooks));
+    const settled = await runWithConcurrency(tasks, maxFile);
+    for (let i = 0; i < settled.length; i++) {
+        const r = settled[i];
+        if (!r.ok)
+            state.errors.push({ phase: "parse", target: fileGroups[i].fileId, error: errorMessage(r.error) });
+    }
+    for (const file of state.decrypted) {
+        if (!file.scannedFileId)
+            continue;
+        db.prepare(`UPDATE scanned_files SET status = 'scanned', scanned_at = datetime('now') WHERE id = ?`).run(file.scannedFileId);
+    }
+    await hooks.afterParse?.(state);
+}

package/dist/scanner/phases/resolve.d.ts

@@ -0,0 +1,10 @@
+import type Database from "libsql";
+import type { ScanState } from "../engine.js";
+import type { ScanHooks } from "../hooks.js";
+/**
+ * Phase 4 — close every open unknown raised during this scan. Deterministic
+ * passes (memory rules, merchant defaults) run first; whatever survives goes
+ * to the LLM resolver agent when interactive. Closed unknowns get compacted
+ * into scanning_hint memories so the next scan picks them up automatically.
+ */
+export declare function resolvePhase(db: Database.Database, state: ScanState, hooks: ScanHooks): Promise<void>;

package/dist/scanner/phases/resolve.js

@@ -0,0 +1,17 @@
+import { runResolve } from "../resolver.js";
+/**
+ * Phase 4 — close every open unknown raised during this scan. Deterministic
+ * passes (memory rules, merchant defaults) run first; whatever survives goes
+ * to the LLM resolver agent when interactive. Closed unknowns get compacted
+ * into scanning_hint memories so the next scan picks them up automatically.
+ */
+export async function resolvePhase(db, state, hooks) {
+    await hooks.beforeResolve?.(state);
+    const summary = await runResolve({
+        db,
+        scanId: state.scanId,
+        interactive: state.options.interactive ?? true,
+    });
+    state.resolveSummary = summary;
+    await hooks.afterResolve?.(state, summary);
+}

package/dist/scanner/phases/review.d.ts

@@ -0,0 +1,10 @@
+import type Database from "libsql";
+import type { ScanState } from "../engine.js";
+import type { ScanHooks } from "../hooks.js";
+/**
+ * Phase 4 — present the buffer to the user for confirmation, then set
+ * `state.review` to either `"commit"` or `"abort"`. Today this is a simple
+ * auto-commit path so the engine compiles; the full Ink TUI is a separate
+ * follow-up (review TUI task).
+ */
+export declare function reviewPhase(_db: Database.Database, state: ScanState, hooks: ScanHooks): Promise<void>;

package/dist/scanner/phases/review.js

@@ -0,0 +1,12 @@
+/**
+ * Phase 4 — present the buffer to the user for confirmation, then set
+ * `state.review` to either `"commit"` or `"abort"`. Today this is a simple
+ * auto-commit path so the engine compiles; the full Ink TUI is a separate
+ * follow-up (review TUI task).
+ */
+export async function reviewPhase(_db, state, hooks) {
+    const snapshot = state.buffer.snapshot();
+    await hooks.beforeReview?.(state, snapshot);
+    state.review = "commit";
+    await hooks.afterReview?.(state);
+}

package/dist/scanner/progress.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Single-typed event sink scan-worker tools emit into as they write to the DB.
+ * Replaces the bus + buffer for in-flight progress: one consumer at a time
+ * (dashboard or plain-hooks counters) reads ticks per chunk.
+ */
+export interface ScanProgressEvent {
+    readonly chunkId: string;
+    readonly kind: "tx" | "question";
+}
+export interface ScanProgress {
+    emit(event: ScanProgressEvent): void;
+    subscribe(handler: (e: ScanProgressEvent) => void): () => void;
+}
+export declare function createProgress(): ScanProgress;

package/dist/scanner/progress.js

@@ -0,0 +1,21 @@
+export function createProgress() {
+    const subscribers = new Set();
+    return {
+        emit(event) {
+            for (const fn of subscribers) {
+                try {
+                    fn(event);
+                }
+                catch (err) {
+                    console.error(`[progress listener] ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+        },
+        subscribe(handler) {
+            subscribers.add(handler);
+            return () => {
+                subscribers.delete(handler);
+            };
+        },
+    };
+}

package/dist/scanner/resolver-memory.d.ts

@@ -0,0 +1,8 @@
+import type Database from "libsql";
+import type { ClosedQuestion } from "../db/queries/questions.js";
+/**
+ * Compact every closed question into a memories row (category `scanning_hint`).
+ * The next scan's deterministic memoryRulePass picks them up. Dedups on body —
+ * an identical rule for the same kind + prompt won't be re-inserted.
+ */
+export declare function synthesizeMemoryRules(db: Database.Database, closures: readonly ClosedQuestion[]): number;

package/dist/scanner/resolver-memory.js

@@ -0,0 +1,24 @@
+/**
+ * Compact every closed question into a memories row (category `scanning_hint`).
+ * The next scan's deterministic memoryRulePass picks them up. Dedups on body —
+ * an identical rule for the same kind + prompt won't be re-inserted.
+ */
+export function synthesizeMemoryRules(db, closures) {
+    if (closures.length === 0)
+        return 0;
+    let inserted = 0;
+    const exists = db.prepare(`SELECT 1 FROM memories WHERE category = ? AND content = ? LIMIT 1`);
+    const insert = db.prepare(`INSERT INTO memories (content, category) VALUES (?, ?)`);
+    for (const c of closures) {
+        const body = formatRule(c);
+        if (exists.get("scanning_hint", body))
+            continue;
+        insert.run(body, "scanning_hint");
+        inserted++;
+    }
+    return inserted;
+}
+function formatRule(c) {
+    const kindLabel = c.kind ?? "general";
+    return `[${kindLabel}] ${c.prompt.replace(/\s+/g, " ").trim()} -> ${c.answer.trim()}`;
+}

package/dist/scanner/resolver.d.ts

@@ -0,0 +1,39 @@
+import type Database from "libsql";
+import { type QuestionRow } from "../db/queries/questions.js";
+export interface ResolverContext {
+    readonly db: Database.Database;
+    readonly tally: Record<string, number>;
+}
+export interface ResolverPass {
+    readonly name: string;
+    readonly kinds: readonly string[];
+    /** Try to close one question. Returns the answer if closed, else null. */
+    tryResolve(u: QuestionRow, ctx: ResolverContext): Promise<string | null>;
+}
+export interface ResolveSummary {
+    readonly total: number;
+    readonly resolved: number;
+    readonly remaining: number;
+    readonly tally: Readonly<Record<string, number>>;
+}
+export interface RunResolveOpts {
+    db: Database.Database;
+    /** Narrows to a single scan's questions. Omit = every question. */
+    scanId?: string;
+    interactive?: boolean;
+    promptUser?: (prompt: string, options?: string[], facts?: any) => Promise<string>;
+    onProgress?: (event: {
+        phase: "tool" | "responding";
+        toolName?: string;
+        toolCount: number;
+        elapsedMs: number;
+    }) => void;
+}
+export declare const RESOLVER_PASSES: readonly ResolverPass[];
+/**
+ * Single entry point shared by the in-scan resolve phase and the standalone
+ * `plasalid resolve` command. Runs deterministic passes first, then (when
+ * interactive) hands the leftovers to the LLM resolver agent. Closed
+ * questions get compacted into scanning_hint memories.
+ */
+export declare function runResolve(opts: RunResolveOpts): Promise<ResolveSummary>;

package/dist/scanner/resolver.js

@@ -0,0 +1,196 @@
+import { closeQuestion, listQuestions, countQuestions, } from "../db/queries/questions.js";
+import { updatePosting } from "../db/queries/transactions.js";
+import { runResolveAgent } from "../ai/agent.js";
+import { synthesizeMemoryRules } from "./resolver-memory.js";
+import { converge } from "./converge.js";
+const MAX_AGENT_PASSES = 3;
+/**
+ * Apply deterministic passes via memory_rules lookups. Closes any question
+ * whose prompt has a stored scanning_hint that already encodes the answer.
+ */
+const memoryRulePass = {
+    name: "memory_rule",
+    kinds: ["uncategorized", "uncategorized_expense", "duplicate", "correlation", "recurrence_candidate", "similar_accounts", "boundary_continuation", "scan_truncated", "scan_commit_failure"],
+    async tryResolve(u, ctx) {
+        const rules = ctx.db
+            .prepare(`SELECT content FROM memories WHERE category = 'scanning_hint'`)
+            .all();
+        const key = canonicalKey(u);
+        for (const r of rules) {
+            const match = parseRule(r.content);
+            if (!match)
+                continue;
+            if (match.key === key)
+                return match.answer;
+        }
+        return null;
+    },
+};
+/**
+ * For an uncategorized expense whose transaction has a merchant with a
+ * stored default_account_id, apply the default to every expense posting on
+ * that transaction.
+ */
+const merchantDefaultPass = {
+    name: "merchant_default",
+    kinds: ["uncategorized_expense"],
+    async tryResolve(u, ctx) {
+        if (!u.transaction_id)
+            return null;
+        const tx = ctx.db
+            .prepare(`SELECT merchant_id FROM transactions WHERE id = ?`)
+            .get(u.transaction_id);
+        if (!tx?.merchant_id)
+            return null;
+        const merchant = ctx.db
+            .prepare(`SELECT default_account_id FROM merchants WHERE id = ?`)
+            .get(tx.merchant_id);
+        const target = merchant?.default_account_id;
+        if (!target)
+            return null;
+        const postings = ctx.db
+            .prepare(`SELECT p.id FROM postings p
+         JOIN accounts a ON a.id = p.account_id
+         WHERE p.transaction_id = ? AND a.id = 'expense:uncategorized'`)
+            .all(u.transaction_id);
+        if (postings.length === 0)
+            return null;
+        for (const p of postings) {
+            updatePosting(ctx.db, p.id, { account_id: target });
+        }
+        return target;
+    },
+};
+export const RESOLVER_PASSES = [
+    memoryRulePass,
+    merchantDefaultPass,
+];
+/**
+ * Single entry point shared by the in-scan resolve phase and the standalone
+ * `plasalid resolve` command. Runs deterministic passes first, then (when
+ * interactive) hands the leftovers to the LLM resolver agent. Closed
+ * questions get compacted into scanning_hint memories.
+ */
+export async function runResolve(opts) {
+    const { db } = opts;
+    const tally = {};
+    const closures = [];
+    const initial = listQuestions(db, { scanId: opts.scanId, limit: 1000 });
+    const total = initial.length;
+    if (total === 0) {
+        return { total: 0, resolved: 0, remaining: 0, tally };
+    }
+    for (const u of initial) {
+        const passes = matchingPasses(u);
+        if (passes.length === 0)
+            continue;
+        const result = await tryPasses(u, passes, { db, tally });
+        if (!result)
+            continue;
+        const closed = closeQuestion(db, u.id, result.answer);
+        if (!closed)
+            continue;
+        closures.push(closed);
+        tally[result.passName] = (tally[result.passName] ?? 0) + 1;
+    }
+    const interactive = opts.interactive ?? true;
+    if (interactive && countRemaining(db, opts.scanId) > 0) {
+        await runAgentLoop(opts, closures, tally);
+    }
+    synthesizeMemoryRules(db, closures);
+    const remaining = countRemaining(db, opts.scanId);
+    return { total, resolved: total - remaining, remaining, tally };
+}
+function matchingPasses(u) {
+    if (!u.kind)
+        return [];
+    return RESOLVER_PASSES.filter(p => p.kinds.includes(u.kind));
+}
+async function tryPasses(u, passes, ctx) {
+    for (const pass of passes) {
+        let answer;
+        try {
+            answer = await pass.tryResolve(u, ctx);
+        }
+        catch (err) {
+            console.error(`[resolver pass ${pass.name}] ${err instanceof Error ? err.message : String(err)}`);
+            answer = null;
+        }
+        if (answer != null)
+            return { passName: pass.name, answer };
+    }
+    return null;
+}
+function countRemaining(db, scanId) {
+    return scanId ? countQuestions(db, { scan_id: scanId }) : countQuestions(db);
+}
+/**
+ * Stall-protected outer loop around the LLM resolver. Each pass re-fetches
+ * leftover questions, hands them to the agent, and the agent closes what it
+ * can via close_question / ask_user. The loop stops when nothing closes
+ * between passes. After each pass we diff the pre/post set to recover the
+ * (prompt, kind, answer) tuples the agent closed without going through the
+ * memoryRulePass path.
+ */
+async function runAgentLoop(opts, closures, tally) {
+    const { db } = opts;
+    await converge({
+        initial: countRemaining(db, opts.scanId),
+        maxAttempts: MAX_AGENT_PASSES,
+        isDone: (n) => n === 0,
+        isStalled: (curr, prev) => curr >= prev,
+        onPass: async () => {
+            const before = listQuestions(db, { scanId: opts.scanId, limit: 1000 });
+            if (before.length === 0)
+                return 0;
+            await runResolveAgent({
+                db,
+                prompt: {},
+                initialMessages: [{ role: "user", content: buildResolveUserMessage(before) }],
+                agentCtx: {
+                    interactive: true,
+                    promptUser: opts.promptUser,
+                    onQuestionClosed: (closed) => {
+                        closures.push(closed);
+                        tally["agent_resolution"] = (tally["agent_resolution"] ?? 0) + 1;
+                    },
+                },
+                onProgress: opts.onProgress,
+            });
+            return countRemaining(db, opts.scanId);
+        },
+    });
+}
+function buildResolveUserMessage(questions) {
+    const lines = [`${questions.length} question(s) to resolve.`, ``, `Questions:`];
+    for (const c of questions) {
+        const options = parseOptions(c.options_json);
+        const optionsStr = options.length > 0 ? ` | options=[${options.join(" / ")}]` : "";
+        lines.push(`- ${c.id} | kind=${c.kind ?? "(none)"} | tx=${c.transaction_id ?? "(none)"} | acct=${c.account_id ?? "(none)"} | file=${c.file_id ?? "(none)"}${optionsStr}`, `    prompt: ${c.prompt.replace(/\n/g, " ")}`);
+    }
+    return lines.join("\n");
+}
+function parseOptions(json) {
+    if (!json)
+        return [];
+    try {
+        const parsed = JSON.parse(json);
+        return Array.isArray(parsed) ? parsed.filter((o) => typeof o === "string") : [];
+    }
+    catch {
+        return [];
+    }
+}
+function canonicalKey(u) {
+    return `[${u.kind ?? "general"}] ${u.prompt.replace(/\s+/g, " ").trim()}`;
+}
+function parseRule(body) {
+    const idx = body.lastIndexOf(" -> ");
+    if (idx < 0)
+        return null;
+    const key = body.slice(0, idx).trim();
+    const answer = body.slice(idx + 4).trim();
+    if (!key || !answer)
+        return null;
+    return { key, answer };
+}

package/dist/scanner/result.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Lightweight Result helpers shared across scanner subdomains. Use this
+ * instead of inline try/catch when a function can fail with a human-readable
+ * reason and the caller needs to branch on the outcome (decrypt, chunk parse,
+ * commit-one-transaction). Distinct from concurrency.ts `Settled<T>` — that
+ * type is owned by `runWithConcurrency` and includes an `error: unknown`;
+ * `Result<T>` stringifies the error up front for ergonomic message handling.
+ */
+export type Result<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function errorMessage(err: unknown): string;
+export declare function tryExecute<T>(fn: () => Promise<T> | T): Promise<Result<T>>;