plasalid 0.3.5 → 0.5.0

package/dist/db/queries/recurrences.js

@@ -0,0 +1,128 @@
+import { randomUUID } from "crypto";
+import { dayDiff } from "./transactions.js";
+export function findRecurrenceCandidates(db, opts = {}) {
+    const minOccurrences = Math.max(2, opts.minOccurrences ?? 3);
+    const accountFilter = opts.accountId ? `AND p.account_id = ?` : ``;
+    const params = opts.accountId ? [opts.accountId] : [];
+    const rows = db.prepare(`SELECT p.account_id,
+            a.name AS account_name,
+            p.currency,
+            CASE WHEN p.debit > 0 THEN p.debit ELSE p.credit END AS amount,
+            CASE WHEN p.debit > 0 THEN 'debit' ELSE 'credit' END AS side,
+            t.id AS transaction_id,
+            t.date,
+            t.description
+     FROM postings p
+     JOIN transactions t ON t.id = p.transaction_id
+     JOIN accounts a ON a.id = p.account_id
+     WHERE t.recurrence_id IS NULL
+       AND (p.debit > 0 OR p.credit > 0)
+       ${accountFilter}
+     ORDER BY p.account_id, p.currency, amount, t.date`).all(...params);
+    const buckets = new Map();
+    for (const r of rows) {
+        const key = `${r.account_id}|${r.currency}|${Math.round(r.amount * 100)}|${r.side}`;
+        const arr = buckets.get(key) ?? [];
+        arr.push(r);
+        buckets.set(key, arr);
+    }
+    const candidates = [];
+    for (const bucket of buckets.values()) {
+        if (bucket.length < minOccurrences)
+            continue;
+        const dates = bucket.map(r => r.date);
+        const diffs = [];
+        for (let i = 1; i < dates.length; i++) {
+            diffs.push(dayDiff(dates[i - 1], dates[i]));
+        }
+        const median = medianOf(diffs);
+        candidates.push({
+            account_id: bucket[0].account_id,
+            account_name: bucket[0].account_name,
+            amount: Math.round(bucket[0].amount * 100) / 100,
+            currency: bucket[0].currency,
+            side: bucket[0].side,
+            transactions: bucket.map(r => ({ id: r.transaction_id, date: r.date, description: r.description })),
+            median_days_between: median,
+            implied_frequency: classifyFrequency(median),
+        });
+    }
+    return candidates;
+}
+function medianOf(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
+}
+function classifyFrequency(medianDays) {
+    if (medianDays >= 6 && medianDays <= 8)
+        return "weekly";
+    if (medianDays >= 13 && medianDays <= 15)
+        return "biweekly";
+    if (medianDays >= 27 && medianDays <= 32)
+        return "monthly";
+    if (medianDays >= 360 && medianDays <= 370)
+        return "annually";
+    return "irregular";
+}
+const FREQ_PERIOD_DAYS = {
+    weekly: 7,
+    biweekly: 14,
+    monthly: 30,
+    annually: 365,
+};
+export function recordRecurrence(db, input) {
+    if (!input.transaction_ids || input.transaction_ids.length === 0) {
+        throw new Error("recordRecurrence requires at least one transaction_id.");
+    }
+    const placeholders = input.transaction_ids.map(() => "?").join(",");
+    const dateRows = db.prepare(`SELECT date FROM transactions WHERE id IN (${placeholders}) ORDER BY date ASC`).all(...input.transaction_ids);
+    if (dateRows.length === 0) {
+        throw new Error("None of the supplied transaction_ids exist.");
+    }
+    const firstSeen = dateRows[0].date;
+    const lastSeen = dateRows[dateRows.length - 1].date;
+    const nextExpected = addDays(lastSeen, FREQ_PERIOD_DAYS[input.frequency]);
+    const id = `rc:${randomUUID()}`;
+    const tx = db.transaction(() => {
+        db.prepare(`INSERT INTO recurrences
+         (id, account_id, description, frequency, amount_typical, currency,
+          first_seen_date, last_seen_date, next_expected_date, notes)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, input.account_id, input.description, input.frequency, input.amount_typical ?? null, input.currency || "THB", firstSeen, lastSeen, nextExpected, input.notes ?? null);
+        const updateTx = db.prepare(`UPDATE transactions SET recurrence_id = ? WHERE id = ?`);
+        for (const transactionId of input.transaction_ids)
+            updateTx.run(id, transactionId);
+    });
+    tx();
+    return id;
+}
+export function linkTransactionToRecurrence(db, transactionId, recurrenceId) {
+    const recurrence = db
+        .prepare(`SELECT frequency FROM recurrences WHERE id = ?`)
+        .get(recurrenceId);
+    if (!recurrence)
+        throw new Error(`Recurrence ${recurrenceId} not found.`);
+    const transaction = db
+        .prepare(`SELECT date FROM transactions WHERE id = ?`)
+        .get(transactionId);
+    if (!transaction)
+        throw new Error(`Transaction ${transactionId} not found.`);
+    const tx = db.transaction(() => {
+        db.prepare(`UPDATE transactions SET recurrence_id = ? WHERE id = ?`).run(recurrenceId, transactionId);
+        const span = db
+            .prepare(`SELECT MIN(date) AS first, MAX(date) AS last FROM transactions WHERE recurrence_id = ?`)
+            .get(recurrenceId);
+        const nextExpected = addDays(span.last, FREQ_PERIOD_DAYS[recurrence.frequency]);
+        db.prepare(`UPDATE recurrences SET first_seen_date = ?, last_seen_date = ?, next_expected_date = ? WHERE id = ?`).run(span.first, span.last, nextExpected, recurrenceId);
+    });
+    tx();
+}
+function addDays(dateIso, days) {
+    const t = Date.parse(dateIso);
+    if (Number.isNaN(t))
+        return dateIso;
+    const next = new Date(t + days * 86_400_000);
+    return next.toISOString().slice(0, 10);
+}

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

@@ -1,7 +1,8 @@
 import type Database from "libsql";
-import type { JournalLineRow } from "./journal.js";
+import type { PostingRow } from "./transactions.js";
 /**
- * Free-text search across journal entry descriptions, line memos, and account
- * names. Returns matching journal lines joined with account + entry metadata.
+ * Free-text search across transaction descriptions, posting memos, account
+ * names, and merchant canonical names. Returns matching postings joined with
+ * account + transaction + merchant metadata.
  */
-export declare function searchJournalLines(db: Database.Database, query: string, limit?: number): JournalLineRow[];
+export declare function searchPostings(db: Database.Database, query: string, limit?: number): PostingRow[];

package/dist/db/queries/search.js

@@ -1,19 +1,23 @@
 /**
- * Free-text search across journal entry descriptions, line memos, and account
- * names. Returns matching journal lines joined with account + entry metadata.
+ * Free-text search across transaction descriptions, posting memos, account
+ * names, and merchant canonical names. Returns matching postings joined with
+ * account + transaction + merchant metadata.
  */
-export function searchJournalLines(db, query, limit = 30) {
+export function searchPostings(db, query, limit = 30) {
     const needle = `%${query}%`;
     const capped = Math.min(Math.max(limit, 1), 200);
-    return db.prepare(`SELECT jl.id, jl.entry_id, jl.account_id, jl.debit, jl.credit, jl.currency, jl.memo,
+    return db.prepare(`SELECT p.id, p.transaction_id, p.account_id, p.debit, p.credit, p.currency, p.memo,
             a.name AS account_name, a.type AS account_type,
-            je.date AS entry_date, je.description AS entry_description
-     FROM journal_lines jl
-     JOIN journal_entries je ON je.id = jl.entry_id
-     JOIN accounts a ON a.id = jl.account_id
-     WHERE je.description LIKE ?
-        OR jl.memo LIKE ?
+            t.date AS transaction_date, t.description AS transaction_description,
+            m.canonical_name AS merchant_name
+     FROM postings p
+     JOIN transactions t ON t.id = p.transaction_id
+     JOIN accounts a ON a.id = p.account_id
+     LEFT JOIN merchants m ON m.id = t.merchant_id
+     WHERE t.description LIKE ?
+        OR p.memo LIKE ?
         OR a.name LIKE ?
-     ORDER BY je.date DESC, je.id DESC
-     LIMIT ?`).all(needle, needle, needle, capped);
+        OR m.canonical_name LIKE ?
+     ORDER BY t.date DESC, t.id DESC
+     LIMIT ?`).all(needle, needle, needle, needle, capped);
 }

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

@@ -0,0 +1,167 @@
+import type Database from "libsql";
+import { type MerchantUpsertInput } from "./merchants.js";
+export interface PostingInput {
+    account_id: string;
+    debit?: number;
+    credit?: number;
+    currency?: string;
+    memo?: string | null;
+    pii_flag?: boolean;
+}
+export interface TransactionInput {
+    /** Optional pre-assigned id. Used by the buffered-write path so concerns recorded mid-scan can reference the transaction before commit. */
+    id?: string;
+    date: string;
+    description: string;
+    source_file_id?: string | null;
+    source_page?: number | null;
+    raw_descriptor?: string | null;
+    merchant?: MerchantUpsertInput | null;
+    /** Pre-resolved merchant id (from scanner's alias pre-resolution pass). Overrides any `merchant` upsert when set. */
+    merchant_id?: string | null;
+    postings: PostingInput[];
+}
+export interface PostingRow {
+    id: string;
+    transaction_id: string;
+    account_id: string;
+    debit: number;
+    credit: number;
+    currency: string;
+    memo: string | null;
+    account_name?: string;
+    account_type?: string;
+    transaction_date?: string;
+    transaction_description?: string;
+    merchant_name?: string | null;
+}
+/**
+ * Insert a balanced transaction. Throws if SUM(debit) !== SUM(credit) or any
+ * posting both debits and credits. Transaction-wrapped: postings never land
+ * without a header, header never lands without postings.
+ */
+export declare function recordTransaction(db: Database.Database, input: TransactionInput): string;
+/**
+ * Validate balance + invariants and assign an id. Pure (no DB writes). Used by
+ * both `recordTransaction` and the buffered-scan commit path; the latter
+ * already runs inside its own transaction and must not open another.
+ */
+export declare function validateTransaction(input: TransactionInput): TransactionInput & {
+    id: string;
+};
+/**
+ * Insert-only counterpart to `recordTransaction`. The caller is responsible
+ * for opening a transaction (or for accepting partial writes). Expects an
+ * already-validated input from `validateTransaction`.
+ */
+export declare function insertTransactionRows(db: Database.Database, input: TransactionInput & {
+    id: string;
+}): void;
+export interface ListPostingsOptions {
+    account_id?: string;
+    from?: string;
+    to?: string;
+    q?: string;
+    limit?: number;
+}
+export interface UpdateTransactionFields {
+    date?: string;
+    description?: string;
+    source_page?: number | null;
+}
+export declare function updateTransaction(db: Database.Database, transactionId: string, fields: UpdateTransactionFields): number;
+export interface UpdatePostingFields {
+    account_id?: string;
+    memo?: string | null;
+}
+/**
+ * Safe single-posting edits only. Refuses changes to `debit`, `credit`, or `currency`
+ * because those would silently break the transaction's balance — to fix amounts the
+ * caller must delete the transaction and record a fresh one.
+ */
+export declare function updatePosting(db: Database.Database, postingId: string, fields: UpdatePostingFields): number;
+/**
+ * Delete a transaction. ON DELETE CASCADE on `postings.transaction_id` removes
+ * the postings automatically.
+ */
+export declare function deleteTransaction(db: Database.Database, transactionId: string): number;
+export interface DuplicateGroupTransaction {
+    id: string;
+    date: string;
+    description: string;
+    amount: number;
+    account_ids: string[];
+    account_names: string[];
+}
+export interface FindDuplicateTransactionsOptions {
+    /** Days of slack when grouping by date. 0 means same-day only. Default 2. */
+    toleranceDays?: number;
+    /** Only consider transactions that have at least one posting on this account. */
+    accountId?: string;
+    /** Skip transactions whose total debit is below this value. */
+    minAmount?: number;
+}
+/**
+ * Heuristic duplicate finder: group transactions by (rounded total debit) and check
+ * pairs whose date difference is ≤ toleranceDays. Returns groups with ≥2 members.
+ * Each transaction carries both account_ids (for follow-up tool calls) and
+ * account_names (for human-readable presentation to the user).
+ */
+export declare function findDuplicateTransactions(db: Database.Database, opts?: FindDuplicateTransactionsOptions): DuplicateGroupTransaction[][];
+export declare function dayDiff(a: string, b: string): number;
+export interface CorrelatedTransactionPair {
+    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 FindCorrelatedTransactionsOptions {
+    from?: string;
+    to?: string;
+    /** Max day difference between paired transactions. Default 3. */
+    toleranceDays?: number;
+    /** Skip transactions below this total debit. Default 0. */
+    minAmount?: number;
+}
+/**
+ * Heuristic: surface pairs of transactions 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 findCorrelatedTransactions(db: Database.Database, opts?: FindCorrelatedTransactionsOptions): CorrelatedTransactionPair[];
+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 `findCorrelatedTransactions` and by the scan-time
+ * coordinator that runs over buffered, not-yet-committed transactions.
+ */
+export declare function correlatePairs(candidates: CorrelationCandidate[], opts?: {
+    toleranceDays?: number;
+}): CorrelatedTransactionPair[];
+export declare function listPostings(db: Database.Database, opts?: ListPostingsOptions): PostingRow[];

package/dist/db/queries/transactions.js

@@ -0,0 +1,320 @@
+import { randomUUID } from "crypto";
+import { upsertMerchant } from "./merchants.js";
+const TOLERANCE = 0.005;
+/**
+ * Insert a balanced transaction. Throws if SUM(debit) !== SUM(credit) or any
+ * posting both debits and credits. Transaction-wrapped: postings never land
+ * without a header, header never lands without postings.
+ */
+export function recordTransaction(db, input) {
+    const validated = validateTransaction(input);
+    const tx = db.transaction(() => { insertTransactionRows(db, validated); });
+    tx();
+    return validated.id;
+}
+/**
+ * Validate balance + invariants and assign an id. Pure (no DB writes). Used by
+ * both `recordTransaction` and the buffered-scan commit path; the latter
+ * already runs inside its own transaction and must not open another.
+ */
+export function validateTransaction(input) {
+    if (!input.postings || input.postings.length < 2) {
+        throw new Error("Transaction must contain at least two postings.");
+    }
+    let debitTotal = 0;
+    let creditTotal = 0;
+    for (const p of input.postings) {
+        const debit = p.debit ?? 0;
+        const credit = p.credit ?? 0;
+        if (debit < 0 || credit < 0) {
+            throw new Error("debit and credit values must be non-negative.");
+        }
+        if (debit > 0 && credit > 0) {
+            throw new Error("A single posting cannot debit and credit at the same time.");
+        }
+        if (debit === 0 && credit === 0) {
+            throw new Error("Each posting must have either a debit or a credit.");
+        }
+        debitTotal += debit;
+        creditTotal += credit;
+    }
+    if (Math.abs(debitTotal - creditTotal) > TOLERANCE) {
+        throw new Error(`Transaction does not balance: debits ${debitTotal.toFixed(2)} vs credits ${creditTotal.toFixed(2)}.`);
+    }
+    return { ...input, id: input.id ?? `tx:${randomUUID()}` };
+}
+/**
+ * Insert-only counterpart to `recordTransaction`. The caller is responsible
+ * for opening a transaction (or for accepting partial writes). Expects an
+ * already-validated input from `validateTransaction`.
+ */
+export function insertTransactionRows(db, input) {
+    let merchantId = input.merchant_id ?? null;
+    if (!merchantId && input.merchant) {
+        merchantId = upsertMerchant(db, input.merchant).id;
+    }
+    db.prepare(`INSERT INTO transactions (id, date, description, merchant_id, raw_descriptor, source_file_id, source_page)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(input.id, input.date, input.description, merchantId, input.raw_descriptor ?? null, input.source_file_id ?? null, input.source_page ?? null);
+    const insertPosting = db.prepare(`INSERT INTO postings (id, transaction_id, account_id, debit, credit, currency, memo, pii_flag)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    for (const p of input.postings) {
+        insertPosting.run(`p:${randomUUID()}`, input.id, p.account_id, p.debit ?? 0, p.credit ?? 0, p.currency || "THB", p.memo ?? null, p.pii_flag ? 1 : 0);
+    }
+}
+export function updateTransaction(db, transactionId, fields) {
+    const sets = [];
+    const params = [];
+    if (fields.date !== undefined) {
+        sets.push("date = ?");
+        params.push(fields.date);
+    }
+    if (fields.description !== undefined) {
+        sets.push("description = ?");
+        params.push(fields.description);
+    }
+    if (fields.source_page !== undefined) {
+        sets.push("source_page = ?");
+        params.push(fields.source_page);
+    }
+    if (sets.length === 0)
+        return 0;
+    params.push(transactionId);
+    return db.prepare(`UPDATE transactions SET ${sets.join(", ")} WHERE id = ?`).run(...params).changes;
+}
+/**
+ * Safe single-posting edits only. Refuses changes to `debit`, `credit`, or `currency`
+ * because those would silently break the transaction's balance — to fix amounts the
+ * caller must delete the transaction and record a fresh one.
+ */
+export function updatePosting(db, postingId, fields) {
+    const sets = [];
+    const params = [];
+    if (fields.account_id !== undefined) {
+        sets.push("account_id = ?");
+        params.push(fields.account_id);
+    }
+    if (fields.memo !== undefined) {
+        sets.push("memo = ?");
+        params.push(fields.memo);
+    }
+    if (sets.length === 0)
+        return 0;
+    params.push(postingId);
+    return db.prepare(`UPDATE postings SET ${sets.join(", ")} WHERE id = ?`).run(...params).changes;
+}
+/**
+ * Delete a transaction. ON DELETE CASCADE on `postings.transaction_id` removes
+ * the postings automatically.
+ */
+export function deleteTransaction(db, transactionId) {
+    return db.prepare(`DELETE FROM transactions WHERE id = ?`).run(transactionId).changes;
+}
+/**
+ * Heuristic duplicate finder: group transactions by (rounded total debit) and check
+ * pairs whose date difference is ≤ toleranceDays. Returns groups with ≥2 members.
+ * Each transaction carries both account_ids (for follow-up tool calls) and
+ * account_names (for human-readable presentation to the user).
+ */
+export function findDuplicateTransactions(db, opts = {}) {
+    const toleranceDays = Math.max(0, Math.floor(opts.toleranceDays ?? 2));
+    const minAmount = opts.minAmount ?? 0;
+    const accountFilter = opts.accountId
+        ? `WHERE t.id IN (SELECT transaction_id FROM postings WHERE account_id = ?)`
+        : ``;
+    const params = opts.accountId ? [opts.accountId] : [];
+    const nameById = loadAccountNames(db);
+    const rows = db.prepare(`SELECT t.id, t.date, t.description,
+            COALESCE(SUM(p.debit), 0) AS amount,
+            GROUP_CONCAT(p.account_id) AS account_ids
+     FROM transactions t
+     LEFT JOIN postings p ON p.transaction_id = t.id
+     ${accountFilter}
+     GROUP BY t.id`).all(...params);
+    const candidates = rows
+        .filter(r => r.amount >= minAmount)
+        .map(r => {
+        const ids = (r.account_ids ?? "").split(",").filter(Boolean);
+        return {
+            id: r.id,
+            date: r.date,
+            description: r.description,
+            amount: Math.round(r.amount * 100) / 100,
+            account_ids: ids,
+            account_names: ids.map(id => nameById.get(id) ?? id),
+        };
+    });
+    const byAmount = new Map();
+    for (const e of candidates) {
+        const key = Math.round(e.amount * 100);
+        const arr = byAmount.get(key) ?? [];
+        arr.push(e);
+        byAmount.set(key, arr);
+    }
+    const groups = [];
+    for (const arr of byAmount.values()) {
+        if (arr.length < 2)
+            continue;
+        arr.sort((a, b) => a.date.localeCompare(b.date));
+        let current = [];
+        for (const e of arr) {
+            if (current.length === 0) {
+                current.push(e);
+                continue;
+            }
+            const last = current[current.length - 1];
+            if (dayDiff(last.date, e.date) <= toleranceDays) {
+                current.push(e);
+            }
+            else {
+                if (current.length >= 2)
+                    groups.push(current);
+                current = [e];
+            }
+        }
+        if (current.length >= 2)
+            groups.push(current);
+    }
+    return groups;
+}
+export function dayDiff(a, b) {
+    const aDate = Date.parse(a);
+    const bDate = Date.parse(b);
+    if (Number.isNaN(aDate) || Number.isNaN(bDate))
+        return Number.POSITIVE_INFINITY;
+    return Math.abs(Math.round((bDate - aDate) / 86_400_000));
+}
+/**
+ * Load all account id → name pairs into an in-memory map. Cheap on the small
+ * charts of accounts Plasalid deals with, and avoids GROUP_CONCAT join hacks
+ * (account names can contain commas which break a comma-separated concat, and
+ * SQLite's GROUP_CONCAT has no robust escape mechanism).
+ */
+function loadAccountNames(db) {
+    const map = new Map();
+    for (const row of db.prepare(`SELECT id, name FROM accounts`).all()) {
+        map.set(row.id, row.name);
+    }
+    return map;
+}
+/**
+ * Heuristic: surface pairs of transactions 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 function findCorrelatedTransactions(db, opts = {}) {
+    const toleranceDays = Math.max(0, Math.floor(opts.toleranceDays ?? 3));
+    const minAmount = opts.minAmount ?? 0;
+    const dateFilter = [];
+    const params = [];
+    if (opts.from) {
+        dateFilter.push("t.date >= ?");
+        params.push(opts.from);
+    }
+    if (opts.to) {
+        dateFilter.push("t.date <= ?");
+        params.push(opts.to);
+    }
+    const where = dateFilter.length ? `WHERE ${dateFilter.join(" AND ")}` : "";
+    const nameById = loadAccountNames(db);
+    const rows = db.prepare(`SELECT t.id, t.date, t.description,
+            COALESCE(SUM(p.debit), 0) AS amount,
+            COALESCE(MAX(p.currency), 'THB') AS currency,
+            GROUP_CONCAT(p.account_id) AS account_ids
+     FROM transactions t
+     LEFT JOIN postings p ON p.transaction_id = t.id
+     ${where}
+     GROUP BY t.id`).all(...params);
+    const candidates = rows
+        .filter(r => r.amount >= minAmount)
+        .map(r => {
+        const ids = (r.account_ids ?? "").split(",").filter(Boolean);
+        return {
+            id: r.id,
+            date: r.date,
+            description: r.description,
+            amount: Math.round(r.amount * 100) / 100,
+            currency: r.currency || "THB",
+            account_ids: ids,
+            account_names: ids.map(id => nameById.get(id) ?? id),
+        };
+    });
+    return correlatePairs(candidates, { toleranceDays });
+}
+/**
+ * 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 `findCorrelatedTransactions` and by the scan-time
+ * coordinator that runs over buffered, not-yet-committed transactions.
+ */
+export function correlatePairs(candidates, opts = {}) {
+    const toleranceDays = Math.max(0, Math.floor(opts.toleranceDays ?? 3));
+    const buckets = new Map();
+    for (const e of candidates) {
+        const key = `${Math.round(e.amount * 100)}|${e.currency}`;
+        const arr = buckets.get(key) ?? [];
+        arr.push(e);
+        buckets.set(key, arr);
+    }
+    const pairs = [];
+    for (const bucket of buckets.values()) {
+        if (bucket.length < 2)
+            continue;
+        bucket.sort((x, y) => x.date.localeCompare(y.date));
+        for (let i = 0; i < bucket.length; i++) {
+            for (let j = i + 1; j < bucket.length; j++) {
+                const a = bucket[i], b = bucket[j];
+                const gap = dayDiff(a.date, b.date);
+                if (gap > toleranceDays)
+                    break;
+                const overlap = a.account_ids.some(id => b.account_ids.includes(id));
+                if (overlap)
+                    continue;
+                pairs.push({
+                    amount: a.amount,
+                    currency: a.currency,
+                    day_gap: gap,
+                    a: { id: a.id, date: a.date, description: a.description, account_ids: a.account_ids, account_names: a.account_names },
+                    b: { id: b.id, date: b.date, description: b.description, account_ids: b.account_ids, account_names: b.account_names },
+                });
+            }
+        }
+    }
+    return pairs;
+}
+export function listPostings(db, opts = {}) {
+    const conditions = [];
+    const params = [];
+    if (opts.account_id) {
+        conditions.push("p.account_id = ?");
+        params.push(opts.account_id);
+    }
+    if (opts.from) {
+        conditions.push("t.date >= ?");
+        params.push(opts.from);
+    }
+    if (opts.to) {
+        conditions.push("t.date <= ?");
+        params.push(opts.to);
+    }
+    if (opts.q) {
+        conditions.push("(t.description LIKE ? OR p.memo LIKE ? OR m.canonical_name LIKE ?)");
+        params.push(`%${opts.q}%`, `%${opts.q}%`, `%${opts.q}%`);
+    }
+    const where = conditions.length ? `WHERE ${conditions.join(" AND ")}` : "";
+    const limit = Math.min(Math.max(opts.limit ?? 50, 1), 500);
+    return db.prepare(`SELECT p.id, p.transaction_id, p.account_id, p.debit, p.credit, p.currency, p.memo,
+            a.name AS account_name, a.type AS account_type,
+            t.date AS transaction_date, t.description AS transaction_description,
+            m.canonical_name AS merchant_name
+     FROM postings p
+     JOIN transactions t ON t.id = p.transaction_id
+     JOIN accounts a ON a.id = p.account_id
+     LEFT JOIN merchants m ON m.id = t.merchant_id
+     ${where}
+     ORDER BY t.date DESC, t.id DESC
+     LIMIT ?`).all(...params, limit);
+}