@morroc/open-ledger 0.14.1

package/datasets/institutions/th.json

@@ -0,0 +1,99 @@
+{
+  "country": "TH",
+  "institutions": [
+    { "code": "KBANK", "label": "Kasikornbank", "kind": "bank" },
+    { "code": "SCB", "label": "Siam Commercial Bank", "kind": "bank" },
+    { "code": "BBL", "label": "Bangkok Bank", "kind": "bank" },
+    { "code": "KTB", "label": "Krungthai Bank", "kind": "bank", "notes": "State-owned." },
+    { "code": "BAY", "label": "Krungsri (Bank of Ayudhya)", "kind": "bank" },
+    { "code": "TTB", "label": "TMBThanachart Bank", "kind": "bank", "notes": "Result of TMB + Thanachart merger." },
+    { "code": "UOB-TH", "label": "UOB Thailand", "kind": "bank", "notes": "Absorbed Citi Thailand's consumer banking (incl. cards) in Nov 2022." },
+    { "code": "CIMB-TH", "label": "CIMB Thai", "kind": "bank" },
+    { "code": "GHB", "label": "Government Housing Bank", "kind": "bank", "notes": "State-owned, mortgage focus." },
+    { "code": "GSB", "label": "Government Savings Bank", "kind": "bank", "notes": "State-owned." },
+    { "code": "LH-BANK", "label": "Land and Houses Bank", "kind": "bank" },
+    { "code": "KKP", "label": "Kiatnakin Phatra Bank", "kind": "bank", "notes": "Merged 2020 from KK + Phatra." },
+    { "code": "TISCO", "label": "TISCO Bank", "kind": "bank" },
+    { "code": "IBT", "label": "Islamic Bank of Thailand", "kind": "bank", "notes": "State-owned; serves all customers." },
+    { "code": "ICBC-TH", "label": "ICBC (Thai)", "kind": "bank", "notes": "Subsidiary of ICBC China." },
+    { "code": "BAAC", "label": "Bank for Agriculture and Agricultural Cooperatives", "kind": "bank", "notes": "State-owned, rural finance." },
+
+    { "code": "KTC", "label": "Krungthai Card", "kind": "card_issuer", "notes": "Listed subsidiary of KTB." },
+    { "code": "AEON", "label": "AEON Thana Sinsap", "kind": "card_issuer" },
+    { "code": "FIRSTCHOICE", "label": "Krungsri First Choice", "kind": "card_issuer" },
+    { "code": "CITI-TH", "label": "Citibank Thailand", "kind": "card_issuer", "notes": "Consumer cards migrated to UOB-TH in Nov 2022; only historical statements still reference Citi." },
+    { "code": "AMEX-TH", "label": "American Express Thailand", "kind": "card_issuer" },
+    { "code": "CARDX", "label": "CardX", "kind": "card_issuer", "notes": "SCB X consumer-card spinoff; issues cards previously branded SCB." },
+    { "code": "DINERS", "label": "Diners Club Thailand", "kind": "card_issuer" },
+    { "code": "UOB-TH", "label": "UOB Thailand (Cards)", "kind": "card_issuer", "notes": "Same legal entity as the bank UOB-TH; now issues both its own card line (UOB Yolo, UOB Premier) and the migrated Citi consumer cards." },
+
+    { "code": "TRUEMONEY", "label": "TrueMoney Wallet", "kind": "wallet" },
+    { "code": "LINEPAY", "label": "Rabbit LINE Pay", "kind": "wallet" },
+    { "code": "SHOPEEPAY", "label": "ShopeePay", "kind": "wallet" },
+    { "code": "GRABPAY", "label": "GrabPay (Thailand)", "kind": "wallet" },
+    { "code": "DOLFIN", "label": "Dolfin Wallet", "kind": "wallet", "notes": "Central Group + JD.com joint venture." },
+    { "code": "MPAY", "label": "mPay", "kind": "wallet", "notes": "AIS-operated." },
+    { "code": "PAOTANG", "label": "Paotang", "kind": "wallet", "notes": "Krungthai-operated; government-benefits and tax e-wallet." },
+
+    { "code": "PROMPTPAY", "label": "PromptPay", "kind": "payment_rail", "notes": "National 24/7 interbank rail; appears on payment slips, not an issuer." },
+
+    { "code": "INNOVESTX", "label": "InnovestX Securities", "kind": "broker", "notes": "Former SCBS; SCBX subsidiary." },
+    { "code": "BLS", "label": "Bualuang Securities", "kind": "broker", "notes": "BBL subsidiary." },
+    { "code": "KS", "label": "Kasikorn Securities", "kind": "broker", "notes": "KBANK subsidiary." },
+    { "code": "KGI-TH", "label": "KGI Securities (Thailand)", "kind": "broker" },
+    { "code": "MAYBANK-SEC", "label": "Maybank Securities (Thailand)", "kind": "broker" },
+    { "code": "ASP", "label": "Asia Plus Securities", "kind": "broker" },
+    { "code": "TISCO-SEC", "label": "TISCO Securities", "kind": "broker" },
+    { "code": "KSS", "label": "Krungsri Securities", "kind": "broker", "notes": "BAY subsidiary." },
+    { "code": "KKPS", "label": "Kiatnakin Phatra Securities", "kind": "broker", "notes": "KKP subsidiary." },
+    { "code": "LH-SEC", "label": "Land and Houses Securities", "kind": "broker" },
+    { "code": "FINANSIA", "label": "Finansia Syrus Securities", "kind": "broker" },
+    { "code": "YUANTA-TH", "label": "Yuanta Securities (Thailand)", "kind": "broker" },
+    { "code": "DBSVICKERS", "label": "DBS Vickers Securities (Thailand)", "kind": "broker" },
+    { "code": "KTBST", "label": "Krungthai Xspring Securities", "kind": "broker", "notes": "Formerly KTBST; KTB-affiliated." },
+
+    { "code": "BITKUB", "label": "Bitkub Exchange", "kind": "crypto_exchange", "notes": "SEC-licensed; dominant market share." },
+    { "code": "UPBIT-TH", "label": "Upbit Thailand", "kind": "crypto_exchange", "notes": "SEC-licensed; subsidiary of South Korean Upbit." },
+    { "code": "ORBIX", "label": "Orbix Trade", "kind": "crypto_exchange", "notes": "Former Satang Pro; rebranded under KBank ownership." },
+    { "code": "GULF-BINANCE", "label": "Binance Thailand (Gulf Binance)", "kind": "crypto_exchange", "notes": "Binance + Gulf Innova JV; SEC-licensed." },
+    { "code": "KUCOIN-TH", "label": "KuCoin Thailand", "kind": "crypto_exchange", "notes": "Former ERX; rebranded 2025 after KuCoin acquisition." },
+    { "code": "WAANX", "label": "WaanX", "kind": "crypto_exchange", "notes": "SEC-licensed." },
+    { "code": "TDX", "label": "Thai Digital Assets Exchange", "kind": "crypto_exchange", "notes": "SET Group subsidiary." },
+    { "code": "GMO-Z-EX", "label": "Z.com EX (GMO-Z.com)", "kind": "crypto_exchange", "notes": "Japanese GMO subsidiary." },
+    { "code": "ZIPMEX", "label": "Zipmex", "kind": "crypto_exchange", "notes": "Defunct since Nov 2023; statements only appear in historical files." },
+
+    { "code": "AIA-TH", "label": "AIA Thailand", "kind": "insurer", "notes": "Life; market leader." },
+    { "code": "MUANG-THAI-LIFE", "label": "Muang Thai Life Insurance", "kind": "insurer", "notes": "Life." },
+    { "code": "THAI-LIFE", "label": "Thai Life Insurance", "kind": "insurer", "notes": "Life; listed (TLI)." },
+    { "code": "FWD-TH", "label": "FWD Thailand", "kind": "insurer", "notes": "Life." },
+    { "code": "ALLIANZ-AYUDHYA-LIFE", "label": "Allianz Ayudhya Assurance", "kind": "insurer", "notes": "Life; Allianz + BAY JV." },
+    { "code": "KTAXA", "label": "Krungthai-AXA Life", "kind": "insurer", "notes": "Life; KTB + AXA JV." },
+    { "code": "BANGKOK-LIFE", "label": "Bangkok Life Assurance", "kind": "insurer", "notes": "Life." },
+    { "code": "CHUBB-SAMAGGI", "label": "Chubb Samaggi Insurance", "kind": "insurer", "notes": "Life and non-life." },
+    { "code": "GENERALI-TH", "label": "Generali Thailand", "kind": "insurer", "notes": "Life." },
+    { "code": "DHIPAYA", "label": "Dhipaya Insurance", "kind": "insurer", "notes": "Non-life." },
+    { "code": "BANGKOK-INS", "label": "Bangkok Insurance", "kind": "insurer", "notes": "Non-life." },
+    { "code": "ALLIANZ-AYUDHYA-GENERAL", "label": "Allianz Ayudhya General Insurance", "kind": "insurer", "notes": "Non-life." },
+    { "code": "VIRIYAH", "label": "Viriyah Insurance", "kind": "insurer", "notes": "Non-life; #1 motor insurer." },
+    { "code": "TOKIO-MARINE", "label": "Tokio Marine (Thailand)", "kind": "insurer", "notes": "Non-life." },
+
+    { "code": "REVDEPT", "label": "Revenue Department (กรมสรรพากร)", "kind": "gov", "notes": "Income tax, VAT, excise." },
+    { "code": "SSO", "label": "Social Security Office (สำนักงานประกันสังคม)", "kind": "gov", "notes": "Employee + self-employed social security contributions." },
+    { "code": "BOT", "label": "Bank of Thailand", "kind": "gov", "notes": "Central bank; rarely on consumer statements outside of regulatory letters." },
+    { "code": "MOF", "label": "Ministry of Finance", "kind": "gov" },
+    { "code": "LDT", "label": "Department of Lands (กรมที่ดิน)", "kind": "gov", "notes": "Land registration, property tax." },
+    { "code": "CUSTOMS", "label": "Customs Department (กรมศุลกากร)", "kind": "gov", "notes": "Import/export duties." },
+
+    { "code": "AIS", "label": "Advanced Info Service (AIS)", "kind": "telco" },
+    { "code": "TRUE-CORP", "label": "True Corporation", "kind": "telco", "notes": "Merged entity of True + dtac since March 2023." },
+    { "code": "TRUEMOVE", "label": "TrueMove H", "kind": "telco", "notes": "Brand retained under TRUE-CORP per NBTC ruling." },
+    { "code": "DTAC", "label": "dtac", "kind": "telco", "notes": "Brand retained under TRUE-CORP per NBTC ruling." },
+    { "code": "NT", "label": "National Telecom (NT)", "kind": "telco", "notes": "Former TOT; state-owned, minimal consumer presence." },
+
+    { "code": "MEA", "label": "Metropolitan Electricity Authority (กฟน.)", "kind": "utility", "notes": "Electricity for Bangkok, Nonthaburi, Samut Prakan." },
+    { "code": "PEA", "label": "Provincial Electricity Authority (กฟภ.)", "kind": "utility", "notes": "Electricity for the rest of Thailand outside MEA's area." },
+    { "code": "MWA", "label": "Metropolitan Waterworks Authority (กปน.)", "kind": "utility", "notes": "Water for Bangkok, Nonthaburi, Samut Prakan." },
+    { "code": "PWA", "label": "Provincial Waterworks Authority (กปภ.)", "kind": "utility", "notes": "Water for the rest of Thailand." },
+    { "code": "EGAT", "label": "Electricity Generating Authority of Thailand (กฟผ.)", "kind": "utility", "notes": "Power generation; rarely appears on consumer bills directly." }
+  ]
+}

