@morroc/open-ledger 0.14.1

package/dist/config.js

@@ -0,0 +1,104 @@
+import "dotenv/config";
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync, } from "fs";
+import { createHash } from "crypto";
+import { resolve } from "path";
+import { homedir } from "os";
+const OLED_DIR = process.env.OLED_DIR
+    ? resolve(process.env.OLED_DIR)
+    : resolve(homedir(), ".oled");
+/**
+ * Also drives the persisted-key list: unknown keys on disk are tolerated on
+ * read and dropped on the next write — `saveConfig` writes only the fields
+ * listed here.
+ */
+const CONFIG_FIELDS = {
+    // Last-resort constants; `config converge` overrides them — other modules
+    // should read the resolved value, not hardcode a currency.
+    displayLocale: { default: "th-TH" },
+    displayCurrency: { default: "THB" },
+    dbPath: { envVar: "OLED_DB_PATH", default: resolve(OLED_DIR, "db.sqlite") },
+    dbEncryptionKey: { envVar: "OLED_DB_ENCRYPTION_KEY", default: "" },
+    dataDir: { envVar: "OLED_DATA_DIR", default: resolve(OLED_DIR, "data") },
+    userName: { default: "User" },
+    ocrBaseUrl: { envVar: "OLED_OCR_BASE_URL", default: "" },
+    // Blank means the preset registry's own default model; src/extract/presets/ owns the id.
+    ocrModel: { envVar: "OLED_OCR_MODEL", default: "" },
+    ocrApiKey: { envVar: "OLED_OCR_API_KEY", default: "" },
+};
+const CONFIG_KEYS = Object.keys(CONFIG_FIELDS);
+/** Config fields whose value must never be echoed in plaintext; `config show`
+ *  renders each as `{ set, fingerprint }` via `keyFingerprint()` instead. */
+export const CONFIG_SECRETS = ["dbEncryptionKey", "ocrApiKey"];
+export function getOledDir() {
+    return OLED_DIR;
+}
+export function getConfigPath() {
+    return resolve(OLED_DIR, "config.json");
+}
+export function getDataDir() {
+    return config.dataDir;
+}
+/** Scratch space for extracted text and page images; env-overridable for tests. */
+export function getCacheDir() {
+    return process.env.OLED_CACHE_DIR || resolve(OLED_DIR, "cache");
+}
+/** Non-reversible fingerprint (`sha256:` + first 8 hex) so `config`/`status`
+ *  can prove a key is set without ever printing the passphrase. */
+export function keyFingerprint(key) {
+    return `sha256:${createHash("sha256").update(key).digest("hex").slice(0, 8)}`;
+}
+function loadFileConfig() {
+    const configPath = getConfigPath();
+    if (!existsSync(configPath))
+        return {};
+    try {
+        return JSON.parse(readFileSync(configPath, "utf-8"));
+    }
+    catch {
+        // Must degrade to defaults, not throw — every command, including the
+        // ones that would repair the file, would crash at startup otherwise.
+        return {};
+    }
+}
+function pickConfigFields(obj) {
+    const out = {};
+    for (const key of CONFIG_KEYS) {
+        if (obj[key] !== undefined)
+            out[key] = obj[key];
+    }
+    return out;
+}
+function buildConfig() {
+    const file = loadFileConfig();
+    const out = {};
+    // Precedence env > file > default. `||` (not `??`) so an empty-string value falls through too.
+    for (const key of CONFIG_KEYS) {
+        const { envVar, default: fallback } = CONFIG_FIELDS[key];
+        out[key] = (envVar && process.env[envVar]) || file[key] || fallback;
+    }
+    return out;
+}
+export const config = buildConfig();
+/**
+ * File values only — no env overrides, no defaults folded in. Converge uses
+ * this to tell an explicitly-persisted value apart from a defaulted one, so
+ * it can slot a dataset-derived default between the two.
+ */
+export function loadPersistedConfig() {
+    return pickConfigFields(loadFileConfig());
+}
+export function saveConfig(partial) {
+    const configPath = getConfigPath();
+    if (!existsSync(OLED_DIR))
+        mkdirSync(OLED_DIR, { recursive: true });
+    const existing = loadFileConfig();
+    const merged = pickConfigFields({ ...existing, ...partial });
+    writeFileSync(configPath, JSON.stringify(merged, null, 2) + "\n", {
+        mode: 0o600,
+    });
+    try {
+        chmodSync(configPath, 0o600);
+    }
+    catch { }
+    Object.assign(config, merged);
+}

