State tax docs / Verification
How the state tax engine is verified
What is tested, against what, and where the testing stops. The status of each state below is an audit of the test suite and the engine's cited sources as they stand, not a statement of confidence.
Golden scenarios
155 rows in the engine's golden-scenario file each carry an expected federal tax, state tax and Medicare surcharge computed by hand, independently of the engine, from the published rules. The suite runs the engine on every row and fails if any result is more than $1 away. When a row's derivation follows a state's own form, worksheet or rate schedule, the row says so; those rows, and unit tests whose derivation does the same, are what the worksheet-tested class below counts.
Tax year 2025 has its own set: 168 2025 returns, worked from the 2025 forms of 43 jurisdictions (15 of them for local income taxes) and held to within $1 in the same suite. The golden scenarios and the 2025 returns run on every build.
Golden rounds
A golden round is a separate, periodic check, not part of every build. A fresh batch of returns is worked from each state's official forms and instructions without access to the engine's source or tests, and every return is compared with the library's answer to the cent. Each difference is settled from the primary source: where the engine was wrong it is corrected, and the case that showed it is added to the test suite. The largest so far, round 11 on state engine 1.24.0, compared 21,888 returns in 43 jurisdictions; it is the round the changelog cites for engine 1.25.0. Golden rounds are counted separately from the 155 golden scenarios and the 168 2025 returns above, which are the cases kept in the test suite.
Unit tests
The state-tax unit suite has tests for individual rules (a state's exclusion cap, its Social Security formula, its married-filing-separately schedule) and structural tests over every jurisdiction: each state resolves, every bracket table is contiguous with non-decreasing rates, no state uses a placeholder schedule, and calls without a spouse split give results identical to the pooled household calculation.
Status classes
- Worksheet-tested Worksheet-tested: at least one golden scenario or unit test pins an exact dollar result for this state, hand-computed independently of the engine, and the test's own derivation names the state form, worksheet or rate schedule it follows.
- Statute and instructions cited Statute and instructions cited: the engine's rules for this state cite the state's statute, instructions or tax agency, and tests pin its rules, but no test derivation follows a named state worksheet.
- Rate table only Rate table only: the state's rate schedule and deductions are its only state-specific inputs and the engine cites only a rate-table compilation for them.
- No income tax No broad personal income tax: nothing to compute beyond any special levy the page lists.
Counts: worksheet-tested 42; statute and instructions cited 0; rate table only 0; no income tax 9.
The depth of that testing differs. For 24 of the worksheet-tested states (AZ, AR, CA, GA, HI, ID, IL, IN, IA, KS, MD, MA, MI, MN, MS, NM, NC, OH, OR, PA, RI, SC, UT, VT) the suite replays the state's return line by line through the API. For the other 18 (AL, CO, CT, DE, DC, KY, LA, ME, MO, MT, NE, NJ, NY, ND, OK, VA, WV, WI) the tests follow the specific form, worksheet or rate schedule named in the Basis column, not the whole return.
Per-state status
| Jurisdiction | Status | Golden rows | State-specific unit tests | Basis |
|---|---|---|---|---|
| Alabama | Worksheet-tested | 7 | 14 | Golden rows follow the Form 40 federal-income-tax worksheet and Schedule RS (per-spouse line 10). |
| Alaska | No income tax | 0 | 0 | No broad personal income tax; the engine returns zero, and the golden scenarios include no-tax rows. |
| Arizona | Worksheet-tested | 1 | 14 | Arizona Form 140 (TY2025 instructions with official 2026 figures: std deduction $16,100/$24,150/$32,200) replayed line by line — lines 12-24 capital-gain subtraction, 29a public pension, 29b military, 30 Social Security, 36 other subtractions (HB 4168 senior subtraction), 38 age-65 exemption, 42-46 — in the engine's test suite. |
| Arkansas | Worksheet-tested | 1 | 15 | Arkansas Form AR1000F (TY2025 form and instructions with the official 2026 figures: DFA 2026 withholding-formula brackets, Act 1 of 2026 top rate 3.7%) replayed line by line — lines 7A/7C/34 personal credits, 14 with AR1000D (50% net capital gain), 16, 17 military retirement, 18A/18B $6,000 per-taxpayer exemption, 25-29 standard deduction and Regular/Low Income Tax Table, 33-38 — in the engine's test suite. |
| California | Worksheet-tested | 6 | 37 | The engine's test suite replays the 2025 Form 540 line by line, with the FTB's published 2026 indexing (Tax Rate Schedules X, Y and Z, the standard deductions and the exemption credits; the 2026 booklet is not out yet): Schedule CA subtractions (Social Security, the military exclusion and its federal-AGI cliff), the standard deduction, the line 7-9 exemption credits, the tax table by its midpoint method and Schedules X and Y, and the line 62 Behavioral Health Services Tax. |
| Colorado | Worksheet-tested | 4 | 31 | Golden and unit tests follow form DR 0104 line 1 (federal taxable income) and DR 0104AD line 4 (the pension and Social Security subtraction). |
| Connecticut | Worksheet-tested | 4 | 17 | Unit and golden tests follow the CT-1040 Tax Calculation Schedule (Tables C and D) and the Social Security benefit adjustment worksheet. |
| Delaware | Worksheet-tested | 5 | 21 | Golden and unit tests follow the PIT-RES instructions, Line 6 pension exclusion worksheet (including the per-taxpayer columns). |
| District of Columbia | Worksheet-tested | 3 | 15 | An engine 1.2.0 test follows the 2026 D-40ES head-of-household deduction; golden rows pin the schedule. |
| Florida | No income tax | 1 | 2 | No broad personal income tax; the engine returns zero, and the golden scenarios include no-tax rows. |
| Georgia | Worksheet-tested | 6 | 24 | The engine's test suite replays the 2025 Form 500 (with the 2026 HB 463 rate 4.99% and $15,000/$30,000 standard deduction substituted) line by line: Schedule 1 page 2 Retirement Income Exclusion per taxpayer column (62-64 and 65+ caps, earned-income part, IRA/conversion/pension/capital-gain pooling, per-spouse caps, joint gains 50/50), Schedule 1 page 3 Military Retirement Income Exclusion (under-62 base and the $17,500 earned-income test), Social Security subtraction, and line 16 rounding. |
| Hawaii | Worksheet-tested | 5 | 11 | The engine's test suite replays the 2025 Form N-11 with the 2026 standard deduction (HRS 235-2.4(a)(2)(F); the 2025-2026 rate schedules are unchanged) line by line: the line 13 employer-funded/military pension and line 14 Social Security subtractions, the standard deduction, the Tax Table by its midpoint method and Schedules I and II, and the Tax on Capital Gains Worksheet. |
| Idaho | Worksheet-tested | 1 | 12 | The engine's test suite replays the 2025 Idaho Form 40 (with the 2026 federal standard-deduction figures Idaho adopts) line by line: Form 39R Part B line 7 (taxable Social Security) and line 8 (Retirement Benefits Deduction for military and CSRS, per-return cap reduced by Social Security), the standard deduction worksheet with the 65+ amounts, line 18 federal Schedule 1-A senior deduction and its phase-out, and the line 20 tax worksheet. |
| Illinois | Worksheet-tested | 2 | 12 | The engine's test suite replays Form IL-1040 (2025, with the 2026 $2,925 exemption) line by line: line 5 Social Security and retirement subtraction (IRA, pensions, military, conversions), the line 10a and 10b exemption allowance per filer and per 65+ box, and line 12 at 4.95%. |
| Indiana | Worksheet-tested | 1 | 14 | Scenarios replay Form IT-40 lines 1-9 with Schedule 2 (Social Security line 5, military code 632), Schedule 3 (lines 1, 4, 5 incl. the $40,000 / MFS $20,000 test) and Schedule CT-40 lines 1-3, using the TY2025 forms with the 2026 2.95% rate from DN #1. |
| Iowa | Worksheet-tested | 2 | 11 | The engine's test suite replays the 2025 IA 1040 (2026 form not yet published; 2026 rate and federal figures substituted) line by line: line 2 federal taxable income, Schedule 1 lines 4 (military), 5 (Social Security) and 7 (retirement income per recipient 55+, incl. Roth conversions), line 4, the line 5 flat 3.8% tax and the line 8 exemption credits, with the alternate-tax and low-income-exemption worksheets checked for each case. |
| Kansas | Worksheet-tested | 2 | 5 | 16 scenarios run through the JSON API follow Form K-40 lines 1-8 (2025 booklet IP25, whose amounts are statutory for 2026), with Schedule S lines A10 and A14, the Tax Table midpoint rows and the Tax Computation Worksheet; 8 more head-of-household and 65+ scenarios (formerly pending findings, resolved by engine 1.5.0) are asserted too. |
| Kentucky | Worksheet-tested | 0 | 13 | A unit test pins the $31,110 exclusion drawn by a Roth conversion, following Schedule P. |
| Louisiana | Worksheet-tested | 4 | 10 | Golden rows follow the IT-540 instructions' Schedule E code 06E definition of retirement income, including per-spouse rows. |
| Maine | Worksheet-tested | 3 | 16 | Golden rows follow the Form 1040ME instructions, including the Schedule 1S pension deduction and its conversion rule. |
| Maryland | Worksheet-tested | 4 | 27 | Worksheet-tested: 22 scenarios through state_tax_json_handle() replay the 2025 Form 502 line by line with the official 2026 figures ($3,400 single deduction, $40,600 pension exclusion): Worksheet 13A per-spouse columns with the Social Security offset, Chart 10A exemption steps at $100,000/$150,000, the Tax Table midpoint rows and Computation Worksheet Schedules I/II, military code u, Form 502CG line 21b and line 28 local tax; each asserted against the form's whole-dollar line 34 and to the cent against Schedule I/II. |
| Massachusetts | Worksheet-tested | 0 | 15 | Form 1 replayed line by line (2025 Form 1 and instructions with the TY2026 4% surtax threshold of $1,107,750): exemptions lines 2a-2d, exempt contributory/military pensions line 4, Schedule X line 2 IRA and conversions, lines 11a/11b, the line 22 tax table and 5% rate, Schedule B 8.5% income, Schedule D line 24, No Tax Status and the Limited Income Credit, Schedule 4% Surtax; 22 scenarios asserted in the engine's test suite (the 5 differences an earlier worksheet review found, resolved by engine 1.6.0), every Form 1 line mapped in the state's form-line map; its 2 form-map findings (the Schedule B / Schedule D order of excess exemptions and no excess exemptions on a separate return) are fixed and asserted. |
| Michigan | Worksheet-tested | 0 | 13 | 16 JSON-API scenarios replay the 2025 MI-1040, Schedule 1 and Form 4884 (Worksheet 3.3, Section A) with the official 2026 figures ($5,900 exemption, $67,610 / $135,220 limit, 100% phase-in); the 6 further differences the worksheet pass found are resolved and asserted (engine 1.6.0 and 1.7.0). The form-line map adds 11 asserted cases and the Tier 2 add-on of Worksheet 2 line 2a (engine 1.8.0); no difference is pending. |
| Minnesota | Worksheet-tested | 2 | 17 | 21 worksheet scenarios replay Form M1 lines 1-10 (standard deduction table with the 65+ boxes, tax table midpoint method below $86,800, rate schedules above) with Schedule M1M lines 12 (Worksheet for line 12, simplified and alternate methods), 25 (military) and 29 (Schedule M1QPEN), on the TY2025 forms with the TY2026 inflation-adjusted amounts substituted; all match within the form's whole-dollar rounding, including the 3 cases (Schedule M1R, the alternate Social Security subtraction, the line 4 standard deduction limitation) that departed from the form until engine 1.6.0. |
| Mississippi | Worksheet-tested | 3 | 8 | 23 worksheet scenarios replay Form 80-105 lines 8-17 and the Schedule of Tax Computation (per-column $10,000 0% band) at the 2026 rate of 4% (2025 instructions, 2026 rate substituted), all exact to the cent, including the 3 cases (head-of-family dependent exemption, separate-return exemption split, the per-spouse 0% band) an earlier worksheet review recorded until engines 1.6.0 and 1.7.0 fixed them. |
| Missouri | Worksheet-tested | 9 | 29 | Golden and unit tests follow Form MO-A Part 3 Sections A, B and C line by line, including the per-spouse columns. |
| Montana | Worksheet-tested | 1 | 11 | A golden row follows Form 2 line 3 (federal taxable income less federal deductions). |
| Nebraska | Worksheet-tested | 0 | 8 | Engine 1.2.0 tests follow the 2026 Form 1040N-ES rate schedules, including head of household. |
| Nevada | No income tax | 0 | 0 | No broad personal income tax; the engine returns zero, and the golden scenarios include no-tax rows. |
| New Hampshire | No income tax | 0 | 0 | No broad personal income tax; the engine returns zero, and the golden scenarios include no-tax rows. |
| New Jersey | Worksheet-tested | 2 | 14 | Engine 1.2.0 tests follow the NJ-1040 pension exclusion worksheet (band percentage of the whole pension) and Tables A and B. |
| New Mexico | Worksheet-tested | 4 | 9 | 22 scenarios in the engine's test suite replay the TY2025 PIT-1, PIT-ADJ and PIT-TRT line by line (2026 federal standard deduction substituted) through the JSON API. |
| New York | Worksheet-tested | 8 | 32 | Engine 1.2.0 tests follow the 2026 IT-2105-I tax rate schedules and recapture worksheets, including the head-of-household schedule. |
| North Carolina | Worksheet-tested | 1 | 3 | 16 worksheet scenarios replay Form D-400 lines 6-15 with Schedule S lines 19 (Social Security) and 21 (military retirement), at the 2026 rate of 3.99% (2025 forms, 2026 rate substituted); every scenario matches the unrounded product to the cent. |
| North Dakota | Worksheet-tested | 1 | 8 | Engine 1.2.0 tests follow the 2026 ND-1ES rate schedules for single, joint and head of household. |
| Ohio | Worksheet-tested | 1 | 14 | The engine's test suite replays the IT 1040 (2025 booklet with the 2026 R.C. 5747.02 schedule and $500,000 cutoffs) line by line, including the joint filing credit, through the API. |
| Oklahoma | Worksheet-tested | 4 | 11 | Golden and unit tests follow Schedule 511-A line 6, including the per-person exclusion. |
| Oregon | Worksheet-tested | 2 | 21 | The engine's test suite replays Form OR-40 lines 7-25 (2025 booklet, 2026 figures): tax table midpoint method and rate charts S/J, the federal tax liability subtraction worksheet with Table 9, and the exemption credit worksheet. |
| Pennsylvania | Worksheet-tested | 2 | 20 | Scenarios replay the 2025 PA-40 (lines 1a, 5, 9, 11, 12), its IRA, pension and Social Security instructions and Schedule SP. |
| Rhode Island | Worksheet-tested | 6 | 8 | Scenarios replay the RI-1040 (lines 1-8), Schedule M lines 1s/1t/1v, the Taxable Social Security Income Worksheet, the tax table (midpoint method) and computation worksheet with ADV 2025-22 2026 figures. |
| South Carolina | Worksheet-tested | 6 | 17 | Scenarios replay the 2025 SC1040 (lines 1, i, o, p-1 to p-5, q-1, q-2, 5, 6) and its p/q worksheets with the Act 110 figures from SC Information Letter #26-20 (federal AGI start, SCIAD, 1.99%/5.21%), and the SC1040TT table method. |
| South Dakota | No income tax | 0 | 0 | No broad personal income tax; the engine returns zero, and the golden scenarios include no-tax rows. |
| Tennessee | No income tax | 0 | 0 | No broad personal income tax; the engine returns zero, and the golden scenarios include no-tax rows. |
| Texas | No income tax | 33 | 8 | No broad personal income tax; the engine returns zero, and the golden scenarios include no-tax rows. |
| Utah | Worksheet-tested | 0 | 16 | Scenarios replay the TC-40 tax and taxpayer tax credit lines 9-22 and the TC-40A Social Security (AH) and military retirement (AJ) credit worksheets, 2025 forms with the 2026 rate and federal deductions. |
| Vermont | Worksheet-tested | 1 | 16 | Scenarios replay the 2025 IN-111 (lines 1-8, tax table and rate schedules), the Schedule IN-112 retirement and military exemption worksheets and Schedule IN-153 with the 2026 schedules and $5,400 exemption. |
| Virginia | Worksheet-tested | 3 | 22 | Golden and unit tests follow the Form 760 Age Deduction Worksheet (lines 9 to 15); engine 1.8.0 (S5) tests replay the Spouse Tax Adjustment Worksheet, the §58.1-321 no-tax threshold and the choice between the age deduction and the disability subtraction. |
| Washington | No income tax | 0 | 3 | No income tax. The capital-gains excise (RCW 82.87) is pinned by an exact unit test. |
| West Virginia | Worksheet-tested | 1 | 12 | A unit test follows the IT-140 Rate Schedule II for married filing separately; engine 1.8.0 (S5) tests follow §11-21-12(c)(9) per person (own public-pension remainder, own half of the household offsets). |
| Wisconsin | Worksheet-tested | 3 | 16 | Engine 1.2.0 tests follow the 2026 Form 1-ES standard-deduction table, including the head-of-household and MFS rows; engine 1.8.0 (S5) tests read it at Form 1 line 7 and replay Schedule SB line 17. |
| Wyoming | No income tax | 0 | 0 | No broad personal income tax; the engine returns zero, and the golden scenarios include no-tax rows. |
Gates
- The engine test suite (unit tests and golden scenarios) runs inside the engine's container build, so an engine that fails a test cannot be built for deployment.
- This documentation is generated from the engine's dump. A docs gate rebuilds the dump from the engine source and fails if it differs from the committed copy, regenerates every page and fails if any differs, and fails if a state page carries a rule with no source, a source with no checked date, or a source checked against a value the engine no longer holds.
- Every other page that restates a state rate or rule (state pages, comparisons, the 51-state study and dataset) is held to the engine's own dump by separate gates.
Recurring checks
- Weekly: every provenance source is fetched; a dead link, a redirect to a different page, or a missing checked figure is reported, and a failure that persists across two weekly runs pages the operator.
- Nightly: realistic households run through the live production engine and are checked against the product's published claims; for state tax this confirms that a taxing state changes the outcome relative to a no-tax state.
Open differences between a source and the engine
| State | Rule | Source says | Engine | Note |
|---|---|---|---|---|
| AZ | Capital gains | 25% subtraction only for assets acquired after December 31, 2011 | 75% | The engine assumes gains are on assets bought after 2011 (75% taxed); it has no acquisition-date input, so gain on older assets is under-taxed by 2.5% of 25% of it. |
| NY | IRA, 401(k) and private pensions | 59½ | age 59 | The engine's ages are whole years, so its test is age 59: from 59 the exclusion is given on all of the year's IRA, employer-plan and private pension income except the part the caller gives as retirementIncomeBefore59Half (received before reaching 59½; accepted at age 59 or 60). For a person who reaches 59½ only in the next year all of it belongs there; without it the engine gives the exclusion the statute does not. A Roth conversion made before 59½ is not separated (the input covers distributions and pensions). |
Rules without an official source
| State | Rule | Why |
|---|---|---|
| ID | Social Security | No official Idaho source could be fetched: tax.idaho.gov and legislature.idaho.gov (and every *.idaho.gov host tried) refuse connections from the server that runs our automated source check. No secondary source for Idaho's Social Security exemption was verified either. |
| ID | IRA, 401(k) and private pensions | No official page states in terms that Idaho has no general retirement exclusion; Idaho Code 63-3022A (see Public pensions and Military retirement pay) lists the only retirement benefits Idaho deducts. |
| ID | Roth conversions | No official Idaho source could be fetched: tax.idaho.gov and legislature.idaho.gov (and every *.idaho.gov host tried) refuse connections from the server that runs our automated source check. |
Sources on the state pages: 1368 citations across 515 rule sections; 304 of them are read from an Internet Archive copy of the official URL, mostly because the state's site refuses connections from the server that runs our automated source check.