package/datasets/institutions/us.json

@@ -0,0 +1,70 @@
+{
+  "country": "US",
+  "institutions": [
+    { "code": "CHASE", "label": "JPMorgan Chase", "kind": "bank" },
+    { "code": "BOFA", "label": "Bank of America", "kind": "bank" },
+    { "code": "WELLSFARGO", "label": "Wells Fargo", "kind": "bank" },
+    { "code": "CITI-US", "label": "Citibank", "kind": "bank" },
+    { "code": "USBANK", "label": "U.S. Bank", "kind": "bank" },
+    { "code": "PNC", "label": "PNC Bank", "kind": "bank" },
+    { "code": "TRUIST", "label": "Truist", "kind": "bank", "notes": "BB&T + SunTrust merger (2019)." },
+    { "code": "CAPITALONE", "label": "Capital One", "kind": "bank", "notes": "Also a major card issuer; acquired Discover in 2025." },
+    { "code": "TD-US", "label": "TD Bank (US)", "kind": "bank" },
+    { "code": "ALLY", "label": "Ally Bank", "kind": "bank", "notes": "Online-only." },
+    { "code": "MARCUS", "label": "Marcus by Goldman Sachs", "kind": "bank", "notes": "Online savings; no checking." },
+    { "code": "SCHWAB-BANK", "label": "Charles Schwab Bank", "kind": "bank", "notes": "Banking arm of the broker; same statements family as SCHWAB." },
+    { "code": "FIFTHTHIRD", "label": "Fifth Third Bank", "kind": "bank" },
+    { "code": "CITIZENS", "label": "Citizens Bank", "kind": "bank" },
+    { "code": "KEYBANK", "label": "KeyBank", "kind": "bank" },
+    { "code": "REGIONS", "label": "Regions Bank", "kind": "bank" },
+    { "code": "MTB", "label": "M&T Bank", "kind": "bank" },
+    { "code": "HUNTINGTON", "label": "Huntington Bank", "kind": "bank" },
+    { "code": "SOFI", "label": "SoFi", "kind": "bank", "notes": "Fintech with a national bank charter since 2022." },
+    { "code": "CHIME", "label": "Chime", "kind": "bank", "notes": "Neobank; accounts held by partner banks (Bancorp/Stride)." },
+    { "code": "AMEX", "label": "American Express", "kind": "card_issuer", "notes": "Issuer and network; also offers savings via Amex Bank." },
+    { "code": "DISCOVER", "label": "Discover", "kind": "card_issuer", "notes": "Acquired by Capital One in 2025; brand retained." },
+    { "code": "CAPITALONE-CARDS", "label": "Capital One (Cards)", "kind": "card_issuer", "notes": "Same entity as the bank CAPITALONE." },
+    { "code": "SYNCHRONY", "label": "Synchrony Bank", "kind": "card_issuer", "notes": "Largest store/private-label card issuer (Amazon, Lowe's, etc.)." },
+    { "code": "BARCLAYS-US", "label": "Barclays US", "kind": "card_issuer", "notes": "Co-branded cards (airlines, retail)." },
+    { "code": "PAYPAL", "label": "PayPal", "kind": "wallet" },
+    { "code": "VENMO", "label": "Venmo", "kind": "wallet", "notes": "PayPal subsidiary." },
+    { "code": "CASHAPP", "label": "Cash App", "kind": "wallet", "notes": "Block (Square) product." },
+    { "code": "APPLECASH", "label": "Apple Cash / Apple Card", "kind": "wallet", "notes": "Apple Card issued by Goldman Sachs." },
+    { "code": "GOOGLEPAY", "label": "Google Pay", "kind": "wallet" },
+    { "code": "ZELLE", "label": "Zelle", "kind": "payment_rail", "notes": "Bank-to-bank instant rail; appears on bank statements, not an account." },
+    { "code": "ACH", "label": "ACH", "kind": "payment_rail", "notes": "Batch interbank rail; shows as ACH credit/debit descriptors." },
+    { "code": "FIDELITY", "label": "Fidelity Investments", "kind": "broker" },
+    { "code": "VANGUARD", "label": "Vanguard", "kind": "broker" },
+    { "code": "SCHWAB", "label": "Charles Schwab", "kind": "broker", "notes": "Absorbed TD Ameritrade accounts by 2024." },
+    { "code": "ROBINHOOD", "label": "Robinhood", "kind": "broker" },
+    { "code": "ETRADE", "label": "E*TRADE", "kind": "broker", "notes": "Morgan Stanley subsidiary." },
+    { "code": "MERRILL", "label": "Merrill", "kind": "broker", "notes": "Bank of America subsidiary." },
+    { "code": "IBKR", "label": "Interactive Brokers", "kind": "broker" },
+    { "code": "WEBULL", "label": "Webull", "kind": "broker" },
+    { "code": "COINBASE", "label": "Coinbase", "kind": "crypto_exchange", "notes": "Largest US-regulated exchange." },
+    { "code": "KRAKEN", "label": "Kraken", "kind": "crypto_exchange" },
+    { "code": "GEMINI", "label": "Gemini", "kind": "crypto_exchange" },
+    { "code": "CRYPTOCOM-US", "label": "Crypto.com (US)", "kind": "crypto_exchange" },
+    { "code": "BINANCE-US", "label": "Binance.US", "kind": "crypto_exchange", "notes": "Separate entity from global Binance; fiat rails limited since 2023." },
+    { "code": "STATEFARM", "label": "State Farm", "kind": "insurer", "notes": "Auto/home leader." },
+    { "code": "GEICO", "label": "GEICO", "kind": "insurer", "notes": "Berkshire Hathaway subsidiary; auto." },
+    { "code": "PROGRESSIVE", "label": "Progressive", "kind": "insurer", "notes": "Auto." },
+    { "code": "ALLSTATE", "label": "Allstate", "kind": "insurer" },
+    { "code": "METLIFE", "label": "MetLife", "kind": "insurer", "notes": "Life and employee benefits." },
+    { "code": "PRUDENTIAL-US", "label": "Prudential Financial", "kind": "insurer", "notes": "Life; unrelated to UK Prudential." },
+    { "code": "NYLIFE", "label": "New York Life", "kind": "insurer", "notes": "Life; mutual company." },
+    { "code": "IRS", "label": "Internal Revenue Service", "kind": "gov", "notes": "Federal income tax." },
+    { "code": "SSA", "label": "Social Security Administration", "kind": "gov", "notes": "Benefits deposits; SSA TREAS descriptors." },
+    { "code": "TREASURY", "label": "U.S. Treasury", "kind": "gov", "notes": "Tax refunds, savings bonds, treasuries via TreasuryDirect." },
+    { "code": "VERIZON", "label": "Verizon", "kind": "telco" },
+    { "code": "ATT", "label": "AT&T", "kind": "telco" },
+    { "code": "TMOBILE", "label": "T-Mobile", "kind": "telco", "notes": "Absorbed Sprint (2020)." },
+    { "code": "XFINITY", "label": "Xfinity (Comcast)", "kind": "telco", "notes": "Cable internet/TV; billed as Comcast." },
+    { "code": "SPECTRUM", "label": "Spectrum (Charter)", "kind": "telco" },
+    { "code": "PGE-CA", "label": "Pacific Gas and Electric", "kind": "utility", "notes": "Northern California." },
+    { "code": "SCE", "label": "Southern California Edison", "kind": "utility" },
+    { "code": "CONED", "label": "Con Edison", "kind": "utility", "notes": "New York City area." },
+    { "code": "DUKE", "label": "Duke Energy", "kind": "utility", "notes": "Southeast/Midwest." },
+    { "code": "NATIONALGRID-US", "label": "National Grid (US)", "kind": "utility", "notes": "Northeast gas/electric." }
+  ]
+}