package/dist/context.js

@@ -0,0 +1,30 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync, chmodSync } from "fs";
+import { dirname, resolve } from "path";
+import { getOledDir } from "./config.js";
+import { tryExecute } from "./lib/result.js";
+export function getContextPath() {
+    return resolve(getOledDir(), "context.md");
+}
+export function readContext() {
+    const p = getContextPath();
+    if (!existsSync(p))
+        return "";
+    const result = tryExecute(() => readFileSync(p, "utf-8"));
+    return result.ok ? result.value : "";
+}
+function writeContext(content) {
+    const p = getContextPath();
+    const dir = dirname(p);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    writeFileSync(p, content, { encoding: "utf-8", mode: 0o600 });
+    try {
+        chmodSync(p, 0o600);
+    }
+    catch { }
+}
+export function createContextTemplate(userName) {
+    if (existsSync(getContextPath()))
+        return;
+    writeContext(`# OpenLedger context for ${userName}\n\n## Family\n- ${userName}\n\n## Income\n- (Optional: add your primary income source so OpenLedger can mark it as PII when sending data to the model.)\n\n## Notes\n- (Free-form notes about your accounts, bank preferences, or anything OpenLedger should keep in mind when ingesting.)\n`);
+}

package/dist/datasets/defaults.js

@@ -0,0 +1,29 @@
+import * as z from "zod";
+import { loadDatasetRows } from "./loader.js";
+// Locale + currency per country, one `<cc>.json` file under `datasets/defaults/`.
+// `config converge` seeds display defaults from it.
+const countryDefaultsSchema = z.object({
+    country: z.string(),
+    locale: z.string(),
+    currency: z.string(),
+});
+export const defaultsDataset = {
+    dirname: "defaults",
+    schema: countryDefaultsSchema,
+    // The file's `country` is re-added by the loader (uppercased); the row carries
+    // only the display fields here to avoid duplicating it.
+    flatten: (file) => [{ locale: file.locale, currency: file.currency }],
+    sortKey: (row) => row.country,
+};
+function all() {
+    return loadDatasetRows("defaults", defaultsDataset);
+}
+/** The locale/currency defaults for a country (case-insensitive), or null. */
+export function findCountryDefaults(country) {
+    const cc = country.toUpperCase();
+    return all().find((r) => r.country === cc) ?? null;
+}
+/** Uppercased country codes that have defaults, sorted — for "unknown country" hints. */
+export function availableCountries() {
+    return all().map((r) => r.country);
+}

package/dist/datasets/index.js

@@ -0,0 +1,33 @@
+import { loadDatasetRows } from "./loader.js";
+import { institutionsDataset } from "./institutions.js";
+import { defaultsDataset } from "./defaults.js";
+/** A dataset with a typed finder of its own (`findCountryDefaults`) exports it from its own module instead. */
+// `any` here only erases the per-entry file shape (institutions vs defaults each
+// have their own concrete `DatasetDefinition<...>`), which the registry doesn't need.
+const REGISTRY = {
+    institutions: institutionsDataset,
+    defaults: defaultsDataset,
+};
+export function listDatasetNames() {
+    return Object.keys(REGISTRY);
+}
+/** Drives the CLI `--kind` guard. */
+export function datasetHasKinds(name) {
+    return !!REGISTRY[name]?.kinds;
+}
+export function listDatasets() {
+    return Object.entries(REGISTRY).map(([name, def]) => {
+        const rows = loadDatasetRows(name, def);
+        const countries = [...new Set(rows.map((r) => r.country))].sort();
+        return { name, countries, rows: rows.length };
+    });
+}
+/** Throws on an unknown name — the CLI validates the name first for a clean error. */
+export function readDataset(name, filter = {}) {
+    const def = REGISTRY[name];
+    if (!def)
+        throw new Error(`unknown dataset "${name}"`);
+    const country = filter.country?.toUpperCase();
+    const { kind } = filter;
+    return loadDatasetRows(name, def).filter((r) => (!country || r.country === country) && (!kind || r.kind === kind));
+}

