swaitsandClaude Opus 5.5
3609bf065e
The money arithmetic every invariant rests on now lives in one kernel,
ledger-core/src/kernel.rs: signing a line, totals, net, per-account
movements, reversal, normal balances, trial-balance columns, closing
lines, and the rounding plug for member splits. It is generic over a
checked `Amount` trait. The engine runs it on Decimal (validate,
movements, reverse_entry, account_balance, close_period_to, allocate,
trial_balance): there is one copy of the arithmetic, and it is the one
under proof.
Three layers, docs/verification.md maps every law to its proofs:
- Kani (src/proofs.rs): 17 harnesses prove the kernel at i64 for every
input up to 4 lines over 3 accounts. An entry is accepted exactly
when it is two or more positive, in-range lines whose debits equal
credits; accepted entries net to zero; grouping by account loses
nothing; a reversal mirrors and cancels its original; trial-balance
columns balance iff the books net to zero; closing lines zero their
accounts and a close balances however the net is split; the plug
makes parts sum to the whole. No panics, no overflow. kani::cover!
shows the proofs are not vacuous.
- Lean 4 (verify/lean): 24 headline theorems for books of any size. The
ledger is a state machine (add account, draft, post, reverse, open,
close), and in every reachable state the books net to zero, the trial
balance balances (as of any date), and the accounting equation holds.
Posting only appends ("posted is forever"), closed periods are
frozen, a close zeroes revenue and expenses and credits exactly the net
income, and period statements add up. Audit.lean shows standard axioms
only, no sorry.
- Bridge (tests/kernel_bridge.rs): the Decimal and i64 kernels agree.
What the proofs found (each one missed by every test, fuzzer, and
mutant):
- The engine accepted negative line amounts; only MCP refused them. Now
NegativeAmountLine: direction is the side's job.
- Summing lines near Decimal::MAX panicked. Lines are now capped at one
quadrillion and ten decimal places (AmountOutOfRange), which keeps
every realistic sum exact, and the kernel's sums are checked.
- FX conversion (foreign_amount * fx_rate) could panic the same way; it
is now a checked multiply.
- Kani itself: 0.68 mis-models symbolic-length copy_from_slice
(model-checking/kani#4904) and reported a reversal that doesn't net to
zero. The counterexample, replayed natively, passes, and a 15-line
standalone crate reproduces the bug. Harnesses avoid bulk copies, and
a should_panic canary will flag the upstream fix.
`just prove` runs it all (Kani memory- and time-capped, fails on an
unsatisfiable cover or a non-standard Lean axiom). AGENTS.md now makes
formal coverage part of every core change.
Also, docs: GnuCash is *an* oracle, never *the* oracle (Stephen). The
spec is accounting principles, proved. Golden files are recomputed from
principles. External implementations (GnuCash, the old Sheet, QBO/Xero)
are cross-checks whose disagreements get adjudicated, never obeyed.
docs/oracle.md gains "Who is right"; AGENTS, README, architecture,
roadmap, parity, and STATUS are reworded to match.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GWVo7x3UHw5kwCUaWxiejX
113 lines
4.9 KiB
Markdown
113 lines
4.9 KiB
Markdown
# wanderbooks
|
|
|
|
Canonical double-entry bookkeeping, rebuilt from scratch. The engine is
|
|
verified against oracles, parity is tracked automatically, and the primary
|
|
interface is AI-first: you talk to an agent, the agent drives the books
|
|
through MCP. Self-hosted, no rent.
|
|
|
|
## What it is
|
|
|
|
- **`ledger-core`** — the semantics engine. Exact decimal money, five
|
|
account types, balanced journal entries, immutable posted log with
|
|
reversing entries, trial balance, P&L, balance sheet, indirect-method
|
|
cash flow, fixed-asset register with straight-line depreciation.
|
|
- **`ledger-store`** — durable storage. The source of truth is an
|
|
append-only, hash-chained JSONL journal; SQLite is a disposable
|
|
projection rebuilt from it; receipts live in a content-addressed blob
|
|
store. Drafts are durable, corrupt projections self-heal.
|
|
- **`ledger-mcp`** — the AI-first interface. 64 MCP tools over stdio or
|
|
Streamable HTTP: draft → preview → post workflow, server-side receipt
|
|
policy (>$25), anti-splitting detection, asset management, digest for
|
|
human review, plus read-only resources for dashboards.
|
|
- **`ledger-import`** — QuickBooks interop. Import bank/credit-card CSVs
|
|
and chart-of-accounts CSVs; export IIF journal entries (for QuickBooks
|
|
Desktop) and XLSX reports.
|
|
- **`ledger-config`** — the company settings in a books dir's
|
|
`wanderbooks.toml`.
|
|
- **`ledger-gui`** — the viewer: a read-only, live window on the books for owners and their
|
|
accountant (egui). Answers first (cash, runway, profit, what needs
|
|
attention), then every number drills down to its lines, its entry, the
|
|
rendered receipt, and the journal history. Follows the journal live:
|
|
a change the agent makes appears in milliseconds. `--demo` opens a
|
|
realistic demo company.
|
|
|
|
## Verification
|
|
|
|
This is the storytold way applied to accounting: agents verify against
|
|
oracles, never ship what they haven't demonstrated.
|
|
|
|
- 190+ workspace tests: invariant tests encoding accounting law, golden-file
|
|
report snapshots, property tests (proptest), end-to-end MCP stdio tests.
|
|
- **Formal proofs of the accounting laws** (`just prove`,
|
|
`docs/verification.md`). Kani model-checks the engine's arithmetic
|
|
kernel exhaustively within bounds. Lean 4 proves that, after any
|
|
sequence of commands, the trial balance balances, the accounting
|
|
equation holds, posted entries are forever, closed periods stay
|
|
frozen, and a close moves exactly the net income to equity. The first
|
|
pass found three engine bugs that every test, fuzzer, and mutant had
|
|
missed: negative amounts accepted, and two crashes on oversized
|
|
amounts. It also caught a soundness bug in the model checker itself.
|
|
- Mutation testing via cargo-mutants; fuzzing via cargo-fuzz (11.5M+
|
|
executions, zero crashes).
|
|
- GnuCash is *a* behavioral cross-check, never the authority and never
|
|
a code source (clean room, MIT OR Apache-2.0). Accounting principles,
|
|
proved, are the spec. Where any other program disagrees, we work out
|
|
from principles who is right.
|
|
|
|
## Status
|
|
|
|
Parity is 12 of 12 against the spreadsheet workflow it replaces
|
|
(`docs/capability-parity.md`). The parallel-run plan
|
|
(`docs/parallel-run.md`) is written; the Google Sheet stays the system of
|
|
record until a clean month and explicit cutover approval.
|
|
|
|
See [`plan/STATUS.md`](plan/STATUS.md) for where things stand and
|
|
[`plan/roadmap.md`](plan/roadmap.md) for where it's going.
|
|
|
|
## Quickstart
|
|
|
|
```bash
|
|
cargo test # whole suite
|
|
cargo run -p ledger-mcp -- --data-dir /tmp/books # MCP server over stdio
|
|
cargo run -p ledger-gui -- --demo # the viewer, on a demo company
|
|
```
|
|
New books, one command (installs Rust and wanderbooks if needed, makes the
|
|
books dir with the MCP server registered for it, and starts the agent):
|
|
|
|
```bash
|
|
curl -fsSL https://wanderbooks.ai/install.sh | sh -s -- ~/Books/Acme
|
|
```
|
|
|
|
Already installed: `wanderbooks new ~/Books/Acme` (add `--codex` to keep the
|
|
books with Codex instead of Claude Code). In a books dir, `just`
|
|
lists the shortcuts (`just gui`, `just agent`, `just backup`).
|
|
|
|
## Developing
|
|
|
|
Every tool the recipes use (Rust, just, Kani, Lean, cargo-mutants,
|
|
cargo-fuzz, Node for deploys) is pinned in `mise.toml`:
|
|
|
|
```sh
|
|
mise install
|
|
just # lists the recipes: check, build, prove, demo, ...
|
|
```
|
|
|
|
## Layout
|
|
|
|
```
|
|
crates/ledger-core/ # engine: money, accounts, journal, ledger, reports
|
|
crates/ledger-store/ # journal + SQLite projection + blob store
|
|
crates/ledger-mcp/ # MCP server: 64 tools, resources, receipt policy
|
|
crates/ledger-import/ # QBO CSV import, IIF/XLSX export
|
|
crates/ledger-config/ # wanderbooks.toml company settings
|
|
crates/ledger-cli/ # `wanderbooks new`: one-command books dir + agent
|
|
crates/ledger-gui/ # the viewer: read-only, live (egui)
|
|
docs/ # requirements, architecture, oracle, parity, glossary
|
|
plan/ # STATUS.md, roadmap.md
|
|
AGENTS.md # operating manual for agents working here
|
|
```
|
|
|
|
## License
|
|
|
|
MIT OR Apache-2.0. See `LICENSE-MIT` and `LICENSE-APACHE`.
|