@crewhaus/tool-ledger 0.7.0

package/dist/lib/amount.d.ts

@@ -0,0 +1,73 @@
+import { CrewhausError } from "@crewhaus/errors";
+import { decimalKernel } from "@crewhaus/tool-math";
+/** Every refusal this package makes, so a caller can tell one from a crash. */
+export declare class LedgerError extends CrewhausError {
+    readonly name = "LedgerError";
+    constructor(message: string);
+}
+export declare const ROUNDING_MODES: readonly ["halfUp", "halfEven", "halfDown", "ceiling", "floor", "up", "down"];
+export type RoundingMode = decimalKernel.RoundingMode;
+/**
+ * Half-even everywhere rounding is unavoidable. It is the mode that does not
+ * drift upward over a long series of conversions, which is the whole of what a
+ * ledger is.
+ */
+export declare const LEDGER_ROUNDING: RoundingMode;
+/** The minor-unit exponent for a currency, refusing a code nobody knows. */
+export declare function exponentFor(currency: string, override?: number): number;
+/** Minor units rendered as a major-unit decimal string: 1050 @2 -> "10.50". */
+export declare function formatMajor(minor: bigint, exponent: number): string;
+/**
+ * A major-unit decimal string ("100.00", "-3.5") as minor units.
+ *
+ * A fraction longer than the currency's exponent is REFUSED. Rounding it here
+ * would mean the entry posts an amount the source document does not contain,
+ * and the difference is invisible until a reconciliation a year later.
+ */
+export declare function parseMajor(text: string, exponent: number, label: string): bigint;
+/** An integer count of minor units, from a string or a safe integer. */
+export declare function parseMinorUnits(value: string | number, label: string): bigint;
+/** A decimal factor — an fx rate, a quantity — parsed exactly. */
+export declare function parseFactor(text: string, label: string): decimalKernel.Decimal;
+/** Multiply minor units by an exact decimal and round once, at the end. */
+export declare function multiplyMinor(minor: bigint, factor: decimalKernel.Decimal, mode?: RoundingMode): bigint;
+/** Apply an fx rate, honouring both currencies' exponents, rounding once. */
+export declare function convertMinor(minor: bigint, rate: decimalKernel.Decimal, fromExponent: number, toExponent: number, mode?: RoundingMode): bigint;
+/**
+ * A calendar date, validated against the calendar.
+ *
+ * `Date.parse` accepts "2026-02-30" and rolls it to 2 March, which puts an
+ * entry in the wrong month without anybody typing a wrong month. The round
+ * trip through the constructed date is what catches it.
+ */
+export declare function assertIsoDate(text: string, label: string): string;
+/** Whole days since the epoch, in UTC. Dates are compared and differenced here. */
+export declare function epochDay(isoDate: string): number;
+/** Signed day difference, `a - b`. */
+export declare function dayDiff(a: string, b: string): number;
+/** The year an invoice sequence resets on comes from the DOCUMENT, not the clock. */
+export declare function yearOf(isoDate: string): string;
+/**
+ * An ISO-8601 instant that carries a UTC offset.
+ *
+ * Matches `@crewhaus/tool-money`'s rule: an offset-less string means local
+ * time per ECMAScript, so the same posting would carry a different instant on
+ * two machines — and the instant is inside the hash chain.
+ */
+export declare function assertInstant(text: string, label: string): string;
+/**
+ * JSON with every object key in codepoint order and no incidental whitespace.
+ *
+ * This is what the hash chain and every idempotency fingerprint are taken
+ * over, so it has to be stable against the one thing JSON is not stable
+ * against: insertion order. A bigint serializes as its decimal string, and a
+ * non-integer number is refused outright — a float in the bytes that identify
+ * a payment is the defect this whole package exists to avoid.
+ */
+export declare function canonicalJson(value: unknown): string;
+/** Locale-independent string order. */
+export declare function byString(a: string, b: string): number;
+/** SHA-256 hex of a string. The chain link and every fingerprint use this. */
+export declare function sha256Hex(text: string): string;
+/** Compact JSON — every byte returned is a byte in somebody's context window. */
+export declare const json: (value: unknown) => string;

