plasalid 0.4.1 → 0.5.1

package/dist/db/queries/account_balance.js

@@ -1,3 +1,13 @@
+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
@@ -12,13 +22,13 @@ export function getAccountBalances(db, opts = {}) {
     }
     const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
     const rows = db.prepare(`SELECT a.*,
-            COALESCE(SUM(jl.debit), 0)  AS sum_debit,
-            COALESCE(SUM(jl.credit), 0) AS sum_credit
+            COALESCE(SUM(p.debit), 0)  AS sum_debit,
+            COALESCE(SUM(p.credit), 0) AS sum_credit
      FROM accounts a
-     LEFT JOIN journal_lines jl ON jl.account_id = a.id
+     LEFT JOIN postings p ON p.account_id = a.id
      ${whereSql}
      GROUP BY a.id
-     ORDER BY a.type, a.name`).all(...params);
+     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;
@@ -40,12 +50,12 @@ export function getNetWorth(db) {
 }
 export function getPeriodTotals(db, from, to) {
     const row = db.prepare(`SELECT
-        COALESCE(SUM(CASE WHEN a.type = 'income'  THEN jl.credit - jl.debit ELSE 0 END), 0) AS income,
-        COALESCE(SUM(CASE WHEN a.type = 'expense' THEN jl.debit - jl.credit ELSE 0 END), 0) AS expenses
-     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.date BETWEEN ? AND ?`).get(from, to);
+        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) {
@@ -55,9 +65,145 @@ export function renameAccount(db, id, name) {
     return db.prepare(`UPDATE accounts SET name = ? WHERE id = ?`).run(name, id).changes;
 }
 /**
- * Re-point every journal line on `fromId` to `toId`, then delete the source
- * account. Wrapped in a transaction. Returns the number of journal lines moved.
- * Throws if either account doesn't exist.
+ * 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)
@@ -68,26 +214,74 @@ export function mergeAccounts(db, fromId, toId) {
     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 journal_lines SET account_id = ? WHERE account_id = ?`)
+            .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 journal_lines reference it. */
+/** 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 journal_lines WHERE account_id = ? LIMIT 1`)
+        .prepare(`SELECT 1 FROM postings WHERE account_id = ? LIMIT 1`)
         .get(id);
     if (inUse) {
-        throw new Error(`Account ${id} still has journal lines; merge it first.`);
+        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
@@ -109,12 +303,37 @@ export function findSimilarAccounts(db, threshold = 0.85) {
 export function findUnusedAccounts(db) {
     return db
         .prepare(`SELECT a.* FROM accounts a
-       LEFT JOIN journal_lines jl ON jl.account_id = a.id
-       WHERE jl.id IS NULL
+       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();
 }
-// ── helpers ────────────────────────────────────────────────────────────────
+/**
+ * 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;

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

@@ -0,0 +1,29 @@
+import type Database from "libsql";
+export type ActionCommand = "record" | "scan" | "review";
+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/concerns.d.ts

@@ -1,25 +1,27 @@
 import type Database from "libsql";
 export interface ConcernTarget {
-    entry_id: string | null;
+    transaction_id: string | null;
     account_id: string | null;
 }
 export interface RecordConcernInput extends ConcernTarget {
     file_id: string | null;
+    kind?: string | null;
     prompt: string;
     options?: string[];
 }
 export interface OpenConcernRow {
     id: string;
     file_id: string | null;
-    entry_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 concerns row and flip the `has_concern` boolean on whichever
- * target (entry / account) was named. Returns the new `cn:<uuid>` id.
+ * target (transaction / account) was named. Returns the new `cn:<uuid>` id.
  */
 export declare function recordConcern(db: Database.Database, input: RecordConcernInput): string;
 /**
@@ -29,19 +31,20 @@ export declare function recordConcern(db: Database.Database, input: RecordConcer
  */
 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.
+ * Look up the transaction/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
+ * Clear `has_concern` on the named transaction / 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;
+    transaction_id?: string;
     account_id?: string;
+    kind?: 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

@@ -1,13 +1,13 @@
 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.
+ * target (transaction / 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);
+    db.prepare(`INSERT INTO concerns (id, file_id, transaction_id, account_id, kind, prompt, options_json) VALUES (?, ?, ?, ?, ?, ?, ?)`).run(id, input.file_id, input.transaction_id, input.account_id, input.kind ?? null, input.prompt, input.options ? JSON.stringify(input.options) : null);
+    if (input.transaction_id) {
+        db.prepare(`UPDATE transactions SET has_concern = 1 WHERE id = ?`).run(input.transaction_id);
     }
     if (input.account_id) {
         db.prepare(`UPDATE accounts SET has_concern = 1 WHERE id = ?`).run(input.account_id);
@@ -28,26 +28,26 @@ export function resolveConcern(db, id, answer) {
     return target;
 }
 /**
- * Look up the entry/account a concern is attached to. Returns null when the
- * concern id doesn't exist.
+ * Look up the transaction/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 = ?`)
+        .prepare(`SELECT transaction_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
+ * Clear `has_concern` on the named transaction / 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) {
+    if (target.transaction_id) {
         const open = db
-            .prepare(`SELECT 1 FROM concerns WHERE entry_id = ? AND resolved_at IS NULL LIMIT 1`)
-            .get(target.entry_id);
+            .prepare(`SELECT 1 FROM concerns WHERE transaction_id = ? AND resolved_at IS NULL LIMIT 1`)
+            .get(target.transaction_id);
         if (!open)
-            db.prepare(`UPDATE journal_entries SET has_concern = 0 WHERE id = ?`).run(target.entry_id);
+            db.prepare(`UPDATE transactions SET has_concern = 0 WHERE id = ?`).run(target.transaction_id);
     }
     if (target.account_id) {
         const open = db
@@ -64,14 +64,18 @@ export function countOpenConcerns(db, scope = {}) {
         conditions.push("file_id = ?");
         params.push(scope.file_id);
     }
-    if (scope.entry_id) {
-        conditions.push("entry_id = ?");
-        params.push(scope.entry_id);
+    if (scope.transaction_id) {
+        conditions.push("transaction_id = ?");
+        params.push(scope.transaction_id);
     }
     if (scope.account_id) {
         conditions.push("account_id = ?");
         params.push(scope.account_id);
     }
+    if (scope.kind) {
+        conditions.push("kind = ?");
+        params.push(scope.kind);
+    }
     const row = db
         .prepare(`SELECT COUNT(*) AS n FROM concerns WHERE ${conditions.join(" AND ")}`)
         .get(...params);
@@ -79,7 +83,7 @@ export function countOpenConcerns(db, scope = {}) {
 }
 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
+    return db.prepare(`SELECT id, file_id, transaction_id, account_id, kind, prompt, options_json, created_at
      FROM concerns
      WHERE resolved_at IS NULL
      ORDER BY created_at ASC

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

@@ -103,6 +103,7 @@ export interface FindDuplicateEntriesOptions {
  */
 export declare function findDuplicateEntries(db: Database.Database, opts?: FindDuplicateEntriesOptions): DuplicateGroupEntry[][];
 export declare function dayDiff(a: string, b: string): number;
+/** Correlations */
 export interface CorrelatedEntryPair {
     amount: number;
     currency: string;

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

@@ -0,0 +1,42 @@
+import type Database from "libsql";
+export interface MerchantUpsertInput {
+    canonical_name: string;
+    alias?: string;
+    default_account_id?: string | null;
+}
+export interface MerchantRow {
+    id: string;
+    canonical_name: string;
+    default_account_id: string | null;
+    created_at: string;
+}
+export declare function normalizeDescriptor(raw: string): string;
+/**
+ * Upsert a merchant by canonical_name. Optionally upsert an alias and update
+ * the cached default_account_id. Idempotent: re-running with the same inputs
+ * does not duplicate rows. Designed to be called inside the same DB transaction
+ * as the posting writes so a transaction never lands without its merchant.
+ */
+export declare function upsertMerchant(db: Database.Database, input: MerchantUpsertInput): MerchantRow;
+export interface MerchantWithDefault {
+    merchant: MerchantRow;
+    default_account_id: string | null;
+}
+/**
+ * Resolve a raw PDF descriptor to a known merchant via the alias table.
+ * Returns null if no alias matches. The scanner uses this in its pre-resolution
+ * pass so the LLM can skip re-categorizing already-seen merchants.
+ */
+export declare function findMerchantByAlias(db: Database.Database, rawDescriptor: string): MerchantWithDefault | null;
+export interface ListMerchantsOptions {
+    withDefaultOnly?: boolean;
+    limit?: number;
+}
+export declare function listMerchants(db: Database.Database, opts?: ListMerchantsOptions): (MerchantRow & {
+    alias_count: number;
+})[];
+export declare function findMerchantById(db: Database.Database, id: string): MerchantRow | null;
+export declare function setMerchantDefaultAccount(db: Database.Database, merchantId: string, accountId: string): {
+    before: string | null;
+    after: string;
+};