Federal tax / Verification

How the federal tax engine is verified

What is tested, against what, and where the testing stops.

Every step has a test

Each calculation step names the tests that prove it (on the calculation order page); the documentation gate fails when a step has no test, or names a test that does not exist. The composition's tests are hand-worked returns on the 2026 parameters (the result and every Form 1040 line), every sign combination of the capital-gain netting, every branch of the senior deduction, and four Form 1040 identities on a random corpus (taxable income, line 7a, total income, total tax).

Every line and branch is executed

The coverage gate builds the engine with coverage instrumentation, runs its tests and fails below these measured floors, and when the counts below no longer match a fresh run:

Outside this gate: rmd.c (the RMD tables and start ages, which the RMD steps call) and irmaa.c (the planner's Medicare tiers, not part of Form 1040). Both have their own unit tests (test_rmd_irmaa.c) but no coverage floor.

No change without a record

The engine was extracted from the planner without changing a single result: a golden corpus recorded from the planner before the extraction (every federal caller: the withdrawal cost and optimiser, every withdrawal policy, the tax-aware simulation's persona panel, full simulation and ACA-bridge responses) is compared bit for bit on every change. A change that moves a result must carry a new engine version, a record in the defects ledger and a re-recorded corpus.

The API is the planner's engine

The API's 2026 parameters are held byte-identical to the planner's 2026 year for every filing status and age pair, and the state API's computeFederal is held to the planner: for a single filer the federal tax and the state tax it returns equal the planner's in every jurisdiction. The published schema, rules and worked examples are regenerated from the code and checked on a seeded corpus of a few thousand requests: every accepted request and every response validates, and every refusal is a documented message.

Sources are re-checked weekly

Every passage on the sources page is re-fetched weekly from its official source; the job fails when a passage is no longer there, and its date on these pages moves only when the passage was found again.

Where it stops

The engine computes the parts of a return listed on the overview and nothing else; what it does not model is listed there too. The API refuses a request key it does not know, but it cannot detect income, credits or taxes that are not sent, so a figure is complete only for a household whose whole return is within its fields. Line ids follow the final 2025 forms (formYear); each line also carries its number on the 2026 drafts (lineNumberDraft2026).