plasalid 0.4.1 → 0.5.1

package/dist/cli/commands/scan.js

@@ -22,7 +22,13 @@ export async function runScanCommand(opts) {
     });
     renderScanSummary(summary);
 }
-// ── Ink-based events (TTY mode) ────────────────────────────────────────────
+function logDecryptProgress(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})`);
+}
+/** 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).
@@ -37,12 +43,7 @@ async function buildInkEvents(parallel) {
             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})`);
-        },
+        decryptProgress: logDecryptProgress,
         decryptDone: (e) => {
             console.log(chalk.dim(`Decrypted ${e.decrypted}, skipped ${e.skipped}, failed ${e.failed}.`));
             console.log("");
@@ -57,7 +58,7 @@ async function buildInkEvents(parallel) {
             type: "scan-end",
             fileName: e.fileName,
             status: e.status,
-            entries: e.entries,
+            transactions: e.transactions,
             concerns: e.concerns,
             error: e.error,
         }),
@@ -81,7 +82,7 @@ async function buildInkEvents(parallel) {
         },
     };
 }
-// ── Plain-text progress (TTY or piped, no ink yet) ─────────────────────────
+/** Plain-text progress (non-TTY or fallback) */
 function buildPlainTextEvents() {
     let decryptTotal = 0;
     // De-dupe scan-progress chatter: only print when the step text changes per file.
@@ -92,12 +93,7 @@ function buildPlainTextEvents() {
             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})`);
-        },
+        decryptProgress: logDecryptProgress,
         decryptDone: (e) => {
             if (decryptTotal === 0)
                 return;
@@ -116,7 +112,7 @@ function buildPlainTextEvents() {
         scanEnd: (e) => {
             lastStepByFile.delete(e.fileName);
             if (e.status === "scanned") {
-                console.log(`${chalk.green("✓")} ${e.fileName} ${chalk.dim(`(${e.entries} entries, ${e.concerns} concerns)`)}`);
+                console.log(`${chalk.green("✓")} ${e.fileName} ${chalk.dim(`(${e.transactions} transactions, ${e.concerns} concerns)`)}`);
             }
             else {
                 console.log(`${chalk.red("✗")} ${e.fileName} ${chalk.dim(`— ${e.error ?? "failed"}`)}`);
@@ -131,7 +127,7 @@ function buildPlainTextEvents() {
         },
     };
 }
-// ── Terse summary ──────────────────────────────────────────────────────────
+/** Terse summary */
 function renderScanSummary(summary) {
     console.log("");
     const headline = `Scanned ${summary.total} file(s) — ` +
@@ -144,12 +140,12 @@ function renderScanSummary(summary) {
         const label = d.relPath;
         switch (d.status) {
             case "scanned": {
-                const tag = chalk.dim(`${d.entries} entries${d.concerns > 0 ? ` · ${d.concerns} concerns` : ""}`);
+                const tag = chalk.dim(`${d.transactions} transactions${d.concerns > 0 ? ` · ${d.concerns} concerns` : ""}`);
                 console.log(`  ${chalk.green("✓")} ${label}  ${tag}`);
                 break;
             }
             case "replaced": {
-                const tag = chalk.dim(`${d.entries} entries${d.concerns > 0 ? ` · ${d.concerns} concerns` : ""} (replaces prior)`);
+                const tag = chalk.dim(`${d.transactions} transactions${d.concerns > 0 ? ` · ${d.concerns} concerns` : ""} (replaces prior)`);
                 console.log(`  ${chalk.cyan("↻")} ${label}  ${tag}`);
                 break;
             }

package/dist/cli/commands/status.js

@@ -1,22 +1,19 @@
 import chalk from "chalk";
 import { getDb } from "../../db/connection.js";
 import { getNetWorth, getPeriodTotals } from "../../db/queries/account_balance.js";
-import { formatCurrencyAmount } from "../../currency.js";
-function fmt(n) {
-    return formatCurrencyAmount(n, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
-}
+import { formatAmount } from "../../currency.js";
 export function showStatus() {
     const db = getDb();
     const nw = getNetWorth(db);
-    console.log(chalk.bold("Net worth: ") + fmt(nw.net_worth));
-    console.log(chalk.dim(`Assets ${fmt(nw.assets)} − Liabilities ${fmt(nw.liabilities)}`));
+    console.log(chalk.bold("Net worth: ") + formatAmount(nw.net_worth));
+    console.log(chalk.dim(`Assets ${formatAmount(nw.assets)} − Liabilities ${formatAmount(nw.liabilities)}`));
     const now = new Date();
     const monthStart = new Date(now.getFullYear(), now.getMonth(), 1).toISOString().slice(0, 10);
     const today = now.toISOString().slice(0, 10);
     const totals = getPeriodTotals(db, monthStart, today);
     console.log("");
     console.log(chalk.bold(`This month (${monthStart} → ${today})`));
-    console.log(`  Income: ${fmt(totals.income)}`);
-    console.log(`  Expenses: ${fmt(totals.expenses)}`);
-    console.log(`  Net: ${fmt(totals.income - totals.expenses)}`);
+    console.log(`  Income: ${formatAmount(totals.income)}`);
+    console.log(`  Expenses: ${formatAmount(totals.expenses)}`);
+    console.log(`  Net: ${formatAmount(totals.income - totals.expenses)}`);
 }

package/dist/cli/commands/transactions.js

@@ -1,15 +1,8 @@
 import chalk from "chalk";
 import { getDb } from "../../db/connection.js";
-import { listJournalLines } from "../../db/queries/journal.js";
-import { formatCurrencyAmount } from "../../currency.js";
-function fmt(n) {
-    return formatCurrencyAmount(n, { minimumFractionDigits: 2, maximumFractionDigits: 2 });
-}
-// eslint-disable-next-line no-control-regex
-const ANSI_RE = /\x1b\[[0-9;]*m/g;
-function visibleLength(s) {
-    return s.replace(ANSI_RE, "").length;
-}
+import { listPostings } from "../../db/queries/transactions.js";
+import { visibleLength } from "../format.js";
+import { formatAmount } from "../../currency.js";
 function truncateMiddle(s, max) {
     if (s.length <= max)
         return s;
@@ -22,71 +15,73 @@ function truncateMiddle(s, max) {
 }
 const ACCOUNT_CAP = 32;
 const MEMO_CAP = 40;
-function groupByEntry(lines) {
+function groupByTransaction(postings) {
     const groups = [];
     let current = null;
-    for (const l of lines) {
-        if (!current || current.entry_id !== l.entry_id) {
+    for (const p of postings) {
+        if (!current || current.transaction_id !== p.transaction_id) {
             current = {
-                entry_id: l.entry_id,
-                date: l.entry_date ?? "",
-                description: l.entry_description ?? "",
-                lines: [],
+                transaction_id: p.transaction_id,
+                date: p.transaction_date ?? "",
+                description: p.transaction_description ?? "",
+                merchant: p.merchant_name ?? null,
+                postings: [],
             };
             groups.push(current);
         }
-        current.lines.push(l);
+        current.postings.push(p);
     }
     return groups;
 }
 export function showTransactions(opts) {
     const db = getDb();
-    const lines = listJournalLines(db, {
+    const postings = listPostings(db, {
         account_id: opts.account,
         from: opts.from,
         to: opts.to,
         q: opts.query,
         limit: opts.limit ?? 100,
     });
-    if (lines.length === 0) {
-        console.log(chalk.yellow("No journal lines match those filters."));
+    if (postings.length === 0) {
+        console.log(chalk.yellow("No postings match those filters."));
         return;
     }
     const truncatedAccount = new Map();
     const truncatedMemo = new Map();
-    for (const l of lines) {
-        const acct = l.account_name ?? l.account_id;
-        truncatedAccount.set(l.id, truncateMiddle(acct, ACCOUNT_CAP));
-        if (l.memo)
-            truncatedMemo.set(l.id, truncateMiddle(l.memo, MEMO_CAP));
+    for (const p of postings) {
+        const acct = p.account_name ?? p.account_id;
+        truncatedAccount.set(p.id, truncateMiddle(acct, ACCOUNT_CAP));
+        if (p.memo)
+            truncatedMemo.set(p.id, truncateMiddle(p.memo, MEMO_CAP));
     }
-    const accountWidth = Math.max(...lines.map((l) => truncatedAccount.get(l.id).length));
-    const amountWidth = Math.max(...lines.map((l) => {
-        const side = l.debit > 0 ? "DR" : "CR";
-        const amt = l.debit > 0 ? l.debit : l.credit;
-        return `${side} ${fmt(amt)}`.length;
+    const accountWidth = Math.max(...postings.map((p) => truncatedAccount.get(p.id).length));
+    const amountWidth = Math.max(...postings.map((p) => {
+        const side = p.debit > 0 ? "DR" : "CR";
+        const amt = p.debit > 0 ? p.debit : p.credit;
+        return `${side} ${formatAmount(amt)}`.length;
     }));
     const cols = process.stdout.columns || 100;
     const descMax = Math.max(20, cols - 14);
-    const groups = groupByEntry(lines);
+    const groups = groupByTransaction(postings);
     for (const g of groups) {
         const desc = truncateMiddle(g.description, descMax);
-        console.log(`${chalk.dim(g.date)}  ${chalk.bold(desc)}`);
-        for (const l of g.lines) {
-            const acct = truncatedAccount.get(l.id);
+        const merchant = g.merchant ? chalk.green(`  · ${g.merchant}`) : "";
+        console.log(`${chalk.dim(g.date)}  ${chalk.bold(desc)}${merchant}`);
+        for (const p of g.postings) {
+            const acct = truncatedAccount.get(p.id);
             const acctPadded = acct + " ".repeat(accountWidth - acct.length);
-            const side = l.debit > 0 ? "DR" : "CR";
-            const amt = l.debit > 0 ? l.debit : l.credit;
-            const rawAmount = `${side} ${fmt(amt)}`;
-            const colored = l.debit > 0 ? chalk.cyan(rawAmount) : chalk.magenta(rawAmount);
+            const side = p.debit > 0 ? "DR" : "CR";
+            const amt = p.debit > 0 ? p.debit : p.credit;
+            const rawAmount = `${side} ${formatAmount(amt)}`;
+            const colored = p.debit > 0 ? chalk.cyan(rawAmount) : chalk.magenta(rawAmount);
             const amountPadded = " ".repeat(amountWidth - visibleLength(colored)) + colored;
-            const memo = truncatedMemo.get(l.id);
+            const memo = truncatedMemo.get(p.id);
             const memoStr = memo ? `    ${chalk.dim(memo)}` : "";
             console.log(`    ${acctPadded}  ${amountPadded}${memoStr}`);
         }
     }
     if (groups.length > 1) {
         console.log("");
-        console.log(chalk.dim(`  ${groups.length} entries · ${lines.length} lines`));
+        console.log(chalk.dim(`  ${groups.length} transactions · ${postings.length} postings`));
     }
 }

package/dist/cli/format.d.ts

@@ -1,3 +1,5 @@
+export declare const ANSI_RE: RegExp;
+export declare function visibleLength(s: string): number;
 export declare function formatDuration(ms: number): string;
 export declare function formatError(error: any, context?: string): string;
 export declare function banner(): string;

package/dist/cli/format.js

@@ -1,4 +1,9 @@
 import chalk from "chalk";
+// eslint-disable-next-line no-control-regex
+export const ANSI_RE = /\x1b\[[0-9;]*m/g;
+export function visibleLength(s) {
+    return s.replace(ANSI_RE, "").length;
+}
 export function formatDuration(ms) {
     const s = Math.floor(ms / 1000);
     if (s < 1)
@@ -49,10 +54,10 @@ export function formatError(error, context) {
     return `${chalk.red("✗")} ${context ? context + ": " : ""}${safeMsg}`;
 }
 export function banner() {
-    return chalk.bold("Plasalid") + chalk.dim("  ·  Talk to your money");
+    return chalk.bold("Plasalid") + chalk.dim("  ·  The Harness Layer for Personal Finance");
 }
 function stripAnsi(str) {
-    return str.replace(/\x1b\[[0-9;]*m/g, "");
+    return str.replace(ANSI_RE, "");
 }
 function box(label, lines) {
     const cols = process.stdout.columns || 100;

package/dist/cli/index.js

@@ -15,7 +15,7 @@ function ensureConfigured() {
 }
 program
     .name("plasalid")
-    .description("The local-first data layer for personal finance")
+    .description("The Harness Layer for Personal Finance — local-first")
     .version(version)
     .addHelpCommand(false)
     .showHelpAfterError(`Run ${chalk.cyan("plasalid --help")} for the list of commands.`)
@@ -62,7 +62,7 @@ program
 });
 program
     .command("transactions")
-    .description("List journal lines")
+    .description("List transactions and their postings")
     .option("-a, --account <id>", "Filter by account id")
     .option("--from <date>", "From date YYYY-MM-DD")
     .option("--to <date>", "To date YYYY-MM-DD")
@@ -79,6 +79,14 @@ program
         limit: Number(opts.limit),
     });
 });
+program
+    .command("record <utterance...>")
+    .description("Add a manual entry, account, or balance update from a plain-language line.")
+    .action(async (utteranceTokens) => {
+    ensureConfigured();
+    const { runRecordCommand } = await import("./commands/record.js");
+    await runRecordCommand({ utterance: utteranceTokens.join(" ") });
+});
 program
     .command("scan [regex...]")
     .description("Scan every new PDF under ~/.plasalid/data (optionally filtered by regex)")
@@ -104,7 +112,7 @@ program
 });
 program
     .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.")
+    .description("See the whole picture — connect related transactions across statements, surface recurring patterns, 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)")
@@ -121,7 +129,7 @@ program
 });
 program
     .command("revert <regex>")
-    .description("Delete scanned files matching <regex> and all their journal entries")
+    .description("Delete scanned files matching <regex> and all their transactions")
     .action(async (regex) => {
     ensureConfigured();
     const { runRevertCommand } = await import("./commands/revert.js");
@@ -141,7 +149,11 @@ program.configureHelp({
         { name: "status", desc: "Show net worth and this-month totals" },
         {
             name: "transactions",
-            desc: "List journal lines (filter by account/date/text)",
+            desc: "List transactions and their postings (filter by account/date/text)",
+        },
+        {
+            name: "record",
+            desc: "Add a manual transaction, account, balance, or merchant from a plain-language line",
         },
         {
             name: "scan",
@@ -149,11 +161,11 @@ program.configureHelp({
         },
         {
             name: "review",
-            desc: "Connect the dots and learn your recurring rhythms",
+            desc: "Cleanup uncategorized, connect duplicates, learn recurring patterns",
         },
         {
             name: "revert",
-            desc: "Delete scanned files matching <regex> and their journal entries",
+            desc: "Delete scanned files matching <regex> and their transactions",
         },
     ]),
 });

package/dist/cli/ink/hooks/useFooterText.js

@@ -1,4 +1,5 @@
 import { useEffect, useMemo, useState } from "react";
+import chalk from "chalk";
 const HINTS = [
     "try: what is my net worth?",
     "try: how much did I spend on food this month?",
@@ -33,7 +34,7 @@ export function useFooterText(db) {
                 scanStr = `scanned ${Math.floor(mins / 1440)}d ago`;
         }
         const idx = (hintIdx + tick) % HINTS.length;
-        const parts = ["Plasalid"];
+        const parts = [`${chalk.cyan("<><")} plasalid`];
         if (scanStr)
             parts.push(scanStr);
         parts.push(HINTS[idx]);

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

@@ -9,7 +9,7 @@ export type ScanDashboardEvent = {
     type: "scan-end";
     fileName: string;
     status: "scanned" | "failed";
-    entries: number;
+    transactions: number;
     concerns: number;
     error?: string;
 };

package/dist/cli/ink/scan_dashboard.js

@@ -41,7 +41,7 @@ export function ScanDashboard({ controller, totalFiles, parallel }) {
                         break;
                     case "scan-end":
                         next.set(event.fileName, event.status === "scanned"
-                            ? { kind: "done", entries: event.entries, concerns: event.concerns }
+                            ? { kind: "done", transactions: event.transactions, concerns: event.concerns }
                             : { kind: "failed", error: event.error ?? "failed" });
                         break;
                 }
@@ -56,7 +56,7 @@ function FileRow({ name, state }) {
         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: "green", children: "\u2713" }), " ", name, " ", _jsxs(Text, { dimColor: true, children: ["(", state.transactions, " transactions, ", 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/setup.d.ts

@@ -1,2 +1 @@
 export declare function runSetup(): Promise<void>;
-export declare function ensureConfigured(): void;

package/dist/cli/setup.js

@@ -2,7 +2,7 @@ import chalk from "chalk";
 import inquirer from "inquirer";
 import { existsSync, mkdirSync } from "fs";
 import { resolve } from "path";
-import { config, saveConfig, getConfigPath, isConfigured, getPlasalidDir, getDataDir, } from "../config.js";
+import { config, saveConfig, getConfigPath, getPlasalidDir, getDataDir, } from "../config.js";
 import { generateKey } from "../db/encryption.js";
 import { createContextTemplate } from "../ai/context.js";
 import { printLogo } from "./logo.js";
@@ -36,7 +36,7 @@ function printSummary(dataDir) {
     console.log("Next steps:");
     console.log(`  1. Run ${chalk.cyan("plasalid data")} to drop your bank/credit card statments PDFs in.`);
     console.log(`  2. Run ${chalk.cyan("plasalid scan")} to allow Plasalid to scan them.`);
-    console.log(`  3. Run ${chalk.cyan("plasalid")} to chat with your financial data.`);
+    console.log(`  3. Run ${chalk.cyan("plasalid")} to query your local ledger.`);
 }
 /**
  * Wraps inquirer's list prompt with a blank line above and below, and inserts
@@ -202,9 +202,3 @@ export async function runSetup() {
     const dataDir = finalizeDataDir(userName || "User");
     printSummary(dataDir);
 }
-export function ensureConfigured() {
-    if (!isConfigured()) {
-        console.error(chalk.red("Plasalid is not configured. Run `plasalid setup` first."));
-        process.exit(1);
-    }
-}

package/dist/currency.d.ts

@@ -3,4 +3,7 @@ export declare function getDisplayCurrency(): string;
 export declare function formatCurrencyAmount(amount: number, options?: {
     minimumFractionDigits?: number;
     maximumFractionDigits?: number;
+    currency?: string;
 }): string;
+export declare function formatAmount(amount: number, currency?: string): string;
+export declare function formatSignedAmount(amount: number, currency?: string): string;

package/dist/currency.js

@@ -9,7 +9,7 @@ export function getDisplayCurrency() {
 }
 export function formatCurrencyAmount(amount, options = {}) {
     const locale = getDisplayLocale();
-    const currency = getDisplayCurrency();
+    const currency = options.currency || getDisplayCurrency();
     return new Intl.NumberFormat(locale, {
         style: "currency",
         currency,
@@ -17,3 +17,14 @@ export function formatCurrencyAmount(amount, options = {}) {
         maximumFractionDigits: options.maximumFractionDigits,
     }).format(Math.abs(amount));
 }
+export function formatAmount(amount, currency) {
+    return formatCurrencyAmount(amount, {
+        minimumFractionDigits: 2,
+        maximumFractionDigits: 2,
+        currency,
+    });
+}
+export function formatSignedAmount(amount, currency) {
+    const body = formatAmount(amount, currency);
+    return amount < 0 ? `-${body}` : body;
+}

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

@@ -1,9 +1,11 @@
 import type Database from "libsql";
 export type AccountType = "asset" | "liability" | "income" | "expense" | "equity";
+export declare const TOP_LEVEL_TYPES: ReadonlyArray<AccountType>;
 export interface AccountRow {
     id: string;
     name: string;
     type: AccountType;
+    parent_id: string | null;
     subtype: string | null;
     bank_name: string | null;
     account_number_masked: string | null;
@@ -41,13 +43,79 @@ export declare function getPeriodTotals(db: Database.Database, from: string, to:
 export declare function findAccountById(db: Database.Database, id: string): AccountRow | null;
 export declare function renameAccount(db: Database.Database, id: string, name: string): number;
 /**
- * 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 declare function ensureTopLevelRoot(db: Database.Database, type: AccountType): void;
+/**
+ * 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 declare function ensureStructuralAccount(db: Database.Database, id: "expense:uncategorized" | "equity:adjustments" | "equity:opening-balance"): void;
+export interface CreateAccountInput {
+    id: string;
+    name: string;
+    type: AccountType;
+    parent_id?: string | null;
+    subtype?: string | null;
+    bank_name?: string | null;
+    account_number_masked?: string | null;
+    currency?: string;
+    due_day?: number | null;
+    statement_day?: number | null;
+    metadata?: Record<string, unknown> | null;
+}
+/**
+ * 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 declare function createAccount(db: Database.Database, input: CreateAccountInput): void;
+export interface UpdateAccountMetadataPatch {
+    due_day?: number | null;
+    statement_day?: number | null;
+    points_balance?: number | null;
+    account_number_masked?: string | null;
+    bank_name?: string | null;
+    metadata?: Record<string, unknown>;
+}
+export interface UpdateAccountMetadataResult {
+    before: Record<string, unknown>;
+    after: Record<string, unknown>;
+    changed: boolean;
+}
+/**
+ * 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 declare function updateAccountMetadata(db: Database.Database, id: string, patch: UpdateAccountMetadataPatch): UpdateAccountMetadataResult;
+/**
+ * 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 declare function mergeAccounts(db: Database.Database, fromId: string, toId: string): number;
-/** 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 declare function deleteAccount(db: Database.Database, id: string): void;
+/**
+ * Recursive CTE walk over `accounts.parent_id` returning the root and every
+ * descendant. Used by `getRollupBalance` and by hierarchical rendering paths.
+ */
+export declare function getAccountSubtree(db: Database.Database, rootId: string): AccountRow[];
+/**
+ * Sum the natural balance of every account in a subtree (root inclusive).
+ * Uses the same debit-normal / credit-normal convention as `getAccountBalances`.
+ */
+export declare function getRollupBalance(db: Database.Database, rootId: string): number;
 export interface SimilarAccountPair {
     a: AccountRow;
     b: AccountRow;
@@ -60,3 +128,14 @@ export interface SimilarAccountPair {
  */
 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;
+}
+/**
+ * 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 declare function findAccountsByFuzzyName(db: Database.Database, query: string, threshold?: number): FuzzyAccountMatch[];