plasalid 0.7.1 → 0.7.3

package/dist/scanner/chunker/chunker.js

@@ -0,0 +1,60 @@
+let mupdfPromise = null;
+function getMupdf() {
+    if (!mupdfPromise)
+        mupdfPromise = import("mupdf");
+    return mupdfPromise;
+}
+/**
+ * Build one Chunk holding exactly page `pageIndex` of `file`. mupdf has no
+ * native page-range extract, so we clone the source doc and delete every
+ * other page, back-to-front so indices stay stable as we splice. Resource
+ * lifetime is contained in the try/finally so a saveToBuffer failure can't
+ * leak the cloned doc.
+ */
+async function extractPage(file, pageIndex, pageCount) {
+    const mupdf = await getMupdf();
+    const clone = mupdf.Document.openDocument(file.decryptedBytes, file.mime);
+    try {
+        for (let j = pageCount - 1; j >= 0; j--) {
+            if (j !== pageIndex)
+                clone.deletePage(j);
+        }
+        const out = clone.saveToBuffer("decrypt");
+        return {
+            chunkId: `${file.path}#p${pageIndex + 1}`,
+            fileId: file.path,
+            fileName: file.fileName,
+            relPath: file.relPath,
+            pageNumber: pageIndex + 1,
+            totalPages: pageCount,
+            bytes: Buffer.from(out.asUint8Array()),
+            mime: file.mime,
+        };
+    }
+    finally {
+        clone.destroy();
+    }
+}
+/**
+ * Split one decrypted PDF into N single-page Chunks. Each chunk is a
+ * standalone, valid PDF so the per-chunk LLM agent gets a clean document
+ * without siblings.
+ */
+export async function chunkPdf(file) {
+    const mupdf = await getMupdf();
+    const probe = mupdf.Document.openDocument(file.decryptedBytes, file.mime);
+    let pageCount;
+    try {
+        pageCount = probe.countPages();
+    }
+    finally {
+        probe.destroy();
+    }
+    if (pageCount <= 0)
+        return [];
+    const chunks = [];
+    for (let i = 0; i < pageCount; i++) {
+        chunks.push(await extractPage(file, i, pageCount));
+    }
+    return chunks;
+}

package/dist/scanner/chunker.d.ts

@@ -0,0 +1,7 @@
+import type { Chunk, DecryptedFile } from "./engine.js";
+/**
+ * Split one decrypted PDF into N single-page Chunks. Each chunk is a
+ * standalone, valid PDF so the per-chunk LLM agent gets a clean document
+ * without siblings.
+ */
+export declare function chunkPdf(file: DecryptedFile): Promise<Chunk[]>;

package/dist/scanner/chunker.js

@@ -0,0 +1,60 @@
+let mupdfPromise = null;
+function getMupdf() {
+    if (!mupdfPromise)
+        mupdfPromise = import("mupdf");
+    return mupdfPromise;
+}
+/**
+ * Build one Chunk holding exactly page `pageIndex` of `file`. mupdf has no
+ * native page-range extract, so we clone the source doc and delete every
+ * other page, back-to-front so indices stay stable as we splice. Resource
+ * lifetime is contained in the try/finally so a saveToBuffer failure can't
+ * leak the cloned doc.
+ */
+async function extractPage(file, pageIndex, pageCount) {
+    const mupdf = await getMupdf();
+    const clone = mupdf.Document.openDocument(file.decryptedBytes, file.mime);
+    try {
+        for (let j = pageCount - 1; j >= 0; j--) {
+            if (j !== pageIndex)
+                clone.deletePage(j);
+        }
+        const out = clone.saveToBuffer("decrypt");
+        return {
+            chunkId: `${file.path}#p${pageIndex + 1}`,
+            fileId: file.path,
+            fileName: file.fileName,
+            relPath: file.relPath,
+            pageNumber: pageIndex + 1,
+            totalPages: pageCount,
+            bytes: Buffer.from(out.asUint8Array()),
+            mime: file.mime,
+        };
+    }
+    finally {
+        clone.destroy();
+    }
+}
+/**
+ * Split one decrypted PDF into N single-page Chunks. Each chunk is a
+ * standalone, valid PDF so the per-chunk LLM agent gets a clean document
+ * without siblings.
+ */
+export async function chunkPdf(file) {
+    const mupdf = await getMupdf();
+    const probe = mupdf.Document.openDocument(file.decryptedBytes, file.mime);
+    let pageCount;
+    try {
+        pageCount = probe.countPages();
+    }
+    finally {
+        probe.destroy();
+    }
+    if (pageCount <= 0)
+        return [];
+    const chunks = [];
+    for (let i = 0; i < pageCount; i++) {
+        chunks.push(await extractPage(file, i, pageCount));
+    }
+    return chunks;
+}