package/dist/accounts/accounts.js

@@ -0,0 +1,99 @@
+import { countChildAccounts, deleteAccount as deleteAccountRow, findAccountById, insertAccount, insertStructuralAccount, TOP_LEVEL_TYPES, } from "../db/queries/accounts.js";
+import { accountHasTransactions, repointTransactions } from "../db/queries/transactions.js";
+const TYPE_ROOT_NAME = {
+    asset: "Assets",
+    liability: "Liabilities",
+    income: "Income",
+    expense: "Expenses",
+    equity: "Equity",
+};
+export function ensureTopLevelRoot(db, type) {
+    if (findAccountById(db, type))
+        return;
+    insertStructuralAccount(db, {
+        id: type,
+        name: TYPE_ROOT_NAME[type],
+        type,
+        parent_id: null,
+    });
+}
+/**
+ * Idempotently insert one of the structural accounts the system auto-creates:
+ *  - `expense:uncategorized`  (suspense for unclassifiable expense entries)
+ *  - `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";
+    insertStructuralAccount(db, { id, name, type, parent_id: type });
+}
+// Throws on any violation; the caller does the INSERT.
+function validateAccountHierarchy(db, input, parentId) {
+    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}".`);
+        }
+        return;
+    }
+    let parent = findAccountById(db, parentId);
+    if (!parent && 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}:".`);
+    }
+}
+/** A duplicate id surfaces as an Error with code 'ACCOUNT_EXISTS'. */
+export function createAccount(db, input) {
+    validateAccountHierarchy(db, input, input.parent_id ?? null);
+    insertAccount(db, input);
+}
+/**
+ * Re-points every leg on `fromId` to `toId`, then deletes the source account.
+ * Refuses if the source account still has children.
+ */
+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 children = countChildAccounts(db, fromId);
+    if (children > 0) {
+        throw new Error(`Account ${fromId} has ${children} child account(s); merge or delete them first.`);
+    }
+    const { moved, deletedSelfTransactions } = repointTransactions(db, fromId, toId);
+    deleteAccountRow(db, fromId);
+    return { moved, deletedSelfTransactions };
+}
+/** Delete an account only if no transactions reference it AND it has no children. */
+export function deleteAccount(db, id) {
+    if (accountHasTransactions(db, id)) {
+        throw new Error(`Account ${id} still has transactions; merge it first.`);
+    }
+    const children = countChildAccounts(db, id);
+    if (children > 0) {
+        throw new Error(`Account ${id} has ${children} child account(s); delete them first.`);
+    }
+    deleteAccountRow(db, id);
+}