package/dist/lib/amount.js

@@ -0,0 +1,204 @@
+/**
+ * Amounts, dates and the canonical bytes everything else is hashed over.
+ *
+ * Three rules hold everywhere below this line, and each of them is a bug that
+ * has shipped in somebody's books:
+ *
+ * 1. **No float ever touches an amount.** Every amount is a bigint count of
+ *    minor units. The arithmetic and the ISO 4217 exponent table come from
+ *    `@crewhaus/tool-math`'s money kernel rather than from a second copy here
+ *    — a JPY exponent guessed at 2 is a 100x error, and there is exactly one
+ *    table in this repo that knows it is 0.
+ * 2. **A scale the currency cannot hold is refused, not rounded.** "1.005" as
+ *    USD is not $1.01; it is a caller who has not decided. A ledger that
+ *    rounds an input silently is a ledger whose total disagrees with the
+ *    document it was posted from.
+ * 3. **Totals accumulate in bigint, not in a JS number.** A single amount fits
+ *    a safe integer — that is why `@crewhaus/tool-money` types one as
+ *    `number` and this package matches it at the tool boundary — but a year of
+ *    them summed does not, and SQLite's own `SUM()` silently promotes a
+ *    64-bit overflow to a float. So amounts are STORED as text and summed
+ *    here.
+ */
+import { createHash } from "node:crypto";
+import { CrewhausError } from "@crewhaus/errors";
+import { decimalKernel, moneyKernel } from "@crewhaus/tool-math";
+/** Every refusal this package makes, so a caller can tell one from a crash. */
+export class LedgerError extends CrewhausError {
+    name = "LedgerError";
+    constructor(message) {
+        super("tool", message);
+    }
+}
+export const ROUNDING_MODES = decimalKernel.ROUNDING_MODES;
+/**
+ * Half-even everywhere rounding is unavoidable. It is the mode that does not
+ * drift upward over a long series of conversions, which is the whole of what a
+ * ledger is.
+ */
+export const LEDGER_ROUNDING = "halfEven";
+/** The minor-unit exponent for a currency, refusing a code nobody knows. */
+export function exponentFor(currency, override) {
+    try {
+        return moneyKernel.minorUnitExponent(currency, override);
+    }
+    catch (err) {
+        throw new LedgerError(err instanceof Error ? err.message : String(err));
+    }
+}
+/** Minor units rendered as a major-unit decimal string: 1050 @2 -> "10.50". */
+export function formatMajor(minor, exponent) {
+    return moneyKernel.formatMinor(minor, exponent);
+}
+/**
+ * A major-unit decimal string ("100.00", "-3.5") as minor units.
+ *
+ * A fraction longer than the currency's exponent is REFUSED. Rounding it here
+ * would mean the entry posts an amount the source document does not contain,
+ * and the difference is invisible until a reconciliation a year later.
+ */
+export function parseMajor(text, exponent, label) {
+    let parsed;
+    try {
+        parsed = decimalKernel.parseDecimal(text);
+    }
+    catch (err) {
+        throw new LedgerError(`${label} ("${text}") is not a decimal number: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (parsed.scale > exponent) {
+        throw new LedgerError(`${label} ("${text}") has ${parsed.scale} decimal places but this currency has ${exponent} — refusing to round an amount that was written down, decide the rounding before posting it`);
+    }
+    return parsed.unscaled * decimalKernel.pow10(exponent - parsed.scale);
+}
+/** An integer count of minor units, from a string or a safe integer. */
+export function parseMinorUnits(value, label) {
+    try {
+        return moneyKernel.toMinor(value, label);
+    }
+    catch (err) {
+        throw new LedgerError(err instanceof Error ? err.message : String(err));
+    }
+}
+/** A decimal factor — an fx rate, a quantity — parsed exactly. */
+export function parseFactor(text, label) {
+    try {
+        return decimalKernel.parseDecimal(text);
+    }
+    catch (err) {
+        throw new LedgerError(`${label} ("${text}") is not a decimal number: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Multiply minor units by an exact decimal and round once, at the end. */
+export function multiplyMinor(minor, factor, mode = LEDGER_ROUNDING) {
+    return moneyKernel.moneyMultiply(minor, factor, mode).rounded;
+}
+/** Apply an fx rate, honouring both currencies' exponents, rounding once. */
+export function convertMinor(minor, rate, fromExponent, toExponent, mode = LEDGER_ROUNDING) {
+    return moneyKernel.convertMinor(minor, rate, fromExponent, toExponent, mode);
+}
+// ---------------------------------------------------------------------------
+// dates
+// ---------------------------------------------------------------------------
+const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
+/**
+ * A calendar date, validated against the calendar.
+ *
+ * `Date.parse` accepts "2026-02-30" and rolls it to 2 March, which puts an
+ * entry in the wrong month without anybody typing a wrong month. The round
+ * trip through the constructed date is what catches it.
+ */
+export function assertIsoDate(text, label) {
+    const m = ISO_DATE.exec(text);
+    if (!m) {
+        throw new LedgerError(`${label} ("${text}") must be an ISO calendar date, YYYY-MM-DD`);
+    }
+    const [, y, mo, d] = m;
+    const at = new Date(Date.UTC(Number(y), Number(mo) - 1, Number(d)));
+    if (at.getUTCFullYear() !== Number(y) ||
+        at.getUTCMonth() + 1 !== Number(mo) ||
+        at.getUTCDate() !== Number(d)) {
+        throw new LedgerError(`${label} ("${text}") is not a date that exists`);
+    }
+    return text;
+}
+/** Whole days since the epoch, in UTC. Dates are compared and differenced here. */
+export function epochDay(isoDate) {
+    const m = ISO_DATE.exec(isoDate);
+    if (!m)
+        throw new LedgerError(`"${isoDate}" is not an ISO calendar date`);
+    const [, y, mo, d] = m;
+    return Math.floor(Date.UTC(Number(y), Number(mo) - 1, Number(d)) / 86_400_000);
+}
+/** Signed day difference, `a - b`. */
+export function dayDiff(a, b) {
+    return epochDay(a) - epochDay(b);
+}
+/** The year an invoice sequence resets on comes from the DOCUMENT, not the clock. */
+export function yearOf(isoDate) {
+    return isoDate.slice(0, 4);
+}
+/**
+ * An ISO-8601 instant that carries a UTC offset.
+ *
+ * Matches `@crewhaus/tool-money`'s rule: an offset-less string means local
+ * time per ECMAScript, so the same posting would carry a different instant on
+ * two machines — and the instant is inside the hash chain.
+ */
+export function assertInstant(text, label) {
+    if (!/(?:Z|[+-]\d{2}:?\d{2})$/i.test(text.trim())) {
+        throw new LedgerError(`${label} ("${text}") has no UTC offset — write it as e.g. 2026-01-01T00:00:00Z, because an offset-less string means local time and would hash differently on two machines`);
+    }
+    const parsed = Date.parse(text);
+    if (Number.isNaN(parsed))
+        throw new LedgerError(`${label} ("${text}") is not a valid instant`);
+    return new Date(parsed).toISOString();
+}
+// ---------------------------------------------------------------------------
+// canonical bytes
+// ---------------------------------------------------------------------------
+/**
+ * JSON with every object key in codepoint order and no incidental whitespace.
+ *
+ * This is what the hash chain and every idempotency fingerprint are taken
+ * over, so it has to be stable against the one thing JSON is not stable
+ * against: insertion order. A bigint serializes as its decimal string, and a
+ * non-integer number is refused outright — a float in the bytes that identify
+ * a payment is the defect this whole package exists to avoid.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+function canonicalize(value) {
+    if (typeof value === "bigint")
+        return value.toString();
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new LedgerError("a non-finite number cannot be canonicalized");
+        return value;
+    }
+    if (value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    const source = value;
+    const out = {};
+    // Codepoint order, never `localeCompare` — a locale-aware sort is not the
+    // same order on two machines, and the hash would move with it.
+    for (const key of Object.keys(source).sort(byString)) {
+        const entry = source[key];
+        if (entry === undefined)
+            continue;
+        out[key] = canonicalize(entry);
+    }
+    return out;
+}
+/** Locale-independent string order. */
+export function byString(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** SHA-256 hex of a string. The chain link and every fingerprint use this. */
+export function sha256Hex(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+/** Compact JSON — every byte returned is a byte in somebody's context window. */
+export const json = (value) => JSON.stringify(value);

package/dist/lib/db.d.ts

@@ -0,0 +1,171 @@
+/**
+ * The store: one `bun:sqlite` file, opened the way `@crewhaus/durable-state`
+ * opens one, with the whole of a posting inside a single `BEGIN IMMEDIATE`.
+ *
+ * THE INVARIANT THIS FILE EXISTS FOR
+ *
+ * A posting is three writes that are only correct together: the rows, the hash
+ * chain's new head, and the idempotency claim that says this batch has been
+ * seen. Commit them separately and there is a window in which the process can
+ * die leaving a ledger whose chain verifies perfectly and whose duplicate
+ * suppression has forgotten the entry — so the retry posts the same payment a
+ * second time, and every check anybody runs says the books are fine. Invoice
+ * numbering has the same shape from the other side: allocate the number, die
+ * before the document is recorded, and the sequence has a gap, which in most
+ * jurisdictions is not untidiness but a finding.
+ *
+ * So every mutation below happens inside ONE `tx.immediate(...)`. `IMMEDIATE`
+ * takes the write lock at BEGIN rather than at the first write, which is what
+ * makes the read half (is this key claimed? what is the chain head? what is the
+ * next invoice number?) serialize against another writer instead of racing it;
+ * `busy_timeout` is what makes the loser wait rather than fail instantly. Bun's
+ * `db.transaction()` rolls the whole thing back on a throw, so a failure
+ * anywhere in the batch leaves the file exactly as it was — no rows, no claim,
+ * no advanced head, no burnt invoice number.
+ *
+ * Amounts are stored as TEXT holding a bigint's decimal digits. SQLite would
+ * take them as INTEGER, but `bun:sqlite` hands an INTEGER column back as a JS
+ * number, and `SUM()` over one silently becomes a float once it overflows —
+ * both of which lose exactly the pennies this package is for.
+ */
+import { Database } from "bun:sqlite";
+/** Bumped when the on-disk shape changes. A mismatch is refused, never migrated silently. */
+export declare const SCHEMA_VERSION = 1;
+/** The `prev_hash` of the first entry. Nothing precedes it. */
+export declare const GENESIS_HASH: string;
+/** How long a writer waits for another writer's lock before giving up. */
+export declare const DEFAULT_BUSY_TIMEOUT_MS = 5000;
+/** The five account types, and the side each one increases on. */
+export declare const ACCOUNT_TYPES: readonly ["asset", "liability", "equity", "income", "expense"];
+export type AccountType = (typeof ACCOUNT_TYPES)[number];
+/**
+ * Which side an account's balance is normally on.
+ *
+ * This lives with the chart of accounts, never in a query. A P&L that decides
+ * the sign of "revenue" by looking at the account's name is a report that is
+ * wrong the first time somebody calls an account "Revenue refunds".
+ */
+export declare const NORMAL_BALANCE: Readonly<Record<AccountType, "debit" | "credit">>;
+export type AccountRow = {
+    readonly code: string;
+    readonly name: string;
+    readonly type: AccountType;
+};
+export type EntryRow = {
+    readonly seq: number;
+    readonly entry_id: string;
+    readonly date: string;
+    readonly memo: string;
+    readonly reference: string;
+    readonly tags: string;
+    readonly source_system: string | null;
+    readonly source_id: string | null;
+    readonly base_currency: string;
+    readonly posted_at: string;
+    readonly prev_hash: string;
+    readonly hash: string;
+};
+export type LineRow = {
+    readonly entry_seq: number;
+    readonly idx: number;
+    readonly account: string;
+    readonly debit_minor: string;
+    readonly credit_minor: string;
+    readonly currency: string;
+    readonly exponent: number;
+    readonly fx_rate: string | null;
+    readonly base_debit_minor: string;
+    readonly base_credit_minor: string;
+    readonly counterparty: string | null;
+    readonly due_date: string | null;
+    readonly line_memo: string | null;
+};
+export type DocumentRow = {
+    readonly number: string;
+    readonly kind: string;
+    readonly sequence_name: string;
+    readonly ordinal: number;
+    readonly issue_date: string;
+    readonly idempotency_key: string;
+    readonly payload_hash: string;
+    readonly files: string;
+    readonly created_at: string;
+};
+export type OpenMode = "read" | "write";
+/**
+ * Open the ledger file.
+ *
+ * `read` opens with SQLite's own read-only flag rather than a promise to
+ * behave: `LedgerQuery` and `LedgerReconcile` are declared read-only tools,
+ * and a declaration the database does not enforce is a comment. It also means
+ * a query against a ledger that does not exist is a refusal naming the path,
+ * not an empty ledger conjured into existence by the act of reading it.
+ */
+export declare function openDb(realPath: string, mode: OpenMode, busyTimeoutMs: number, 
+/**
+ * What to call the file in a message. Every other refusal in this package
+ * names the workspace-relative path, and this one used to name the absolute
+ * one — putting the machine's home directory into a result that goes
+ * straight into a model's context. Defaults to the real path for the
+ * in-memory and direct-library callers, which have no relative form.
+ */
+label?: string): Database;
+export declare function readMeta(db: Database, key: string): string | null;
+export declare function writeMeta(db: Database, key: string, value: string): void;
+/** The chain's tip: the last entry's hash and how many entries it covers. */
+export type ChainHead = {
+    readonly hash: string;
+    readonly length: number;
+};
+/**
+ * The head is stored, not derived.
+ *
+ * A prefix of a valid hash chain is itself a valid hash chain, so recomputing
+ * the head from the rows cannot tell a complete ledger from one somebody
+ * truncated. The stored head can: `length` disagreeing with the row count is
+ * the only evidence that entries were removed.
+ */
+export declare function readHead(db: Database): ChainHead;
+/** The bytes one entry's hash is taken over. Order is fixed by canonicalJson. */
+export declare function entryHash(prevHash: string, payload: unknown): string;
+export type ChainVerification = {
+    readonly ok: boolean;
+    readonly entries: number;
+    readonly head: string;
+    readonly storedHead: string;
+    readonly storedLength: number;
+    readonly problems: ReadonlyArray<{
+        readonly seq: number | null;
+        readonly reason: string;
+    }>;
+};
+/**
+ * Walk the chain from the genesis hash and report every break.
+ *
+ * Reports ALL of them rather than the first: "the chain broke at entry 4" and
+ * "the chain broke at entries 4, 900 and 901" are different findings, and the
+ * second one is the one that means somebody edited the file.
+ */
+export declare function verifyChain(db: Database, payloadOf: (entry: EntryRow, lines: ReadonlyArray<LineRow>) => unknown): ChainVerification;
+/**
+ * A rollback asked for on purpose.
+ *
+ * `dryRun` runs the real posting — every validation, every insert, the chain
+ * advance, the claim — and then throws this to undo it. Running a separate
+ * "check only" path instead is how a dry run comes back clean and the real
+ * call fails: the two paths drift, and the one nobody exercises is the one
+ * that matters.
+ */
+export declare class DryRunRollback extends Error {
+    readonly payload: unknown;
+    constructor(payload: unknown);
+}
+/**
+ * Run `work` inside one `BEGIN IMMEDIATE`, and turn SQLite's lock failure into
+ * a sentence that names the cause.
+ *
+ * The distinction matters for a caller deciding whether to retry: "another
+ * writer holds the ledger" is worth retrying and "debits do not equal credits"
+ * never is, and a bare `SQLITE_BUSY` stack trace tells a model neither.
+ */
+export declare function inImmediateTransaction<T>(db: Database, work: () => T): T;