package/dist/scanner/clarifier-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/clarifier-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/clarifier.d.ts

@@ -0,0 +1,39 @@
+import type Database from "libsql";
+import { type QuestionRow } from "../db/queries/questions.js";
+export interface ClarifierContext {
+    readonly db: Database.Database;
+    readonly tally: Record<string, number>;
+}
+export interface ClarifierPass {
+    readonly name: string;
+    readonly kinds: readonly string[];
+    /** Try to close one question. Returns the answer if closed, else null. */
+    tryResolve(u: QuestionRow, ctx: ClarifierContext): Promise<string | null>;
+}
+export interface ClarifySummary {
+    readonly total: number;
+    readonly clarified: number;
+    readonly remaining: number;
+    readonly tally: Readonly<Record<string, number>>;
+}
+export interface RunClarifyOpts {
+    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 CLARIFIER_PASSES: readonly ClarifierPass[];
+/**
+ * Single entry point shared by the in-scan resolve phase and the standalone
+ * `plasalid clarify` command. Runs deterministic passes first, then (when
+ * interactive) hands the leftovers to the LLM clarifier agent. Closed
+ * questions get compacted into scanning_hint memories.
+ */
+export declare function runClarify(opts: RunClarifyOpts): Promise<ClarifySummary>;

package/dist/scanner/clarifier.js

@@ -0,0 +1,196 @@
+import { closeQuestion, listQuestions, countQuestions, } from "../db/queries/questions.js";
+import { updatePosting } from "../db/queries/transactions.js";
+import { runClarifyAgent } from "../ai/agent.js";
+import { synthesizeMemoryRules } from "./clarifier-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 CLARIFIER_PASSES = [
+    memoryRulePass,
+    merchantDefaultPass,
+];
+/**
+ * Single entry point shared by the in-scan resolve phase and the standalone
+ * `plasalid clarify` command. Runs deterministic passes first, then (when
+ * interactive) hands the leftovers to the LLM clarifier agent. Closed
+ * questions get compacted into scanning_hint memories.
+ */
+export async function runClarify(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, clarified: 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, clarified: total - remaining, remaining, tally };
+}
+function matchingPasses(u) {
+    if (!u.kind)
+        return [];
+    return CLARIFIER_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(`[clarifier 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 clarifier. 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 runClarifyAgent({
+                db,
+                prompt: {},
+                initialMessages: [{ role: "user", content: buildResolveUserMessage(before) }],
+                agentCtx: {
+                    interactive: true,
+                    promptUser: opts.promptUser,
+                    onQuestionClosed: (closed) => {
+                        closures.push(closed);
+                        tally["agent_clarification"] = (tally["agent_clarification"] ?? 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/converge.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Drive a stateful loop toward convergence: keep running passes until the
+ * caller's `isDone` predicate is true (success), `isStalled` returns true
+ * across two passes (stall), or `maxAttempts` is exhausted (fail).
+ *
+ * The driver owns counting passes, stall detection, and the iteration cap.
+ * Everything else (work per pass, callbacks per terminal state) lives in the
+ * hooks the caller supplies. `S` is whatever quantity decides "are we done?".
+ */
+export interface ConvergeOpts<S> {
+    /** Initial state (e.g. `countQuestions(db)`). */
+    initial: S;
+    /** Maximum number of passes before declaring failure. Must be >= 1. */
+    maxAttempts: number;
+    /** True when the work is finished and the loop should stop cleanly. */
+    isDone: (state: S) => boolean;
+    /**
+     * True when this pass made no progress vs the previous pass. Fires after
+     * the first pass at the earliest.
+     */
+    isStalled: (curr: S, prev: S) => boolean;
+    /** Run one pass; return the new state. Pass numbers are 1-indexed. */
+    onPass: (pass: number, state: S) => Promise<S>;
+    onStart?: (state: S) => void;
+    onStall?: (state: S) => void;
+    onSuccess?: (state: S) => void;
+    onFail?: (state: S) => void;
+}
+export declare function converge<S>(opts: ConvergeOpts<S>): Promise<S>;

package/dist/scanner/converge.js

@@ -0,0 +1,15 @@
+export async function converge(opts) {
+    let state = opts.initial;
+    let prev = state;
+    opts.onStart?.(state);
+    for (let pass = 1; pass <= opts.maxAttempts && !opts.isDone(state); pass++) {
+        if (pass > 1 && opts.isStalled(state, prev)) {
+            opts.onStall?.(state);
+            return state;
+        }
+        prev = state;
+        state = await opts.onPass(pass, state);
+    }
+    (opts.isDone(state) ? opts.onSuccess : opts.onFail)?.(state);
+    return state;
+}

package/dist/scanner/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/decrypt.js

@@ -0,0 +1,80 @@
+import { randomUUID } from "crypto";
+import { readPdf } from "./pdf/pdf.js";
+import { unlockIfNeeded, persistUnlockOutcome } from "./pdf/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/engine/scanEngine.d.ts

@@ -0,0 +1,24 @@
+import type Database from "libsql";
+import type { CommitOutcome, Phase, PhaseName, RunScanOptions, ScanState } from "./types.js";
+import type { ScanHooks } from "../hooks/types.js";
+export interface ScanResult {
+    readonly scanId: string;
+    readonly state: ScanState;
+    readonly committed: CommitOutcome | null;
+    readonly aborted: boolean;
+}
+export declare const DEFAULT_PHASES: readonly {
+    name: PhaseName;
+    phase: Phase;
+}[];
+/**
+ * Composition root for a scan run. Builds the singleton subdomain instances
+ * (bus, buffer, audit engine) once, threads them through ScanState, then
+ * runs the phase chain. Auditor lifecycle wraps the whole chain so it sees
+ * every event from decrypt through commit.
+ *
+ * Per-run isolation: every call to runScan creates fresh instances. Nothing
+ * survives between scans.
+ */
+export declare function runScan(db: Database.Database, opts?: RunScanOptions, hooks?: ScanHooks): Promise<ScanResult>;
+export type { ScanState, ScanHooks, RunScanOptions, CommitOutcome, } from "./types.js";

package/dist/scanner/engine/scanEngine.js

@@ -0,0 +1,87 @@
+import { randomUUID } from "crypto";
+import { createBus } from "../bus/engine.js";
+import { createBuffer } from "../buffer/engine.js";
+import { createAuditEngine } from "../audit/engine.js";
+import { AUDIT_PASSES } from "../audit/passes/index.js";
+import { decryptPhase } from "../phases/decrypt.js";
+import { chunkPhase } from "../phases/chunk.js";
+import { parsePhase } from "../phases/parse.js";
+import { reviewPhase } from "../phases/review.js";
+import { commitPhase } from "../phases/commit.js";
+export const DEFAULT_PHASES = [
+    { name: "decrypt", phase: decryptPhase },
+    { name: "chunk", phase: chunkPhase },
+    { name: "parse", phase: parsePhase },
+    { name: "review", phase: reviewPhase },
+    { name: "commit", phase: commitPhase },
+];
+/**
+ * Composition root for a scan run. Builds the singleton subdomain instances
+ * (bus, buffer, audit engine) once, threads them through ScanState, then
+ * runs the phase chain. Auditor lifecycle wraps the whole chain so it sees
+ * every event from decrypt through commit.
+ *
+ * Per-run isolation: every call to runScan creates fresh instances. Nothing
+ * survives between scans.
+ */
+export async function runScan(db, opts = {}, hooks = {}) {
+    const scanId = `sc:${randomUUID()}`;
+    const bus = createBus();
+    const buffer = createBuffer(scanId, bus);
+    const audit = createAuditEngine({ db, bus, buffer, passes: AUDIT_PASSES });
+    const state = {
+        scanId,
+        startedAt: Date.now(),
+        options: opts,
+        buffer,
+        bus,
+        files: [],
+        decrypted: [],
+        skipped: [],
+        failed: [],
+        chunks: [],
+        review: null,
+        committed: null,
+        errors: [],
+        auditApplied: {},
+    };
+    await fire(hooks.onStart, state);
+    audit.start();
+    const phases = opts.phases ?? DEFAULT_PHASES;
+    let aborted = false;
+    try {
+        for (const { name, phase } of phases) {
+            try {
+                await phase(db, state, hooks);
+            }
+            catch (err) {
+                state.errors.push({ phase: name, error: err });
+                await fire(hooks.onError, err, name, state);
+                aborted = true;
+                break;
+            }
+            if (name === "review" && state.review === "abort") {
+                aborted = true;
+                break;
+            }
+        }
+    }
+    finally {
+        audit.stop();
+        for (const [name, count] of Object.entries(audit.tally)) {
+            state.auditApplied[name] = count;
+        }
+        await fire(hooks.onFinish, state);
+    }
+    return { scanId, state, committed: state.committed, aborted };
+}
+async function fire(fn, ...args) {
+    if (!fn)
+        return;
+    try {
+        await fn(...args);
+    }
+    catch (err) {
+        console.error(`[scan-engine hook] ${err.message}`);
+    }
+}