README.md
taxbender v0.0.1 — a machine-verified Form 1040
A federal income tax computation (2024, Form 1040) written in
Bend, with every claim about it proven by the
compiler. bend PROOF.bend is the compliance gate: ALL PROOFS CHECK
or it ships not.
Why
Tax software fails silently: a wrong bracket boundary, a float that
rounds the wrong way, an overflow nobody noticed. This project makes
those mistakes unrepresentable:
- All money is
Nat— unbounded natural numbers. No floats, and overflow is structurally impossible. - Rates are integer basis points —
1240nis 12.4%. No rounding surprises beyond the explicit, IRS-worksheet-mandated floors. - The laws are code. LAWS.bend states what an auditor would ask ("every dollar lands in exactly one bracket", "the QBI deduction never exceeds 20% of QBI"); PROOF.bend proves each one, and the checker rejects any edit that breaks a proof.
Layout
| File | Role |
|---|---|
| tax.bend | The engine. Kernels parameterized over the statutory tables; no numbers. |
| tables_2024.bend | 2024 amounts that don't depend on filing status (rates, SS wage base). |
| tables_2024_single.bend | 2024 brackets, LTCG breakpoints, standard deduction — single. |
| tables_2024_mfj.bend | Same — married filing jointly. |
| prepare.sh | Interactive wizard: walks the 1040, edit-or-accept each line. |
| return.bend | Prints the finished return: headline first, story after. |
| inputs.bend | Generated taxpayer facts (gitignored — it's your data). |
| demo.bend | A worked MFJ example run. |
| LAWS.bend | The claims, in human-read form. |
| PROOF.bend | The machine-checked proofs of those claims. |
inputs.bend is the seam: the wizard writes it, return.bend reads it.
Taxpayer facts live there; the law travels in Tables, built by
whichever tables_<year>_<status> module the inputs select.
Usage
Bend must be installed (curl -fsSL https://bend-lang.com/install.sh | sh);
the binary lands in ~/.bend/bin.
File a return interactively — it walks you through income, then
payments, letting you accept (Enter) or edit (type a number) each line:
./prepare.sh
It ends by printing the return in journalistic order: the headline
(TOTAL TAX, payments, refund or owed) first, then the story — income,
the Schedule SE side, deductions, and how the tax was computed.
Run the worked example:
~/.bend/bin/bend demo.bend
Run the compliance gate (also required before committing, per
~/.bend/bin/bend PROOF.bend # checker
~/.bend/bin/bend PROOF.bend --verdict # independent Lean kernel re-check
What's proven
- Tiling: a chained 6-bracket table (each floor literally the
previous floor plus band width) splits income with no gap and no
overlap — proven generically for any chained table, so a new year's
numbers inherit the proof by construction. demo.bend re-checks the
concrete instantiation at runtime.
- Worksheet identity: the ordinary tax is exactly Σ (band width × rate), floored, plus the top slice.
- LTCG bands behave as labeled: below the 0% threshold the whole gain is in the 0% band; when the stack ends under the 15%→20% breakpoint the 20% band is empty.
- Schedule SE: the SE tax is exactly Medicare part + Social Security part, and the §164(f) deduction is exactly half of it.
- §199A: the QBI deduction never exceeds 20% of qualified business income.
Scope (on purpose)
Single standard deduction only; one taxpayer per return; wage/SSTB
limits on §199A, NIIT, itemized deductions, and multi-year tables are
deferred. The Tables struct is where the next year or filing status
plugs in: copy a tables_2024_*.bend file, change the numbers, keep the
shape — the proofs carry over.