package/dist/datasets/institutions.js

@@ -0,0 +1,31 @@
+import * as z from "zod";
+const INSTITUTION_KINDS = [
+    "bank",
+    "card_issuer",
+    "wallet",
+    "payment_rail",
+    "broker",
+    "crypto_exchange",
+    "insurer",
+    "gov",
+    "telco",
+    "utility",
+];
+const institutionSchema = z.object({
+    code: z.string(),
+    label: z.string(),
+    kind: z.enum(INSTITUTION_KINDS),
+    notes: z.string().optional(),
+});
+/** Exported so the loader test can exercise validation directly without writing a malformed file to disk. */
+export const countryFileSchema = z.object({
+    country: z.string(),
+    institutions: z.array(institutionSchema),
+});
+export const institutionsDataset = {
+    dirname: "institutions",
+    schema: countryFileSchema,
+    flatten: (file) => file.institutions,
+    sortKey: (row) => String(row.code ?? ""),
+    kinds: INSTITUTION_KINDS,
+};

package/dist/datasets/loader.js

@@ -0,0 +1,57 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Generic loader for the shipped reference datasets: one subdirectory per
+ * dataset under `datasets/`, one `<cc>.json` per country. Adding a country is
+ * a new file, not a code change — dataset-specific shape lives in the
+ * per-dataset modules (institutions.ts, defaults.ts).
+ */
+// Two levels below the package root either way (src/datasets/ under tsx, dist/datasets/
+// built); the uncompiled datasets/ dir is reached by the same relative walk in both.
+const DATASETS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "../../datasets");
+// Memoized per dataset name so importing a dataset module does no file I/O.
+const cache = new Map();
+function readCountryFile(def, file) {
+    const path = resolve(DATASETS_DIR, def.dirname, file);
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        // A shipped dataset file that won't parse is a packaging defect, not user
+        // input — surface it loudly rather than degrading to an empty registry.
+        throw new Error(`dataset file ${def.dirname}/${file} is not valid JSON: ${err.message}`);
+    }
+    const parsed = def.schema.safeParse(raw);
+    if (!parsed.success) {
+        const detail = parsed.error.issues
+            .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+            .join("; ");
+        throw new Error(`dataset file ${def.dirname}/${file} has an invalid shape: ${detail}`);
+    }
+    const country = parsed.data.country.toUpperCase();
+    return def.flatten(parsed.data).map((row) => ({ ...row, country }));
+}
+function loadAll(def) {
+    const dir = resolve(DATASETS_DIR, def.dirname);
+    const files = readdirSync(dir)
+        .filter((f) => f.endsWith(".json"))
+        .sort();
+    const rows = files.flatMap((f) => readCountryFile(def, f));
+    rows.sort((a, b) => a.country.localeCompare(b.country) ||
+        (def.sortKey ? def.sortKey(a).localeCompare(def.sortKey(b)) : 0));
+    return rows;
+}
+/**
+ * Every row of a named dataset, sorted by country then the sort key. Returns
+ * the shared memoized array — callers must copy before mutating it.
+ */
+export function loadDatasetRows(name, def) {
+    const cached = cache.get(name);
+    if (cached)
+        return cached;
+    const rows = loadAll(def);
+    cache.set(name, rows);
+    return rows;
+}

package/dist/db/connection.js