package/dist/accounts/balances.js

@@ -0,0 +1,109 @@
+import { findAccountById, getAccountSubtree, } from "../db/queries/accounts.js";
+import { getAccountLegSums, getLegSumsForAccounts, getPeriodLegSums, } from "../db/queries/balances.js";
+import { insertTransaction } from "../db/queries/transactions.js";
+import { config } from "../config.js";
+import { fromMinorUnits, toMinorUnits } from "../lib/money.js";
+import { todayIso, ISO_DATE_RE } from "../lib/date.js";
+import { ensureStructuralAccount } from "./accounts.js";
+/**
+ * Shared normal-balance rule: asset/expense are debit-normal, the rest
+ * credit-normal. Leg sums are integer minor units; every decimal here comes
+ * from the account's currency exponent (`fromMinorUnits`).
+ */
+export function getAccountBalances(db, opts = {}) {
+    return getAccountLegSums(db, opts).map((r) => {
+        const debitNormal = r.type === "asset" || r.type === "expense";
+        const balance_minor = debitNormal ? r.sum_debit - r.sum_credit : r.sum_credit - r.sum_debit;
+        const { sum_debit, sum_credit, ...account } = r;
+        return {
+            ...account,
+            debits_posted: sum_debit,
+            credits_posted: sum_credit,
+            balance_minor,
+            balance: fromMinorUnits(balance_minor, account.currency),
+        };
+    });
+}
+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 };
+}
+/**
+ * Income (credits − debits) and expenses (debits − credits) over a date range.
+ * Grouped by (type, currency) so each currency converts with its own exponent.
+ */
+export function getPeriodTotals(db, from, to) {
+    let income = 0;
+    let expenses = 0;
+    for (const r of getPeriodLegSums(db, from, to)) {
+        if (r.type === "income")
+            income += fromMinorUnits(r.c_minus_d, r.currency);
+        else if (r.type === "expense")
+            expenses += fromMinorUnits(-r.c_minus_d, r.currency);
+    }
+    return { income, expenses };
+}
+/** Subtree balance (root inclusive), grouped by (type, currency) for correct conversion. */
+export function getRollupBalance(db, rootId) {
+    const subtree = getAccountSubtree(db, rootId);
+    if (subtree.length === 0)
+        return 0;
+    let total = 0;
+    for (const r of getLegSumsForAccounts(db, subtree.map((a) => a.id))) {
+        const debitNormal = r.type === "asset" || r.type === "expense";
+        const minor = debitNormal ? r.sum_debit - r.sum_credit : r.sum_credit - r.sum_debit;
+        total += fromMinorUnits(minor, r.currency);
+    }
+    return total;
+}
+const EQUITY_ADJUST_ID = "equity:adjustments";
+/**
+ * Moves an account to `targetAmount` by posting one balancing transaction
+ * against `equity:adjustments`. Delta math is integer minor units (no float
+ * drift); a zero delta is a no-op.
+ */
+export function adjustAccountBalance(db, opts) {
+    const account = findAccountById(db, opts.accountId);
+    if (!account)
+        throw new Error(`Account "${opts.accountId}" not found.`);
+    const target = Number(opts.targetAmount);
+    if (!Number.isFinite(target)) {
+        throw new Error(`targetAmount must be a number, got ${JSON.stringify(opts.targetAmount)}.`);
+    }
+    const currency = account.currency || config.displayCurrency;
+    const currentMinor = getAccountBalances(db, { idOrParent: account.id }).find((b) => b.id === account.id)
+        ?.balance_minor ?? 0;
+    const targetMinor = toMinorUnits(target, currency);
+    const deltaMinor = targetMinor - currentMinor;
+    if (deltaMinor === 0)
+        return { transactionId: null, delta: 0 };
+    const amount = Math.abs(deltaMinor);
+    const debitNormal = account.type === "asset" || account.type === "expense";
+    const accountIsDebit = (debitNormal && deltaMinor > 0) || (!debitNormal && deltaMinor < 0);
+    const debitAccountId = accountIsDebit ? account.id : EQUITY_ADJUST_ID;
+    const creditAccountId = accountIsDebit ? EQUITY_ADJUST_ID : account.id;
+    const date = opts.date && ISO_DATE_RE.test(opts.date) ? opts.date : todayIso();
+    const reason = String(opts.reason || "Balance adjustment").trim();
+    let transactionId = "";
+    const tx = db.transaction(() => {
+        ensureStructuralAccount(db, "equity:adjustments");
+        transactionId = insertTransaction(db, {
+            date,
+            description: reason,
+            debit_account_id: debitAccountId,
+            credit_account_id: creditAccountId,
+            amount,
+            currency,
+        }).id;
+    });
+    tx();
+    return { transactionId, delta: fromMinorUnits(deltaMinor, currency) };
+}

