docs: the 2026-10-28 drift review; the plan, status and docs brought to date
The planning session read plan/served.md, every design document and the five branches the owner paused on 2026-10-27 against main (44ee4083), with dry-run merges touching no branch. plan/2026-10-28_DRIFT_REPORT.md lists every divergence and judges every recorded departure (all kept; three owed back; one needs a decision: P6 made ledger-store depend on ledger-import). The plan: section 0 "What changed on 2026-10-28"; 8.0.1 and the unit Status lines name S4.4, S5, S6, S7 and P6 as built but unmerged; 8.0.2 records the destination (D-56: the installed app, P11a starts now) and the resume order with the known conflicts (the shared documents.rs test file, the types.rs appends, P6 retaking schema 18, the law numbers 34 to 37); 8.0.3 lists the names the EM approved during the wave; P11a gains step 0 (the macOS and Windows keyring stores, the Windows data root and pipes, a cross-platform CI build: today the agent path runs on Linux alone); Q-5 is due and Q-8 asks whether D-47 to D-54 stand; the Landlock sentences in section 2 and server.toml are struck. STATUS.md and HANDOFF.md say where things stand and how to resume; roadmap.md and gui.md are rewritten to today. The docs lose their stale facts: 122 tools, 2,700 tests, the parity floor at 21 with the P4b notes the slices never wrote, the ten crates and their dependency graph (jiff added to the core's allowed list), the cutover of 2026-10-20 recorded in capability-parity.md and parallel-run.md, the P4b S1 law and its two Kani harnesses added to verification.md (law 34), the proof counts (51 and 9), and README, the site and install.sh honest about macOS (the viewer runs; connecting an agent waits for P11a's keyring store, and the installer now says so instead of failing). just check on main at44ee4083: exit 0 (167 suites, 2,871 passed, 0 failed, 7 ignored, the server-only build clean). No code changed. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HS8WZziDnyxunC23MUxrLp
This commit is contained in:
swaitsandClaude Fable 5.1 committed
1 parent
44ee408312
commit
af553a3706
21 files changed
+662
-220
No files matched your search
+48
-28
@@ -21,21 +21,51 @@ 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
|
||||
## The crates (2026-10-28)
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
Two Cargo workspaces: the engine and its application in `crates/`, and
|
||||
the specification in `bookspec/` (which never depends on the engine).
|
||||
|
||||
| Crate | Role | Depends on (ours) |
|
||||
|---|---|---|
|
||||
| `ledger-core` | the semantics engine: money, chart, journal, `Ledger` commands, reports, periods, assets, schedules, parties, A/R and A/P, payroll, projects, settings and conventions, the kernel and its Kani harnesses | nothing |
|
||||
| `ledger-vault` | the TIN vault: XChaCha20-Poly1305 records under the book's key | nothing |
|
||||
| `ledger-config` | the `wanderbooks.toml` codec (adoption in, `books.export_settings` out) and the receipt policy until P4 moves it into the core | `ledger-core` |
|
||||
| `ledger-store` | the source of truth: the hash-chained JSONL journal, its format gate, the SQLite projection (schema 16; a file per schema), the blob store, backups, the access log, `Snapshot` for readers | `ledger-core` |
|
||||
| `ledger-import` | formats: QuickBooks CSV in; IIF, XLSX, Typst PDFs (statements, the invoice, labels) out | `ledger-core` |
|
||||
| `ledger-package` | the shared read-only view over `Store` or `Snapshot` (`PackageBooks`): the CPA package, the 1099 worksheet, the invoice document, Needs attention | `ledger-core`, `ledger-store`, `ledger-config`, `ledger-import`, `ledger-vault` |
|
||||
| `ledger-mcp` | the books server: the MCP tools (122), resources, the handbook, scopes, the door and the access log, backups' scheduling | all of the above |
|
||||
| `ledger-host` | the host and its leases, the agent bridge (`wanderbooks mcp`), tokens in the OS keyring, the owner's commands, uploads and downloads | `ledger-store`, `ledger-mcp`, `ledger-config` |
|
||||
| `ledger-gui` | the viewer: read-only, live, egui; the Books menu hands work to the server | `ledger-core`, `ledger-store`, `ledger-config`, `ledger-import`, `ledger-package`, `ledger-vault`, `ledger-host` |
|
||||
| `ledger-cli` | `wanderbooks`, the one executable: every mode (`serve`, `server`, `host`, `mcp`, `gui`, `setup`, `books`, `token`, `connect`, `doctor`, …) and the over-the-wire test suites | everything |
|
||||
| `bookspec/checker`, `bookspec/runner` | the example schema and parser, the rule catalogue, the `Engine` trait; the per-rule runner | nothing of ours (the adapter in `ledger-core`'s tests depends on them) |
|
||||
|
||||
Dependency direction is always inward toward `ledger-core`; nothing in
|
||||
the core depends on another crate of ours. UI concerns (formatting,
|
||||
locale, widgets) never leak into the core; the core speaks `Decimal` and
|
||||
ISO codes. A crate that was planned and never created is not missing:
|
||||
`ledger-export` became part of `ledger-import`; `ledger-oracle` is the
|
||||
test `crates/ledger-core/tests/oracle_gnucash.rs` with `oracle/gnucash/`
|
||||
(`just oracle`); `ledger-view` and `ledger-extract` were closed by D-53
|
||||
(`PackageBooks` is the shared view; extraction is in-process in
|
||||
`ledger-import`, P6).
|
||||
|
||||
Pending (the P6 branch, 2026-10-27, unmerged): P6 made `ledger-store`
|
||||
depend on `ledger-import` so the writer can extract a file's text at
|
||||
attach time and on the backfill command. That keeps the direction inward
|
||||
but pulls Typst, the fonts and hayro into the store's dependency closure;
|
||||
whether it stands, or extraction moves to the server before the store
|
||||
call, is decided at P6's review.
|
||||
|
||||
`ledger-core` itself (`crates/ledger-core/src/`): `money`, `account`,
|
||||
`journal`, `ledger` (the command surface and replay), `kernel` (every
|
||||
money arithmetic, generic over `Amount`) and `proofs` (its Kani
|
||||
harnesses), `reports`, `cashflow`, `analysis`, `periods`, `assets`,
|
||||
`schedules`, `recurring`, `payouts`, `payroll`, `form1099`, `tax`,
|
||||
`classes`, `parties`, `arap`, `settings`, `conventions`, `calendar`,
|
||||
`shares`, `tax_capital`, `rules`, `error`; its tests in `tests/`
|
||||
(`invariants.rs`, `properties.rs`, `spec_*.rs`, `kernel_bridge.rs`,
|
||||
`model.rs`, `bookspec.rs`, `golden/`).
|
||||
|
||||
## Dependency rules
|
||||
|
||||
@@ -45,24 +75,14 @@ crates/ledger-core/
|
||||
- `thiserror` — the error type
|
||||
- `chrono` — dates (`NaiveDate`; no wall-clock reads in the core)
|
||||
- `serde` / `serde_json` — the oracle interchange format
|
||||
- `jiff` — the bundled time-zone database behind `company.timezone`
|
||||
("today" is computed by the caller and passed in; the core reads no
|
||||
clock)
|
||||
|
||||
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
|
||||
@@ -127,7 +147,7 @@ engine keeps them beside the ledger (`ledger_core::settings::Settings`,
|
||||
`ledger_core::conventions::Conventions`, fields of `Ledger`), so the store,
|
||||
its replay and the viewer's `Snapshot` share one reading; `Ledger::
|
||||
differs_from` and `verify` compare them, and the projection has a table
|
||||
for each (schema v12). `ledger-config` is the codec between them and a
|
||||
for each (schema 16 on 2026-10-28; a file per schema). `ledger-config` is the codec between them and a
|
||||
`wanderbooks.toml` (`codec::import`, `codec::export`): adoption (`wanderbooks
|
||||
books adopt`) moves an older books dir's file in through it, once, and
|
||||
`books.export_settings` writes the books' settings out as one. The books
|
||||
|
||||
@@ -43,7 +43,16 @@ Statuses: `covered` (built and tested), `partial` (built, known gaps listed),
|
||||
- Row 12 is deliberately excluded. Email filing is a mail problem, not a
|
||||
books problem; it stays where it is.
|
||||
|
||||
## Cutover rule
|
||||
## Cutover: done 2026-10-20
|
||||
|
||||
The three conditions below were met and the owner said so: the books were
|
||||
adopted into the server's data root as the first company's live books on
|
||||
2026-10-20 (P2 slice 9), the Sheet is frozen as of 2026-10-11 with the
|
||||
final `verify-sheet` run filed as a workpaper, and the old copies moved
|
||||
into the data root's `legacy/` (Q-3, D-2). The rule is kept for the record
|
||||
and for the next company.
|
||||
|
||||
## Cutover rule (as it was)
|
||||
|
||||
The sheet does not retire on a date. It retires when **all three** hold:
|
||||
|
||||
|
||||
@@ -8,12 +8,16 @@ exposes both over the Model Context Protocol — the open standard, so the
|
||||
books are drivable by any MCP client (Muse, Claude Code, IDE agents), not
|
||||
locked to one assistant.
|
||||
|
||||
## Crates in this phase
|
||||
## Crates
|
||||
|
||||
| Crate | Role | Spec |
|
||||
|---|---|---|
|
||||
| `ledger-store` | SQLite persistence, blob metadata, event log | `docs/receipt-store.md` |
|
||||
| `ledger-mcp` | MCP server wrapping store + core | this document |
|
||||
| `ledger-store` | the hash-chained journal (the source of truth), the SQLite projection, the blob store | `docs/receipt-store.md` |
|
||||
| `ledger-mcp` | the books server: the tools, resources and handbook over store + core | this document |
|
||||
| `ledger-host` | the agent bridge (`wanderbooks mcp`), the host and its leases, tokens | `plan/served.md` 3.3, 3.9 |
|
||||
|
||||
(The overview sections of this document date from the first MCP phase; P5
|
||||
rewrites them. The per-tool sections are held to the code by a test.)
|
||||
|
||||
Rust, `rmcp` SDK (the Rust MCP SDK). The MCP crate holds no accounting
|
||||
logic: it translates tool calls into `Ledger` commands and formats results.
|
||||
|
||||
+10
-9
@@ -53,7 +53,7 @@ case: partial first/final months in different-length calendar months don't
|
||||
complement, so the lifetime total drifted by cents (fixed with the
|
||||
final-month true-up in `depreciation_schedule`).
|
||||
|
||||
**Layer 3 — Mutation testing (live now).** `cargo mutants -p ledger-core`
|
||||
**Layer 3 — Mutation testing (paused for development until P12, D-33, 2026-10-20; CI's weekly shards still run).** `cargo mutants -p ledger-core`
|
||||
(228 mutants as of 2026-10-10: 159 caught, 28 unviable, 2 timeouts from
|
||||
induced infinite loops, 39 missed). Every *missed* mutant is triaged:
|
||||
real gaps get new tests (this pass added parent-account validation,
|
||||
@@ -94,12 +94,11 @@ built through wanderbooks (entries, foreign lines, reversals, closes),
|
||||
every account's balance at month ends and random dates, and each month's
|
||||
P&L, compared exactly (15,800 comparisons). Its first run found one real
|
||||
difference, adjudicated from principles: wanderbooks kept sub-cent
|
||||
amounts on foreign lines; it now books in cents (rules.md B-3). The
|
||||
original plan follows. A
|
||||
`ledger-oracle` crate will run fixture books through our engine and through
|
||||
other implementations (GnuCash headless first), then diff `snapshot()`
|
||||
output automatically: `cargo xtask oracle`. This is the direct analog of
|
||||
storytold's `cargo xtask corpus` / `oracle_diff`, with one difference: a
|
||||
amounts on foreign lines; it now books in cents (rules.md B-3). What the
|
||||
original plan still owes (roadmap phase 3): fixture books, not only random
|
||||
ones, diffed as `snapshot()` output automatically, inside the harness as
|
||||
it is (no `ledger-oracle` crate is planned: D-53). This is the direct analog
|
||||
of storytold's `cargo xtask corpus` / `oracle_diff`, with one difference: a
|
||||
diff does not mean we are wrong. Each one is adjudicated from principles
|
||||
(see "Who is right"). Note also: GnuCash is *a* behavioral cross-check, not
|
||||
a file-format target
|
||||
@@ -113,8 +112,10 @@ evidence. It never overrides them.
|
||||
## What the oracle does NOT cover (yet)
|
||||
|
||||
- **Workflows**, only semantics: that an invoice *posts the right lines* is
|
||||
oracle-covered; that the invoice *screen* is usable is a UI concern for the
|
||||
egui phase, where storytold's screenshot-in-the-loop comes back.
|
||||
oracle-covered; that the invoice *screen* is usable is the viewer's
|
||||
concern (since 2026-10-12: `crates/ledger-gui/tests/*.rs` render every
|
||||
page with `shot(..)` and `tests/view_model.rs` holds every figure shown
|
||||
to the engine's).
|
||||
- **Tax law.** The engine computes what you tell it; it does not know the
|
||||
tax code. Tax-adjacent logic gets its own fixtures and its own goldens
|
||||
when it arrives, sourced from IRS publications — never from memory.
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# Parallel-run readiness
|
||||
|
||||
> **Historical (2026-10-28).** The run happened; the books cut over on
|
||||
> 2026-10-20 (P2 slice 9, `plan/STATUS.md`): the Google Sheet is frozen
|
||||
> as of 2026-10-11, its final comparison (`verify-sheet`) is a filed
|
||||
> workpaper, and the books are the system of record. Kept as the record
|
||||
> of how cutover was decided. The counts below are of 2026-10-11.
|
||||
|
||||
The Google Sheet stays the system of record until the parallel run passes
|
||||
and the owner explicitly approves cutover. This doc is the plan; the run
|
||||
itself needs the owner's go-ahead.
|
||||
|
||||
+19
-4
@@ -8,7 +8,7 @@ Statuses: `done` = implemented + invariant-tested + golden-covered.
|
||||
`partial` = implemented but missing tests or goldens. `todo` = not started.
|
||||
No other statuses.
|
||||
|
||||
**Floor: 10 done** (2026-10-10; fixed-asset register added).
|
||||
**Floor: 21 done** (2026-10-28; it was 10 on 2026-10-10, when the fixed-asset register was added, and the sections below record each rise).
|
||||
|
||||
| Area | GnuCash counterpart (a cross-check, not the spec) | Status | Notes |
|
||||
|---|---|---|---|
|
||||
@@ -34,8 +34,8 @@ No other statuses.
|
||||
| Bank reconciliation (cleared flags + report) | Reconcile | done | — |
|
||||
| QuickBooks CSV import (bank txns, chart of accounts) | Banking → Upload | done | R-FUTURE-4 |
|
||||
| QuickBooks IIF + XLSX export | Export / reports | done | R-FUTURE-4 |
|
||||
| A/R invoices + payments + aging | Business → Invoices | done | R-FUTURE-5 |
|
||||
| A/P bills + payments + aging | Business → Bills | done | R-FUTURE-5 |
|
||||
| A/R invoices + payments + aging | Business → Invoices | done | R-FUTURE-5; since P4b S1 (D-45) a document's paid, outstanding and status are read from its tagged ledger lines, hand lines on the receivables account are refused, `books.void_document` and `books.control_check` tie the subledger to the control account (rules.md B-38); S2 `books.documents`/`books.document` and the viewer pages; S3 the invoice PDF; S4.1-S4.3 terms, numbers, line accounts, the issued PDF filed at issue (behind `documents_v2`, the owner's next upgrade) |
|
||||
| A/P bills + payments + aging | Business → Bills | done | R-FUTURE-5; the same S1 derivation and control guard on the payables account; S4.1-S4.3 the vendor's invoice number, terms, every line on its own account (behind `documents_v2`) |
|
||||
| Payroll runs (accounting only, no tax tables) + tax remittance | Payroll | done | — |
|
||||
| Tracking classes (divisional P&L) | Class tracking | done | invoice and bill lines take a class too (projects, rules.md B-37 item 8; QBO/Xero class or tracking per line) |
|
||||
| CPA handoff package (TB + GL xlsx, P&L + BS pdf, zip) | Reports → export | done | — |
|
||||
@@ -44,7 +44,7 @@ No other statuses.
|
||||
| Payout gross-up (deposit → revenue, fees, adjustments) | Bank deposit with fee lines; Xero/QBO Stripe & Shopify integrations | partial | hand-verified fixture incl. classes and a negative payout; no statement parsers yet |
|
||||
| 1099 vendor tracking + year-end worksheet | Vendors → Track payments for 1099; 1099 report | partial | hand-verified fixture (bill payments, card exclusion, reversal, year boundary); no golden file yet |
|
||||
| Prepaid expense + deferred revenue amortization | Amortization schedules (Xero/QBO add-ons) | partial | hand-verified fixture, to the cent; no golden file yet |
|
||||
| Automated cross-implementation diff harness (GnuCash first) | — (our `xtask oracle`) | todo | roadmap phase 3 |
|
||||
| Automated cross-implementation diff harness (GnuCash first) | — (`just oracle`) | partial | live: `tests/oracle_gnucash.rs` runs 200 random books through GnuCash 5.10 in a pinned container, 15,800 exact comparisons, weekly in CI (docs/oracle.md Layer 5); open: fixture books diffed as `snapshot()` output, and the machine-readable catalog with CI enforcing this floor |
|
||||
|
||||
Workflow/UI parity (QuickBooks/Xero reference) gets its own catalog when the
|
||||
egui phase starts; semantics come first.
|
||||
@@ -63,6 +63,21 @@ D-46); no file with a full TIN is filed into the books (B-26); the agent is
|
||||
told the rules in force in a short connect text and a handbook, and no
|
||||
agent text points at the books' files, git or the repo.
|
||||
|
||||
## P4b: receivables and payables, first class (D-45; 2026-10-23 to 2026-10-27)
|
||||
|
||||
The two A/R and A/P rows above were `done` before P4b and stay `done`;
|
||||
what moved is their notes, so the floor stands at 21. S1 changed what the
|
||||
figures *are* (derived from tagged standing lines, so a reversed payment
|
||||
no longer counts and a void is exact; proven by Lean `control_agrees`
|
||||
and Kani `bounds_kept_is_the_definition_on_books_in_bounds`), S2 and S3
|
||||
added the read tools, the viewer pages and the PDF, and S4.1 to S4.3
|
||||
added terms, numbers, line accounts, the parties' snapshots and the
|
||||
issued copy, journaled only when set so an old-shape document is byte
|
||||
for byte the same. The rest of P4b (S4.4 and S4.5, S5 sent tracking, S6
|
||||
paying on terms, S7 bad debts) is built on paused branches or open as
|
||||
`plan/served.md` 8.0.1 says; each adds a note to these rows when it
|
||||
lands. No golden moved.
|
||||
|
||||
## U0b: one attention engine (D-53, 2026-10-26)
|
||||
|
||||
No semantic feature changed, so no status moved and the floor stands (10
|
||||
|
||||
@@ -2,7 +2,10 @@
|
||||
|
||||
Design for two features built together (the owner, 2026-10-15): a directory
|
||||
of the parties the company deals with, and attachments that link to any
|
||||
subject. Status: design; built after asset tax basis.
|
||||
subject. Status: built (2026-10-15 to 2026-10-17: parties with roles, the
|
||||
TIN vault, attachments linked to any subject; the party's contact block,
|
||||
D-55, is built on branch S4.4 as of 2026-10-28). The design is kept as
|
||||
written; departures are in `plan/served.md` and `docs/spec/rules.md` B-26.
|
||||
|
||||
## Why together
|
||||
|
||||
|
||||
@@ -184,11 +184,12 @@ Suspected corruption is fixed by rebuild, never by forensics.
|
||||
projection from the journal and comparing reports before/after. A newer
|
||||
schema version than the binary understands is a hard error, not a guess.
|
||||
|
||||
## Migration from Google Drive
|
||||
## Migration from Google Drive (done)
|
||||
|
||||
Backfill walks the Drive `the first company` folders and files each
|
||||
document via the equivalent of `books.file_document` with its category.
|
||||
The Drive folders stay exactly as they are until the capability-parity
|
||||
cutover rule (see `docs/capability-parity.md`) is satisfied. Migration is an
|
||||
implementation task, not part of this spec — but the spec is written so the
|
||||
migration is a straightforward script, not a redesign.
|
||||
The company's records were filed into the books at the P1 cutover
|
||||
(2026-10-17, D-20: formation papers, notices, plans and history, through
|
||||
`books.file_document` with their categories) and the books cut over on
|
||||
2026-10-20. The Drive manifest and comparison tools once planned for P6
|
||||
were struck (`plan/served.md` 8.4): the Drive folder is frozen history.
|
||||
P6 (on its branch) adds the categories `notices`, `correspondence`,
|
||||
`plans`, `history` and text extraction for every filed document.
|
||||
+23
-9
@@ -97,11 +97,14 @@ requirement conflict, the requirement wins.
|
||||
receipts and documents are withdrawn with a reason. Unlinking may never
|
||||
leave an entry the policy (R-13) requires a receipt for with none. Every
|
||||
step is a journal event; no blob is deleted.
|
||||
- **R-13 — Receipt enforcement.** The MCP layer (not the engine — the engine
|
||||
stays policy-free) enforces a configurable receipt policy: postings at or
|
||||
above a threshold (`require_receipts_above`, default `"25.00"` in base
|
||||
currency) must have at least one attached receipt, with per-account
|
||||
overrides. `post_entry` with `confirmed: true` refuses with a typed
|
||||
- **R-13 — Receipt enforcement.** The server (not the engine — the engine
|
||||
stays policy-free) enforces the books' evidence policy: postings at or
|
||||
above a threshold (the journaled setting `policy.evidence.threshold`,
|
||||
with required and exempt accounts; P1, rules.md B-29) must have at least
|
||||
one attached receipt. Evaluated by `ledger-config`'s `ReceiptPolicy`
|
||||
today; P4 moves the evaluation into `ledger_core::evidence` so the
|
||||
store, the server and the viewer call one function (plan I-5, D-47:
|
||||
reversals, closes, schedule and depreciation runs are exempt by origin). `post_entry` with `confirmed: true` refuses with a typed
|
||||
`receipt_required` error otherwise. The draft preview always includes the
|
||||
receipt checklist (`attached: [...]`, `required_but_missing: bool`), so the
|
||||
human sees it before confirming. Full spec: `docs/mcp-interface.md`.
|
||||
@@ -162,7 +165,14 @@ requirement conflict, the requirement wins.
|
||||
overridable threshold. Schema v7.
|
||||
- **R-? — A/R and A/P workflows.** Was R-FUTURE-5.
|
||||
`ledger-core::arap`: customers, vendors, invoices, bills, payments,
|
||||
AR/AP aging. MCP tools for the full workflow.
|
||||
AR/AP aging. MCP tools for the full workflow. Since P4b S1 (D-45,
|
||||
rules.md B-38): a document's figures are the signed sum of its tagged
|
||||
ledger lines dated on or before the day asked about, so reversals,
|
||||
voids and write-offs are right by construction; a hand line on a
|
||||
control account is refused; `books.control_check` ties the subledger to
|
||||
the control account. S4 to S7 add terms, numbers, line accounts, the
|
||||
issued PDF, sends, settlements with discounts and the processor's fee,
|
||||
and bad debts, behind the `documents_v2` journal feature.
|
||||
- **R-? — Bank reconciliation.** Cleared flags on posted lines,
|
||||
`reconciliation_report` with uncleared-line detail.
|
||||
- **R-? — Payroll (accounting only).** `ledger-core::payroll`:
|
||||
@@ -173,9 +183,13 @@ requirement conflict, the requirement wins.
|
||||
`JournalLine.class_id`, `add_class`, `set_line_class` (drafts only),
|
||||
`profit_and_loss_filtered`, `profit_and_loss_by_class`. Shared costs are
|
||||
split explicitly across lines at entry time.
|
||||
- **R-? — CPA handoff package.** `books.export_cpa_package`: zip with
|
||||
trial-balance XLSX, general-ledger XLSX (every posted line), P&L and
|
||||
balance-sheet PDFs (printpdf, MIT).
|
||||
- **R-? — CPA handoff package.** `books.export_cpa_package` (and the
|
||||
viewer's Export menu, D-29): a zip, built by `ledger-package` for both,
|
||||
as of a day (B-33), with the trial balance and general ledger as XLSX,
|
||||
the statements as Typst PDFs, the journal as IIF (B-34), every receipt
|
||||
behind the period's entries with an index, the company's documents, the
|
||||
1099 worksheet, the members' equity and K-1 worksheets (book and tax
|
||||
basis, B-36), and a README; handed over as a download (D-46).
|
||||
|
||||
## Non-goals (all phases of the engine)
|
||||
|
||||
|
||||
+2
-2
@@ -23,7 +23,7 @@ promise.
|
||||
| Model-based stateful | the Lean state machine, transcribed (3) | `tests/model.rs` | `just check` | ~3s | every change |
|
||||
| Differential: Decimal vs i64 | the kernel at two types (3) | `kernel_bridge.rs` | `just check` | <1s | every change |
|
||||
| Differential: GnuCash | another implementation, adjudicated (3) | `tests/oracle_gnucash.rs`, `oracle/gnucash/` | `just oracle` | ~2 min | weekly |
|
||||
| Formal proofs | Kani (bounded) and Lean (unbounded) | `src/proofs.rs`, `verify/lean/` | `just prove` (48 harnesses and Lean), `just prove-slow` (the 8 in the justfile's `kani_slow`, each under its own 30-minute cap) | prove ~5 min and prove-slow ~8 min at four jobs on a quiet laptop (each ~25 min under heavy load; docs/verification.md, "Running it") | weekly (CI runs both) |
|
||||
| Formal proofs | Kani (bounded) and Lean (unbounded) | `src/proofs.rs`, `verify/lean/` | `just prove` (51 harnesses and Lean), `just prove-slow` (the 9 in the justfile's `kani_slow`, each under its own 30-minute cap); 60 harnesses in all with the checker canary (2026-10-28) | prove ~5 min and prove-slow ~8 min at four jobs on a quiet laptop (each ~25 min under heavy load; docs/verification.md, "Running it") | weekly (CI runs both) |
|
||||
| Fuzzing | crash, hang, broken books (4); for `fuzz_store_replay` (validly chained journals with fuzz-chosen events): books that open must verify, and the viewer must accept exactly what the writer does | `fuzz/fuzz_targets/`, corpora in `fuzz/corpus/` | `just fuzz <target> <secs>` | 10 min each | weekly |
|
||||
| Miri | undefined behavior in our use of dependencies (4) | the core's unit, bridge, invariant tests (the exhaustive calendar walk aside) | `just miri` | ~4 min | on demand |
|
||||
| Golden | `tests/golden/fixture_company.json` (5) | `invariants.rs` | `just check` | <1s | every change |
|
||||
@@ -37,7 +37,7 @@ promise.
|
||||
| Mutation (GUI) | can the tests fail? | `ledger-gui` view model and formatting (2026-10-14: 140 caught of 176 viable on the full run, then 92 of 99 on a targeted rerun of the money paths after new tests; of its 7 survivors, one then killed by a test (burn over exactly one month, confirmed by a rerun of `compute_kpis`'s 48 mutants), two dead arms removed (`parties`' bill arms: the ledger tags bill entries with their vendor, which wins), four equivalent: an entry's debits vs its credits (they balance), the three-month burn boundary (both paths give 3), burn over zero covered months (only when the first entry is after the window, which then holds no loss), and `compact`'s sign test at zero (zero prints "$0" unsigned either way)) | retired 2026-10-18 (owner: it crushed the machine; for the viewer, test its two musts directly: it never writes the books, `tests/read_only.rs`, and every figure it shows is the engine's, `tests/view_model.rs`) | | never |
|
||||
|
||||
CI: `.github/workflows/check.yml` runs `just check` on every push;
|
||||
`scheduled.yml` runs proofs, the oracle, fuzzing, and mutation weekly. Mutation is split into shards, one job each (`just mutants-mcp 3/16` runs the fourth of sixteen), because GitHub stops a job at six hours and a whole crate takes longer on its runners (2026-10-19, the first scheduled run: the core and MCP runs were stopped at the limit). Test timeouts are three times each run's own baseline, never under the recipe's floor, so a slower runner doesn't report false timeouts. The viewer has no mutation job.
|
||||
`scheduled.yml` runs proofs, the oracle, fuzzing, and mutation weekly. Mutation is split into shards, one job each (`just mutants-mcp 3/16` runs the fourth of sixteen), because GitHub stops a job at six hours and a whole crate takes longer on its runners (2026-10-19, the first scheduled run: the core and MCP runs were stopped at the limit). Test timeouts are three times each run's own baseline, never under the recipe's floor, so a slower runner doesn't report false timeouts. The viewer has no mutation job. Development mutation runs are paused until the P12 max-testing pass (D-33, 2026-10-20): each unit records its targets in a **For P12** paragraph instead; the weekly shards keep running in CI.
|
||||
|
||||
Seeds and failure databases: proptest's `*.proptest-regressions` files
|
||||
are checked in and replay on every run. The GnuCash oracle's books come
|
||||
|
||||
+42
-2
@@ -479,6 +479,44 @@ one kernel function, `kernel::unrecovered_cost`:
|
||||
`unrecovered_cost_only_for_on_spec_and_never_negative`. No Lean model:
|
||||
the function is one subtraction and a `max`.
|
||||
|
||||
### Documents and their control accounts (P4b S1, D-45)
|
||||
|
||||
**Law 34. A control account is its documents.** For a receivables or
|
||||
payables account A and any day D, the account's balance on D equals the
|
||||
sum over documents of `outstanding(d, D)` (the signed sum of the lines
|
||||
tagged with d and dated on or before D, whatever their entries' standing:
|
||||
a reversal's mirror carries the same tag and cancels) plus the legacy
|
||||
untagged lines that still stand. A document never owes less than nothing
|
||||
or more than its total on any day a payment path or a reversal touches
|
||||
it. Rule: `docs/spec/rules.md` B-38.
|
||||
|
||||
- Kernel: `kernel::running_bounds(total, deltas)` and
|
||||
`kernel::bounds_kept(total, before, after)` decide, at every date in
|
||||
date order, whether 0 ≤ outstanding ≤ total holds; `Ledger::
|
||||
check_item_bounds` runs them on the documents a step touches. Kani:
|
||||
`bounds_check_matches_definition` (the check equals the definition on a
|
||||
symbolic sequence of deltas) and
|
||||
`bounds_kept_is_the_definition_on_books_in_bounds` (on books already
|
||||
within bounds, `bounds_kept` is exactly the definition over the new
|
||||
deltas), both with covers reaching a refused and an accepted sequence.
|
||||
Bridge: `crates/ledger-store/tests/bounds.rs` and the properties in
|
||||
`crates/ledger-store/tests/arap_props.rs` (`subledger_equals_control`
|
||||
after every operation, at every date; `status_is_a_function_of_journal
|
||||
_and_date`; `reversal_twice_restores_state`).
|
||||
- Lean, `verify/lean/Wanderbooks/Documents.lean`: `control_agrees` and
|
||||
`control_agrees_through` (the identity, for every account and through
|
||||
every day), `Step.document_unattached` (an untagged legacy line only
|
||||
grows `unattached`, never a document), `Step.reverse_moves` and
|
||||
`reverse_twice` (a reversal moves exactly the opposite of its tagged
|
||||
lines from its date; reversing it restores them),
|
||||
`Reachable.control_is_documents` (the identity on every reachable
|
||||
book). Listed in `Audit.lean`; standard axioms only.
|
||||
- Laws 35 to 37 are taken, in the order the paused branches merge, by
|
||||
S5 (`Step.markSent`: a send changes no figure), S6
|
||||
(`settle_is_exact`: a settlement's cash, discounts and fee are exact)
|
||||
and S7 (`writeOff_within_bounds`); the branches wrote 34 and are
|
||||
renumbered at merge (`plan/served.md` 8.0.2).
|
||||
|
||||
### Payment terms and document lines (P4b S4.1)
|
||||
|
||||
Payment terms (rules.md B-39) give a due date and a discount date by
|
||||
@@ -660,8 +698,8 @@ Lean carrying any weights.
|
||||
|
||||
```sh
|
||||
mise install # once: Kani, Lean, and the rest, pinned in mise.toml
|
||||
just prove # 48 Kani harnesses and Lean
|
||||
just prove-slow # the other 8: the justfile's kani_slow
|
||||
just prove # 51 Kani harnesses and Lean
|
||||
just prove-slow # the other 9: the justfile's kani_slow
|
||||
just prove-all # both
|
||||
```
|
||||
|
||||
@@ -766,4 +804,6 @@ each harness's whole run, its compile of about 50 s included):
|
||||
| `unrecovered_cost_laws` | 32 | prove | 0 |
|
||||
| `discount_max_is_bounded` | 33 | prove-slow | 163 |
|
||||
| `line_amount_is_exact` | 33 | prove | 6 |
|
||||
| `bounds_check_matches_definition` | 34 | prove | (not in the 2026-10-22 run; P4b S1, 2026-10-24) |
|
||||
| `bounds_kept_is_the_definition_on_books_in_bounds` | 34 | prove | (as above) |
|
||||
| `kani_symbolic_copy_canary` | (the checker: "Trusting the checker") | prove | 3 |
|
||||
Reference in new issue
Block a user