@@ -0,0 +1,39 @@
+import Database from "libsql";
+import { config } from "../config.js";
+import { migrate } from "./schema.js";
+import { dirname } from "path";
+import { mkdirSync, existsSync, chmodSync } from "fs";
+let singleDb = null;
+function openDb(dbPath, encryptionKey) {
+    const dir = dirname(dbPath);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const opts = {};
+    if (encryptionKey) {
+        opts.encryptionCipher = "aes256cbc";
+        opts.encryptionKey = encryptionKey;
+    }
+    const db = new Database(dbPath, opts);
+    try {
+        db.pragma("journal_mode = WAL");
+    }
+    catch (err) {
+        db.close();
+        // Remaps into a NOT_READY-matching message (see NOT_READY_PATTERNS in cli/output.ts).
+        throw new Error("Failed to open database. Wrong encryption key or corrupt database file. " +
+            "If you changed your encryption key, restore from backup or delete ~/.oled/db.sqlite to start fresh.", { cause: err });
+    }
+    db.pragma("foreign_keys = ON");
+    migrate(db, dbPath);
+    try {
+        chmodSync(dbPath, 0o600);
+    }
+    catch { }
+    return db;
+}
+export function getDb() {
+    if (!singleDb) {
+        singleDb = openDb(config.dbPath, config.dbEncryptionKey || undefined);
+    }
+    return singleDb;
+}

package/dist/db/encryption.js

@@ -0,0 +1,42 @@
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from "crypto";
+const SECRET_KEY_SALT = "oled-secret-v1";
+const FORMAT_PREFIX = "gcm:";
+export function generateKey() {
+    return randomBytes(32).toString("hex");
+}
+function deriveSecretKey(dbKey) {
+    return scryptSync(dbKey, SECRET_KEY_SALT, 32);
+}
+/**
+ * Encrypts a secret (e.g. PDF password) with AES-256-GCM, key derived from
+ * `dbKey` via scrypt; a passthrough when `dbKey` is empty. Output format:
+ * `gcm:<iv-hex>:<tag-hex>:<ciphertext-hex>`.
+ */
+export function encryptSecret(plaintext, dbKey) {
+    if (!dbKey)
+        return plaintext;
+    const key = deriveSecretKey(dbKey);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return `${FORMAT_PREFIX}${iv.toString("hex")}:${tag.toString("hex")}:${ct.toString("hex")}`;
+}
+export function decryptSecret(ciphertext, dbKey) {
+    if (!dbKey || !ciphertext.startsWith(FORMAT_PREFIX))
+        return ciphertext;
+    const rest = ciphertext.slice(FORMAT_PREFIX.length);
+    const parts = rest.split(":");
+    if (parts.length !== 3) {
+        throw new Error("Malformed encrypted secret.");
+    }
+    const [ivHex, tagHex, ctHex] = parts;
+    const key = deriveSecretKey(dbKey);
+    const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(ivHex, "hex"));
+    decipher.setAuthTag(Buffer.from(tagHex, "hex"));
+    const pt = Buffer.concat([
+        decipher.update(Buffer.from(ctHex, "hex")),
+        decipher.final(),
+    ]);
+    return pt.toString("utf8");
+}

package/dist/db/migrations/0001_baseline.js