package/dist/accounts/matching.js

@@ -0,0 +1,72 @@
+import { listAccounts } from "../db/queries/accounts.js";
+import { accountNumberKey, tailAfterMask } from "../lib/masked.js";
+// A mask in the text (`470686XXXXXX9483`) is authoritative: its tail wins over the
+// longest-digit-run fallback, which would prefer the longer unmasked prefix.
+function queryNumberKey(text) {
+    const tail = tailAfterMask(text);
+    if (tail !== text)
+        return accountNumberKey(tail);
+    const runs = text.match(/\d+/g);
+    if (!runs)
+        return "";
+    const longest = runs.reduce((a, b) => (b.length > a.length ? b : a));
+    return accountNumberKey(longest);
+}
+/** Substring hits get a 0.85 floor ("ttb saving" finds "TTB Savings ••1234" despite
+ *  mediocre Levenshtein), and a query carrying an account number matches the row's
+ *  masked number — callers confirm before acting, so a same-last-4 collision is recoverable. */
+export function findAccountsByFuzzyName(db, query, threshold = 0.5) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const qKey = queryNumberKey(q);
+    const rows = listAccounts(db);
+    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 (qKey) {
+            const rowKey = row.account_number_masked
+                ? accountNumberKey(row.account_number_masked)
+                : queryNumberKey(name);
+            if (rowKey && rowKey === qKey)
+                score = Math.max(score, 0.9);
+        }
+        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/accounts/resolve.js

