swaitsandClaude Opus 5.5
3f20df9700
check / check (push) Canceled after 0s
ledger-config: parse gets a sourced spec. A fiscal year starts on the first of a month (IRS Pub. 538); tax_classification is read by whole words (Treas. Reg. 301.7701-3, Schedule C instructions; "business corp" no longer reads as an S corp, "corporation or S corporation" is refused); duplicate or blank members and shared capital accounts are refused; a negative or non-grammatical receipt threshold is refused; codes trimmed. tests/spec_config.rs (65 spec-blind tests, 14 properties), fuzz target fuzz_config_parse (weekly). Mutation: 55 of 55 viable caught (from 25/38). The receipt policy moves to ledger-config, with one loader (effective_receipt_policy) and one decimal grammar, so the server and the viewer enforce and show the same rule (the viewer had its own: only expense-like debits, a silent $25 default, and no config.json). ledger-mcp: a module spec (MCP 2025-06-18 tools, JSON-RPC 2.0, the operating contract). Amounts in are exactly -?digits[.digits]; a number that is one account's code and another's id (vendors, classes alike) is refused, not guessed; the threshold is validated at startup. Fixed: add_line with a bad class journaled the line before refusing; profit_and_loss_by_class ignored `class`; aging buckets said "0". A wire in front of rmcp answers malformed JSON with -32700 and invalid requests with -32600 and their id (rmcp dropped the first, omitted the id). tests/spec_mcp.rs (26 spec-blind tests: every tool's result against its own outputSchema, a random-call state machine checking the journal is untouched by every refusal, amount grammar, previews, the receipt policy). ledger-gui: money, accounting, and dollars never round (they rounded to cents, banker's style); export file names avoid Windows device names, trailing dots and spaces, empty names, and 255-byte overflow; specs on attention, history, fuzzy search, and axis ticks. ledger-core: the lifetime profit_and_loss is renamed unclosed_earnings (docs/testing.md #3). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01GWVo7x3UHw5kwCUaWxiejX
83 lines
3.7 KiB
Markdown
83 lines
3.7 KiB
Markdown
# Architecture
|
|
|
|
## The one big idea: engine-first, everything is a command
|
|
|
|
`ledger-core` owns all accounting knowledge. Every state change is a method
|
|
on `Ledger`:
|
|
|
|
- `add_account` — extend the chart of accounts
|
|
- `create_entry` / `add_line` — build a draft journal entry
|
|
- `post_entry` — validate and apply (one-way)
|
|
- `reverse_entry` — correct via reversal (one-way)
|
|
|
|
Each command validates *before* it applies, and each failure is a typed
|
|
`LedgerError` variant. There is no other mutation path: struct fields are
|
|
private, and constructors are `pub(crate)` where it matters. This is what
|
|
makes the ledger auditable and what will make the future oracle harness
|
|
trustworthy — the harness only needs to drive the command surface.
|
|
|
|
Reports (`trial_balance`, `balance_sheet`, `unclosed_earnings`, `snapshot`)
|
|
are free functions: pure, total, and deterministic. Same ledger in, same
|
|
report out, every time, on every platform. That determinism is the entire
|
|
basis of `docs/oracle.md`.
|
|
|
|
## Current crate layout
|
|
|
|
```
|
|
crates/ledger-core/
|
|
src/
|
|
lib.rs # crate docs, re-exports, design rules
|
|
money.rs # Currency + Money (Decimal, checked arithmetic)
|
|
account.rs # AccountType, Side, Account, ChartOfAccounts
|
|
journal.rs # JournalLine, JournalEntry, validate()
|
|
ledger.rs # Ledger: the command surface, append-only log
|
|
reports.rs # trial_balance, unclosed_earnings, balance_sheet, snapshot
|
|
tests/
|
|
invariants.rs # accounting-law tests + randomized property test
|
|
golden/ # hand-verified expected report snapshots
|
|
```
|
|
|
|
## Dependency rules
|
|
|
|
`ledger-core` may depend only on:
|
|
|
|
- `rust_decimal` — exact decimal arithmetic
|
|
- `thiserror` — the error type
|
|
- `chrono` — dates (`NaiveDate`; no wall-clock reads in the core)
|
|
- `serde` / `serde_json` — the oracle interchange format
|
|
|
|
New dependencies need justification in the commit message. In particular:
|
|
no I/O, no networking, no async runtime, no logging framework in the core.
|
|
The core is a pure domain library and stays that way.
|
|
|
|
## Future crates (do not create until the roadmap says so)
|
|
|
|
| Crate | Purpose | Depends on |
|
|
|---|---|---|
|
|
| `ledger-store` | Journal (hash-chained JSONL) + SQLite projection, blob store | `ledger-core` |
|
|
| `ledger-import` | QuickBooks CSV read-only import (bank transactions, chart of accounts) | `ledger-core` |
|
|
| `ledger-export` | Format renderers: CSV, XLSX, IIF journal entries (QuickBooks Desktop) | `ledger-core` |
|
|
| `ledger-oracle` | Cross-check harness: our engine vs other implementations (GnuCash first) on fixture books; diffs are adjudicated, not obeyed | `ledger-core`, `ledger-import` |
|
|
|
|
Dependency direction is always inward toward `ledger-core`. Nothing in the
|
|
core may depend on a future crate. UI concerns (formatting, locale, widgets)
|
|
never leak into the core; the core speaks `Decimal` and ISO codes.
|
|
|
|
## Why Rust
|
|
|
|
Exact decimal semantics, exhaustive pattern matching on the five account
|
|
types, and a type system that makes invalid states (mutable posted entries,
|
|
float money) unrepresentable. The storytold pipeline this project is modeled
|
|
on is Rust + egui for the same reasons; when the UI crate arrives it will be
|
|
one codebase compiling to native and WASM.
|
|
|
|
## The GUI (`ledger-gui`)
|
|
|
|
Read-only by construction: it opens a `ledger_store::Snapshot` (journal
|
|
verified and replayed into its own `Ledger`, projected into a private
|
|
in-memory SQLite, blobs read through the verifying store) and never writes
|
|
to the data directory. A loader thread watches the directory and applies
|
|
appended journal lines; the UI renders an immutable view model rebuilt per
|
|
change. Statements and series come from `ledger-core` (`reports`,
|
|
`analysis`); the GUI only arranges them. See `plan/gui.md`.
|