@@ -0,0 +1,121 @@
+export function up(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS accounts (
+      id TEXT PRIMARY KEY,
+      name TEXT NOT NULL,
+      type TEXT NOT NULL CHECK(type IN ('asset','liability','income','expense','equity')),
+      parent_id TEXT REFERENCES accounts(id),
+      subtype TEXT,
+      bank_name TEXT,
+      account_number_masked TEXT,
+      currency TEXT NOT NULL DEFAULT 'THB',
+      due_day INTEGER,
+      statement_day INTEGER,
+      points_balance REAL,
+      metadata_json TEXT,
+      pii_flag INTEGER NOT NULL DEFAULT 0,
+      has_question INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS accounts_parent_idx ON accounts(parent_id);
+    CREATE INDEX IF NOT EXISTS accounts_type_idx ON accounts(type);
+
+    CREATE TABLE IF NOT EXISTS merchants (
+      id TEXT PRIMARY KEY,
+      canonical_name TEXT NOT NULL UNIQUE,
+      default_account_id TEXT REFERENCES accounts(id),
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS merchant_aliases (
+      id TEXT PRIMARY KEY,
+      merchant_id TEXT NOT NULL REFERENCES merchants(id) ON DELETE CASCADE,
+      normalized_pattern TEXT NOT NULL UNIQUE,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS merchant_aliases_merchant_idx ON merchant_aliases(merchant_id);
+
+    CREATE TABLE IF NOT EXISTS files (
+      id TEXT PRIMARY KEY,
+      path TEXT NOT NULL,
+      file_hash TEXT NOT NULL UNIQUE,
+      mime TEXT NOT NULL,
+      status TEXT NOT NULL CHECK(status IN ('pending','ingested','failed')),
+      ingested_at TEXT,
+      source TEXT,
+      error TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS transactions (
+      id                TEXT PRIMARY KEY,
+      group_id          TEXT,
+      date              TEXT NOT NULL,
+      description       TEXT NOT NULL,
+      merchant_id       TEXT REFERENCES merchants(id),
+      raw_descriptor    TEXT,
+      source_file_id    TEXT REFERENCES files(id) ON DELETE CASCADE,
+      source_page       INTEGER,
+      debit_account_id  TEXT NOT NULL REFERENCES accounts(id),
+      credit_account_id TEXT NOT NULL REFERENCES accounts(id),
+      amount            INTEGER NOT NULL,
+      currency          TEXT NOT NULL DEFAULT 'THB',
+      code              TEXT,
+      user_ref          TEXT,
+      void_of           TEXT,
+      has_question      INTEGER NOT NULL DEFAULT 0,
+      created_at        TEXT NOT NULL DEFAULT (datetime('now')),
+      CHECK (amount > 0),
+      CHECK (debit_account_id <> credit_account_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS transactions_date_idx ON transactions(date);
+    CREATE INDEX IF NOT EXISTS transactions_debit_account_idx ON transactions(debit_account_id);
+    CREATE INDEX IF NOT EXISTS transactions_credit_account_idx ON transactions(credit_account_id);
+    CREATE INDEX IF NOT EXISTS transactions_source_file_idx ON transactions(source_file_id);
+    CREATE INDEX IF NOT EXISTS transactions_group_idx ON transactions(group_id);
+    CREATE INDEX IF NOT EXISTS transactions_merchant_idx ON transactions(merchant_id);
+
+    CREATE TABLE IF NOT EXISTS questions (
+      id TEXT PRIMARY KEY,
+      batch_id TEXT,
+      file_id TEXT REFERENCES files(id) ON DELETE CASCADE,
+      transaction_id TEXT REFERENCES transactions(id) ON DELETE CASCADE,
+      account_id TEXT REFERENCES accounts(id) ON DELETE CASCADE,
+      kind TEXT,
+      prompt TEXT NOT NULL,
+      options_json TEXT,
+      context_json TEXT,
+      answer TEXT,
+      resolved_at TEXT,
+      deferred_until TEXT,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE INDEX IF NOT EXISTS questions_batch_idx ON questions(batch_id);
+    CREATE INDEX IF NOT EXISTS questions_deferred_idx ON questions(deferred_until);
+
+    CREATE TABLE IF NOT EXISTS notes (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      content TEXT NOT NULL,
+      category TEXT NOT NULL CHECK(category IN ('rule','preference','fact')),
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+
+    CREATE TABLE IF NOT EXISTS settings (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+
+    CREATE TABLE IF NOT EXISTS file_passwords (
+      id TEXT PRIMARY KEY,
+      pattern TEXT NOT NULL UNIQUE,
+      password_encrypted TEXT NOT NULL,
+      last_used_at TEXT,
+      use_count INTEGER NOT NULL DEFAULT 0,
+      created_at TEXT NOT NULL DEFAULT (datetime('now'))
+    );
+  `);
+}

package/dist/db/migrations/index.js

@@ -0,0 +1,3 @@
+import * as baseline from "./0001_baseline.js";
+/** Explicit list (no fs glob) so bare `tsc` type-checks it. Append only; never reorder or remove. */
+export const MIGRATIONS = [baseline];

package/dist/db/queries/accounts.js

@@ -0,0 +1,108 @@
+import { config } from "../../config.js";
+import { parseJsonOrNull } from "../../lib/json.js";
+import { normalizeMaskedAccountNumber } from "../../lib/masked.js";
+import { buildPatch } from "../../lib/patch.js";
+import { errorMessage } from "../../lib/result.js";
+export const TOP_LEVEL_TYPES = [
+    "asset", "liability", "income", "expense", "equity",
+];
+export function findAccountById(db, id) {
+    return db.prepare(`SELECT * FROM accounts WHERE id = ?`).get(id) ?? null;
+}
+export function accountExists(db, id) {
+    return !!db.prepare(`SELECT 1 FROM accounts WHERE id = ? LIMIT 1`).get(id);
+}
+export function countAccounts(db) {
+    const row = db.prepare(`SELECT COUNT(*) AS n FROM accounts`).get();
+    return row.n;
+}
+export function listAccounts(db) {
+    return db.prepare(`SELECT * FROM accounts ORDER BY name`).all();
+}
+export function countChildAccounts(db, parentId) {
+    const row = db
+        .prepare(`SELECT COUNT(*) AS n FROM accounts WHERE parent_id = ?`)
+        .get(parentId);
+    return row.n;
+}
+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);
+}
+/** The currency a transaction leg inherits from its account. */
+export function findAccountCurrency(db, id) {
+    const row = db.prepare(`SELECT currency FROM accounts WHERE id = ?`).get(id);
+    return row?.currency ?? null;
+}
+/** A duplicate id surfaces as an Error coded 'ACCOUNT_EXISTS'. Hierarchy
+ *  invariants are the caller's (`createAccount`). */
+export function insertAccount(db, input) {
+    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, input.parent_id ?? null, input.subtype ?? null, input.bank_name ? String(input.bank_name).toUpperCase() : null, normalizeMaskedAccountNumber(input.account_number_masked), input.currency ?? config.displayCurrency, input.due_day ?? null, input.statement_day ?? null, input.metadata ? JSON.stringify(input.metadata) : null);
+    }
+    catch (err) {
+        const message = errorMessage(err);
+        if (message.includes("UNIQUE")) {
+            const dup = new Error(`Account "${input.id}" already exists.`);
+            dup.code = "ACCOUNT_EXISTS";
+            throw dup;
+        }
+        throw err;
+    }
+}
+/** Currency and the rest deliberately take the schema defaults. */
+export function insertStructuralAccount(db, row) {
+    db.prepare(`INSERT INTO accounts (id, name, type, parent_id) VALUES (?, ?, ?, ?)`).run(row.id, row.name, row.type, row.parent_id);
+}
+export function renameAccount(db, id, name) {
+    return db.prepare(`UPDATE accounts SET name = ? WHERE id = ?`).run(name, id).changes;
+}
+const ACCOUNT_PATCH = {
+    due_day: {},
+    statement_day: {},
+    points_balance: {},
+    account_number_masked: {
+        transform: (v) => normalizeMaskedAccountNumber(v),
+    },
+    bank_name: {
+        transform: (v) => (v == null ? null : String(v).toUpperCase()),
+    },
+};
+/** Returns before/after snapshots of touched fields; `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, params, before, after } = buildPatch(ACCOUNT_PATCH, current, patch);
+    if (patch.metadata !== undefined) {
+        // A corrupt blob must error, not be silently overwritten with {}.
+        let existing = {};
+        if (current.metadata_json != null) {
+            const parsed = parseJsonOrNull(current.metadata_json);
+            if (parsed == null || typeof parsed !== "object") {
+                throw new Error(`Account "${id}" has unreadable metadata_json; refusing to overwrite it.`);
+            }
+            existing = parsed;
+        }
+        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 };
+    params.push(id);
+    db.prepare(`UPDATE accounts SET ${sets.join(", ")} WHERE id = ?`).run(...params);
+    return { before, after };
+}
+/** Deletes the row alone; transaction/child guards are the caller's (src/accounts/accounts.ts). */
+export function deleteAccount(db, id) {
+    return db.prepare(`DELETE FROM accounts WHERE id = ?`).run(id).changes > 0;
+}

package/dist/db/queries/balances.js

@@ -0,0 +1,61 @@
+// Leg expansion only: the normal-balance rule and decimal conversion are the
+// caller's, in src/accounts/balances.ts.
+/** Debit + credit legs of every non-void transaction, one row per leg (`void_of`
+ *  rows excluded so a merged mirror never double-counts). */
+const TRANSACTION_LEGS = `SELECT debit_account_id  AS acct, amount, date, 'D' AS side FROM transactions WHERE void_of IS NULL
+       UNION ALL
+       SELECT credit_account_id AS acct, amount, date, 'C' AS side FROM transactions WHERE void_of IS NULL`;
+/** Per-account leg sums, including accounts with no legs at all (LEFT JOIN). */
+export function getAccountLegSums(db, opts = {}) {
+    const params = [];
+    const where = [];
+    if (opts.type) {
+        where.push("a.type = ?");
+        params.push(opts.type);
+    }
+    if (opts.idOrParent) {
+        where.push("(a.id = ? OR a.parent_id = ?)");
+        params.push(opts.idOrParent, opts.idOrParent);
+    }
+    const whereSql = where.length ? `WHERE ${where.join(" AND ")}` : "";
+    return db
+        .prepare(`SELECT a.*,
+              COALESCE(SUM(CASE WHEN t.side = 'D' THEN t.amount ELSE 0 END), 0) AS sum_debit,
+              COALESCE(SUM(CASE WHEN t.side = 'C' THEN t.amount ELSE 0 END), 0) AS sum_credit
+         FROM accounts a
+         LEFT JOIN (${TRANSACTION_LEGS}) t ON t.acct = a.id
+         ${whereSql}
+         GROUP BY a.id
+         ORDER BY a.type, a.id`)
+        .all(...params);
+}
+/**
+ * Income and expense legs dated within `from`..`to`, netted per
+ * (type, currency) so each currency converts with its own exponent.
+ */
+export function getPeriodLegSums(db, from, to) {
+    return db
+        .prepare(`SELECT a.type AS type, a.currency AS currency,
+              SUM(CASE WHEN t.side = 'C' THEN t.amount ELSE -t.amount END) AS c_minus_d
+         FROM (${TRANSACTION_LEGS}) t
+         JOIN accounts a ON a.id = t.acct
+         WHERE t.date BETWEEN ? AND ? AND a.type IN ('income', 'expense')
+         GROUP BY a.type, a.currency`)
+        .all(from, to);
+}
+/** Leg sums for a set of accounts (a subtree), grouped by (type, currency). */
+export function getLegSumsForAccounts(db, ids) {
+    // An empty IN () is a syntax error, and no accounts means no legs.
+    if (ids.length === 0)
+        return [];
+    const placeholders = ids.map(() => "?").join(",");
+    return db
+        .prepare(`SELECT a.type AS type, a.currency AS currency,
+              COALESCE(SUM(CASE WHEN t.side = 'D' THEN t.amount ELSE 0 END), 0) AS sum_debit,
+              COALESCE(SUM(CASE WHEN t.side = 'C' THEN t.amount ELSE 0 END), 0) AS sum_credit
+         FROM accounts a
+         LEFT JOIN (${TRANSACTION_LEGS}) t ON t.acct = a.id
+         WHERE a.id IN (${placeholders})
+         GROUP BY a.type, a.currency`)
+        .all(...ids);
+}