@crewhaus/tool-ledger 0.7.0

package/README.md

@@ -0,0 +1,243 @@
+# @crewhaus/tool-ledger
+
+A local double-entry ledger, and the reports and reconciliation that make one
+usable.
+
+| Tool | Answers |
+|---|---|
+| `LedgerPost` | record these entries, or say exactly why not |
+| `LedgerQuery` | what is the balance, the P&L, the sheet, the aging, the chain |
+| `LedgerReconcile` | which of these rows are the same event, and which are not |
+| `InvoiceRender` | produce a numbered document, with the totals computed |
+
+Storage is `bun:sqlite`, which is built into Bun. There are no runtime
+dependencies outside the workspace.
+
+## Nothing here moves money
+
+Nothing in this package opens a socket. No schema in it accepts an account
+number, a card, a routing number, an API key or any other credential —
+`index.test.ts` walks every schema and asserts that, and scans every source
+file for anything that could dial out, and both checks assert their own hit
+count so a scan that matched nothing cannot pass as a clean result.
+
+An invoice is rendered to a file under the workspace. A reconciliation returns
+entries a person could post. Sending a payment instruction is a different job,
+in a different package, with different gates.
+
+## Debits equal credits, or the entry does not post
+
+That is the whole of double entry, and a ledger that accepts an unbalanced
+entry is not a ledger with a small error in it — it is a pile of rows, and
+every report over it is unfalsifiable. So the check happens at POST time and
+an unbalanced entry is rejected with the difference named. One rejected entry
+does not stop the rest of the batch; each rejection carries its index and its
+reason.
+
+Also refused, each with a reason rather than a correction: a negative debit
+(it is a credit, so write it as one), a zero line, a line carrying both sides,
+an entry with fewer than two lines, an amount whose decimals the currency
+cannot hold (`1.005` as USD is not `1.01`, it is a caller who has not
+decided), a date that does not exist, an account not in the chart, and a date
+inside a locked period.
+
+## Amounts are never JS floats
+
+Decimal strings in, integer minor units out, bigints in between. The
+arithmetic and the ISO 4217 exponent table come from `@crewhaus/tool-math`'s
+money kernel — one table, so JPY has no cents and a Gulf dinar has three
+decimal places. An unknown currency code is refused rather than assumed to
+have two.
+
+Amounts are stored as TEXT holding a bigint's digits. SQLite would take them
+as INTEGER, but `bun:sqlite` hands an INTEGER column back as a JS number and
+`SUM()` silently promotes a 64-bit overflow to a float. Totals are therefore
+summed here, exactly.
+
+## The one transaction
+
+A posting is three writes that are only correct together:
+
+1. the entry and line rows,
+2. the hash chain's new head,
+3. the idempotency claim that says this batch has been seen.
+
+Commit them separately and there is a window in which a crash leaves 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. All three go inside one
+`BEGIN IMMEDIATE` transaction, following `@crewhaus/durable-state`'s pattern:
+`IMMEDIATE` takes the write lock at `BEGIN` rather than at the first write, so
+the read half (is this key claimed? what is the head?) serializes against
+another writer instead of racing it, and `busy_timeout` makes the loser wait
+rather than fail instantly.
+
+`dryRun` is the same code path, rolled back on purpose. A separate "check
+only" path is how a dry run comes back clean and the real call fails.
+
+Invoice numbering has the same shape from the other side. Allocate the number
+and then write the file, and a crash in between burns a number out of a
+sequence that is legally required not to have gaps; write the file and then
+allocate, and two concurrent calls issue one number twice. So the number and
+the document record — including the hash of everything that determines the
+rendered bytes — are allocated in one transaction, and the render happens
+after. If the render dies, repeating the call with the same idempotency key
+returns the **same number** and re-renders the **same bytes**. And because a
+bad template is found at render time, the render is proved once against a
+provisional number before the sequence is touched at all.
+
+## Multi-currency: rounding is bounded
+
+An entry with a foreign line balances in the base currency after conversion,
+and conversions round, so a residue of a minor unit or two is arithmetic and
+goes to the configured `fxAccount`. A residue of nine hundred is not rounding;
+it is a rate entered as 1.09 instead of 0.91. So the residue is capped at one
+minor unit per converted line — the most rounding can produce — and anything
+larger is refused with both numbers in the message. Booking it to "FX
+rounding" would hide a real loss in the one account nobody reads.
+
+With no `fxAccount` configured, a residue is a refusal rather than an extra
+cent added to whichever line happened to be last.
+
+## A tolerance does not widen matching
+
+`LedgerReconcile` reports **matched**, **unmatched on each side**, and **near
+misses** as three separate lists. A match requires the amounts to be *equal*.
+The tolerance defines the near-miss radius: a 100.00 and a 100.01 come back as
+a near miss for a person to look at, and both rows stay unmatched.
+
+This is the opposite of what most reconcilers do, and it is the reason this
+one is worth running unattended. Those two rows are two facts that disagree by
+a penny; pairing them destroys the only evidence that anything is wrong. For
+the same reason, a matching *reference* with a different amount is a near miss
+rather than a match — that pair is the most interesting row in the file.
+
+Bundled payouts are found by a bounded subset-sum. Several different bundles
+of charges routinely add up to the same payout, so the search walks subsets by
+ascending size and then lexicographically over a pool sorted by (date, id) and
+takes the first exact hit: the same bundle is chosen on every rerun, and the
+fee entry proposed next to it does not move. The search is capped, and a row
+it gave up on is named in `groupingTruncated` rather than reported as
+unmatched.
+
+Rows on both sides use `@crewhaus/tool-money`'s `Transaction` — the shape
+`StatementParse` produces — imported rather than re-declared. A side with
+`kind: "statement"` is read through tool-money's own parser, so a file whose
+dates could be day-first or month-first is refused there too.
+
+## Aging refuses rather than answering partially
+
+Aging needs a `counterparty` and a `dueDate` on the lines it ages, and an
+explicit `asOf`. Without a due date, every amount lands in "current" and the
+report says nothing is overdue — an answer that looks like an answer. So:
+
+- no `asOf` is a refusal (the clock would make the same ledger produce a
+  different report tomorrow, and an aging report is a document somebody
+  files);
+- `asOf` narrows the selection as well as labelling it, as it does on a
+  balance sheet: an aging as of June does not include an invoice dated August,
+  which would otherwise land in "current" and inflate what a counterparty
+  owes;
+- no `accounts` is a refusal (ageing every account produces a table with no
+  meaning);
+- a line with no `counterparty` is a refusal, naming the field and the count;
+- *no* line carrying a `dueDate` is a refusal.
+
+Lines that do have a counterparty but no due date are payments and credits.
+They are reported as `unapplied` against that counterparty rather than folded
+into "current", where they would quietly cancel an overdue invoice.
+
+## Signs come from the chart of accounts
+
+A trial balance says `balanced: true` or `false` only when the selection holds
+whole entries. Filtering by account, counterparty, text or amount keeps one leg
+and drops the other, so the totals cannot pair up; `balanced` is `null` there
+with a note saying why, because `false` would read as "somebody edited the
+file" about a caller who typed a filter.
+
+Whether a balance reads positive depends on the account's normal side, which
+is a property of the account, not of the query. A report that decides it from
+the account's *name* is wrong the first time somebody books a contra account.
+`autoCreateAccounts` is off by default for the same reason: an auto-created
+account's type is guessed from the numbering convention, and reports sign
+their sums by that field.
+
+## Invoice totals add up on the page
+
+The four figures a document shows are `subtotal`, `discount`, `tax` and
+`total`, and they satisfy the sum a reader will do on them:
+
+```
+subtotal − discount + tax = total
+```
+
+So `subtotal` is the lines *before* discount. Reporting the net there leaves
+every individual figure defensible and the document as a whole wrong — 90.00
+less 10.00 plus 18.00 is not the 108.00 printed at the bottom, and the first
+person to check the arithmetic is the customer being asked to pay it. The
+after-discount figure is carried as `net` for anyone who wants it without
+subtracting, and the lines' own `total` column sums to the same `total`.
+
+A document number is also a file name. It is constrained to letters, digits,
+`.`, `-` and `_`, whether it came from `number` or from `numbering.prefix`,
+and the check runs before the sequence is touched — so a number that would
+walk out of `outDir` is a refusal rather than a burnt number and an
+overwritten file somewhere else. `gapFree` comes back `null`, never `true`,
+for a number the caller assigned: there is no sequence there to check, and a
+gap in a document sequence is a finding.
+
+## Invoice bytes do not move
+
+`Intl.NumberFormat` output varies with the ICU version the runtime was built
+against, so the same invoice can render differently on a laptop and in CI — on
+a document somebody files. This package has no locale formatter at all.
+Amounts are rendered from exact decimal strings with separators the caller
+names; dates are ISO. The yearly sequence reset takes its year from
+`issueDate`, never from the clock, so a document back-dated across New Year
+lands in the right sequence.
+
+The template is logic-less: variables, array sections, inverted sections.
+Nothing computes, because a template that can compute can compute a total, and
+totals come from the line data. Only arrays iterate — a plain object would
+iterate in insertion order, and that is not a property of the document. An
+unknown placeholder is refused by default rather than rendered as a blank: a
+mistyped `{{seller.taxId}}` would drop the VAT number off the invoice and
+nothing would say so.
+
+## The chain, and what it can and cannot tell you
+
+Each entry hashes its predecessor's hash together with a canonical
+serialization of the entry and all of its lines, so editing a memo or an
+amount after the fact is detectable. `LedgerQuery view: "chain"` walks it and
+reports **every** break rather than the first — "entries 4, 900 and 901" and
+"entry 4" are different findings.
+
+The head is stored as well as derivable, because a prefix of a valid chain is
+itself a valid chain: recomputing the head cannot tell a complete ledger from
+a truncated one, and the recorded head and length can.
+
+What this is not, in two parts. The file is on disk and whoever can write it
+can rewrite the whole chain from any point: tamper-**evident** against an
+edit, not tamper-proof against an author. For that, publish the head somewhere
+the same person cannot write. And the chain covers the entries and their
+lines — not the chart of accounts. An account's *type* is outside the hash, so
+re-typing one from income to expense turns a P&L over and the chain still
+reports `ok`. The `chain` view says so in its notes; check account types
+against your own record separately.
+
+## Bounds
+
+Everything that can grow is capped, and hitting a cap is said rather than
+silently truncating: 500 entries per post, 200 lines per entry, 200 000 lines
+scanned by one query (past that it refuses and names the range to narrow),
+20 000 rows per reconciliation side, 64 MB per statement file, 256 KB per
+template.
+
+## Testing
+
+`bun test packages/tool-ledger`. Nothing in the suite opens a socket or reads
+a wall clock — `_setClock` is the one seam, because `postedAt` is inside the
+hash chain. The transaction guarantees are tested by aborting inside the
+transaction and asserting the rows, the head *and* the claim all rolled back,
+and by holding the write lock on a second connection and asserting the failure
+names the lock rather than merely happening.

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+import type { RegisteredTool } from "@crewhaus/tool-catalog";
+import { LedgerError } from "./lib/amount";
+/**
+ * Replace the clock. Tests drive this so that `postedAt` — which is inside the
+ * hashed payload — is fixed, and so no assertion in this package depends on
+ * wall-clock time.
+ */
+export declare function _setClock(fn: () => number): void;
+export declare const ledgerPost: RegisteredTool;
+export declare const ledgerQuery: RegisteredTool;
+export declare const ledgerReconcile: RegisteredTool;
+export declare const invoiceRender: RegisteredTool;
+export { LedgerError };
+/** Every tool this package registers, in the order a catalog should list them. */
+export declare const LEDGER_TOOLS: ReadonlyArray<RegisteredTool>;