plasalid 0.3.4 → 0.4.1

package/dist/cli/commands/scan.js

@@ -11,35 +11,163 @@ export async function runScanCommand(opts) {
             return;
         }
     }
-    const summary = await runScan({ regex: opts.regex, force: opts.force, interactive: true });
+    const useInk = !!process.stdout.isTTY;
+    const events = useInk ? await buildInkEvents(opts.parallel ?? 3) : buildPlainTextEvents();
+    const summary = await runScan({
+        regex: opts.regex,
+        force: opts.force,
+        interactive: true,
+        concurrency: opts.parallel,
+        events,
+    });
     renderScanSummary(summary);
 }
+// ── Ink-based events (TTY mode) ────────────────────────────────────────────
+async function buildInkEvents(parallel) {
+    // Lazy-load ink + react so this module stays importable in non-TTY contexts
+    // (and so test environments without React don't choke on the JSX).
+    const { render } = await import("ink");
+    const { createElement } = await import("react");
+    const { ScanDashboard, ScanDashboardController } = await import("../ink/scan_dashboard.js");
+    const controller = new ScanDashboardController();
+    let inkInstance = null;
+    let mountedFiles = 0;
+    return {
+        decryptStart: (count) => {
+            if (count > 0)
+                console.log(chalk.dim(`Decrypting ${count} file(s)...`));
+        },
+        decryptProgress: (e) => {
+            const marker = e.outcome === "decrypted" ? chalk.dim("·")
+                : e.outcome === "skipped" ? chalk.dim("•")
+                    : chalk.red("✗");
+            console.log(`  ${marker} [${e.index + 1}/${e.total}] ${e.fileName} (${e.outcome})`);
+        },
+        decryptDone: (e) => {
+            console.log(chalk.dim(`Decrypted ${e.decrypted}, skipped ${e.skipped}, failed ${e.failed}.`));
+            console.log("");
+            mountedFiles = e.decrypted;
+            if (e.decrypted > 0) {
+                inkInstance = render(createElement(ScanDashboard, { controller, totalFiles: e.decrypted, parallel }));
+            }
+        },
+        scanStart: (e) => controller.publish({ type: "scan-start", fileName: e.fileName }),
+        scanProgress: (e) => controller.publish({ type: "scan-progress", fileName: e.fileName, step: e.step }),
+        scanEnd: (e) => controller.publish({
+            type: "scan-end",
+            fileName: e.fileName,
+            status: e.status,
+            entries: e.entries,
+            concerns: e.concerns,
+            error: e.error,
+        }),
+        correlating: (pairs) => {
+            if (inkInstance) {
+                inkInstance.unmount();
+                inkInstance = null;
+            }
+            if (mountedFiles > 0 && pairs > 0) {
+                console.log(chalk.dim(`Correlating across files... ${pairs} pair(s) flagged.`));
+            }
+        },
+        committing: () => {
+            // In case correlating fired with 0 pairs, ink may still be mounted; unmount now.
+            if (inkInstance) {
+                inkInstance.unmount();
+                inkInstance = null;
+            }
+            if (mountedFiles > 0)
+                console.log(chalk.dim("Committing..."));
+        },
+    };
+}
+// ── Plain-text progress (TTY or piped, no ink yet) ─────────────────────────
+function buildPlainTextEvents() {
+    let decryptTotal = 0;
+    // De-dupe scan-progress chatter: only print when the step text changes per file.
+    const lastStepByFile = new Map();
+    return {
+        decryptStart: (count) => {
+            decryptTotal = count;
+            if (count > 0)
+                console.log(chalk.dim(`Decrypting ${count} file(s)...`));
+        },
+        decryptProgress: (e) => {
+            const marker = e.outcome === "decrypted" ? chalk.dim("·")
+                : e.outcome === "skipped" ? chalk.dim("•")
+                    : chalk.red("✗");
+            console.log(`  ${marker} [${e.index + 1}/${e.total}] ${e.fileName} (${e.outcome})`);
+        },
+        decryptDone: (e) => {
+            if (decryptTotal === 0)
+                return;
+            console.log(chalk.dim(`Decrypted ${e.decrypted}, skipped ${e.skipped}, failed ${e.failed}.`));
+            console.log("");
+        },
+        scanStart: (e) => {
+            console.log(`${chalk.cyan("→")} ${e.fileName} ${chalk.dim("starting...")}`);
+        },
+        scanProgress: (e) => {
+            if (lastStepByFile.get(e.fileName) === e.step)
+                return;
+            lastStepByFile.set(e.fileName, e.step);
+            console.log(chalk.dim(`    ${e.fileName} · ${e.step}`));
+        },
+        scanEnd: (e) => {
+            lastStepByFile.delete(e.fileName);
+            if (e.status === "scanned") {
+                console.log(`${chalk.green("✓")} ${e.fileName} ${chalk.dim(`(${e.entries} entries, ${e.concerns} concerns)`)}`);
+            }
+            else {
+                console.log(`${chalk.red("✗")} ${e.fileName} ${chalk.dim(`— ${e.error ?? "failed"}`)}`);
+            }
+        },
+        correlating: (pairs) => {
+            if (pairs > 0)
+                console.log(chalk.dim(`Correlating across files... ${pairs} pair(s) flagged.`));
+        },
+        committing: () => {
+            console.log(chalk.dim("Committing..."));
+        },
+    };
+}
+// ── Terse summary ──────────────────────────────────────────────────────────
 function renderScanSummary(summary) {
     console.log("");
-    console.log(chalk.bold(`Scanned ${summary.total} file(s)`));
-    console.log(`  ${chalk.green(`${summary.scanned} scanned`)}  ` +
-        `${chalk.cyan(`${summary.replaced} replaced`)}  ` +
-        `${chalk.dim(`${summary.skipped} skipped`)}  ` +
-        `${chalk.yellow(`${summary.needsInput} needs input`)}  ` +
-        `${chalk.red(`${summary.failed} failed`)}`);
+    const headline = `Scanned ${summary.total} file(s) — ` +
+        `${summary.scanned + summary.replaced} ok, ` +
+        `${summary.failed} failed, ` +
+        `${summary.concerns} concern${summary.concerns === 1 ? "" : "s"} flagged`;
+    console.log(chalk.bold(headline));
+    console.log("");
     for (const d of summary.details) {
         const label = d.relPath;
-        switch (d.result.status) {
-            case "scanned":
-                console.log(`  ${chalk.green("✓")} ${label}${d.result.summary ? chalk.dim(` — ${d.result.summary}`) : ""}`);
+        switch (d.status) {
+            case "scanned": {
+                const tag = chalk.dim(`${d.entries} entries${d.concerns > 0 ? ` · ${d.concerns} concerns` : ""}`);
+                console.log(`  ${chalk.green("✓")} ${label}  ${tag}`);
                 break;
-            case "replaced":
-                console.log(`  ${chalk.cyan("↻")} ${label} (replaces previous records)`);
+            }
+            case "replaced": {
+                const tag = chalk.dim(`${d.entries} entries${d.concerns > 0 ? ` · ${d.concerns} concerns` : ""} (replaces prior)`);
+                console.log(`  ${chalk.cyan("↻")} ${label}  ${tag}`);
                 break;
-            case "skipped":
-                console.log(`  ${chalk.dim("•")} ${label} (already scanned)`);
+            }
+            case "skipped": {
+                console.log(`  ${chalk.dim("•")} ${label}  ${chalk.dim("(already scanned)")}`);
                 break;
-            case "needs_input":
-                console.log(`  ${chalk.yellow("!")} ${label} (${d.result.pendingQuestions} pending)`);
-                break;
-            case "failed":
-                console.log(`  ${chalk.red("✗")} ${label}${d.result.error ? chalk.dim(` — ${d.result.error}`) : ""}`);
+            }
+            case "failed": {
+                console.log(`  ${chalk.red("✗")} ${label}  ${chalk.dim(`— ${d.error ?? "failed"}`)}`);
                 break;
+            }
         }
     }
+    const newlyProcessed = summary.scanned + summary.replaced;
+    if (newlyProcessed > 0) {
+        console.log("");
+        console.log(`${chalk.dim("Next:")} ${chalk.cyan("plasalid review")}${chalk.dim(summary.concerns > 0
+            ? " — to clear the concerns and learn your recurring rhythms."
+            : " — to connect related transactions and learn your recurring rhythms.")}`);
+    }
 }

package/dist/cli/index.js

@@ -83,6 +83,7 @@ program
     .command("scan [regex...]")
     .description("Scan every new PDF under ~/.plasalid/data (optionally filtered by regex)")
     .option("-f, --force", "Re-scan matching files (cascade-deletes prior records)")
+    .option("-p, --parallel <n>", "Number of files to scan concurrently (default 3, max 8). Override env PLASALID_SCAN_CONCURRENCY.", (v) => parseInt(v, 10))
     .action(async (regexes, opts) => {
     ensureConfigured();
     if (regexes.length > 1) {
@@ -96,20 +97,22 @@ program
         console.error(`  ${chalk.cyan("plasalid scan 'KBank|SCB'")}`);
         process.exit(1);
     }
+    const envParallel = parseInt(process.env.PLASALID_SCAN_CONCURRENCY ?? "", 10);
+    const parallel = Number.isFinite(opts.parallel) ? opts.parallel : (Number.isFinite(envParallel) ? envParallel : undefined);
     const { runScanCommand } = await import("./commands/scan.js");
-    await runScanCommand({ regex: regexes[0], force: !!opts.force });
+    await runScanCommand({ regex: regexes[0], force: !!opts.force, parallel });
 });
 program
-    .command("reconcile")
-    .description("Revisit the existing journal: find duplicate entries, similar accounts, and unused accounts; apply fixes after user confirmation")
-    .option("-a, --account <id>", "Limit reconciliation to a single account")
+    .command("review")
+    .description("See the whole picture — connect related transactions across statements, learn the rhythm of your recurring money, and clear up anything that's still in question.")
+    .option("-a, --account <id>", "Limit review to a single account")
     .option("--from <date>", "Only consider entries on or after this date (YYYY-MM-DD)")
     .option("--to <date>", "Only consider entries on or before this date (YYYY-MM-DD)")
     .option("-d, --dry-run", "Surface findings without applying any change")
     .action(async (opts) => {
     ensureConfigured();
-    const { runReconcileCommand } = await import("./commands/reconcile.js");
-    await runReconcileCommand({
+    const { runReviewCommand } = await import("./commands/review.js");
+    await runReviewCommand({
         accountId: opts.account,
         from: opts.from,
         to: opts.to,
@@ -145,8 +148,8 @@ program.configureHelp({
             desc: "Scan new PDFs (optionally by regex; --force to re-scan)",
         },
         {
-            name: "reconcile",
-            desc: "Review and fix existing journal entries / accounts",
+            name: "review",
+            desc: "Connect the dots and learn your recurring rhythms",
         },
         {
             name: "revert",

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

@@ -0,0 +1,38 @@
+export type ScanDashboardEvent = {
+    type: "scan-start";
+    fileName: string;
+} | {
+    type: "scan-progress";
+    fileName: string;
+    step: string;
+} | {
+    type: "scan-end";
+    fileName: string;
+    status: "scanned" | "failed";
+    entries: number;
+    concerns: number;
+    error?: string;
+};
+/**
+ * Subscribe / publish channel between the pipeline (which knows nothing about
+ * UI) and the dashboard (which knows nothing about the pipeline). The CLI
+ * creates one of these, fans events into it, and hands it to the component.
+ */
+export declare class ScanDashboardController {
+    private subscribers;
+    publish(event: ScanDashboardEvent): void;
+    subscribe(handler: (e: ScanDashboardEvent) => void): () => void;
+}
+interface Props {
+    controller: ScanDashboardController;
+    totalFiles: number;
+    parallel: number;
+}
+/**
+ * Multi-row live dashboard for the scan phase. Rows appear when a file starts
+ * scanning, update as steps flow, and freeze when the agent loop ends. Counts
+ * shown are the in-buffer counts at scan-end; correlation may add concerns
+ * later, which the terse summary reflects.
+ */
+export declare function ScanDashboard({ controller, totalFiles, parallel }: Props): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/cli/ink/scan_dashboard.js

@@ -0,0 +1,62 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { Box, Text } from "ink";
+import Spinner from "ink-spinner";
+/**
+ * Subscribe / publish channel between the pipeline (which knows nothing about
+ * UI) and the dashboard (which knows nothing about the pipeline). The CLI
+ * creates one of these, fans events into it, and hands it to the component.
+ */
+export class ScanDashboardController {
+    subscribers = [];
+    publish(event) {
+        for (const sub of this.subscribers)
+            sub(event);
+    }
+    subscribe(handler) {
+        this.subscribers.push(handler);
+        return () => {
+            this.subscribers = this.subscribers.filter(s => s !== handler);
+        };
+    }
+}
+/**
+ * Multi-row live dashboard for the scan phase. Rows appear when a file starts
+ * scanning, update as steps flow, and freeze when the agent loop ends. Counts
+ * shown are the in-buffer counts at scan-end; correlation may add concerns
+ * later, which the terse summary reflects.
+ */
+export function ScanDashboard({ controller, totalFiles, parallel }) {
+    const [rows, setRows] = useState(() => new Map());
+    useEffect(() => {
+        return controller.subscribe(event => {
+            setRows(prev => {
+                const next = new Map(prev);
+                switch (event.type) {
+                    case "scan-start":
+                        next.set(event.fileName, { kind: "scanning", step: "starting..." });
+                        break;
+                    case "scan-progress":
+                        next.set(event.fileName, { kind: "scanning", step: event.step });
+                        break;
+                    case "scan-end":
+                        next.set(event.fileName, event.status === "scanned"
+                            ? { kind: "done", entries: event.entries, concerns: event.concerns }
+                            : { kind: "failed", error: event.error ?? "failed" });
+                        break;
+                }
+                return next;
+            });
+        });
+    }, [controller]);
+    return (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { children: ["Scanning ", totalFiles, " file(s) (", parallel, " in parallel)"] }), Array.from(rows.entries()).map(([name, state]) => (_jsx(FileRow, { name: name, state: state }, name)))] }));
+}
+function FileRow({ name, state }) {
+    if (state.kind === "scanning") {
+        return (_jsxs(Text, { children: ["  ", _jsx(Text, { color: "yellow", children: _jsx(Spinner, { type: "dots" }) }), " ", name, " ", _jsxs(Text, { dimColor: true, children: ["\u00B7 ", state.step] })] }));
+    }
+    if (state.kind === "done") {
+        return (_jsxs(Text, { children: ["  ", _jsx(Text, { color: "green", children: "\u2713" }), " ", name, " ", _jsxs(Text, { dimColor: true, children: ["(", state.entries, " entries, ", state.concerns, " concerns)"] })] }));
+    }
+    return (_jsxs(Text, { children: ["  ", _jsx(Text, { color: "red", children: "\u2717" }), " ", name, " ", _jsxs(Text, { dimColor: true, children: ["\u2014 ", state.error] })] }));
+}

package/dist/cli/ux.d.ts

@@ -1,4 +1,5 @@
 import type { ProgressCallback } from "../ai/agent.js";
+import type { PromptUserFacts } from "../ai/tools/types.js";
 /**
  * Minimal spinner interface so callers don't care whether we're animating in
  * a TTY or just printing plain lines. The same instance can be `pause()`d and
@@ -27,7 +28,7 @@ export declare function statusSpinner(text: string): SpinnerLike;
  * line, pads with blank lines for readability, and always includes a free-text
  * escape on choice prompts ("Type a different answer…").
  */
-export declare function makePromptUser(spinner: SpinnerLike): (prompt: string, options?: string[]) => Promise<string>;
+export declare function makePromptUser(spinner: SpinnerLike): (prompt: string, options?: string[], facts?: PromptUserFacts) => Promise<string>;
 /**
  * Standard agent-progress → spinner-text bridge.
  * - `phase: "tool"` maps the tool name through `TOOL_LABELS`.

package/dist/cli/ux.js

@@ -1,5 +1,6 @@
 import inquirer from "inquirer";
 import ora from "ora";
+import chalk from "chalk";
 import { TOOL_LABELS } from "../ai/tools/index.js";
 import { pickThinking } from "../ai/thinking.js";
 import { formatDuration } from "./format.js";
@@ -45,9 +46,12 @@ export function statusSpinner(text) {
  */
 export function makePromptUser(spinner) {
     const OTHER = "__plasalid_other__";
-    return async (prompt, options) => {
+    return async (prompt, options, facts) => {
         spinner.pause();
         console.log("");
+        const factsLine = facts ? formatFacts(facts) : null;
+        if (factsLine)
+            console.log(factsLine);
         try {
             if (options && options.length > 0) {
                 const choices = [
@@ -60,7 +64,18 @@ export function makePromptUser(spinner) {
                     { name: "Type a different answer…", value: OTHER },
                 ];
                 const { choice } = await inquirer.prompt([
-                    { type: "list", name: "choice", message: prompt, choices },
+                    {
+                        type: "list",
+                        name: "choice",
+                        message: prompt,
+                        choices,
+                        // Stop the cursor at the top/bottom instead of wrapping forever —
+                        // the wrap-around default makes the list feel infinite.
+                        loop: false,
+                        // Show every choice without paginating. Floor of 10 keeps the
+                        // prompt height predictable for small option sets.
+                        pageSize: Math.max(choices.length, 10),
+                    },
                 ]);
                 if (choice === OTHER) {
                     const { freeform } = await inquirer.prompt([
@@ -102,3 +117,22 @@ export function makeAgentOnProgress(spinner, subject) {
         }
     };
 }
+/**
+ * Render the structured facts the review agent attaches to ask_user as a
+ * single colored line above the inquirer prompt. Each category has a fixed
+ * chalk color so the user's eye picks out the type without reading prose.
+ * Returns null when there's nothing to render (so the caller can skip the
+ * blank line entirely).
+ */
+function formatFacts(f) {
+    const parts = [];
+    if (f.amount)
+        parts.push(chalk.yellow(f.amount));
+    if (f.date)
+        parts.push(chalk.cyan(f.date));
+    if (f.merchant)
+        parts.push(chalk.green(f.merchant));
+    for (const a of f.accounts ?? [])
+        parts.push(chalk.magenta(a));
+    return parts.length ? parts.join(chalk.dim(" · ")) : null;
+}

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

@@ -13,6 +13,7 @@ export interface AccountRow {
     points_balance: number | null;
     metadata_json: string | null;
     pii_flag: number;
+    has_concern: number;
     created_at: string;
 }
 export interface AccountBalance extends AccountRow {

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

@@ -0,0 +1,47 @@
+import type Database from "libsql";
+export interface ConcernTarget {
+    entry_id: string | null;
+    account_id: string | null;
+}
+export interface RecordConcernInput extends ConcernTarget {
+    file_id: string | null;
+    prompt: string;
+    options?: string[];
+}
+export interface OpenConcernRow {
+    id: string;
+    file_id: string | null;
+    entry_id: string | null;
+    account_id: string | null;
+    prompt: string;
+    options_json: string | null;
+    created_at: string;
+}
+/**
+ * Insert a new concerns row and flip the `has_concern` boolean on whichever
+ * target (entry / account) was named. Returns the new `cn:<uuid>` id.
+ */
+export declare function recordConcern(db: Database.Database, input: RecordConcernInput): string;
+/**
+ * Mark an existing concern as resolved with the user's answer and, if no other
+ * open concerns reference the same target, clear the target's `has_concern`
+ * flag. Returns the concern's target so callers can log or react.
+ */
+export declare function resolveConcern(db: Database.Database, id: string, answer: string): ConcernTarget | null;
+/**
+ * Look up the entry/account a concern is attached to. Returns null when the
+ * concern id doesn't exist.
+ */
+export declare function getConcernTarget(db: Database.Database, id: string): ConcernTarget | null;
+/**
+ * Clear `has_concern` on the named entry / account if no other open concerns
+ * still reference it. Safe to call after any concern resolution; idempotent.
+ */
+export declare function maybeClearHasConcernFlags(db: Database.Database, target: ConcernTarget): void;
+export interface CountOpenConcernsScope {
+    file_id?: string;
+    entry_id?: string;
+    account_id?: string;
+}
+export declare function countOpenConcerns(db: Database.Database, scope?: CountOpenConcernsScope): number;
+export declare function listOpenConcerns(db: Database.Database, limit?: number): OpenConcernRow[];

package/dist/db/queries/concerns.js

@@ -0,0 +1,87 @@
+import { randomUUID } from "crypto";
+/**
+ * Insert a new concerns row and flip the `has_concern` boolean on whichever
+ * target (entry / account) was named. Returns the new `cn:<uuid>` id.
+ */
+export function recordConcern(db, input) {
+    const id = `cn:${randomUUID()}`;
+    db.prepare(`INSERT INTO concerns (id, file_id, entry_id, account_id, prompt, options_json) VALUES (?, ?, ?, ?, ?, ?)`).run(id, input.file_id, input.entry_id, input.account_id, input.prompt, input.options ? JSON.stringify(input.options) : null);
+    if (input.entry_id) {
+        db.prepare(`UPDATE journal_entries SET has_concern = 1 WHERE id = ?`).run(input.entry_id);
+    }
+    if (input.account_id) {
+        db.prepare(`UPDATE accounts SET has_concern = 1 WHERE id = ?`).run(input.account_id);
+    }
+    return id;
+}
+/**
+ * Mark an existing concern as resolved with the user's answer and, if no other
+ * open concerns reference the same target, clear the target's `has_concern`
+ * flag. Returns the concern's target so callers can log or react.
+ */
+export function resolveConcern(db, id, answer) {
+    const target = getConcernTarget(db, id);
+    if (!target)
+        return null;
+    db.prepare(`UPDATE concerns SET answer = ?, resolved_at = datetime('now') WHERE id = ?`).run(answer, id);
+    maybeClearHasConcernFlags(db, target);
+    return target;
+}
+/**
+ * Look up the entry/account a concern is attached to. Returns null when the
+ * concern id doesn't exist.
+ */
+export function getConcernTarget(db, id) {
+    const row = db
+        .prepare(`SELECT entry_id, account_id FROM concerns WHERE id = ?`)
+        .get(id);
+    return row ?? null;
+}
+/**
+ * Clear `has_concern` on the named entry / account if no other open concerns
+ * still reference it. Safe to call after any concern resolution; idempotent.
+ */
+export function maybeClearHasConcernFlags(db, target) {
+    if (target.entry_id) {
+        const open = db
+            .prepare(`SELECT 1 FROM concerns WHERE entry_id = ? AND resolved_at IS NULL LIMIT 1`)
+            .get(target.entry_id);
+        if (!open)
+            db.prepare(`UPDATE journal_entries SET has_concern = 0 WHERE id = ?`).run(target.entry_id);
+    }
+    if (target.account_id) {
+        const open = db
+            .prepare(`SELECT 1 FROM concerns WHERE account_id = ? AND resolved_at IS NULL LIMIT 1`)
+            .get(target.account_id);
+        if (!open)
+            db.prepare(`UPDATE accounts SET has_concern = 0 WHERE id = ?`).run(target.account_id);
+    }
+}
+export function countOpenConcerns(db, scope = {}) {
+    const conditions = ["resolved_at IS NULL"];
+    const params = [];
+    if (scope.file_id) {
+        conditions.push("file_id = ?");
+        params.push(scope.file_id);
+    }
+    if (scope.entry_id) {
+        conditions.push("entry_id = ?");
+        params.push(scope.entry_id);
+    }
+    if (scope.account_id) {
+        conditions.push("account_id = ?");
+        params.push(scope.account_id);
+    }
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n FROM concerns WHERE ${conditions.join(" AND ")}`)
+        .get(...params);
+    return row.n;
+}
+export function listOpenConcerns(db, limit = 50) {
+    const capped = Math.min(Math.max(limit, 1), 200);
+    return db.prepare(`SELECT id, file_id, entry_id, account_id, prompt, options_json, created_at
+     FROM concerns
+     WHERE resolved_at IS NULL
+     ORDER BY created_at ASC
+     LIMIT ?`).all(capped);
+}

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

@@ -8,20 +8,14 @@ export interface JournalLineInput {
     pii_flag?: boolean;
 }
 export interface JournalEntryInput {
+    /** Optional pre-assigned id. Used by the buffered-write path so concerns recorded mid-scan can reference the entry before commit. */
+    id?: string;
     date: string;
     description: string;
     source_file_id?: string | null;
     source_page?: number | null;
     lines: JournalLineInput[];
 }
-export interface JournalEntryRow {
-    id: string;
-    date: string;
-    description: string;
-    source_file_id: string | null;
-    source_page: number | null;
-    created_at: string;
-}
 export interface JournalLineRow {
     id: string;
     entry_id: string;
@@ -41,6 +35,22 @@ export interface JournalLineRow {
  * a header, header never lands without lines.
  */
 export declare function recordJournalEntry(db: Database.Database, entry: JournalEntryInput): string;
+/**
+ * Validate balance + invariants and assign an id. Pure (no DB writes). Used by
+ * both `recordJournalEntry` and the buffered-scan commit path; the latter
+ * already runs inside its own transaction and must not open another.
+ */
+export declare function validateJournalEntry(entry: JournalEntryInput): JournalEntryInput & {
+    id: string;
+};
+/**
+ * Insert-only counterpart to `recordJournalEntry`. The caller is responsible
+ * for opening a transaction (or for accepting partial writes). Expects an
+ * already-validated entry from `validateJournalEntry`.
+ */
+export declare function insertJournalEntryRows(db: Database.Database, entry: JournalEntryInput & {
+    id: string;
+}): void;
 export interface ListJournalLinesOptions {
     account_id?: string;
     from?: string;
@@ -92,4 +102,60 @@ export interface FindDuplicateEntriesOptions {
  * account_names (for human-readable presentation to the user).
  */
 export declare function findDuplicateEntries(db: Database.Database, opts?: FindDuplicateEntriesOptions): DuplicateGroupEntry[][];
+export declare function dayDiff(a: string, b: string): number;
+export interface CorrelatedEntryPair {
+    amount: number;
+    currency: string;
+    day_gap: number;
+    a: {
+        id: string;
+        date: string;
+        description: string;
+        account_ids: string[];
+        account_names: string[];
+    };
+    b: {
+        id: string;
+        date: string;
+        description: string;
+        account_ids: string[];
+        account_names: string[];
+    };
+}
+export interface FindCorrelatedEntriesOptions {
+    from?: string;
+    to?: string;
+    /** Max day difference between paired entries. Default 3. */
+    toleranceDays?: number;
+    /** Skip entries below this total debit. Default 0. */
+    minAmount?: number;
+}
+/**
+ * Heuristic: surface pairs of entries that look like the same money movement
+ * recorded against different accounts (e.g. a bank-to-card transfer that lands
+ * once on the bank statement and again on the card statement). Filters out
+ * pairs whose account-id sets overlap (those are duplicates, not correlations).
+ */
+export declare function findCorrelatedEntries(db: Database.Database, opts?: FindCorrelatedEntriesOptions): CorrelatedEntryPair[];
+export interface CorrelationCandidate {
+    id: string;
+    date: string;
+    description: string;
+    amount: number;
+    currency: string;
+    account_ids: string[];
+    account_names: string[];
+}
+/**
+ * Pure pair-finder: given an array of candidates already filtered by amount
+ * and equipped with account_ids/names, return the cross-pairs that look like
+ * the same money movement on different accounts (date within toleranceDays,
+ * same amount + currency, non-overlapping account sets).
+ *
+ * Used by the DB-backed `findCorrelatedEntries` and by the scan-time
+ * coordinator that runs over buffered, not-yet-committed entries.
+ */
+export declare function correlatePairs(entries: CorrelationCandidate[], opts?: {
+    toleranceDays?: number;
+}): CorrelatedEntryPair[];
 export declare function listJournalLines(db: Database.Database, opts?: ListJournalLinesOptions): JournalLineRow[];