@book.dev/sdk 3.5.0 → 3.6.0

package/dist/ledger.js

@@ -0,0 +1,493 @@
+/**
+ * Ledger contract (LGR-3): the shared types, typed errors, and pure audit-replay
+ * reducer for the server-enforced double-entry ledger.
+ *
+ * Data model: ledger data lives in FOUR server-managed OpenBook databases
+ * (accounts / transactions / postings / reconciliations) seeded on a restricted
+ * host page. Rows are ordinary pages; every ledger value is a database property.
+ * The server's `LedgerStore` is the ONLY writer — the generic page/row mutation
+ * surface (HTTP routes AND direct store calls) rejects writes to ledger rows, so
+ * the invariants hold in both server mode and browser-local (PGlite) mode.
+ *
+ * Money: amounts are SIGNED INTEGER MINOR UNITS (LGR-2, see `./money`). Amounts
+ * on the wire are integers — never parsed strings.
+ */
+/**
+ * HTTP status the API maps each {@link LedgerErrorCode} to.
+ *
+ * The three LGR-11 reconciliation rejections are 409, not 400: they are all
+ * "not valid for the CURRENT state of the book" rather than malformed requests.
+ * The identical call becomes legal once the open reconciliation is finished,
+ * once the difference reaches zero, or once the posting is posted — which is
+ * what tells a client to re-read and retry instead of fixing its payload.
+ */
+export function ledgerErrorStatus(code) {
+    switch (code) {
+        case 'not-initialized':
+        case 'not-found':
+            return 404;
+        case 'managed':
+        case 'immutable':
+        case 'reconciled-locked':
+            return 403;
+        // The three LGR-12 period rejections are state-of-the-book conflicts too:
+        // the identical call becomes legal once the period is reopened (or, for a
+        // close conflict, simply retried against the settled book). So is the LGR-14
+        // evidence rejection: the identical post becomes legal once evidence is
+        // attached to the draft (or the account's evidence-required toggle is turned
+        // off) — re-read and retry, don't fix the payload.
+        case 'invalid-state':
+        case 'nonzero-balance':
+        case 'reconciliation-exists':
+        case 'reconciliation-unbalanced':
+        case 'posting-not-reconcilable':
+        case 'reconciliation-too-large':
+        case 'period-closed':
+        case 'period-overlap':
+        case 'period-out-of-order':
+        case 'period-close-conflict':
+        case 'evidence-required':
+            return 409;
+        default:
+            return 400;
+    }
+}
+/**
+ * Typed ledger error. The server REJECTS invariant violations with these (never
+ * advises); the HTTP layer maps them to `{error, code}` bodies via
+ * {@link ledgerErrorStatus} and `HttpDataClient` re-materializes them, so a
+ * caller catches the same error class over either transport.
+ */
+export class LedgerError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.name = 'LedgerError';
+        this.code = code;
+    }
+}
+/** The set of valid codes, for wire-body → {@link LedgerError} re-materialization. */
+export const LEDGER_ERROR_CODES = [
+    'not-initialized',
+    'not-found',
+    'managed',
+    'immutable',
+    'unbalanced',
+    'too-few-postings',
+    'invalid-amount',
+    'account-not-found',
+    'account-closed',
+    'currency-mismatch',
+    'invalid-state',
+    'nonzero-balance',
+    'reconciled-locked',
+    'reconciliation-exists',
+    'reconciliation-unbalanced',
+    'posting-not-reconcilable',
+    'reconciliation-too-large',
+    'period-closed',
+    'period-overlap',
+    'period-out-of-order',
+    'period-close-conflict',
+    'evidence-required',
+    'invalid-input',
+];
+// ── Domain enums ───────────────────────────────────────────────────────────────
+export const LEDGER_ACCOUNT_TYPES = ['asset', 'liability', 'equity', 'revenue', 'expense'];
+export const LEDGER_ACCOUNT_STATUSES = ['open', 'closed'];
+export const LEDGER_TRANSACTION_STATES = ['draft', 'posted', 'void'];
+export const LEDGER_CLEARED_STATES = ['pending', 'cleared', 'reconciled'];
+/**
+ * A reconciliation's lifecycle (LGR-11 + LGR-22).
+ *
+ * `abandoned` is a TERMINAL status, not a deletion: a statement someone opened
+ * against the wrong closing balance still happened, and the record of it — with
+ * the audit events that amended and ended it — is what lets a later reader tell
+ * "this account was never reconciled" apart from "this attempt was given up on".
+ * It is invisible to the one-open-per-account rule (which asks only for `open`),
+ * so abandoning immediately frees the account for a fresh start.
+ */
+export const LEDGER_RECONCILIATION_STATUSES = ['open', 'finished', 'abandoned'];
+/**
+ * A period's lifecycle (LGR-12). `reopened` is TERMINAL for the RECORD, not for
+ * the range: reopening keeps the row (with the reversal that voided its closing
+ * entry) so the settings UI and the audit trail can show that a close happened
+ * and was undone; closing the range again writes a NEW period record. Only
+ * `closed` periods lock dates.
+ */
+export const LEDGER_PERIOD_STATUSES = ['closed', 'reopened'];
+/**
+ * The account types a period close sweeps into retained earnings (LGR-12): the
+ * income-statement ("flow") accounts. ONE list, exported, because the server's
+ * closing-entry generator and any report fold that classifies flow accounts
+ * must agree — this epic's recurring defect is two copies of one fact.
+ */
+export const LEDGER_INCOME_STATEMENT_ACCOUNT_TYPES = ['revenue', 'expense'];
+/** Whether `type` names an income-statement (flow) account. */
+export function isIncomeStatementAccountType(type) {
+    return LEDGER_INCOME_STATEMENT_ACCOUNT_TYPES.includes(type);
+}
+// ── Read bounds ────────────────────────────────────────────────────────────────
+/**
+ * The server's HARD CAP on one `listTransactions` page: a larger `limit` is
+ * clamped to this, silently.
+ *
+ * Exported because a reader that totals what it fetched — a report — cannot
+ * tell a full page from a complete book without it, and a duplicated literal
+ * would rot: if this cap ever dropped, a report asking for the old number would
+ * be clamped, conclude it had read everything, and render a PARTIAL total as a
+ * complete one. Both the server clamp and the ledger plugin's report read this
+ * one constant, and `ledger.test.ts` asserts the clamp actually holds.
+ */
+export const LEDGER_MAX_TRANSACTION_LIMIT = 1000;
+/** The page size `listTransactions` uses when the caller names none. */
+export const LEDGER_DEFAULT_TRANSACTION_LIMIT = 500;
+// ── Property ids (stable — the seeded database schemas key rows by these) ──────
+/** Stable property ids for the seeded ledger database schemas. */
+export const LEDGER_PROP = {
+    account: {
+        type: 'lp_type',
+        status: 'lp_status',
+        currency: 'lp_currency',
+        /** LGR-14: `true` on an account that refuses to accept a posting from an
+         *  entry with no evidence attached; absent everywhere else (additive — no
+         *  migration, pre-LGR-14 accounts read back `false`). */
+        evidenceRequired: 'lp_evidence_required',
+    },
+    transaction: {
+        date: 'lp_date',
+        description: 'lp_description',
+        state: 'lp_state',
+        postedAt: 'lp_posted_at',
+        postedBy: 'lp_posted_by',
+        reverses: 'lp_reverses',
+        evidence: 'lp_evidence',
+        entryNo: 'lp_entry_no',
+        /** LGR-12: `'closing'` on a period-close entry; absent on ordinary entries. */
+        kind: 'lp_kind',
+    },
+    posting: {
+        transaction: 'lp_transaction',
+        account: 'lp_account',
+        amount: 'lp_amount_minor',
+        cleared: 'lp_cleared',
+        reconciliation: 'lp_reconciliation',
+        memo: 'lp_memo',
+    },
+    reconciliation: {
+        account: 'lp_account',
+        statementDate: 'lp_statement_date',
+        statementBalance: 'lp_statement_balance_minor',
+        status: 'lp_status',
+    },
+};
+/**
+ * THE period predicate (LGR-12), shared by the store's post/reverse guards and
+ * every UI surface that wants to say WHY a date is refused: the `closed` period
+ * containing `date`, or `null`. Pure; string comparison is safe because both
+ * sides are ISO `YYYY-MM-DD`.
+ */
+export function closedPeriodContaining(periods, date) {
+    for (const period of periods) {
+        if (period.status !== 'closed')
+            continue;
+        if (period.start <= date && date <= period.end)
+            return period;
+    }
+    return null;
+}
+/**
+ * Every CLOSED period overlapping the inclusive range `[from, to]` (`''` means
+ * open at that end) — the display-only "this report crosses a closed period"
+ * marker the report blocks render. Sorted by start date so the marker reads in
+ * calendar order.
+ */
+export function closedPeriodsOverlapping(periods, from, to) {
+    return periods
+        .filter((p) => p.status === 'closed' && (to === '' || p.start <= to) && (from === '' || from <= p.end))
+        .sort((a, b) => (a.start < b.start ? -1 : a.start > b.start ? 1 : a.id < b.id ? -1 : 1));
+}
+/**
+ * Every known audit action — the validation set for a stored `action` value.
+ *
+ * `as const satisfies` (not a widened annotation) so the array's element type is
+ * the literal union: adding a member to {@link LedgerAuditAction} without adding
+ * it here is then caught by the exhaustiveness check below at COMPILE time,
+ * rather than surfacing at runtime as a log this build refuses to interpret.
+ */
+export const LEDGER_AUDIT_ACTIONS = [
+    'ledger.init',
+    'ledger.acl',
+    'account.create',
+    'account.update',
+    'transaction.create',
+    'transaction.update',
+    'transaction.delete',
+    'transaction.post',
+    'transaction.reverse',
+    'posting.cleared',
+    'reconciliation.start',
+    'reconciliation.finish',
+    'reconciliation.reopen',
+    'reconciliation.amend',
+    'reconciliation.abandon',
+    'period.close',
+    'period.reopen',
+    'ledger.autoExportPath',
+    'ledger.restore',
+];
+/**
+ * Compile-time exhaustiveness: every {@link LedgerAuditAction} must appear in
+ * {@link LEDGER_AUDIT_ACTIONS}. If a new union member is added without listing
+ * it, this assignment fails to typecheck (the union is not assignable to the
+ * array's narrower element type).
+ */
+const _LEDGER_AUDIT_ACTIONS_EXHAUSTIVE = null;
+void _LEDGER_AUDIT_ACTIONS_EXHAUSTIVE;
+/**
+ * Pure reducer: fold the audit event stream (ascending `seq`) into the expected
+ * current ledger state. Deterministic and side-effect free — the replay test
+ * compares this against the live store to prove the audit log is a complete
+ * record of every ledger mutation.
+ */
+export function replayLedgerAudit(events) {
+    const state = { initialized: false, accounts: {}, transactions: {}, reconciliations: {}, periods: {} };
+    /** Apply one recorded posting change to the replayed transaction holding it. */
+    const applyPostingChange = (change) => {
+        const tx = state.transactions[change.transactionId];
+        if (!tx)
+            return;
+        state.transactions[change.transactionId] = {
+            ...tx,
+            postings: tx.postings.map((p) => p.id === change.postingId ? { ...p, cleared: change.cleared, reconciliationId: change.reconciliationId } : p),
+        };
+    };
+    for (const ev of events) {
+        // An action this reducer does not know about means the log records a
+        // mutation the replay cannot account for — so the reconstruction would be
+        // silently INCOMPLETE (state drifting from the books with no signal). That
+        // is exactly the failure a replayable audit log exists to rule out, so it is
+        // a hard error, not a skipped iteration. Any new action MUST land here.
+        const p = ev.payload;
+        switch (ev.action) {
+            case 'ledger.init':
+                state.initialized = true;
+                break;
+            case 'ledger.acl':
+                // A sharing grant/revoke on a ledger page: recorded for the trail, but it
+                // carries no ledger CONTENT, so replayed state is unchanged.
+                break;
+            case 'ledger.autoExportPath':
+                // An instance-policy change (where the canonical export is written):
+                // recorded for the trail, but it touches no ledger entity, so replayed
+                // state is unchanged. Explicit rather than falling through to `default`,
+                // which must keep throwing on actions this build genuinely cannot model.
+                break;
+            case 'ledger.restore':
+                // A bundle's history was installed (LGR-15): provenance for the trail —
+                // the restored entity events precede this one and already carry all the
+                // content, so replayed state is unchanged. Explicit for the same reason
+                // as `autoExportPath` above.
+                break;
+            case 'account.create':
+            case 'account.update':
+                if (p.account)
+                    state.accounts[p.account.id] = p.account;
+                break;
+            case 'transaction.create':
+            case 'transaction.update':
+            case 'transaction.post':
+                if (p.transaction)
+                    state.transactions[p.transaction.id] = p.transaction;
+                break;
+            case 'transaction.delete':
+                if (p.transactionId)
+                    delete state.transactions[p.transactionId];
+                break;
+            case 'transaction.reverse':
+                if (p.transaction)
+                    state.transactions[p.transaction.id] = p.transaction;
+                if (p.originalId && state.transactions[p.originalId]) {
+                    state.transactions[p.originalId] = {
+                        ...state.transactions[p.originalId],
+                        state: p.originalState ?? 'void',
+                    };
+                }
+                break;
+            case 'posting.cleared':
+                if (p.transactionId && p.postingId && p.cleared && state.transactions[p.transactionId]) {
+                    const tx = state.transactions[p.transactionId];
+                    state.transactions[p.transactionId] = {
+                        ...tx,
+                        postings: tx.postings.map((post) => (post.id === p.postingId ? { ...post, cleared: p.cleared } : post)),
+                    };
+                }
+                break;
+            case 'reconciliation.start':
+            case 'reconciliation.amend':
+            case 'reconciliation.abandon':
+                // ROW-ONLY events. Neither an amend nor an abandon touches a posting —
+                // that is the LGR-22 guarantee, stated here as well as enforced in the
+                // store — so unlike finish/reopen below there is no posting change to
+                // apply, and a payload that carried one would be a bug in the writer.
+                if (p.reconciliation)
+                    state.reconciliations[p.reconciliation.id] = p.reconciliation;
+                break;
+            case 'reconciliation.finish':
+            case 'reconciliation.reopen':
+                // ONE event, TWO effects: the reconciliation's new status, and the
+                // cleared/reconciliationId state of every posting it froze or unfroze.
+                // Both must land, or the replayed postings drift from the book and the
+                // verifier's content-hash comparison reports a clean ledger as tampered.
+                if (p.reconciliation)
+                    state.reconciliations[p.reconciliation.id] = p.reconciliation;
+                for (const change of p.postings ?? [])
+                    applyPostingChange(change);
+                break;
+            case 'period.close':
+                // ONE event, TWO effects (LGR-12): the period record, and the closing
+                // entry it posted (absent when the range held nothing to close).
+                if (p.period)
+                    state.periods[p.period.id] = p.period;
+                if (p.transaction)
+                    state.transactions[p.transaction.id] = p.transaction;
+                break;
+            case 'period.reopen':
+                // The reversal pair rides in the same shape `transaction.reverse` uses:
+                // the reversal lands, and the original closing entry flips to void.
+                if (p.period)
+                    state.periods[p.period.id] = p.period;
+                if (p.transaction)
+                    state.transactions[p.transaction.id] = p.transaction;
+                if (p.originalId && state.transactions[p.originalId]) {
+                    state.transactions[p.originalId] = {
+                        ...state.transactions[p.originalId],
+                        state: p.originalState ?? 'void',
+                    };
+                }
+                break;
+            default:
+                throw new LedgerError('invalid-state', `replayLedgerAudit: unknown audit action ${JSON.stringify(ev.action)} — the replay cannot reconstruct state it does not model`);
+        }
+    }
+    return state;
+}
+/**
+ * The tamper-evidence hash of ONE audit event: SHA-256 over its canonical
+ * content INCLUDING `prevHash`, which is what links each event to its
+ * predecessor. Async because it uses WebCrypto (isomorphic: Node, browser,
+ * sidecar). `seq` is deliberately part of the hashed content, so renumbering
+ * events breaks the chain just as rewriting one does.
+ */
+export async function ledgerAuditEventHash(event) {
+    const canonical = canonicalLedgerJson({
+        seq: event.seq,
+        id: event.id,
+        actorSubject: event.actorSubject,
+        actorName: event.actorName,
+        action: event.action,
+        entityIds: event.entityIds,
+        payload: event.payload,
+        beforeHash: event.beforeHash,
+        afterHash: event.afterHash,
+        prevHash: event.prevHash,
+        createdAt: event.createdAt,
+    });
+    const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(canonical));
+    return Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * Verify the audit log's hash chain over `events` (ASCENDING `seq`, contiguous
+ * from the genesis event). Each event must carry its predecessor's
+ * {@link ledgerAuditEventHash} in `prevHash`; the first must carry `null`.
+ *
+ * THE PRECISE GUARANTEE — a green result is NOT "this log is authentic":
+ *
+ *  - DETECTED: any edit, reordering, or middle deletion whose perpetrator does
+ *    not also recompute every following link. That covers the realistic
+ *    accident-and-opportunist cases (a stray `UPDATE`, a row deleted to hide one
+ *    entry), and it distinguishes a deleted event from the innocuous BIGSERIAL
+ *    gap a rolled-back transaction leaves.
+ *  - NOT DETECTED: truncation of the HEAD or the TAIL — a prefix or suffix of
+ *    the log removed wholesale still verifies clean, because nothing in the data
+ *    states where the chain is supposed to start or end. Nor a WHOLESALE REWRITE:
+ *    this hash is unkeyed and this function is exported, so an actor with
+ *    database access can rewrite every event and recompute every link.
+ *
+ * Detecting those requires an off-box ANCHOR — periodically publishing the tail
+ * hash somewhere the database's owner cannot rewrite — which is tracked
+ * separately (LGR-18) and is not implemented here. Treat this as integrity
+ * against tampering that does not control the whole log, not as a signature.
+ *
+ * Verifying a PAGE of the log (not starting at genesis) is supported: pass the
+ * slice and it checks the links WITHIN it, reporting the first break.
+ */
+export async function verifyLedgerAuditChain(events) {
+    let expectedPrev = undefined; // undefined = first seen
+    for (let i = 0; i < events.length; i += 1) {
+        const event = events[i];
+        if (i > 0 && event.seq <= events[i - 1].seq) {
+            return { ok: false, checked: i, brokenAtSeq: event.seq, reason: 'events are not in ascending seq order' };
+        }
+        if (expectedPrev !== undefined && event.prevHash !== expectedPrev) {
+            return {
+                ok: false,
+                checked: i,
+                brokenAtSeq: event.seq,
+                reason: `prevHash mismatch: expected ${String(expectedPrev)}, got ${String(event.prevHash)} — an event was rewritten, reordered, or removed`,
+            };
+        }
+        expectedPrev = await ledgerAuditEventHash(event);
+    }
+    return { ok: true, checked: events.length, brokenAtSeq: null, reason: null };
+}
+/**
+ * Canonical JSON of an entity for audit content-hashing: keys sorted at every
+ * depth, so a byte-identical serialization is independent of insertion order.
+ */
+export function canonicalLedgerJson(value) {
+    const sortValue = (v) => {
+        if (Array.isArray(v))
+            return v.map(sortValue);
+        if (v !== null && typeof v === 'object') {
+            const out = {};
+            for (const key of Object.keys(v).sort()) {
+                out[key] = sortValue(v[key]);
+            }
+            return out;
+        }
+        return v;
+    };
+    return JSON.stringify(sortValue(value));
+}
+/**
+ * Validate a hierarchical, colon-delimited account name (`Assets:Bank:Checking`):
+ * one or more non-empty, non-whitespace-only segments separated by single colons.
+ */
+export function isValidLedgerAccountName(name) {
+    if (typeof name !== 'string' || name.trim() === '')
+        return false;
+    return name.split(':').every((seg) => seg.trim().length > 0);
+}
+/** Validate an ISO `YYYY-MM-DD` date string (a real calendar date). */
+export function isValidLedgerDate(date) {
+    if (typeof date !== 'string' || !/^\d{4}-\d{2}-\d{2}$/.test(date))
+        return false;
+    const parsed = new Date(`${date}T00:00:00Z`);
+    return !Number.isNaN(parsed.getTime()) && parsed.toISOString().slice(0, 10) === date;
+}
+/**
+ * The ADVISORY band of the finding-code union (LGR-14 Q3): codes that report
+ * "the book does not satisfy today's POLICY", never "storage was tampered
+ * with". Every other code is the tamper band. Keyed off the code union — not
+ * message text — because exit policies and alerting hang off this distinction:
+ * `--verify-ledger` exits 0 on an advisory-only report (still printed), so a
+ * healthy book that enables evidence-required over bare history does not turn
+ * every backup-verification script permanently red and teach operators to
+ * ignore the one alarm that matters. Any future advisory code MUST land here.
+ */
+export const LEDGER_VERIFY_ADVISORY_CODES = ['evidence-required-missing'];
+/** Whether `code` is an advisory (current-policy) finding, not a tamper one. */
+export function isLedgerVerifyAdvisory(code) {
+    return LEDGER_VERIFY_ADVISORY_CODES.includes(code);
+}
+//# sourceMappingURL=ledger.js.map

package/dist/ledger.js.map

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

package/dist/ledgerBeancount.d.ts

@@ -0,0 +1,117 @@
+/**
+ * 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 { type LedgerAccount, type LedgerAccountType, type LedgerPeriod, type LedgerTransaction } 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 declare const BEANCOUNT_ROOT_BY_TYPE: Readonly<Record<LedgerAccountType, string>>;
+/**
+ * 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 declare function formatBeancountAmount(minor: number): string;
+/**
+ * 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 declare function quoteBeancountString(value: string): string;
+/**
+ * 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 declare function mangleBeancountComponent(segment: string): string;
+/**
+ * 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 declare function beancountAccountName(account: Pick<LedgerAccount, 'name' | 'type'>): string;
+/**
+ * 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 declare function buildBeancountAccountNames(accounts: readonly LedgerAccount[]): Map<string, string>;
+/**
+ * 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 declare function buildLedgerBeancount(accounts: readonly LedgerAccount[], transactions: readonly LedgerTransaction[], periods: readonly LedgerPeriod[]): string;