plasalid 0.5.8 → 0.6.0

package/dist/db/queries/account-balance.js

@@ -0,0 +1,355 @@
+export const TOP_LEVEL_TYPES = [
+    "asset", "liability", "income", "expense", "equity",
+];
+const TYPE_ROOT_NAME = {
+    asset: "Assets",
+    liability: "Liabilities",
+    income: "Income",
+    expense: "Expenses",
+    equity: "Equity",
+};
+/**
+ * Balance per account using the natural debit/credit convention:
+ *   asset / expense  → debit-normal  → balance = debits − credits
+ *   liability / income / equity → credit-normal → balance = credits − debits
+ */
+export function getAccountBalances(db, opts = {}) {
+    const params = [];
+    const where = [];
+    if (opts.type) {
+        where.push("a.type = ?");
+        params.push(opts.type);
+    }
+    const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+    const rows = db.prepare(`SELECT a.*,
+            COALESCE(SUM(p.debit), 0)  AS sum_debit,
+            COALESCE(SUM(p.credit), 0) AS sum_credit
+     FROM accounts a
+     LEFT JOIN postings p ON p.account_id = a.id
+     ${whereSql}
+     GROUP BY a.id
+     ORDER BY a.type, a.id`).all(...params);
+    return rows.map(r => {
+        const debitNormal = r.type === "asset" || r.type === "expense";
+        const balance = debitNormal ? r.sum_debit - r.sum_credit : r.sum_credit - r.sum_debit;
+        const { sum_debit: _d, sum_credit: _c, ...account } = r;
+        return { ...account, balance };
+    });
+}
+export function getNetWorth(db) {
+    const balances = getAccountBalances(db);
+    let assets = 0;
+    let liabilities = 0;
+    for (const b of balances) {
+        if (b.type === "asset")
+            assets += b.balance;
+        else if (b.type === "liability")
+            liabilities += b.balance;
+    }
+    return { assets, liabilities, net_worth: assets - liabilities };
+}
+export function getPeriodTotals(db, from, to) {
+    const row = db.prepare(`SELECT
+        COALESCE(SUM(CASE WHEN a.type = 'income'  THEN p.credit - p.debit ELSE 0 END), 0) AS income,
+        COALESCE(SUM(CASE WHEN a.type = 'expense' THEN p.debit - p.credit ELSE 0 END), 0) AS expenses
+     FROM postings p
+     JOIN transactions t ON t.id = p.transaction_id
+     JOIN accounts a ON a.id = p.account_id
+     WHERE t.date BETWEEN ? AND ?`).get(from, to);
+    return { income: row.income, expenses: row.expenses };
+}
+export function findAccountById(db, id) {
+    return db.prepare(`SELECT * FROM accounts WHERE id = ?`).get(id) ?? null;
+}
+export function renameAccount(db, id, name) {
+    return db.prepare(`UPDATE accounts SET name = ? WHERE id = ?`).run(name, id).changes;
+}
+/**
+ * Idempotently insert one of the five top-level type roots (id = type name,
+ * parent_id = null). Called by `createAccount` when a child's declared parent
+ * is a missing top-level root.
+ */
+export function ensureTopLevelRoot(db, type) {
+    if (findAccountById(db, type))
+        return;
+    db.prepare(`INSERT INTO accounts (id, name, type, parent_id) VALUES (?, ?, ?, NULL)`).run(type, TYPE_ROOT_NAME[type], type);
+}
+/**
+ * Idempotently insert one of the structural accounts the system auto-creates:
+ *  - `expense:uncategorized`  (suspense for unclassifiable expense postings)
+ *  - `equity:adjustments`     (balancing side of `adjust_account_balance`)
+ *  - `equity:opening-balance` (starting state imports)
+ * The top-level root is bootstrapped first when missing.
+ */
+export function ensureStructuralAccount(db, id) {
+    if (findAccountById(db, id))
+        return;
+    const [type, leaf] = id.split(":");
+    ensureTopLevelRoot(db, type);
+    const name = leaf === "uncategorized" ? "Uncategorized"
+        : leaf === "adjustments" ? "Adjustments"
+            : "Opening Balance";
+    db.prepare(`INSERT INTO accounts (id, name, type, parent_id) VALUES (?, ?, ?, ?)`).run(id, name, type, type);
+}
+/**
+ * Insert a new account row. Enforces the three hierarchy invariants:
+ *   1. Top-level roots: parent_id null, id == type, one of TOP_LEVEL_TYPES.
+ *   2. Children: parent_id non-null, parent must exist (the top-level root is
+ *      auto-bootstrapped if missing — intermediate categories must be created
+ *      explicitly), parent.type must equal input.type, input.id must start with
+ *      parent.id + ':'.
+ *   3. UNIQUE on id (surfaces as code: 'ACCOUNT_EXISTS').
+ */
+export function createAccount(db, input) {
+    const bank = input.bank_name ? String(input.bank_name).toUpperCase() : null;
+    const parentId = input.parent_id ?? null;
+    if (parentId === null) {
+        if (!TOP_LEVEL_TYPES.includes(input.id)) {
+            throw new Error(`Account "${input.id}" has no parent_id; only top-level type roots may have a null parent (one of ${TOP_LEVEL_TYPES.join(", ")}).`);
+        }
+        if (input.id !== input.type) {
+            throw new Error(`Top-level root id "${input.id}" must equal its type "${input.type}".`);
+        }
+    }
+    else {
+        let parent = findAccountById(db, parentId);
+        if (!parent) {
+            if (TOP_LEVEL_TYPES.includes(parentId)) {
+                ensureTopLevelRoot(db, parentId);
+                parent = findAccountById(db, parentId);
+            }
+        }
+        if (!parent) {
+            throw new Error(`Parent account "${parentId}" does not exist; create it first.`);
+        }
+        if (parent.type !== input.type) {
+            throw new Error(`Account "${input.id}" type "${input.type}" does not match parent "${parentId}" type "${parent.type}".`);
+        }
+        if (!input.id.startsWith(parent.id + ":")) {
+            throw new Error(`Account id "${input.id}" must start with parent id "${parent.id}:".`);
+        }
+    }
+    try {
+        db.prepare(`INSERT INTO accounts (id, name, type, parent_id, subtype, bank_name, account_number_masked, currency, due_day, statement_day, metadata_json)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(input.id, input.name, input.type, parentId, input.subtype ?? null, bank, input.account_number_masked ?? null, input.currency ?? "THB", input.due_day ?? null, input.statement_day ?? null, input.metadata ? JSON.stringify(input.metadata) : null);
+    }
+    catch (err) {
+        if (String(err.message).includes("UNIQUE")) {
+            const dup = new Error(`Account "${input.id}" already exists.`);
+            dup.code = "ACCOUNT_EXISTS";
+            throw dup;
+        }
+        throw err;
+    }
+}
+/**
+ * Patch metadata fields on an account. Returns before/after snapshots of the
+ * touched fields so callers can persist a reversible audit record. `metadata`
+ * is shallow-merged into the existing metadata_json blob.
+ */
+export function updateAccountMetadata(db, id, patch) {
+    const current = findAccountById(db, id);
+    if (!current)
+        throw new Error(`Account "${id}" not found.`);
+    const sets = [];
+    const params = [];
+    const before = {};
+    const after = {};
+    if (patch.due_day !== undefined) {
+        sets.push("due_day = ?");
+        params.push(patch.due_day);
+        before.due_day = current.due_day;
+        after.due_day = patch.due_day;
+    }
+    if (patch.statement_day !== undefined) {
+        sets.push("statement_day = ?");
+        params.push(patch.statement_day);
+        before.statement_day = current.statement_day;
+        after.statement_day = patch.statement_day;
+    }
+    if (patch.points_balance !== undefined) {
+        sets.push("points_balance = ?");
+        params.push(patch.points_balance);
+        before.points_balance = current.points_balance;
+        after.points_balance = patch.points_balance;
+    }
+    if (patch.account_number_masked !== undefined) {
+        sets.push("account_number_masked = ?");
+        params.push(patch.account_number_masked);
+        before.account_number_masked = current.account_number_masked;
+        after.account_number_masked = patch.account_number_masked;
+    }
+    if (patch.bank_name !== undefined) {
+        const next = patch.bank_name == null ? null : String(patch.bank_name).toUpperCase();
+        sets.push("bank_name = ?");
+        params.push(next);
+        before.bank_name = current.bank_name;
+        after.bank_name = next;
+    }
+    if (patch.metadata) {
+        const existing = current.metadata_json ? JSON.parse(current.metadata_json) : {};
+        const merged = { ...existing, ...patch.metadata };
+        sets.push("metadata_json = ?");
+        params.push(JSON.stringify(merged));
+        before.metadata = existing;
+        after.metadata = merged;
+    }
+    if (sets.length === 0)
+        return { before, after, changed: false };
+    params.push(id);
+    db.prepare(`UPDATE accounts SET ${sets.join(", ")} WHERE id = ?`).run(...params);
+    return { before, after, changed: true };
+}
+/**
+ * Re-point every posting on `fromId` to `toId`, then delete the source account.
+ * Wrapped in a transaction. Refuses if the source still has children. Returns
+ * the number of postings moved.
+ */
+export function mergeAccounts(db, fromId, toId) {
+    if (fromId === toId)
+        throw new Error("Cannot merge an account into itself.");
+    const from = findAccountById(db, fromId);
+    if (!from)
+        throw new Error(`Source account ${fromId} not found.`);
+    const to = findAccountById(db, toId);
+    if (!to)
+        throw new Error(`Destination account ${toId} not found.`);
+    const childCount = db
+        .prepare(`SELECT COUNT(*) AS n FROM accounts WHERE parent_id = ?`)
+        .get(fromId);
+    if (childCount.n > 0) {
+        throw new Error(`Account ${fromId} has ${childCount.n} child account(s); merge or delete them first.`);
+    }
+    let moved = 0;
+    const tx = db.transaction(() => {
+        moved = db
+            .prepare(`UPDATE postings SET account_id = ? WHERE account_id = ?`)
+            .run(toId, fromId).changes;
+        db.prepare(`DELETE FROM accounts WHERE id = ?`).run(fromId);
+    });
+    tx();
+    return moved;
+}
+/** Delete an account only if no postings reference it AND it has no children. */
+export function deleteAccount(db, id) {
+    const inUse = db
+        .prepare(`SELECT 1 FROM postings WHERE account_id = ? LIMIT 1`)
+        .get(id);
+    if (inUse) {
+        throw new Error(`Account ${id} still has postings; merge it first.`);
+    }
+    const childCount = db
+        .prepare(`SELECT COUNT(*) AS n FROM accounts WHERE parent_id = ?`)
+        .get(id);
+    if (childCount.n > 0) {
+        throw new Error(`Account ${id} has ${childCount.n} child account(s); delete them first.`);
+    }
+    db.prepare(`DELETE FROM accounts WHERE id = ?`).run(id);
+}
+/**
+ * Recursive CTE walk over `accounts.parent_id` returning the root and every
+ * descendant. Used by `getRollupBalance` and by hierarchical rendering paths.
+ */
+export function getAccountSubtree(db, rootId) {
+    return db.prepare(`WITH RECURSIVE subtree AS (
+       SELECT * FROM accounts WHERE id = ?
+       UNION ALL
+       SELECT a.* FROM accounts a JOIN subtree s ON a.parent_id = s.id
+     )
+     SELECT * FROM subtree ORDER BY id`).all(rootId);
+}
+/**
+ * Sum the natural balance of every account in a subtree (root inclusive).
+ * Uses the same debit-normal / credit-normal convention as `getAccountBalances`.
+ */
+export function getRollupBalance(db, rootId) {
+    const subtree = getAccountSubtree(db, rootId);
+    if (subtree.length === 0)
+        return 0;
+    const ids = subtree.map(a => a.id);
+    const placeholders = ids.map(() => "?").join(",");
+    const row = db.prepare(`SELECT a.type,
+            COALESCE(SUM(p.debit), 0)  AS sum_debit,
+            COALESCE(SUM(p.credit), 0) AS sum_credit
+     FROM accounts a
+     LEFT JOIN postings p ON p.account_id = a.id
+     WHERE a.id IN (${placeholders})
+     GROUP BY a.type`).all(...ids);
+    let total = 0;
+    for (const r of row) {
+        const debitNormal = r.type === "asset" || r.type === "expense";
+        total += debitNormal ? r.sum_debit - r.sum_credit : r.sum_credit - r.sum_debit;
+    }
+    return total;
+}
+/**
+ * Pairwise Levenshtein similarity over `accounts.name`. Returns pairs above the
+ * threshold (0–1, where 1 = identical), sorted highest first. Quadratic in the
+ * number of accounts — fine for the small N a personal chart of accounts holds.
+ */
+export function findSimilarAccounts(db, threshold = 0.85) {
+    const rows = db.prepare(`SELECT * FROM accounts ORDER BY name`).all();
+    const pairs = [];
+    for (let i = 0; i < rows.length; i++) {
+        for (let j = i + 1; j < rows.length; j++) {
+            const sim = similarity(rows[i].name.toLowerCase(), rows[j].name.toLowerCase());
+            if (sim >= threshold)
+                pairs.push({ a: rows[i], b: rows[j], similarity: Math.round(sim * 1000) / 1000 });
+        }
+    }
+    pairs.sort((x, y) => y.similarity - x.similarity);
+    return pairs;
+}
+/**
+ * Rank the chart of accounts by name similarity to a free-text query. Returns
+ * matches at or above `threshold`, highest first. Bonus weight when the query
+ * is a substring of the name so "ttb saving" still finds "TTB Savings ••1234"
+ * even though pure Levenshtein on the full strings is mediocre.
+ */
+export function findAccountsByFuzzyName(db, query, threshold = 0.5) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const rows = db.prepare(`SELECT * FROM accounts ORDER BY name`).all();
+    const out = [];
+    for (const row of rows) {
+        const name = row.name.toLowerCase();
+        let score = similarity(q, name);
+        if (name.includes(q) || q.includes(name))
+            score = Math.max(score, 0.85);
+        if (score >= threshold) {
+            out.push({ account: row, similarity: Math.round(score * 1000) / 1000 });
+        }
+    }
+    out.sort((a, b) => b.similarity - a.similarity);
+    return out;
+}
+function similarity(a, b) {
+    if (a === b)
+        return 1;
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const dist = levenshtein(a, b);
+    return 1 - dist / Math.max(a.length, b.length);
+}
+function levenshtein(a, b) {
+    const m = a.length, n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    const prev = new Array(n + 1);
+    const curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a.charCodeAt(i - 1) === b.charCodeAt(j - 1) ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        for (let j = 0; j <= n; j++)
+            prev[j] = curr[j];
+    }
+    return prev[n];
+}

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

@@ -127,7 +127,6 @@ export interface SimilarAccountPair {
  * number of accounts — fine for the small N a personal chart of accounts holds.
  */
 export declare function findSimilarAccounts(db: Database.Database, threshold?: number): SimilarAccountPair[];
-export declare function findUnusedAccounts(db: Database.Database): AccountRow[];
 export interface FuzzyAccountMatch {
     account: AccountRow;
     similarity: number;

package/dist/db/queries/account_balance.js

@@ -300,16 +300,6 @@ export function findSimilarAccounts(db, threshold = 0.85) {
     pairs.sort((x, y) => y.similarity - x.similarity);
     return pairs;
 }
-export function findUnusedAccounts(db) {
-    return db
-        .prepare(`SELECT a.* FROM accounts a
-       LEFT JOIN postings p ON p.account_id = a.id
-       WHERE p.id IS NULL
-         AND NOT EXISTS (SELECT 1 FROM accounts c WHERE c.parent_id = a.id)
-         AND a.id NOT IN ('asset','liability','income','expense','equity')
-       ORDER BY a.name`)
-        .all();
-}
 /**
  * Rank the chart of accounts by name similarity to a free-text query. Returns
  * matches at or above `threshold`, highest first. Bonus weight when the query

package/dist/db/queries/action-log.d.ts

@@ -0,0 +1,29 @@
+import type Database from "libsql";
+export type ActionCommand = "record" | "scan" | "resolve";
+export type ActionType = "create_account" | "update_account_metadata" | "record_transaction" | "adjust_balance" | "create_merchant" | "update_merchant_default";
+export interface ActionLogInput {
+    correlation_id: string;
+    command: ActionCommand;
+    user_input?: string | null;
+    action_type: ActionType;
+    target_id: string;
+    payload: Record<string, unknown>;
+}
+export interface ActionLogRow {
+    id: string;
+    correlation_id: string;
+    command: ActionCommand;
+    user_input: string | null;
+    action_type: ActionType;
+    target_id: string;
+    payload_json: string;
+    created_at: string;
+    reverted_at: string | null;
+}
+export declare function appendAction(db: Database.Database, input: ActionLogInput): string;
+export interface ListActionsOptions {
+    limit?: number;
+    command?: ActionCommand;
+    correlationId?: string;
+}
+export declare function listActions(db: Database.Database, opts?: ListActionsOptions): ActionLogRow[];

package/dist/db/queries/action-log.js

@@ -0,0 +1,27 @@
+import { randomUUID } from "crypto";
+export function appendAction(db, input) {
+    const id = `al:${randomUUID()}`;
+    db.prepare(`INSERT INTO action_log
+       (id, correlation_id, command, user_input, action_type, target_id, payload_json)
+     VALUES (?, ?, ?, ?, ?, ?, ?)`).run(id, input.correlation_id, input.command, input.user_input ?? null, input.action_type, input.target_id, JSON.stringify(input.payload));
+    return id;
+}
+export function listActions(db, opts = {}) {
+    const conds = [];
+    const params = [];
+    if (opts.command) {
+        conds.push("command = ?");
+        params.push(opts.command);
+    }
+    if (opts.correlationId) {
+        conds.push("correlation_id = ?");
+        params.push(opts.correlationId);
+    }
+    const where = conds.length ? `WHERE ${conds.join(" AND ")}` : "";
+    const limit = Math.min(Math.max(opts.limit ?? 100, 1), 1000);
+    return db
+        .prepare(`SELECT id, correlation_id, command, user_input, action_type, target_id,
+              payload_json, created_at, reverted_at
+       FROM action_log ${where} ORDER BY rowid ASC LIMIT ?`)
+        .all(...params, limit);
+}

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

@@ -1,5 +1,5 @@
 import type Database from "libsql";
-export type ActionCommand = "record" | "scan" | "review";
+export type ActionCommand = "record" | "scan" | "resolve";
 export type ActionType = "create_account" | "update_account_metadata" | "record_transaction" | "adjust_balance" | "create_merchant" | "update_merchant_default";
 export interface ActionLogInput {
     correlation_id: string;

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

@@ -48,3 +48,13 @@ export interface CountOpenConcernsScope {
 }
 export declare function countOpenConcerns(db: Database.Database, scope?: CountOpenConcernsScope): number;
 export declare function listOpenConcerns(db: Database.Database, limit?: number): OpenConcernRow[];
+/**
+ * Open concerns filtered by `kind`, ordered by the position of the kind in the
+ * input array (priority) then by created_at. Pass `["uncategorized","duplicate"]`
+ * to drain uncategorized concerns before duplicates.
+ *
+ * `kind` is free-text TEXT in the schema; canonical values used by built-ins:
+ *   uncategorized, duplicate, correlation, recurrence_candidate,
+ *   similar_accounts, file_password
+ */
+export declare function listOpenConcernsByKind(db: Database.Database, kinds: string[], limit?: number): OpenConcernRow[];

package/dist/db/queries/concerns.js

@@ -89,3 +89,24 @@ export function listOpenConcerns(db, limit = 50) {
      ORDER BY created_at ASC
      LIMIT ?`).all(capped);
 }
+/**
+ * Open concerns filtered by `kind`, ordered by the position of the kind in the
+ * input array (priority) then by created_at. Pass `["uncategorized","duplicate"]`
+ * to drain uncategorized concerns before duplicates.
+ *
+ * `kind` is free-text TEXT in the schema; canonical values used by built-ins:
+ *   uncategorized, duplicate, correlation, recurrence_candidate,
+ *   similar_accounts, file_password
+ */
+export function listOpenConcernsByKind(db, kinds, limit = 50) {
+    if (kinds.length === 0)
+        return [];
+    const capped = Math.min(Math.max(limit, 1), 200);
+    const placeholders = kinds.map(() => "?").join(",");
+    const cases = kinds.map((_, i) => `WHEN ? THEN ${i}`).join(" ");
+    return db.prepare(`SELECT id, file_id, transaction_id, account_id, kind, prompt, options_json, created_at
+     FROM concerns
+     WHERE resolved_at IS NULL AND kind IN (${placeholders})
+     ORDER BY CASE kind ${cases} ELSE ${kinds.length} END, created_at ASC
+     LIMIT ?`).all(...kinds, ...kinds, capped);
+}

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

@@ -9,7 +9,7 @@ export interface PostingInput {
     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. */
+    /** Optional pre-assigned id. Used by the buffered-write path so unknowns recorded mid-scan can reference the transaction before commit. */
     id?: string;
     date: string;
     description: string;
@@ -90,6 +90,8 @@ export interface DuplicateGroupTransaction {
     date: string;
     description: string;
     amount: number;
+    source_file_id: string | null;
+    merchant_id: string | null;
     account_ids: string[];
     account_names: string[];
 }
@@ -143,25 +145,4 @@ export interface FindCorrelatedTransactionsOptions {
  * 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

@@ -123,7 +123,7 @@ export function findDuplicateTransactions(db, opts = {}) {
         : ``;
     const params = opts.accountId ? [opts.accountId] : [];
     const nameById = loadAccountNames(db);
-    const rows = db.prepare(`SELECT t.id, t.date, t.description,
+    const rows = db.prepare(`SELECT t.id, t.date, t.description, t.source_file_id, t.merchant_id,
             COALESCE(SUM(p.debit), 0) AS amount,
             GROUP_CONCAT(p.account_id) AS account_ids
      FROM transactions t
@@ -139,6 +139,8 @@ export function findDuplicateTransactions(db, opts = {}) {
             date: r.date,
             description: r.description,
             amount: Math.round(r.amount * 100) / 100,
+            source_file_id: r.source_file_id,
+            merchant_id: r.merchant_id,
             account_ids: ids,
             account_names: ids.map(id => nameById.get(id) ?? id),
         };
@@ -246,11 +248,8 @@ export function findCorrelatedTransactions(db, opts = {}) {
  * 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 = {}) {
+function correlatePairs(candidates, opts = {}) {
     const toleranceDays = Math.max(0, Math.floor(opts.toleranceDays ?? 3));
     const buckets = new Map();
     for (const e of candidates) {

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

@@ -0,0 +1,62 @@
+import type Database from "libsql";
+export interface UnknownTarget {
+    transaction_id: string | null;
+    account_id: string | null;
+}
+export interface RecordUnknownInput extends UnknownTarget {
+    file_id: string | null;
+    kind?: string | null;
+    prompt: string;
+    options?: string[];
+}
+export interface OpenUnknownRow {
+    id: string;
+    file_id: string | null;
+    transaction_id: string | null;
+    account_id: string | null;
+    kind: string | null;
+    prompt: string;
+    options_json: string | null;
+    created_at: string;
+}
+/**
+ * Insert a new unknowns row and flip the `has_unknown` boolean on whichever
+ * target (transaction / account) was named. Returns the new id. The id keeps
+ * the historical `cn:` prefix — it's opaque and nothing else references it,
+ * so the prefix is a no-op detail.
+ */
+export declare function recordUnknown(db: Database.Database, input: RecordUnknownInput): string;
+/**
+ * Mark an existing unknown as resolved with the user's answer and, if no other
+ * open unknowns reference the same target, clear the target's `has_unknown`
+ * flag. Returns the unknown's target so callers can log or react.
+ */
+export declare function resolveUnknown(db: Database.Database, id: string, answer: string): UnknownTarget | null;
+/**
+ * Look up the transaction/account an unknown is attached to. Returns null when
+ * the unknown id doesn't exist.
+ */
+export declare function getUnknownTarget(db: Database.Database, id: string): UnknownTarget | null;
+/**
+ * Clear `has_unknown` on the named transaction / account if no other open
+ * unknowns still reference it. Safe to call after any resolution; idempotent.
+ */
+export declare function maybeClearHasUnknownFlags(db: Database.Database, target: UnknownTarget): void;
+export interface CountOpenUnknownsScope {
+    file_id?: string;
+    transaction_id?: string;
+    account_id?: string;
+    kind?: string;
+}
+export declare function countOpenUnknowns(db: Database.Database, scope?: CountOpenUnknownsScope): number;
+export declare function listOpenUnknowns(db: Database.Database, limit?: number): OpenUnknownRow[];
+/**
+ * Open unknowns filtered by `kind`, ordered by the position of the kind in the
+ * input array (priority) then by created_at. Pass `["uncategorized","duplicate"]`
+ * to drain uncategorized rows before duplicates.
+ *
+ * `kind` is free-text TEXT in the schema; canonical values used by built-ins:
+ *   uncategorized, duplicate, correlation, recurrence_candidate,
+ *   similar_accounts, file_password
+ */
+export declare function listOpenUnknownsByKind(db: Database.Database, kinds: string[], limit?: number): OpenUnknownRow[];