@book.dev/sdk 3.5.0 → 3.6.0

package/dist/ledgerBeancount.js

@@ -0,0 +1,309 @@
+/**
+ * Beancount export (LGR-13): the ledger serialized as a Beancount journal, so
+ * the whole book can be re-checked by an INDEPENDENT accounting implementation
+ * (`bean-check`, the beancount loader, Fava) — free QA for every invariant the
+ * ledger claims to enforce.
+ *
+ * This module is a PURE function from ledger entities to journal text — no
+ * I/O, no clock, no locale — with the same hard guarantee as the canonical CSV
+ * (`./ledgerCsv`): the SAME DATA always produces IDENTICAL BYTES. It reads the
+ * same entities the CSV export reads (one read model, two serializers).
+ *
+ * WHAT IS EMITTED (and why — the full contract lives in
+ * `docs/ledger/beancount-export.md`):
+ *
+ *  - `open` for every account (earliest reported posting date, else the
+ *    account's creation date), pinning the account's currency so bean-check
+ *    enforces the ledger's own one-currency-per-account rule independently;
+ *  - one `txn` per POSTED or VOID transaction — the exact set the report folds
+ *    count (`REPORTED_STATES` in the ledger plugin's reports): a void original
+ *    is offset by its posted reversal, and exporting only one half of the pair
+ *    would misstate every balance. Drafts are not on the books and never
+ *    export. Ledger-only facts (id, entry number, state, kind, reverses,
+ *    evidence, memo, cleared state) ride as `lp-*` metadata;
+ *  - `balance` assertions the day after each CLOSED period's end, for every
+ *    account with a reported posting on or before the end — so bean-check
+ *    re-verifies both the arithmetic and the closing sweep (income-statement
+ *    accounts assert to zero) from the directives alone.
+ *
+ * SIGN MAPPING — the identity. The ledger stores signed DEBIT-POSITIVE minor
+ * units (LGR-2); Beancount amounts are signed decimals where an asset increase
+ * is positive and a credit-normal balance (Income/Liabilities/Equity) is
+ * negative — the same convention. No re-signing happens anywhere, including
+ * for contra/credit-normal accounts: a revenue balance exports negative, which
+ * is exactly how Beancount's own Income accounts carry it.
+ *
+ * MONEY DISCIPLINE: amounts pass through {@link formatBeancountAmount} (exact
+ * BigInt digit math, the `formatAmount` discipline without display grouping)
+ * and {@link sumAmounts} — never float arithmetic.
+ *
+ * CORRUPT BOOKS: unlike the insurance CSV (which must always leave the
+ * building), this export REFUSES a damaged book — an unresolvable account or a
+ * non-safe-integer amount throws a typed error instead of serializing a
+ * plausible-but-wrong journal. The reference implementation must never be
+ * handed data the ledger itself cannot vouch for; the LGR-7 verifier is the
+ * tool that names the damage.
+ */
+import { MoneyRangeError, isValidMinor, sumAmounts } from './money';
+import { LedgerError } from './ledger';
+/**
+ * The Beancount ROOT for each ledger account type. Beancount requires every
+ * account to live under one of exactly five roots; the ledger's five types map
+ * onto them 1:1 (`revenue` → `Income` is the only rename).
+ */
+export const BEANCOUNT_ROOT_BY_TYPE = {
+    asset: 'Assets',
+    liability: 'Liabilities',
+    equity: 'Equity',
+    revenue: 'Income',
+    expense: 'Expenses',
+};
+/**
+ * Serialize signed integer minor units as Beancount's plain decimal
+ * (`-1234.56`, `0.00`) — {@link formatAmount}'s exact BigInt digit math minus
+ * the display affordances (no thousands grouping, no symbols, no parens),
+ * because Beancount wants a machine number. Negative zero normalises to
+ * `0.00`. Throws {@link MoneyRangeError} on anything that is not a safe
+ * integer — see the module doc's corrupt-books stance.
+ */
+export function formatBeancountAmount(minor) {
+    if (!isValidMinor(minor)) {
+        throw new MoneyRangeError(`formatBeancountAmount: amount must be a safe integer of minor units, got ${String(minor)}`);
+    }
+    const big = BigInt(minor);
+    const negative = big < 0n;
+    const abs = negative ? -big : big;
+    return `${negative ? '-' : ''}${abs / 100n}.${(abs % 100n).toString().padStart(2, '0')}`;
+}
+/**
+ * Quote a string for Beancount: backslash and double-quote are escaped (the
+ * two characters the lexer treats specially inside a string); everything else
+ * — including literal newlines and non-ASCII — is verbatim, which the lexer
+ * accepts (verified against beancount 3.1.0). Escaping only these two keeps
+ * the mapping injective: a re-importer that unescapes `\\` and `\"` recovers
+ * the original exactly.
+ */
+export function quoteBeancountString(value) {
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+/** Beancount's currency grammar (shape only, like `isValidCurrencyCode`). */
+const BEANCOUNT_CURRENCY_RE = /^[A-Z][A-Z0-9'._-]{0,22}[A-Z0-9]$|^[A-Z]$/;
+/**
+ * Mangle ONE colon-separated component of a ledger account name into
+ * Beancount's component charset, deterministically:
+ *
+ *  1. every character outside `[A-Za-z0-9-]` becomes `-` (one `-` per
+ *     character — no collapsing, so distinct inputs stay distinct more often);
+ *  2. a leading lowercase letter is uppercased; any other invalid lead
+ *     (digit-ok, letter-ok; a `-` or nothing) is prefixed with `X`.
+ *
+ * The ledger's own name validator guarantees non-empty, non-whitespace-only
+ * components, but raw storage is not trusted: an empty component mangles to
+ * `X` instead of producing an invalid name.
+ */
+export function mangleBeancountComponent(segment) {
+    let s = segment.replace(/[^A-Za-z0-9-]/g, '-');
+    if (s === '')
+        s = 'X';
+    if (!/^[A-Z0-9]/.test(s)) {
+        s = /^[a-z]/.test(s) ? s[0].toUpperCase() + s.slice(1) : `X${s}`;
+    }
+    return s;
+}
+/**
+ * Map ONE ledger account name onto a Beancount account name (before collision
+ * handling — see {@link buildBeancountAccountNames} for the full map):
+ *
+ *  - the ROOT comes from the account TYPE ({@link BEANCOUNT_ROOT_BY_TYPE}),
+ *    never from the name — `Revenue:Sales` typed `revenue` becomes
+ *    `Income:Revenue:Sales`;
+ *  - each component is mangled ({@link mangleBeancountComponent});
+ *  - a first component that already equals the root is not repeated
+ *    (`Assets:Bank` stays `Assets:Bank`, not `Assets:Assets:Bank`) — unless
+ *    dropping it would leave the bare root, which Beancount rejects (an
+ *    account named exactly `Assets` becomes `Assets:Assets`).
+ */
+export function beancountAccountName(account) {
+    const root = BEANCOUNT_ROOT_BY_TYPE[account.type] ?? 'Equity';
+    const components = String(account.name).split(':').map(mangleBeancountComponent);
+    const rest = components[0] === root && components.length > 1 ? components.slice(1) : components;
+    return `${root}:${rest.join(':')}`;
+}
+/**
+ * The full account-id → Beancount-name map, with DETERMINISTIC collision
+ * handling: accounts are visited in (createdAt, id) order; the first claimant
+ * keeps the mapped name, later ones append `-2`, `-3`, … to the final
+ * component (bumping until free). Stable for a given book — the suffix order
+ * depends only on stored creation data, never on read order.
+ */
+export function buildBeancountAccountNames(accounts) {
+    const ordered = [...accounts].sort((a, b) => byteCompare(a.createdAt, b.createdAt) || byteCompare(a.id, b.id));
+    const taken = new Set();
+    const names = new Map();
+    for (const account of ordered) {
+        const base = beancountAccountName(account);
+        let name = base;
+        for (let n = 2; taken.has(name); n += 1)
+            name = `${base}-${n}`;
+        taken.add(name);
+        names.set(account.id, name);
+    }
+    return names;
+}
+/** Locale-independent, byte-deterministic string compare (never `localeCompare`). */
+function byteCompare(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** The transaction states that are ON THE BOOKS — the report folds' rule
+ *  (posted and void both count; a void original is offset by its posted
+ *  reversal). Drafts never export. */
+const EXPORTED_STATES = new Set(['posted', 'void']);
+/** ISO `YYYY-MM-DD` + 1 day, in UTC (balance assertions bind at the START of
+ *  their date, so "after period end" means the following day). */
+function nextIsoDay(date) {
+    const parsed = new Date(`${date}T00:00:00Z`);
+    parsed.setUTCDate(parsed.getUTCDate() + 1);
+    return parsed.toISOString().slice(0, 10);
+}
+/** The account's currency, coerced onto Beancount's currency grammar. The
+ *  ledger validates ISO-4217 shape at write time, so anything else is raw
+ *  corruption — mapped to the ISO placeholder `XXX` rather than emitting a
+ *  token bean-check cannot lex (the amount still exports verbatim, so the
+ *  corruption stays visible instead of failing the whole journal on syntax). */
+function beancountCurrency(currency) {
+    return typeof currency === 'string' && BEANCOUNT_CURRENCY_RE.test(currency) ? currency : 'XXX';
+}
+/**
+ * Canonical transaction order — the CSV export's: entry number ascending
+ * (posted and void entries always carry one), then (createdAt, id) for
+ * defensive totality over raw-corrupted rows.
+ */
+function canonicalTxOrder(a, b) {
+    const an = a.entryNo ?? Number.POSITIVE_INFINITY;
+    const bn = b.entryNo ?? Number.POSITIVE_INFINITY;
+    if (an !== bn)
+        return an < bn ? -1 : 1;
+    return byteCompare(a.createdAt, b.createdAt) || byteCompare(a.id, b.id);
+}
+/**
+ * Build the Beancount journal from the full account list, the full
+ * transaction list (with postings) and the period records — the same read
+ * model the canonical CSV uses. Pure and byte-deterministic; see module doc.
+ *
+ * Throws {@link LedgerError} `account-not-found` when a posting references an
+ * account the list does not carry, and {@link MoneyRangeError} on a stored
+ * amount that is not a safe integer — the corrupt-books stance.
+ */
+export function buildLedgerBeancount(accounts, transactions, periods) {
+    const names = buildBeancountAccountNames(accounts);
+    const accountById = new Map();
+    for (const account of accounts)
+        accountById.set(account.id, account);
+    const reported = transactions.filter((tx) => EXPORTED_STATES.has(tx.state)).sort(canonicalTxOrder);
+    // Earliest reported posting date per account — the `open` date (an account
+    // must be open on or before its first use; creation timestamps can postdate
+    // a backdated entry, so the postings win when they exist).
+    const firstUse = new Map();
+    for (const tx of reported) {
+        for (const posting of tx.postings) {
+            const seen = firstUse.get(posting.accountId);
+            if (seen === undefined || tx.date < seen)
+                firstUse.set(posting.accountId, tx.date);
+        }
+    }
+    const lines = [
+        '; OpenBook ledger — Beancount export (LGR-13).',
+        '; Deterministic: the same book always serializes to identical bytes.',
+        '; Sign mapping, account-name mangling, and round-trip limitations:',
+        ';   docs/ledger/beancount-export.md',
+        'option "title" "OpenBook ledger"',
+        '',
+    ];
+    // ── open directives (sorted by mapped name — unique by construction) ────────
+    const openOrder = [...accounts].sort((a, b) => byteCompare(names.get(a.id) ?? '', names.get(b.id) ?? ''));
+    for (const account of openOrder) {
+        const name = names.get(account.id) ?? beancountAccountName(account);
+        const date = firstUse.get(account.id) ?? String(account.createdAt).slice(0, 10);
+        lines.push(`${date} open ${name} ${beancountCurrency(account.currency)}`);
+        lines.push(`  lp-id: ${quoteBeancountString(account.id)}`);
+        // The original ledger name, when mangling changed it — what makes the
+        // mapping reversible without consulting the ledger.
+        if (account.name !== name)
+            lines.push(`  lp-name: ${quoteBeancountString(account.name)}`);
+    }
+    lines.push('');
+    // ── transactions ────────────────────────────────────────────────────────────
+    for (const tx of reported) {
+        lines.push(`${tx.date} * ${quoteBeancountString(tx.description)}`);
+        lines.push(`  lp-id: ${quoteBeancountString(tx.id)}`);
+        if (tx.entryNo != null)
+            lines.push(`  lp-entry-no: ${String(tx.entryNo)}`);
+        if (tx.state === 'void')
+            lines.push('  lp-state: "void"');
+        if (tx.kind === 'closing')
+            lines.push('  lp-kind: "closing"');
+        if (tx.reverses != null && tx.reverses !== '')
+            lines.push(`  lp-reverses: ${quoteBeancountString(tx.reverses)}`);
+        // Evidence attachments are ids + hashes, not exportable files, so they ride
+        // as metadata — a `document` directive would make bean-check fail on the
+        // missing file (verified against beancount 3.1.0; see docs).
+        tx.evidence.forEach((item, i) => {
+            const e = (item ?? {});
+            const described = `${String(e.filename ?? '')} sha256=${String(e.sha256 ?? '')} size=${String(e.size ?? '')}`;
+            lines.push(`  lp-evidence-${i + 1}: ${quoteBeancountString(described)}`);
+        });
+        for (const posting of tx.postings) {
+            const account = accountById.get(posting.accountId);
+            if (account === undefined) {
+                throw new LedgerError('account-not-found', `Beancount export: posting ${posting.id} references unknown account ${posting.accountId} — run the ledger verifier; the reference export refuses a damaged book`);
+            }
+            const name = names.get(posting.accountId) ?? beancountAccountName(account);
+            lines.push(`  ${name}  ${formatBeancountAmount(posting.amountMinor)} ${beancountCurrency(account.currency)}`);
+            if (typeof posting.memo === 'string' && posting.memo !== '') {
+                lines.push(`    lp-memo: ${quoteBeancountString(posting.memo)}`);
+            }
+            if (posting.cleared === 'cleared' || posting.cleared === 'reconciled') {
+                lines.push(`    lp-cleared: ${quoteBeancountString(posting.cleared)}`);
+            }
+        }
+        lines.push('');
+    }
+    // ── balance assertions after each CLOSED period ─────────────────────────────
+    // Only `closed` periods assert (a reopened period is history, not a live
+    // claim). Every account with a reported posting on or before the period end
+    // asserts its whole-book balance as of that end — income-statement accounts
+    // come out 0 after the closing sweep, so bean-check re-verifies the close.
+    const closed = periods
+        .filter((p) => p.status === 'closed')
+        .sort((a, b) => byteCompare(a.end, b.end) || byteCompare(a.start, b.start) || byteCompare(a.id, b.id));
+    for (const period of closed) {
+        lines.push(`; Balance assertions after closed period ${period.start} .. ${period.end}.`);
+        const assertDate = nextIsoDay(period.end);
+        for (const account of openOrder) {
+            const first = firstUse.get(account.id);
+            if (first === undefined || first > period.end)
+                continue;
+            const amounts = [];
+            for (const tx of reported) {
+                if (tx.date > period.end)
+                    continue;
+                for (const posting of tx.postings) {
+                    if (posting.accountId !== account.id)
+                        continue;
+                    if (!isValidMinor(posting.amountMinor)) {
+                        throw new MoneyRangeError(`Beancount export: posting ${posting.id} carries a non-integer amount — run the ledger verifier`);
+                    }
+                    amounts.push(posting.amountMinor);
+                }
+            }
+            const name = names.get(account.id) ?? beancountAccountName(account);
+            lines.push(`${assertDate} balance ${name} ${formatBeancountAmount(sumAmounts(amounts))} ${beancountCurrency(account.currency)}`);
+        }
+        lines.push('');
+    }
+    // Exactly one trailing newline: drop the trailing blank separator, join LF.
+    while (lines.length > 0 && lines[lines.length - 1] === '')
+        lines.pop();
+    return `${lines.join('\n')}\n`;
+}
+//# sourceMappingURL=ledgerBeancount.js.map

package/dist/ledgerBeancount.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledgerBeancount.js","sourceRoot":"","sources":["../src/ledgerBeancount.ts"],"names":[],"mappings":"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"}

package/dist/ledgerBeancountFixture.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Deterministic fixture books for the Beancount reference harness (LGR-13).
+ *
+ * The parity/bean-check gate needs a 500-transaction book; committing the
+ * serialized fixture would be megabytes of noise, so the GENERATOR is the
+ * artifact: seeded, pure, no clock — every call reproduces the identical book,
+ * so the exported journal is byte-identical across machines and runs (which is
+ * itself asserted by the byte-stability tests).
+ *
+ * Two books:
+ *  - {@link buildBeancountMiniBook} — small and hostile: names that need
+ *    mangling (spaces, unicode, lowercase, a bare-root name, a mangling
+ *    collision), quote/backslash/newline text, a reversal pair, evidence,
+ *    a closed period with its closing entry, and a draft (which must NOT
+ *    export);
+ *  - {@link buildBeancountParityBook} — exactly 500 reported (posted + void)
+ *    transactions across two currencies, with reversal pairs, a closed period
+ *    (closing entry + balance assertions), a reopened period (void closing
+ *    entry + reversal), evidence, and drafts.
+ *
+ * Exported from the SDK because three consumers must share ONE book: the sdk
+ * unit tests, the ui parity gate (which runs the plugin's LGR-8 fold through
+ * the real loader), and the CI bean-check job.
+ */
+import type { LedgerAccount, LedgerPeriod, LedgerTransaction } from './ledger';
+/** The entity slices {@link buildLedgerBeancount} consumes — one book. */
+export interface LedgerBeancountFixtureBook {
+    accounts: LedgerAccount[];
+    transactions: LedgerTransaction[];
+    periods: LedgerPeriod[];
+}
+/**
+ * The small hostile book: mangling edge cases, hostile text, a reversal pair,
+ * evidence, a closed period, and a draft that must not export.
+ */
+export declare function buildBeancountMiniBook(): LedgerBeancountFixtureBook;
+/** How many reported (posted + void) transactions the parity book carries. */
+export declare const BEANCOUNT_PARITY_TX_COUNT = 500;
+/**
+ * The 500-transaction parity book: two currencies, reversal pairs, one closed
+ * period (with closing entry — its balance assertions gate the close in
+ * bean-check), one reopened period, evidence, drafts.
+ */
+export declare function buildBeancountParityBook(): LedgerBeancountFixtureBook;
+/** Postings carried by {@link buildLedgerBenchBook} with default arguments. */
+export declare const LEDGER_BENCH_POSTING_COUNT = 10000;
+/**
+ * The LGR-15 benchmark book: `txCount` posted transactions of `legsPerTx`
+ * postings each (defaults: 1000 × 10 = {@link LEDGER_BENCH_POSTING_COUNT}
+ * postings). Seeded/deterministic like the parity book — the GENERATOR is the
+ * committed artifact, never the serialized data.
+ *
+ * Shape rationale: the trial-balance benchmark reads the book through
+ * `listTransactions`, whose hard cap is `LEDGER_MAX_TRANSACTION_LIMIT` (1000)
+ * — so the 10k postings ride on exactly 1000 transactions, which keeps the
+ * benchmarked read the SAME single-page read the report block performs on a
+ * real book. Single currency, no drafts/periods/evidence: the benchmark
+ * measures the arithmetic + read path, not fixture variety (the parity book
+ * covers variety).
+ */
+export declare function buildLedgerBenchBook(txCount?: number, legsPerTx?: number): LedgerBeancountFixtureBook;