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
105 lines
4.1 KiB
Lean4
105 lines
4.1 KiB
Lean4
import Wanderbooks.Entry
|
||
|
||
/-!
|
||
# Balances and statements
|
||
|
||
Mirrors `kernel::normal_balance`, `kernel::columns`,
|
||
`Ledger::account_balance`, and `reports::trial_balance`.
|
||
-/
|
||
|
||
namespace Wanderbooks
|
||
|
||
/-- A chart of accounts: each account's code and type. -/
|
||
abbrev Chart := List (Nat × AccountType)
|
||
|
||
/-- The chart's codes. -/
|
||
def codes (c : Chart) : List Nat := c.map Prod.fst
|
||
|
||
@[simp] theorem codes_nil : codes [] = [] := rfl
|
||
@[simp] theorem codes_cons (a : Nat) (t : AccountType) (c : Chart) :
|
||
codes ((a, t) :: c) = a :: codes c := rfl
|
||
|
||
/-- An account's balance on its normal side (`kernel::normal_balance`). -/
|
||
def balance (t : AccountType) (m : Int) : Int := signed t.normal m
|
||
|
||
/-- **A normal-side line raises a balance by its amount; an opposite-side
|
||
line lowers it.** -/
|
||
theorem balance_after_line (t : AccountType) (m : Int) (s : Side) (a : Int) :
|
||
balance t (m + signed s a) = balance t m + (if s = t.normal then a else -a) := by
|
||
cases t <;> cases s <;> simp [balance, AccountType.normal, signed] <;> omega
|
||
|
||
/-- The total balance of every account of type `t`. -/
|
||
def typeTotal (t : AccountType) (ls : List Line) : Chart → Int
|
||
| [] => 0
|
||
| (a, t') :: rest => (if t' = t then balance t' (movement a ls) else 0) + typeTotal t ls rest
|
||
|
||
/-- The accounting equation's two sides differ by the net movement of the
|
||
chart's accounts. -/
|
||
theorem equation_gap (ls : List Line) (c : Chart) :
|
||
typeTotal .asset ls c + typeTotal .expense ls c
|
||
- typeTotal .liability ls c - typeTotal .equity ls c - typeTotal .revenue ls c
|
||
= sumOver (fun a => movement a ls) (codes c) := by
|
||
induction c with
|
||
| nil => rfl
|
||
| cons x c ih =>
|
||
obtain ⟨a, t⟩ := x
|
||
cases t <;> simp [typeTotal, balance, AccountType.normal, signed] <;> omega
|
||
|
||
/-- **The accounting equation.** For lines that net to zero, over a chart
|
||
with distinct codes covering every line's account:
|
||
Assets = Liabilities + Equity + (Revenue - Expenses). -/
|
||
theorem accounting_equation (ls : List Line) (c : Chart) (hd : Distinct (codes c))
|
||
(hcov : ∀ l ∈ ls, l.account ∈ codes c) (hnet : net ls = 0) :
|
||
typeTotal .asset ls c
|
||
= typeTotal .liability ls c + typeTotal .equity ls c
|
||
+ (typeTotal .revenue ls c - typeTotal .expense ls c) := by
|
||
have := equation_gap ls c
|
||
rw [sum_movements _ hd ls hcov, hnet] at this
|
||
omega
|
||
|
||
/-! ## Trial balance -/
|
||
|
||
/-- The debit column for a movement (`kernel::columns`). -/
|
||
def colDebit (m : Int) : Int := if 0 < m then m else 0
|
||
/-- The credit column for a movement (`kernel::columns`). -/
|
||
def colCredit (m : Int) : Int := if 0 < m then 0 else -m
|
||
|
||
theorem columns_spec (m : Int) :
|
||
0 ≤ colDebit m ∧ 0 ≤ colCredit m ∧ (colDebit m = 0 ∨ colCredit m = 0)
|
||
∧ colDebit m - colCredit m = m := by
|
||
unfold colDebit colCredit; split <;> omega
|
||
|
||
/-- The trial balance's debit column total. -/
|
||
def tbDebits (ls : List Line) (as : List Nat) : Int := sumOver (fun a => colDebit (movement a ls)) as
|
||
/-- The trial balance's credit column total. -/
|
||
def tbCredits (ls : List Line) (as : List Nat) : Int :=
|
||
sumOver (fun a => colCredit (movement a ls)) as
|
||
|
||
theorem tb_gap (ls : List Line) (as : List Nat) :
|
||
tbDebits ls as - tbCredits ls as = sumOver (fun a => movement a ls) as := by
|
||
induction as with
|
||
| nil => rfl
|
||
| cons a as ih =>
|
||
simp only [tbDebits, tbCredits, sumOver_cons] at ih ⊢
|
||
have := (columns_spec (movement a ls)).2.2.2
|
||
omega
|
||
|
||
/-- **The trial balance balances** for lines that net to zero. -/
|
||
theorem trial_balance_balances (ls : List Line) (as : List Nat) (hd : Distinct as)
|
||
(hcov : ∀ l ∈ ls, l.account ∈ as) (hnet : net ls = 0) :
|
||
tbDebits ls as = tbCredits ls as := by
|
||
have := tb_gap ls as
|
||
rw [sum_movements as hd ls hcov, hnet] at this
|
||
omega
|
||
|
||
/-- And conversely: a balanced trial balance means the lines net to zero.
|
||
The trial balance is a complete check of the books' arithmetic. -/
|
||
theorem trial_balance_iff (ls : List Line) (as : List Nat) (hd : Distinct as)
|
||
(hcov : ∀ l ∈ ls, l.account ∈ as) :
|
||
tbDebits ls as = tbCredits ls as ↔ net ls = 0 := by
|
||
have := tb_gap ls as
|
||
rw [sum_movements as hd ls hcov] at this
|
||
omega
|
||
|
||
end Wanderbooks
|