@@ -0,0 +1,118 @@
+import { createAccount, ensureStructuralAccount, ensureTopLevelRoot, } from "./accounts.js";
+import { findAccountById, TOP_LEVEL_TYPES, } from "../db/queries/accounts.js";
+import { merchantExists } from "../db/queries/merchants.js";
+import { findAccountsByFuzzyName } from "./matching.js";
+/**
+ * A merchant id that doesn't exist is recorded as attempted-unknown, so the
+ * caller can raise a question.
+ */
+export function resolveMerchantId(db, merchantId) {
+    if (!merchantId)
+        return { merchantId: null, attemptedUnknownId: null };
+    if (merchantExists(db, merchantId))
+        return { merchantId, attemptedUnknownId: null };
+    return { merchantId: null, attemptedUnknownId: merchantId };
+}
+/** `hint` is null on an exact match; `uncategorized_fallback` is the ambiguous case the commit pipeline turns into a question. */
+export function resolveOnePosting(db, posting, opts = {}) {
+    if (findAccountById(db, posting.account_id)) {
+        return { posting, hint: null };
+    }
+    if (!opts.skipFuzzy) {
+        const matched = bestFuzzyMatch(db, posting.account_id);
+        if (matched) {
+            return {
+                posting: { ...posting, account_id: matched },
+                hint: {
+                    type: "similar_matched",
+                    originalId: posting.account_id,
+                    matchedId: matched,
+                },
+            };
+        }
+    }
+    const placeholder = ensurePlaceholderAccount(db, posting.account_id);
+    return {
+        posting: { ...posting, account_id: placeholder.accountId },
+        hint: placeholder.fellBack
+            ? { type: "uncategorized_fallback", accountId: placeholder.accountId }
+            : { type: "placeholder_created", accountId: placeholder.accountId },
+    };
+}
+const FUZZY_THRESHOLD = 0.7;
+function bestFuzzyMatch(db, accountId) {
+    const leaf = leafSegment(accountId).replace(/[-_]+/g, " ");
+    if (!leaf)
+        return null;
+    const matches = findAccountsByFuzzyName(db, leaf, FUZZY_THRESHOLD);
+    return matches[0]?.account.id ?? null;
+}
+function leafSegment(id) {
+    const segments = id.split(":");
+    return segments[segments.length - 1] ?? id;
+}
+// `upTo` is 1-based. `ACCOUNT_EXISTS` races are swallowed as a no-op; every other error propagates.
+function walkAncestorChain(db, segments, type, upTo) {
+    const created = [];
+    if (!findAccountById(db, type))
+        created.push(type);
+    ensureTopLevelRoot(db, type);
+    for (let i = 2; i <= upTo; i++) {
+        const id = segments.slice(0, i).join(":");
+        if (findAccountById(db, id))
+            continue;
+        const parentId = segments.slice(0, i - 1).join(":");
+        const name = humanizeSegment(segments[i - 1]);
+        try {
+            createAccount(db, { id, name, type, parent_id: parentId });
+            created.push(id);
+        }
+        catch (err) {
+            if (err?.code === "ACCOUNT_EXISTS")
+                continue;
+            throw err;
+        }
+    }
+    return created;
+}
+// Never surfaces an error: always returns a usable id, falling back to `expense:uncategorized`.
+function ensurePlaceholderAccount(db, accountId) {
+    const segments = accountId.split(":").filter(Boolean);
+    if (segments.length < 2)
+        return { accountId: ensureUncategorizedFallback(db), fellBack: true };
+    const type = segments[0];
+    if (!TOP_LEVEL_TYPES.includes(type))
+        return { accountId: ensureUncategorizedFallback(db), fellBack: true };
+    // Any hierarchy failure here degrades to the fallback silently; `--resolve` depends on that.
+    try {
+        walkAncestorChain(db, segments, type, segments.length);
+    }
+    catch {
+        return { accountId: ensureUncategorizedFallback(db), fellBack: true };
+    }
+    return { accountId, fellBack: false };
+}
+/**
+ * Creates any missing ancestor above the leaf for a multi-segment id (e.g.
+ * `asset:bank:ttb`), so `accounts create` doesn't need every intermediate
+ * category pre-created. Unlike `ensurePlaceholderAccount`, propagates
+ * hierarchy errors as-is so the CLI can surface a real INVALID.
+ */
+export function ensureAccountAncestors(db, id, type) {
+    const segments = id.split(":").filter(Boolean);
+    if (segments.length < 2)
+        return { parentId: null, createdParents: [] };
+    const createdParents = walkAncestorChain(db, segments, type, segments.length - 1);
+    const parentId = segments.slice(0, segments.length - 1).join(":");
+    return { parentId, createdParents };
+}
+function ensureUncategorizedFallback(db) {
+    ensureStructuralAccount(db, "expense:uncategorized");
+    return "expense:uncategorized";
+}
+function humanizeSegment(segment) {
+    const spaced = segment.replace(/[-_]+/g, " ").trim();
+    if (!spaced)
+        return "Placeholder";
+    return spaced.replace(/\b\w/g, (c) => c.toUpperCase());
+}