plasalid 0.3.5 → 0.5.0

package/dist/db/schema.js

@@ -4,6 +4,7 @@ export function migrate(db) {
       id TEXT PRIMARY KEY,
       name TEXT NOT NULL,
       type TEXT NOT NULL CHECK(type IN ('asset','liability','income','expense','equity')),
+      parent_id TEXT REFERENCES accounts(id),
       subtype TEXT,
       bank_name TEXT,
       account_number_masked TEXT,
@@ -13,33 +14,78 @@ export function migrate(db) {
       points_balance REAL,
       metadata_json TEXT,
       pii_flag INTEGER NOT NULL DEFAULT 0,
+      has_concern INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
+    CREATE INDEX IF NOT EXISTS accounts_parent_idx ON accounts(parent_id);
+    CREATE INDEX IF NOT EXISTS accounts_type_idx ON accounts(type);
+
+    CREATE TABLE IF NOT EXISTS merchants (
+      id TEXT PRIMARY KEY,
+      canonical_name TEXT NOT NULL UNIQUE,
+      default_account_id TEXT REFERENCES accounts(id),
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS merchant_aliases (
+      id TEXT PRIMARY KEY,
+      merchant_id TEXT NOT NULL REFERENCES merchants(id) ON DELETE CASCADE,
+      normalized_pattern TEXT NOT NULL UNIQUE,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS merchant_aliases_merchant_idx ON merchant_aliases(merchant_id);
+
     CREATE TABLE IF NOT EXISTS scanned_files (
       id TEXT PRIMARY KEY,
       path TEXT NOT NULL,
       file_hash TEXT NOT NULL UNIQUE,
       mime TEXT NOT NULL,
-      status TEXT NOT NULL CHECK(status IN ('pending','scanned','needs_input','failed')),
+      status TEXT NOT NULL CHECK(status IN ('pending','scanned','failed')),
       raw_text TEXT,
       scanned_at TEXT,
       error TEXT,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
-    CREATE TABLE IF NOT EXISTS journal_entries (
+    CREATE TABLE IF NOT EXISTS recurrences (
+      id TEXT PRIMARY KEY,
+      account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
+      description TEXT NOT NULL,
+      frequency TEXT NOT NULL CHECK(frequency IN ('weekly','biweekly','monthly','annually')),
+      amount_typical REAL,
+      currency TEXT NOT NULL DEFAULT 'THB',
+      first_seen_date TEXT,
+      last_seen_date TEXT,
+      next_expected_date TEXT,
+      notes TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS recurrences_account_idx ON recurrences(account_id);
+
+    CREATE TABLE IF NOT EXISTS transactions (
       id TEXT PRIMARY KEY,
       date TEXT NOT NULL,
       description TEXT NOT NULL,
+      merchant_id TEXT REFERENCES merchants(id),
+      raw_descriptor TEXT,
       source_file_id TEXT REFERENCES scanned_files(id) ON DELETE CASCADE,
       source_page INTEGER,
+      recurrence_id TEXT REFERENCES recurrences(id) ON DELETE SET NULL,
+      has_concern INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
 
-    CREATE TABLE IF NOT EXISTS journal_lines (
+    CREATE INDEX IF NOT EXISTS transactions_recurrence_idx ON transactions(recurrence_id);
+    CREATE INDEX IF NOT EXISTS transactions_source_file_idx ON transactions(source_file_id);
+    CREATE INDEX IF NOT EXISTS transactions_date_idx ON transactions(date);
+    CREATE INDEX IF NOT EXISTS transactions_merchant_idx ON transactions(merchant_id);
+
+    CREATE TABLE IF NOT EXISTS postings (
       id TEXT PRIMARY KEY,
-      entry_id TEXT NOT NULL REFERENCES journal_entries(id) ON DELETE CASCADE,
+      transaction_id TEXT NOT NULL REFERENCES transactions(id) ON DELETE CASCADE,
       account_id TEXT NOT NULL REFERENCES accounts(id),
       debit REAL NOT NULL DEFAULT 0,
       credit REAL NOT NULL DEFAULT 0,
@@ -49,14 +95,15 @@ export function migrate(db) {
       CHECK (debit >= 0 AND credit >= 0 AND (debit = 0 OR credit = 0))
     );
 
-    CREATE INDEX IF NOT EXISTS journal_lines_entry_idx ON journal_lines(entry_id);
-    CREATE INDEX IF NOT EXISTS journal_lines_account_idx ON journal_lines(account_id);
-    CREATE INDEX IF NOT EXISTS journal_entries_source_file_idx ON journal_entries(source_file_id);
-    CREATE INDEX IF NOT EXISTS journal_entries_date_idx ON journal_entries(date);
+    CREATE INDEX IF NOT EXISTS postings_transaction_idx ON postings(transaction_id);
+    CREATE INDEX IF NOT EXISTS postings_account_idx ON postings(account_id);
 
-    CREATE TABLE IF NOT EXISTS pending_questions (
+    CREATE TABLE IF NOT EXISTS concerns (
       id TEXT PRIMARY KEY,
       file_id TEXT REFERENCES scanned_files(id) ON DELETE CASCADE,
+      transaction_id TEXT REFERENCES transactions(id) ON DELETE CASCADE,
+      account_id TEXT REFERENCES accounts(id) ON DELETE CASCADE,
+      kind TEXT,
       prompt TEXT NOT NULL,
       options_json TEXT,
       answer TEXT,
@@ -91,5 +138,23 @@ export function migrate(db) {
       use_count INTEGER NOT NULL DEFAULT 0,
       created_at TEXT NOT NULL DEFAULT (datetime('now'))
     );
+
+    CREATE TABLE IF NOT EXISTS action_log (
+      id TEXT PRIMARY KEY,
+      correlation_id TEXT NOT NULL,
+      command TEXT NOT NULL,
+      user_input TEXT,
+      action_type TEXT NOT NULL CHECK(action_type IN (
+        'create_account','update_account_metadata','record_transaction','adjust_balance',
+        'create_merchant','update_merchant_default'
+      )),
+      target_id TEXT NOT NULL,
+      payload_json TEXT NOT NULL,
+      created_at TEXT NOT NULL DEFAULT (datetime('now')),
+      reverted_at TEXT
+    );
+
+    CREATE INDEX IF NOT EXISTS action_log_correlation_idx ON action_log(correlation_id);
+    CREATE INDEX IF NOT EXISTS action_log_created_idx ON action_log(created_at);
   `);
 }

package/dist/reviewer/pipeline.d.ts

@@ -0,0 +1,18 @@
+export interface ReviewOptions {
+    accountId?: string;
+    from?: string;
+    to?: string;
+    dryRun?: boolean;
+    interactive?: boolean;
+}
+export interface ReviewSummary {
+    summary: string;
+    dryRun: boolean;
+}
+/**
+ * Walk the existing ledger with the review-profile agent: surface open
+ * concerns (uncategorized cleanup first), detect correlated transactions and
+ * recurrences, propose fixes, apply them (or print "would do X" stubs when
+ * dryRun is on) after the user confirms one step at a time.
+ */
+export declare function runReview(opts?: ReviewOptions): Promise<ReviewSummary>;

package/dist/reviewer/pipeline.js

@@ -0,0 +1,46 @@
+import { getDb } from "../db/connection.js";
+import { runReviewAgent } from "../ai/agent.js";
+import { statusSpinner, makePromptUser, makeAgentOnProgress, } from "../cli/ux.js";
+import { buildReviewUserMessage } from "./prompts.js";
+/**
+ * Walk the existing ledger with the review-profile agent: surface open
+ * concerns (uncategorized cleanup first), detect correlated transactions and
+ * recurrences, propose fixes, apply them (or print "would do X" stubs when
+ * dryRun is on) after the user confirms one step at a time.
+ */
+export async function runReview(opts = {}) {
+    const db = getDb();
+    const interactive = opts.interactive ?? true;
+    const dryRun = !!opts.dryRun;
+    const scope = {
+        accountId: opts.accountId,
+        from: opts.from,
+        to: opts.to,
+        dryRun,
+    };
+    const spinner = statusSpinner(`Reviewing${dryRun ? " (dry-run)" : ""}...`);
+    const promptUser = interactive ? makePromptUser(spinner) : undefined;
+    let summary = "";
+    try {
+        await runReviewAgent({
+            db,
+            prompt: scope,
+            initialMessages: [
+                { role: "user", content: buildReviewUserMessage(scope) },
+            ],
+            agentCtx: {
+                interactive,
+                dryRun,
+                promptUser,
+                onComplete: (s) => { summary = s; },
+            },
+            onProgress: makeAgentOnProgress(spinner),
+        });
+        spinner.succeed(dryRun ? "Review complete (dry-run — no writes)." : "Review complete.");
+    }
+    catch (err) {
+        spinner.fail(`Review failed: ${err.message}`);
+        throw err;
+    }
+    return { summary, dryRun };
+}

package/dist/reviewer/prompts.d.ts

@@ -0,0 +1,12 @@
+export interface ReviewScope {
+    accountId?: string;
+    from?: string;
+    to?: string;
+    dryRun: boolean;
+}
+/**
+ * Kickoff message the review agent receives. The persona + chart-of-accounts
+ * snapshot live in the system prompt (`buildReviewSystemPrompt`); this is
+ * the per-session instruction.
+ */
+export declare function buildReviewUserMessage(scope: ReviewScope): string;

package/dist/reviewer/prompts.js

@@ -0,0 +1,22 @@
+/**
+ * Kickoff message the review agent receives. The persona + chart-of-accounts
+ * snapshot live in the system prompt (`buildReviewSystemPrompt`); this is
+ * the per-session instruction.
+ */
+export function buildReviewUserMessage(scope) {
+    return [
+        `Review the local Plasalid ledger.`,
+        ``,
+        `Scope:`,
+        `- account: ${scope.accountId ?? "all"}`,
+        `- from: ${scope.from ?? "all time"}`,
+        `- to: ${scope.to ?? "now"}`,
+        `- dry run: ${scope.dryRun ? "yes — write tools are no-ops" : "no — writes commit after confirmation"}`,
+        ``,
+        `Steps:`,
+        `1. Survey first: list_accounts, get_net_worth, count open concerns (especially kind='uncategorized_expense'), then find_duplicate_transactions, find_similar_accounts, find_unused_accounts, find_correlated_transactions, find_recurrences. Hold the candidate list internally.`,
+        `2. Prioritize: (a) uncategorized expense cleanup — these are postings parked in expense:uncategorized awaiting a real category; resolving one should also call set_merchant_default_account when the transaction has a merchant, so future statements skip the categorizer. (b) other open concerns. (c) correlated transactions. (d) recurrences. (e) chart-of-accounts hygiene.`,
+        `3. Ask one focused question at a time via ask_user. Group sibling concerns (same merchant, same answer) via related_concern_ids so the user answers once. After each answer, apply the change and re-survey only if the change invalidated other candidates.`,
+        `4. Loop until no open concerns remain (or the user keeps choosing "Skip — leave as is"). Then call mark_review_done with a short summary of what was applied, recorded, and skipped.`,
+    ].join("\n");
+}

package/dist/scanner/account_mutex.d.ts

@@ -0,0 +1 @@
+export declare function runExclusive<T>(fn: () => Promise<T> | T): Promise<T>;

package/dist/scanner/account_mutex.js

@@ -0,0 +1,16 @@
+/**
+ * Process-wide serialization for write operations that race when multiple scan
+ * agents run in parallel. Each in-flight `create_account` / `update_account_metadata`
+ * is held inside `runExclusive` so the SQLite write + the subsequent read-back
+ * by another agent's `list_accounts` are consistent.
+ *
+ * Single tail-promise queue: cheap, deterministic, no extra deps.
+ */
+let tail = Promise.resolve();
+export function runExclusive(fn) {
+    const next = tail.then(() => fn());
+    // Swallow rejection so a thrown callback doesn't poison the queue for the
+    // next caller. The caller still sees the rejection through `next`.
+    tail = next.catch(() => undefined);
+    return next;
+}

package/dist/scanner/buffer.d.ts

@@ -0,0 +1,51 @@
+import type Database from "libsql";
+import { type TransactionInput } from "../db/queries/transactions.js";
+/**
+ * One scan agent's pending writes. Transactions and concerns accumulate here
+ * while the LLM works; nothing hits the DB until `commit()` runs inside a
+ * single SQLite transaction. If `commit()` throws, the transaction rolls back
+ * and the DB stays exactly as it was before this file's scan began.
+ *
+ * Account writes (`create_account`, `update_account_metadata`) and merchant
+ * writes deliberately bypass the buffer — they go directly to the DB through
+ * their own mutexes so concurrent agents see each other's creates and don't
+ * duplicate.
+ */
+export interface BufferedConcern {
+    /** Synthesized when the LLM called note_concern with a buffered transaction_id. */
+    transaction_id: string | null;
+    account_id: string | null;
+    kind?: string | null;
+    prompt: string;
+    options?: string[];
+}
+export interface BufferedTransaction {
+    /** Synthesized at queue-time so concerns can reference this transaction. */
+    transaction_id: string;
+    input: TransactionInput;
+}
+export declare class BufferedWriteContext {
+    readonly fileName: string;
+    readonly transactions: BufferedTransaction[];
+    readonly concerns: BufferedConcern[];
+    doneSummary: string | null;
+    constructor(fileName: string);
+    /**
+     * Queue a transaction. Returns the synthesized transaction id so the agent
+     * can use it in subsequent note_concern calls inside the same file.
+     */
+    appendTransaction(input: TransactionInput): string;
+    appendConcern(concern: BufferedConcern): void;
+    markDone(summary: string): void;
+    get isDone(): boolean;
+    /**
+     * Replay all buffered writes inside one DB transaction. `scannedFileId` is
+     * stamped onto every transaction and concern so they're attributable to this
+     * file. Returns `{ transactions, concerns }` counts so the caller can report
+     * them.
+     */
+    commit(db: Database.Database, scannedFileId: string): {
+        transactions: number;
+        concerns: number;
+    };
+}

package/dist/scanner/buffer.js

@@ -0,0 +1,63 @@
+import { randomUUID } from "crypto";
+import { insertTransactionRows, validateTransaction, } from "../db/queries/transactions.js";
+import { recordConcern } from "../db/queries/concerns.js";
+export class BufferedWriteContext {
+    fileName;
+    transactions = [];
+    concerns = [];
+    doneSummary = null;
+    constructor(fileName) {
+        this.fileName = fileName;
+    }
+    /**
+     * Queue a transaction. Returns the synthesized transaction id so the agent
+     * can use it in subsequent note_concern calls inside the same file.
+     */
+    appendTransaction(input) {
+        const transactionId = `tx:${randomUUID()}`;
+        this.transactions.push({ transaction_id: transactionId, input });
+        return transactionId;
+    }
+    appendConcern(concern) {
+        this.concerns.push(concern);
+    }
+    markDone(summary) {
+        this.doneSummary = summary;
+    }
+    get isDone() {
+        return this.doneSummary !== null;
+    }
+    /**
+     * Replay all buffered writes inside one DB transaction. `scannedFileId` is
+     * stamped onto every transaction and concern so they're attributable to this
+     * file. Returns `{ transactions, concerns }` counts so the caller can report
+     * them.
+     */
+    commit(db, scannedFileId) {
+        const validated = this.transactions.map(b => ({
+            buffered: b,
+            validated: validateTransaction({
+                ...b.input,
+                id: b.transaction_id,
+                source_file_id: scannedFileId,
+            }),
+        }));
+        const tx = db.transaction(() => {
+            for (const { validated: v } of validated) {
+                insertTransactionRows(db, v);
+            }
+            for (const c of this.concerns) {
+                recordConcern(db, {
+                    file_id: scannedFileId,
+                    transaction_id: c.transaction_id,
+                    account_id: c.account_id,
+                    kind: c.kind ?? null,
+                    prompt: c.prompt,
+                    options: c.options,
+                });
+            }
+        });
+        tx();
+        return { transactions: this.transactions.length, concerns: this.concerns.length };
+    }
+}

package/dist/scanner/concurrency.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Run an array of async task factories with a fixed concurrency bound. Resolves
+ * to an array of results in the same order as the input tasks (regardless of
+ * completion order). Any rejection settles that slot with `undefined` and the
+ * caller is responsible for tracking failures — but since each task is wrapped
+ * in `Promise.resolve()` and pushed through `try/catch`, one task throwing
+ * never aborts the rest of the run.
+ *
+ * No new dependency. Simple worker-pool: kicks off up to `n` tasks, then each
+ * worker pulls the next index from a shared cursor until the queue is drained.
+ */
+export declare function runWithConcurrency<T>(tasks: Array<() => Promise<T>>, n: number): Promise<Array<T | {
+    error: unknown;
+}>>;

package/dist/scanner/concurrency.js

@@ -0,0 +1,31 @@
+/**
+ * Run an array of async task factories with a fixed concurrency bound. Resolves
+ * to an array of results in the same order as the input tasks (regardless of
+ * completion order). Any rejection settles that slot with `undefined` and the
+ * caller is responsible for tracking failures — but since each task is wrapped
+ * in `Promise.resolve()` and pushed through `try/catch`, one task throwing
+ * never aborts the rest of the run.
+ *
+ * No new dependency. Simple worker-pool: kicks off up to `n` tasks, then each
+ * worker pulls the next index from a shared cursor until the queue is drained.
+ */
+export async function runWithConcurrency(tasks, n) {
+    const results = new Array(tasks.length);
+    const workerCount = Math.max(1, Math.min(n, tasks.length));
+    let cursor = 0;
+    async function worker() {
+        while (true) {
+            const index = cursor++;
+            if (index >= tasks.length)
+                return;
+            try {
+                results[index] = await tasks[index]();
+            }
+            catch (err) {
+                results[index] = { error: err };
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    return results;
+}

package/dist/scanner/decrypt_queue.d.ts

@@ -0,0 +1,57 @@
+import type Database from "libsql";
+import type { ScannedFile } from "./walker.js";
+export interface DecryptedFile {
+    path: string;
+    fileName: string;
+    relPath: string;
+    hash: string;
+    mime: string;
+    decryptedBytes: Buffer;
+    /** True if a prior scan covered this hash; only present when --force is set. */
+    replacesPriorScannedFileId?: string;
+}
+export interface SkippedFile {
+    file: ScannedFile;
+    /** id of the scanned_files row that already has this hash. */
+    existingScannedFileId: string;
+}
+export interface FailedFile {
+    file: ScannedFile;
+    error: string;
+}
+export interface DecryptQueueResult {
+    decrypted: DecryptedFile[];
+    skipped: SkippedFile[];
+    failed: FailedFile[];
+}
+export interface DecryptQueueOptions {
+    /** Re-decrypt and queue files that match a prior hash. */
+    force: boolean;
+    /** If false, never prompt for a password; treat unlock failure as failed. */
+    interactive: boolean;
+    /** Called as each file finishes (any outcome) so a spinner can update its label. */
+    onProgress?: (event: {
+        index: number;
+        total: number;
+        fileName: string;
+        outcome: "decrypted" | "skipped" | "failed";
+    }) => void;
+}
+/**
+ * Phase 1 of scan: walk every file in the queue, decrypt any that need it,
+ * and return a partition (decrypted / skipped / failed). The actual agent
+ * work in Phase 2 only sees `decrypted` — no password prompts during the
+ * parallel scan loop.
+ *
+ * Failures don't abort; the caller (CLI) confirms whether to proceed.
+ */
+export declare function decryptQueue(db: Database.Database, files: ScannedFile[], opts: DecryptQueueOptions): Promise<DecryptQueueResult>;
+/**
+ * Interactive go/no-go gate when some files failed to decrypt. Returns true
+ * if the caller should proceed with the decrypted set, false to abort the
+ * whole scan run.
+ *
+ * Returns true automatically when interactive is false (CI / non-TTY runs);
+ * the caller is expected to inspect `result.failed` and report.
+ */
+export declare function confirmProceedAfterFailures(result: DecryptQueueResult, interactive: boolean): Promise<boolean>;

package/dist/scanner/decrypt_queue.js

@@ -0,0 +1,96 @@
+import chalk from "chalk";
+import inquirer from "inquirer";
+import { readPdf } from "./pdf.js";
+import { unlockIfNeeded, persistUnlockOutcome } from "./unlock.js";
+/**
+ * Phase 1 of scan: walk every file in the queue, decrypt any that need it,
+ * and return a partition (decrypted / skipped / failed). The actual agent
+ * work in Phase 2 only sees `decrypted` — no password prompts during the
+ * parallel scan loop.
+ *
+ * Failures don't abort; the caller (CLI) confirms whether to proceed.
+ */
+export async function decryptQueue(db, files, opts) {
+    const decrypted = [];
+    const skipped = [];
+    const failed = [];
+    for (let i = 0; i < files.length; i++) {
+        const f = files[i];
+        let pdf;
+        try {
+            pdf = readPdf(f.path);
+        }
+        catch (err) {
+            failed.push({ file: f, error: `read failed: ${err.message}` });
+            opts.onProgress?.({ index: i, total: files.length, fileName: f.name, outcome: "failed" });
+            continue;
+        }
+        const existing = findScannedByHash(db, pdf.hash);
+        if (existing && !opts.force) {
+            skipped.push({ file: f, existingScannedFileId: existing.id });
+            opts.onProgress?.({ index: i, total: files.length, fileName: f.name, outcome: "skipped" });
+            continue;
+        }
+        try {
+            const unlocked = await unlockIfNeeded({
+                db,
+                filePath: f.path,
+                bytes: pdf.bytes,
+                interactive: opts.interactive,
+            });
+            persistUnlockOutcome(db, f.path, unlocked.outcome);
+            decrypted.push({
+                path: f.path,
+                fileName: f.name,
+                relPath: f.relPath,
+                hash: pdf.hash,
+                mime: pdf.mime,
+                decryptedBytes: unlocked.decrypted,
+                replacesPriorScannedFileId: existing?.id,
+            });
+            opts.onProgress?.({ index: i, total: files.length, fileName: f.name, outcome: "decrypted" });
+        }
+        catch (err) {
+            failed.push({ file: f, error: err.message ?? "unlock failed" });
+            opts.onProgress?.({ index: i, total: files.length, fileName: f.name, outcome: "failed" });
+        }
+    }
+    return { decrypted, skipped, failed };
+}
+/**
+ * Interactive go/no-go gate when some files failed to decrypt. Returns true
+ * if the caller should proceed with the decrypted set, false to abort the
+ * whole scan run.
+ *
+ * Returns true automatically when interactive is false (CI / non-TTY runs);
+ * the caller is expected to inspect `result.failed` and report.
+ */
+export async function confirmProceedAfterFailures(result, interactive) {
+    if (result.failed.length === 0)
+        return true;
+    console.log("");
+    console.log(chalk.yellow(`${result.failed.length} file(s) could not be decrypted:`));
+    for (const f of result.failed) {
+        console.log(`  ${chalk.red("✗")} ${f.file.relPath} — ${chalk.dim(f.error)}`);
+    }
+    if (result.decrypted.length === 0) {
+        console.log(chalk.red("Nothing to scan."));
+        return false;
+    }
+    if (!interactive)
+        return true;
+    const { proceed } = (await inquirer.prompt([
+        {
+            type: "confirm",
+            name: "proceed",
+            message: `Proceed scanning the ${result.decrypted.length} file(s) that decrypted successfully?`,
+            default: true,
+        },
+    ]));
+    return proceed;
+}
+function findScannedByHash(db, hash) {
+    return db
+        .prepare(`SELECT id FROM scanned_files WHERE file_hash = ?`)
+        .get(hash) ?? null;
+}

package/dist/scanner/pipeline.d.ts

@@ -1,32 +1,61 @@
+export type ScanFileStatus = "scanned" | "replaced" | "failed" | "skipped";
 export interface ScanFileResult {
-    fileId: string | null;
-    status: "scanned" | "needs_input" | "failed" | "skipped" | "replaced";
-    summary?: string;
+    name: string;
+    relPath: string;
+    status: ScanFileStatus;
+    transactions: number;
+    concerns: number;
     error?: string;
-    pendingQuestions: number;
 }
-export interface ScanOptions {
-    interactive?: boolean;
-    force?: boolean;
-    onProgress?: (msg: string) => void;
-}
-export declare function scanFile(filePath: string, opts?: ScanOptions): Promise<ScanFileResult>;
 export interface ScanSummary {
     total: number;
     scanned: number;
     replaced: number;
     skipped: number;
-    needsInput: number;
     failed: number;
-    details: {
-        name: string;
-        relPath: string;
-        result: ScanFileResult;
-    }[];
+    concerns: number;
+    details: ScanFileResult[];
 }
-export interface RunScanOptions extends ScanOptions {
-    /** Optional regex (string). Partial, case-insensitive, against the relative path. */
+/** Event hooks the CLI subscribes to. All callbacks are best-effort and ignored if absent. */
+export interface ScanRunEvents {
+    decryptStart?: (count: number) => void;
+    decryptProgress?: (e: {
+        index: number;
+        total: number;
+        fileName: string;
+        outcome: "decrypted" | "skipped" | "failed";
+    }) => void;
+    decryptDone?: (e: {
+        decrypted: number;
+        skipped: number;
+        failed: number;
+    }) => void;
+    scanStart?: (e: {
+        fileName: string;
+    }) => void;
+    scanProgress?: (e: {
+        fileName: string;
+        step: string;
+    }) => void;
+    scanEnd?: (e: {
+        fileName: string;
+        status: "scanned" | "failed";
+        transactions: number;
+        concerns: number;
+        error?: string;
+    }) => void;
+    correlating?: (pairs: number) => void;
+    committing?: () => void;
+}
+export interface RunScanOptions {
     regex?: string;
+    force?: boolean;
+    /** Allow interactive password prompts when a PDF is encrypted. */
+    interactive?: boolean;
+    /** Max concurrent scan agents. Default 3, hard cap 8. */
+    concurrency?: number;
+    events?: ScanRunEvents;
 }
 export declare function compileMatcher(input: string): RegExp;
+/** Orchestration */
 export declare function runScan(opts?: RunScanOptions): Promise<ScanSummary>;