swaitsandClaude Opus 5.5
528c070605
A client project's invoiced revenue and a contractor's billed cost could never count toward the project: books.create_invoice and books.create_bill posted at once with untagged lines, and only a draft's line takes a class. Job costing (B-37 item 3) collects a job's billings and the supplier invoices for its direct costs on its cost sheet, so each document line now takes an optional project. The owner decided it on 2026-10-22 (plan D-43, rules.md B-37 item 8): each line takes one project or none; a document spanning N projects is N lines, each with its own amount; no percentage split, so every figure is exact; a cost truly shared among projects names none on the document and reaches projects only as entries of their own under the company's monthly allocation convention, when books.conventions has one (otherwise it stays untagged and the agent asks the human). The reasoning, stated in B-37: job costing charges a job the costs traceable to it, whole, and reaches shared costs only by allocation on a stated basis. ASC 340-40-25-7 counts as directly related both the costs traceable to a contract (25-7(a), (b), (d), (e)) and allocations of costs that relate directly to it (25-7(c)); 25-8 expenses general and administrative cost. The books carry the first whole on the document's line and the second as the allocation convention's own entries; neither is a percentage on the document (sources/fasb-asc.md, 25-7 and 25-8 added). The handbook's projects rule and the line's class parameter say the same, and no handbook sentence lets a shared cost be split across a document's lines. The accounting: the document's entry posts one revenue (an invoice's) or expense (a bill's) line per project its lines name, in the order each is first named, each the sum of that project's lines, and the untagged lines' sum as one more line (arap::document_parts, conservation checked by a proptest). A document naming no project therefore posts exactly the one line every document posted before. The receivable or payable line is never tagged: it is a balance-sheet line, which item 3 counts nothing; the payments (receive_payment, pay_bill) move cash against it and take no project either. Nothing but the projects moves: the P&L, the 1099 worksheet (payments made, B-19) and party totals (what moved the money, B-35) read the same with or without the tags (twin-books test); the projects with the untagged lines still partition the P&L. - ledger-core: DocumentLine.class_id (serde-omitted when none, so old documents serialize as before); create_invoice / create_bill split the revenue or expense side by project and tag it; an unknown project is refused whole (atomically). - ledger-store: a document line's project is journaled as class_id on invoice.created / bill.created, and the entry's line as entry.line_class_set right after its entry.line_added (the entry.posted lines carry class_id, as a hand-built entry's do). Behind a NEW journal feature, document_line_projects (KNOWN_FEATURES, declared by new books, asked for before the first journaled line, not even the control accounts written on refusal); not `projects`, which the live books already declared: the owner consents again at the next upgrade. A malformed class_id is corrupt; null or absent is none. Untagged documents journal byte for byte as before; old journals replay unchanged. - ledger-mcp: each line takes class (id or name, resolved like add_line's, every one before anything is written); the result gains notes for a finished or abandoned project, and on an invoice for an on-spec project (is there now an agreement? on spec a hoped-for payment is no receivable, B-37 item 4), tagged anyway; books lacking the feature refuse with format_upgrade_pending. books.get_entry shows a line's class_id and project. The handbook's "an invoice or bill takes no project yet" caveat now depends on the books: gone where the feature is declared, an "until their format upgrade" note where it isn't. - ledger-gui: an invoice's or bill's page (its entry's) lists the document's lines, each project a link that opens it; the demo's client invoices are tagged to "Client work", whose snapshot is now its revenue less its contractors. Looking at the page in a narrow window found a tagged line's tag pushing the amounts past the pane (any tagged entry): the name is now cut to leave the tag room, the tag itself at most half the cell. - bookspec: an `invoice` event, and `lines` with `project` on a bill or an invoice; example projects-invoice-and-bill-lines-count-by-project, worked by hand, both projects client work (Zeta 3,500.00 - 1,200.00 = 2,300.00; Harbor 200.00; untagged -1,750.00; together the P&L's 750.00; Dana's 1099 payments 1,250.00). - fuzz: fuzz_store_replay can declare journal features. - Tests: core, store, MCP, viewer, the P2-served cutover fixture and a viewer/server parity test (its month lists the same length, not empty); a tagged document's reversal nets its projects to zero, live and replayed; books.get_entry's class_id; the handbook served as a resource both ways; each fix broken to confirm its test fails (docs/testing.md). Docs: rules.md B-27 and B-37 items 3 and 8, sources/fasb-asc.md, plan/served.md D-43, mcp-interface.md, testing.md, parity.md, plan/STATUS.md. No proof changed (no kernel arithmetic: document_parts sums with the existing document_total). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T3gXMVt7XJPi6ens1or9Dj
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, the statement of cash flows (direct method, with the reconciliation and noncash schedules), 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'swanderbooks.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.--demoopens 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 for where things stand and
plan/roadmap.md for where it's going.
Quickstart
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' private folder, starts books called acme and lets Claude Code reach
them; nothing needs sudo):
curl -fsSL https://wanderbooks.ai/install.sh | sh -s -- acme
Already installed, three commands: wanderbooks setup, wanderbooks books create acme, wanderbooks connect claude --book acme (or connect codex).
Then talk to the agent; wanderbooks gui acme shows the books, and its
Books menu backs them up, restores, starts new books and closes them.
Developing
Every tool the recipes use (Rust, just, Kani, Lean, cargo-mutants,
cargo-fuzz, Node for deploys) is pinned in mise.toml:
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: 119 tools, resources, handbook, receipt policy
crates/ledger-import/ # QBO CSV import, IIF/XLSX export
crates/ledger-config/ # wanderbooks.toml company settings
crates/ledger-cli/ # `wanderbooks`: the one executable (every mode)
crates/ledger-host/ # the host, the agents' bridge, the owner's commands
crates/ledger-package/ # The CPA package and the 1099 worksheet (server and viewer)
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.