QuantCalc QuantCalc Federal tax engine docs

Federal tax / Calculation order

Federal tax: the calculation, step by step

Every step the federal engine takes, in the order it takes them: the Form 1040 lines it fills, the code that does it, the tests that prove it and the official sources of the rule. The API returns the same line ids in lines[], each with its rule naming a section below. Line ids (lines[].line) and lineNumber follow the final 2025 forms, the latest the IRS has published as final; the ids stay fixed so API callers are not broken. The IRS's early-release drafts of the 2026 forms (marked 'DRAFT—NOT FOR FILING', subject to change) renumber several lines, and each line also carries its number on the 2026 draft (lineNumberDraft2026). The engine applies the 2026 law either way; only the line numbers differ. Each line below gives both numbers. The 2026 drafts: Form 1040 (2026), early release draft, Schedule 1-A (Form 1040) (2026), early release draft, Schedule 2 (Form 1040) (2026), early release draft, Schedule A (Form 1040) (2026), early release draft, Form 5329 (2026), early release draft.

Request handling (the API)

One field table: keys, types, limits and unknown keys

Every request key is one row of a table: its camelCase name, its snake_case spelling, its type and limits, whether it is required, and where its value goes in the engine input. The parser reads the body through the table; a key that is not a row is refused with 400 rather than ignored, because a field the engine does not model (a tax credit, for example) would otherwise vanish from a figure that looks complete. Keys match case-insensitively; a row sent twice (two spellings or two cases) is refused. GET /api/federal-tax/schema is generated from the same table.

Code: backend/src/federal_tax_json.c federal_tax_json_fields, federal_tax_json_parse. Tests: test_federal_api.c test_parse_types; test_federal_api.c test_unknown_and_duplicate_keys; test_federal_api.c test_f2_duplicate_null; test_federal_api.c test_f2_typed_stage2; test_federal_api.c test_field_table_documented; test_federal_api.c test_r1r2_fields.

Sources: API design, not tax law.

Value checks and the return's facts

age is required: the filer's age at the end of the year decides the §72(t) additional tax, the §63(f) aged amount and the senior deduction, and no default would be right for everyone. Amounts are finite and at most $100 billion; gains may be negative (a loss), every other amount may not. spouseAge is required on a joint return and refused on any other; mfsLivedApart only on a separate return.

Code: backend/src/federal_tax_json.c federal_tax_request_eval. Tests: test_federal_api.c test_value_checks; test_federal_api.c test_status_dependent_fields; test_federal_api.c test_extended_fields.

Sources: API design, not tax law.

The year's parameters

The 2026 parameters of the filing status (Rev. Proc. 2025-32), the §63(f) aged amount for each 65+ filer (both spouses on a joint return) added to the standard deduction, and the senior deduction's amount, count, threshold and rate when someone qualifies: built by federal_tax_config_for_year (backend/src/federal_tax.c), the same builder /api/simulate uses for its 2026 year and the ACA bridge uses for every year (a test holds the API, the simulation and the builder byte-identical for every status and age pair).

Code: backend/src/federal_tax_json.c federal_tax_json_config. Tests: test_federal_api_sim.c test_config_matches_simulation.

Sources: API design, not tax law: the rules themselves are the deduction steps below.

The projection: a later tax year

projection {year, inflation or cpiFactor, awiFactor, indexing} asks for a tax year after 2026. The year is 2026 to 2100; exactly one of inflation (the annual CPI assumption, the factor is (1 + inflation) to the power of the years since 2026) or cpiFactor (the cumulative factor itself; 1 for 2026); awiFactor moves the wage-indexed amounts and defaults to the CPI factor; indexing "law" (the default) moves each amount the way its statute does, "inflation" is the planner's convention before federal engine 2.0. The return is priced on the year's projected amounts, the extended composition reads the year (the SALT schedule, the senior deduction's end, the Roth and RMD clocks), and the response carries rulesYear, projectedYear, projected and a projection block with every amount the return reads, its 2026 and projected values and its rule and sources. A later year has no published Tax Table: without taxTable the rate schedules price line 16; taxTable true with indexing "law" is refused (the table's ceiling after 2026 is not established by an official source). Form 2210 is refused with a later year (its due dates and interest rates are 2026's).

Code: backend/src/federal_tax_json.c parse_projection, projection_values_ok, federal_tax_json_projection. Tests: test_federal_2_projection.c test_f_api; test_federal_2_projection.c test_g_state_compute_federal.

Sources: API design, not tax law: the amounts and their rules are the projection steps below and research/data/federal-tax-indexing.json.

The response: result, Form 1040 lines and sources

The response carries the inputs as sent, the year's result, one entry per Form 1040 line the composition fills (with the rule that produced it) and, per calculation step on the return, its official sources with the quote that was checked and the date (only the bracket table of the return's filing status). includeSources: false leaves the sources out; nothing else changes. rules.notModeled lists what the engine does not compute.

Code: backend/src/federal_tax_json.c federal_tax_json_response. Tests: test_federal_api.c test_response_shape; test_federal_api.c test_sources_per_step; test_federal_api.c test_metadata_endpoints.

Sources: API design, not tax law.

The state API's computeFederal

POST /api/state-tax with computeFederal: true builds one federal return from the state request (each person's wages, as one W-2 with the employer's social security and Medicare withholding, and self-employment income, as a Schedule C net profit; IRA and employer-plan distributions, pensions including Railroad Retirement Tier 2, Roth conversions, gains, gross Social Security, the ages) prices it as POST /api/federal-tax files it (line 16 from the Tax Table on the 2026 return and the rate schedules in a projected year, Form 6251, the credits with the ages of their tests; since 2026-10-09) and hands the state engine the return's own figures: the taxable Social Security, line 22 (after the alternative minimum tax and the nonrefundable credits) as the federal tax after credits, line 18 as the tax before them, the refundable credits (the earned income credit, which Alabama subtracts), the NIIT and federal taxable income. The state engine receives each person's wages plus the self-employment profit less half that person's self-employment tax as earned income (federal engine 2.0 W5; the self-employment and Additional Medicare taxes are not income tax, so the federal tax handed over stays the income tax). A state request carrying anything the federal engine does not model (disability pay, the state request's early-distribution split, IRA basis without the year-end value, disability, dependents, a separate filer's blind spouse) or its own federal figures is refused with 400. Off by default: without it the state API is unchanged, byte for byte. Its federal return is POST /api/federal-tax's for the same household, and the planner's year is the same request with taxTable:false (tested); for a single filer the state tax equals the planner's in every jurisdiction that does not read the federal tax (the Alabama, Missouri and Oregon deductions and Nebraska's cap read the return as filed, a few dollars of federal tax apart at most; tested); on a joint return the state API attributes each amount to the spouse who received it (the spouse object), which the planner's household model does not, so the two can differ in states with per-spouse rules while the federal return is the same. Blindness and filingStatus qss are priced (§63(f)(2); the joint tables for a qualifying surviving spouse), and so is investment income: the state request's ordinaryIncome (interest, non-qualified dividends) goes on line 2b and its qualifiedDividends on lines 3a and 3b.

Code: backend/src/state_tax_federal.c state_tax_federal_json_eval. Tests: test_federal_api_sim.c test_compute_federal_matches_simulation; test_federal_api.c test_compute_federal_values; test_federal_api.c test_compute_federal_refusals; test_federal_api.c test_compute_federal_off_is_unchanged; test_federal_api.c test_compute_federal_extended; test_federal_api.c test_compute_federal_investment_income.

Sources: API design, not tax law: it composes the federal and state engines, the federal return as POST /api/federal-tax files it.

Extended fields: Schedule A, 8606, 5329, the RMD, blindness, QSS and Form 2210

Any of the fields for the forms beyond the base return (birthMonth, blindCount, the Schedule A amounts, the retirement-account fields, the RMD fields, the Form 2210 fields) or filingStatus qss runs the extended composition and adds schedules to the response; without one, the response is the one the base composition gives. The Form 2210 calendar (due dates and quarterly underpayment rates) is the one the underpayment calculator uses, compared row by row by the drift gate.

Code: backend/src/federal_tax_json.c federal_tax_request_eval, federal_tax_json_schedules, federal_tax_json_est_calendar. Tests: test_federal_api.c test_extended_fields; test_federal_api.c test_extended_forms.

Income: Form 1040 lines 2a to 8

Tax-exempt interest

Tax-exempt interest (taxExemptInterest) is reported on line 2a and never taxed. It is added to provisional income for the Social Security test (§86(b)(2)(B)) and to the income the IRMAA tiers read, and nowhere else: not to AGI and not to the NIIT's MAGI.

Form lines (2025 forms): Form 1040 line 2a (Tax-exempt interest, 1040.2a)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_tax_exempt_interest.

IRA distributions and Roth conversions

A traditional IRA or plan distribution (iraDistributions) is ordinary income (§408(d)(1)), line 4b. A Roth conversion (rothConversion) is a distribution too and is reported on line 4b with it; the engine taxes it as ordinary income and, unlike the distribution, never charges the §72(t) additional tax on it. On the base return every dollar is taxable; with iraBasis and iraYearEndValue the extended return recovers after-tax basis pro rata (the Form 8606 steps below). The planner has no basis input.

Form lines (2025 forms): Form 1040 line 4b (IRA distributions, taxable amount, 1040.4b)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_single_senior_with_gains; test_federal_api.c test_lines_map_inputs.

Pensions and annuities

Pension and annuity income (pension) is ordinary income (§72(a)), line 5b, the taxable amount (no exclusion ratio for after-tax contributions is computed: send the taxable part). It is never net investment income, which is right for a plan pension (§401(a), 403(a), 403(b), IRAs, governmental 457(b); §1411(c)(5)). nonqualifiedAnnuity (engine 1.5.0) is also on line 5b; unlike a plan pension it is net investment income (Form 8960 line 3).

Form lines (2025 forms): Form 1040 line 5b (Pensions and annuities, taxable amount, 1040.5b)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_api.c test_lines_map_inputs; test_federal_formmap.c test_fm3_effects.

Social Security benefits

Gross Social Security benefits (socialSecurityGross, with any Railroad Retirement Tier 1) are line 6a; the taxable part is the next step.

Form lines (2025 forms): Form 1040 line 6a (Social security benefits, 1040.6a)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_single_senior_with_gains.

Taxable Social Security (the Pub 915 worksheet)

Provisional income is every other income item (IRA, pension, conversions, other income, interest and dividends, and both gain buckets after netting, less an allowed capital loss), plus tax-exempt interest, plus half the benefits. Up to 50% of benefits are taxable above the base amount ($25,000; $32,000 joint; $0 separate) and up to 85% above the adjusted base ($34,000; $44,000 joint; $0 separate), the smaller of the two worksheet amounts. A separate filer who lived apart from the spouse all year (mfsLivedApart) uses the single amounts.

Form lines (2025 forms): Form 1040 line 6b (Social security benefits, taxable amount, 1040.6b)

Code: backend/src/tax_calculator.c compute_ss_taxable_amount_v2. Tests: test_tax_calculator.c test_ss_taxation; test_tax_calculator.c test_ss_mfj; test_tax_calculator.c test_ss_mfs_zero_thresholds; test_tax_calculator.c test_ss_mfs_lived_apart_single_thresholds.

Other ordinary income

otherOrdinaryIncome is ordinary income that is neither an IRA distribution, a conversion nor a pension, and is not net investment income, for example taxable jury-duty pay or prizes (Schedule 1 line 8 items that are not investment income). Rents, royalties, partnership, S corporation and trust income and nonqualified annuities are net investment income: they have no field, and sent here they would escape the NIIT. It goes to line 8. Interest and dividends are not this field: send them as taxableInterest and ordinaryDividends / qualifiedDividends, which count toward the NIIT and the capital-gains worksheet.

Form lines (2025 forms): Form 1040 line 8 (Additional income from Schedule 1, line 10, 1040.8)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_api.c test_lines_map_inputs.

Rental real estate: the passive activity loss limit (Form 8582)

The rental real estate amounts (rentalNetIncome, the sum of Schedule E line 21 over the properties, and the prior years' unallowed loss) are one group on Form 8582: line 1 with active participation, line 2 without. When line 3 (the net) is zero or more, every loss is allowed. Otherwise, with active participation, the special allowance is up to $25,000, less half of modified AGI over $100,000 (line 6: AGI without the rental amounts, the taxable social security and the deductible part of self-employment tax); a married filer filing separately gets $12,500 over $50,000 after living apart all year and none after living with the spouse at any time. The loss not allowed is carried to the next year. A real estate professional's rentals are not passive: the year's amount is allowed in full and a prior unallowed loss offsets only that rental income.

Form lines (2025 forms): Form 8582 line 3 (Combine lines 1d and 2d, 8582.3); Form 8582 line 6 (Modified adjusted gross income, 8582.6); Form 8582 line 8 (Multiply line 7 by 50% (0.50). Do not enter more than $25,000, 8582.8); Form 8582 line 9 (Enter the smaller of line 4 or line 8, 8582.9); Form 8582 line 11 (Total losses allowed from all passive activities, 8582.11); Form 8582 line 2d (Combine lines 2a, 2b, and 2c, 8582.2d)

Code: backend/src/federal_tax.c ext_rental. Tests: test_federal_2_w21.c test_w21_rental_allowance; test_federal_2_w21.c test_w21_rental_phaseout; test_federal_2_w21.c test_w21_rental_mfs; test_federal_2_w21.c test_w21_rental_not_active; test_federal_2_w21.c test_w21_rental_professional; test_federal_2_w21.c test_w21_properties.

Rental real estate income or loss (Schedule E line 26, Schedule 1 line 5)

Schedule E line 26 is the rental net income, or the loss Form 8582 allows; it goes to Schedule 1 line 5 and Form 1040 line 8, so into AGI, the provisional income of the social security worksheet, the IRMAA MAGI and every AGI floor and phase-out. It is not self-employment income and not qualified business income (the rental safe harbor of Rev. Proc. 2019-38 is not modelled). With a K-1 amount on the return (federal engine 2.3), Schedule 1 line 5 is Schedule E line 41.

Form lines (2025 forms): Schedule E line 26 (Total rental real estate and royalty income or (loss), 1040se.26); Schedule 1 line 5 (Rental real estate, royalties, partnerships, S corporations, trusts, etc. Attach Schedule E, 1040s1.5)

Code: backend/src/federal_tax.c ext_rental, compose. Tests: test_federal_2_w21.c test_w21_rental_allowance; test_federal_2_w21.c test_w21_rental_niit.

Taxable interest (line 2b)

Interest from Schedule B is ordinary income: it is in AGI, so it raises Social Security provisional income, the IRMAA MAGI and the senior-deduction phase-out, and it is net investment income for the NIIT. API taxableInterest.

Form lines (2025 forms): Form 1040 line 2b (Taxable interest, 1040.2b)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_r1r2.c test_r1_schedule_b_single.

Ordinary dividends (line 3b)

All ordinary dividends, the qualified ones of line 3a included. The part that is not qualified is taxed as ordinary income; all of it is in AGI and is net investment income. API ordinaryDividends.

Form lines (2025 forms): Form 1040 line 3b (Ordinary dividends, 1040.3b)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_r1r2.c test_r1_nonqualified_dividends_only.

Partnerships, S corporations, estates and trusts (Schedule E Parts II-III) and Form 8582's other passive activities

Schedule E Parts II and III as net amounts per class, each after the basis and at-risk limits (the caller's): the K-1s' passive income or loss (k1PassiveIncome: trade or business activities without material participation, non-real-estate rentals, a limited partner's rental real estate) and its prior years' unallowed loss, the nonpassive income or loss (k1NonpassiveIncome, with the section 179 deduction), an estate's or trust's net income or loss (estateTrustIncome, passive with estateTrustPassive). The nonpassive amounts enter AGI as they are. The passive classes go on Form 8582 line 2 (all other passive activities) with the rental real estate (line 1): line 3 combines them; the special allowance (Part II, up to $25,000) reaches only the rental real estate with active participation (line 4: the smaller of the loss on line 1d or the loss on line 3); Part VI gives line 9 to the rental loss and Part VII spreads the rest of the line 3 loss over the remaining losses by their shares; an activity with an overall gain is allowed in full. Schedule E line 32 = the K-1 passive result + the nonpassive amount, line 37 the estate or trust, line 41 = 26 + 32 + 37 -> Schedule 1 line 5. A partner's self-employment earnings (partnershipSeEarnings, K-1 box 14 code A) go on Schedule SE line 2 only. A return whose net trade or business losses (Schedule C, Schedule E Parts II-III) exceed the section 461(l) threshold ($256,000; $512,000 joint) is refused: the excess business loss limitation is not modelled.

Form lines (2025 forms): Schedule E line 32 (Total partnership and S corporation income or (loss). Combine lines 30 and 31, 1040se.32); Schedule E line 37 (Total estate and trust income or (loss). Combine lines 35 and 36, 1040se.37); Schedule E line 41 (Total income or (loss). Combine lines 26, 32, 37, 39, and 40, 1040se.41)

Code: backend/src/federal_tax.c ext_passive, ext_k1_any, compose. Tests: test_federal_2_w23.c test_w23_k1_passive; test_federal_2_w23.c test_w23_k1_nonpassive; test_federal_2_w23.c test_w23_k1_guards; test_federal_2_w23.c test_w23_k1_properties.

Capital gains: Schedule D netting

Net short-term gain or loss

shortTermGains is the year's net short-term gain or loss (Schedule D line 7), signed.

Form lines (2025 forms): Schedule D line 7 (Net short-term capital gain or (loss), 1040sd.7)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_netting.

Net long-term gain or loss

longTermGains is the year's net long-term gain or loss (Schedule D line 15), signed.

Form lines (2025 forms): Schedule D line 15 (Net long-term capital gain or (loss), 1040sd.15)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_netting.

Combined net gain or loss

Schedule D line 16 is the sum of lines 7 and 15. A net loss in one bucket first offsets a net gain in the other; what is left in each bucket is taxed by its own character: short-term as ordinary income, long-term in the capital-gains worksheet.

Form lines (2025 forms): Schedule D line 16 (Lines 7 and 15 combined, 1040sd.16)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_netting.

Capital-gain distributions (Schedule D line 13)

Form 1099-DIV box 2a is long-term capital gain whatever the holding period. It enters Schedule D line 13, so it nets with the year's losses and the long-term carryover, and it is net investment income (Form 8960 line 5a). When the return needs no Schedule D the same amount goes on Form 1040 line 7a directly; the return is the same. API capitalGainDistributions (federal engine 2.0).

Form lines (2025 forms): Schedule D line 13 (Capital gain distributions, 1040sd.13)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_2_w1.c test_w1_cgd; test_federal_2_w1.c test_w1_properties; test_federal_2_w1.c test_w1_api.

28% rate gain (Schedule D line 18)

The 28% Rate Gain Worksheet: collectibles gain or loss (Form 1099-DIV box 2d included) and the taxable part of the section 1202 exclusion, less the long-term carryover and a net short-term loss, not below zero (IRC §1(h)(4)). API rate28Gain is the worksheet's lines 1 to 4; the engine applies lines 5 to 7.

Form lines (2025 forms): Schedule D line 18 (28% Rate Gain Worksheet, line 7, 1040sd.18)

Code: backend/src/federal_tax.c federal_rate28_gain. Tests: test_federal_2_w1.c test_w1_rate28_worksheet; test_federal_2_w1.c test_w1_sdtw_case_a; test_federal_2_w1.c test_w1_sdtw_gating.

Unrecaptured section 1250 gain (Schedule D line 19)

The Unrecaptured Section 1250 Gain Worksheet, lines 13 to 18: the gain (Form 1099-DIV box 2b included) less whatever loss is left after the 28% rate gain absorbs the net short-term loss and the long-term carryover, not below zero (IRC §1(h)(6)). API unrecapturedSection1250Gain is line 13.

Form lines (2025 forms): Schedule D line 19 (Unrecaptured Section 1250 Gain Worksheet, line 18, 1040sd.19)

Code: backend/src/federal_tax.c federal_unrecaptured_1250_gain. Tests: test_federal_2_w1.c test_w1_u1250_worksheet; test_federal_2_w1.c test_w1_sdtw_case_b.

Line 7a: the net gain, or a net loss

Line 7a is the net gain after netting. When the year's combined result is a loss, line 7a is the loss allowed on Schedule D line 21: up to $3,000 ($1,500 married filing separately; §1211(b)), a statutory amount that is not indexed, and the rest carries forward (see the capital-loss steps). Since engine 1.3.0 this applies on every return; before it, a net loss entered as 0 unless capitalLossRules was on. capitalLossRules: false keeps that old floor as an explicit opt-out, which is not the law.

Form lines (2025 forms): Form 1040 line 7a (Capital gain or (loss), 1040.7a)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_netting; test_federal_tax.c test_identities; test_federal_tax.c test_r13_capital_loss_default; test_federal_r1r2.c test_r2_limit_and_short_term_carryover.

Short-term capital loss carryover in (Schedule D line 6)

Last year's short-term carryover enters as a short-term loss. API capitalLossCarryoverShortTerm. The capital-loss rules apply on every return (engine 1.3.0); a carryover does not switch anything on.

Form lines (2025 forms): Schedule D line 6 (Short-term capital loss carryover, 1040sd.6)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_r1r2.c test_r2_carryover_in_absorbed.

Long-term capital loss carryover in (Schedule D line 14)

Last year's long-term carryover enters as a long-term loss. API capitalLossCarryoverLongTerm. The capital-loss rules apply on every return (engine 1.3.0); a carryover does not switch anything on.

Form lines (2025 forms): Schedule D line 14 (Long-term capital loss carryover, 1040sd.14)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_r1r2.c test_r2_carryover_in_absorbed.

Capital loss allowed (Schedule D line 21)

A net loss on line 16 is deductible up to $3,000 ($1,500 married filing separately), a statutory amount that is not indexed. It reduces AGI, so it also lowers provisional income for Social Security, the IRMAA MAGI, the senior-deduction phase-out and the NIIT base. On every return since engine 1.3.0 (the Monte Carlo planner, /api/simulate, the withdrawal optimizer, POST /api/federal-tax and computeFederal); capitalLossRules: false is an explicit opt-out to the pre-1.3.0 floor.

Form lines (2025 forms): Schedule D line 21 (Capital loss allowed, 1040sd.21)

Code: backend/src/federal_tax.c federal_tax_compute, federal_tax_compute_ext. Tests: test_federal_r1r2.c test_r2_mfs_limit_long_term_carryover; test_federal_tax.c test_r13_mfs_limit; test_federal_tax.c test_r13_capital_loss_default.

Short-term capital loss carryover to next year

The Capital Loss Carryover Worksheet, lines 1-8: the short-term loss not used this year. The allowed loss counts as used only up to taxable income plus the allowed loss (§1212(b)(2)), and it uses the short-term loss first. The carryover out is reported by the extended return (schedules.scheduleD); the Monte Carlo planner carries it per simulated path. In the year a spouse dies the planner carries forward only the survivor's share (IRS Pub 550: a decedent's loss is deductible only on the final return and the estate cannot carry it over; engine 1.4.0, API spouseCapitalLossShare on /api/simulate, default 0.5). A single return here reports the joint carryover; the caller enters the survivor's share next year.

Form lines (2025 forms): Capital Loss Carryover Worksheet line 8 (Short-term capital loss carryover to next year, 1040sdcw.8)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_r1r2.c test_r2_no_taxable_income_keeps_the_carryover; test_tax_aware_mc.c test_f14_carryover_split_at_spouse_death.

Long-term capital loss carryover to next year

The Capital Loss Carryover Worksheet, lines 9-13: the long-term loss not used this year, after this year's short-term gain and the part of the allowed loss the short-term loss did not use. The carryover out is reported by the extended return (schedules.scheduleD); the Monte Carlo planner carries it per simulated path. In the year a spouse dies the planner carries forward only the survivor's share (IRS Pub 550: a decedent's loss is deductible only on the final return and the estate cannot carry it over; engine 1.4.0, API spouseCapitalLossShare on /api/simulate, default 0.5). A single return here reports the joint carryover; the caller enters the survivor's share next year.

Form lines (2025 forms): Capital Loss Carryover Worksheet line 13 (Long-term capital loss carryover to next year, 1040sdcw.13)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_r1r2.c test_r2_mixed_character_carryover; test_tax_aware_mc.c test_f14_carryover_split_at_spouse_death.

Work income: wages, self-employment tax, the Additional Medicare Tax, tips, overtime and the QBI deduction

Wages (Form 1040 line 1a)

Form W-2 box 1 of the filer and, on a joint return, the spouse: ordinary income on line 1a (line 1z). Wages count in AGI, provisional income for Social Security and every MAGI; they are not net investment income. API wages, spouseWages (federal engine 2.0).

Form lines (2025 forms): Form 1040 line 1a (Total amount from Form(s) W-2, box 1, 1040.1a); Form 1040 line 1z (Add lines 1a through 1h, 1040.1z)

Code: backend/src/federal_tax.c ext_work_income. Tests: test_federal_2_w2.c test_w2_wages; test_federal_2_w2.c test_w2_api.

Business income (Schedule 1 line 3)

The net profit or loss of the self-employed business (Schedule C line 31, or a partnership's self-employment earnings): ordinary income through Schedule 1 line 3 and Form 1040 line 8. A loss offsets other income. API selfEmploymentIncome.

Form lines (2025 forms): Schedule 1 line 3 (Business income or (loss), 1040s1.3)

Code: backend/src/federal_tax.c ext_work_income. Tests: test_federal_2_w2.c test_w2_se; test_federal_2_w2.c test_w2_se_loss.

Self-employment tax (Schedule SE, Schedule 2 line 4)

Per person: 92.35% of the net profit (line 4a); under the floor no tax. Social security at 12.4% on the net earnings up to the wage base less the person's W-2 social security wages (lines 7 to 10), Medicare at 2.9% on all of them (line 11). Line 12 goes to Schedule 2 line 4.

Form lines (2025 forms): Schedule SE line 12 (Self-employment tax (the filer), 1040sse.12); Schedule SE line 12 (spouse) (Self-employment tax (the spouse's Schedule SE), 1040sse.12.spouse); Schedule 2 line 4 (Self-employment tax, 1040s2.4)

Code: backend/src/federal_tax.c federal_se_tax, ext_work_income. Tests: test_federal_2_w2.c test_w2_se; test_federal_2_w2.c test_w2_se_wage_base; test_federal_2_w2.c test_w2_properties.

Deductible part of self-employment tax (Schedule 1 line 15)

Half of Schedule SE line 12 (the Additional Medicare Tax is not part of it) is an adjustment to income (IRC §164(f)).

Form lines (2025 forms): Schedule 1 line 15 (Deductible part of self-employment tax, 1040s1.15)

Code: backend/src/federal_tax.c ext_work_income. Tests: test_federal_2_w2.c test_w2_se.

Self-employed retirement plan deduction (Schedule 1 line 16)

The deductible SEP, SIMPLE or qualified-plan contribution for the self-employed person, as the caller figured it (API sepContribution). It reduces AGI and the business's qualified business income.

Form lines (2025 forms): Schedule 1 line 16 (Self-employed SEP, SIMPLE, and qualified plans, 1040s1.16)

Code: backend/src/federal_tax.c ext_work_income. Tests: test_federal_2_w2.c test_w2_adjustments.

Self-employed health insurance deduction (Schedule 1 line 17)

The premiums, limited to the earned income from the business: the net profit less half the self-employment tax and the plan deduction (IRC §162(l)(2)(A)). It reduces AGI and qualified business income. The premium tax credit interaction is not modelled.

Form lines (2025 forms): Schedule 1 line 17 (Self-employed health insurance deduction, 1040s1.17)

Code: backend/src/federal_tax.c ext_work_income. Tests: test_federal_2_w2.c test_w2_adjustments.

Additional Medicare Tax (Form 8959)

0.9% of the Medicare wages over the threshold of the filing status (Part I) and of the self-employment income over the threshold less those wages (Part II). TY2025 puts the total on Schedule 2 line 11; the 2026 draft sends the wages part to Schedule 2 line 17b and the self-employment part to line 11. Part V: the withholding above 1.45% of the Medicare wages goes to Form 1040 line 25c (withholding, not the tax).

Form lines (2025 forms): Form 8959 line 7 (Additional Medicare Tax on Medicare wages, 8959.7; 2026 draft: 7 (to Schedule 2 line 17b)); Form 8959 line 13 (Additional Medicare Tax on self-employment income, 8959.13; 2026 draft: 18 (to Schedule 2 line 11)); Schedule 2 line 11 (Additional Medicare Tax, 1040s2.11; 2026 draft: 11 (SE part) + 17b (wages part)); Form 8959 line 24 (Total Additional Medicare Tax withholding (to Form 1040 line 25c), 8959.24)

Code: backend/src/federal_tax.c ext_work_income. Tests: test_federal_2_w2.c test_w2_8959; test_federal_2_w2.c test_w2_properties.

Excess social security tax withheld (Schedule 3 line 11)

Per person with more than one employer: the social security tax withheld above 6.2% of the wage base. It is a payment (Schedule 3 Part II), not a reduction of the total tax on line 24. API socialSecurityWithheld, employerCount.

Form lines (2025 forms): Schedule 3 line 11 (Excess social security and tier 1 RRTA tax withheld, 1040s3.11)

Code: backend/src/federal_tax.c ext_work_income. Tests: test_federal_2_w2.c test_w2_excess_ss.

Employee payroll taxes (FICA), a standalone function

The employee's social security (6.2% of the W-2 social security wages up to the wage base), Medicare (1.45%) and the Additional Medicare Tax the employer withholds above its withholding threshold (IRC §3102(f)). Used by the paycheck calculators; not part of Form 1040.

Code: backend/src/federal_tax.c federal_payroll. Tests: test_federal_2_w2.c test_w2_payroll.

The Social Security earnings test, a standalone function

Before the year of full retirement age, $1 of benefits withheld for every $2 of earnings over the lower exempt amount; in that year $1 for every $3 over the upper amount, counting only earnings before the month of full retirement age. Benefits are withheld in whole months. The planner applies it to each person's wages and net self-employment earnings in the years before that person's full retirement age, pays the withheld excess back the next year and, from full retirement age, refigures the benefit for the months withheld (federal engine 2.0).

Code: backend/src/federal_tax.c federal_ss_earnings_test. Tests: test_federal_2_w2.c test_w2_earnings_test.

Total income and adjusted gross income

Adjustments to income (Form 1040 line 10)

Schedule 1 line 26: the half-SE-tax, plan and health-insurance deductions. AGI (line 11a) is total income (line 9) less line 10. The other Schedule 1 Part II adjustments are not modelled.

Form lines (2025 forms): Form 1040 line 10 (Adjustments to income from Schedule 1, line 26, 1040.10)

Code: backend/src/federal_tax.c ext_work_income. Tests: test_federal_2_w2.c test_w2_adjustments; test_federal_2_w2.c test_w2_se.

Total income

Line 9 adds lines 4b, 5b, 6b, 7a and 8.

Form lines (2025 forms): Form 1040 line 9 (Total income, 1040.9)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_identities.

Adjusted gross income

No adjustment to income (Schedule 1 Part II) is modelled, so AGI (line 11a) equals total income. AGI is also the MAGI of the NIIT and of the senior deduction's phase-out.

Form lines (2025 forms): Form 1040 line 11a (Adjusted gross income, 1040.11a)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_identities; test_federal_tax.c test_single_senior_with_gains.

Deductions: the standard deduction, §63(f) and the senior deduction

Standard deduction and the §63(f) aged amount

The 2026 standard deduction of the filing status ($16,100 single and separate, $32,200 joint, $24,150 head of household), plus the §63(f) additional amount for each filer 65 or older at the end of the year ($2,050 unmarried, $1,650 per spouse married; on a joint return each spouse 65+ adds one). Itemizing (Schedule A) and the blindness amount are on the extended return (the steps below); the planner always takes the standard deduction and has no blindness input. Someone born on January 1 counts as 65 at the end of the year they reach 64: the IRS counts age 65 from the day before the 65th birthday (birthDay with birthMonth, and spouseBirthMonth with spouseBirthDay on a joint return; /api/simulate reads birthDay too; engine 1.5.0).

Form lines (2025 forms): Form 1040 line 12e (Standard deduction, 1040.12e)

Code: backend/src/tax_calculator.c tax_config_init, additional_std_deduction_aged_2026_couple. Tests: test_tax_calculator.c test_std_deduction_2026_all_statuses; test_tax_calculator.c test_aged_deduction_couple; test_federal_formmap.c test_fm1_effects.

Additional standard deduction for blindness

§63(f)(2): an additional amount for a filer who is blind at the end of the year, and for the spouse on a joint return: $2,050 if unmarried (single or head of household) and $1,650 if married or a qualifying surviving spouse (Rev. Proc. 2025-32). Added to the standard deduction; lost when the return itemizes. Request field blindCount.

Form lines (2025 forms): Form 1040 line 12e (part) (Additional standard deduction for blindness (§63(f)(2); no line of its own), 1040.12e.blind)

Code: backend/src/federal_tax.c ext_deduction. Tests: test_federal_tax_forms.c test_blind.

The senior deduction (Schedule 1-A)

For tax years 2025 to 2028, $6,000 for each individual 65 or older at the end of the year (both spouses on a joint return), reduced by 6% of MAGI over $75,000 ($150,000 joint), each individual's amount separately, not below zero. A separate return does not qualify. MAGI here is AGI. Someone born on January 1 counts as 65 at the end of the year they reach 64: the IRS counts age 65 from the day before the 65th birthday (birthDay with birthMonth, and spouseBirthMonth with spouseBirthDay on a joint return; /api/simulate reads birthDay too; engine 1.5.0). The engine assumes each qualifying individual has a valid social security number on the return, a condition of the deduction (§151(d)(5)(C)(iv)).

Form lines (2025 forms): Schedule 1-A line 37 (Enhanced deduction for seniors, 1040s1a.37; 2026 draft: 43)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_senior_branches; test_tax_calculator.c test_obbba_senior_deduction_couple; test_federal_formmap.c test_fm1_effects.

Tips received in a trade or business (section 224(c))

Qualified tips received in the filer's or the spouse's own business (not as an employee) count toward the tips deduction only up to that business's net profit, figured without the tips deduction (26 CFR 1.224-1(e)): each person's the smaller of the tips and Schedule C line 31 (not below 0), summed on Schedule 1-A 2025 line 5 (2026 draft line 7). The employee tips are not limited by it. API selfEmployedQualifiedTips, spouseSelfEmployedQualifiedTips (federal engine 2.3.2).

Form lines (2025 forms): Schedule 1-A line 5 (Qualified tips received in the course of a trade or business (after the net-profit limit), 1040s1a.5; 2026 draft: 7)

Code: backend/src/federal_tax.c ext_tips_overtime. Tests: test_federal_2_w2.c test_w2_tips_trade_or_business.

No tax on tips (Schedule 1-A Part II)

Qualified tips (the employee tips plus the business tips after section 224(c)) up to the cap, reduced by $100 for each whole $1,000 of MAGI over the threshold; tax years 2025 to 2028; a married filer must file jointly. A below-the-line deduction (Form 1040 line 13b with the senior deduction; 2026 draft 13a): it does not reduce AGI. API qualifiedTips, selfEmployedQualifiedTips.

Form lines (2025 forms): Schedule 1-A line 13 (Qualified tips deduction, 1040s1a.13; 2026 draft: 15)

Code: backend/src/federal_tax.c ext_tips_overtime. Tests: test_federal_2_w2.c test_w2_tips_overtime.

No tax on overtime (Schedule 1-A Part III)

Qualified overtime compensation up to the cap (twice as much on a joint return), with the same MAGI reduction, years and joint-return rule as tips. API qualifiedOvertime.

Form lines (2025 forms): Schedule 1-A line 21 (Qualified overtime compensation deduction, 1040s1a.21; 2026 draft: 27)

Code: backend/src/federal_tax.c ext_tips_overtime. Tests: test_federal_2_w2.c test_w2_tips_overtime.

Qualified business income deduction (Forms 8995 / 8995-A)

The self-employed business's qualified business income is its net profit less the half-SE-tax, plan and health-insurance deductions. At or below the threshold (Form 8995): 20% of it. Above (Form 8995-A): the W-2 wage and UBIA limit and, for a specified service business, the applicable percentage, both phased in over the range; losses of one spouse's business net against the other's. The deduction is at most 20% of taxable income before it less net capital gain and qualified dividends; from 2026 it is at least the section 199A(i) minimum when active QBI reaches the floor. Taxable income before the deduction is after the Schedule 1-A deductions (8995 line 11). A loss is carried forward (reported, not read back). Federal engine 2.3: the K-1s' qualified business income (k1QualifiedBusinessIncome, with its W-2 wages, UBIA and SSTB flag) is one more trade or business on Form 8995 / 8995-A, active for the section 199A(i) minimum only with k1QbiActive; when a partner's SE earnings share Schedule SE with a Schedule C business, the deductible part of SE tax that reduces the Schedule C QBI is its share of Schedule SE line 3.

How we read it (our interpretation, not settled guidance): Two readings of the 2026 draft forms. (1) Taxable income before the QBI deduction (Form 8995 line 11) is figured after the Schedule 1-A deductions (the senior deduction, tips and overtime): the 2026 draft instructions say "line 11a, minus lines 12e, 12f, and 13a", where line 13a is the Schedule 1-A total on the 2026 draft Form 1040. (2) The section 199A(i) minimum is not capped by taxable income (the statute sets it as the greater of the regular deduction or the minimum); Form 1040 line 15 cannot go below zero either way, so only the reported deduction differs. Every business is taken as one the filer materially participates in (an active business for the minimum).

Read from: www.irs.gov/pub/irs-dft/i8995--dft.pdf (line 11a, minus lines 12e, 12f, and 13a).

Form lines (2025 forms): Form 8995 line 11 (Taxable income before qualified business income deduction, 8995.11); Form 1040 line 13a (Qualified business income deduction, 1040.13a; 2026 draft: 13b)

Code: backend/src/federal_tax.c ext_qbi. Tests: test_federal_2_w2.c test_w2_qbi_8995; test_federal_2_w2.c test_w2_qbi_8995a; test_federal_2_w2.c test_w2_qbi_sstb; test_federal_2_w2.c test_w2_qbi_minimum; test_federal_2_w2.c test_w2_properties; test_federal_2_w23.c test_w23_k1_nonpassive.

Additional deductions on line 13b

Schedule 1-A's total (line 38) goes to Form 1040 line 13b (on the 2026 drafts: Schedule 1-A line 44 to Form 1040 line 13a). The engine's only Schedule 1-A deduction is the senior deduction; the tips, overtime and car-loan interest deductions are not modelled.

Form lines (2025 forms): Form 1040 line 13b (Additional deductions from Schedule 1-A, line 38 (the senior deduction, tips and overtime), 1040.13b; 2026 draft: 13a)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_single_senior_with_gains.

Total deductions

Line 14 adds the standard deduction (12e), the senior deduction (13b) and, from 2026, the non-itemizer charitable deduction (12f on the 2026 draft). There is no qualified business income deduction (2025 line 13a, 13b on the 2026 draft).

Form lines (2025 forms): Form 1040 line 14 (Total deductions (lines 12e, 13a and 13b), 1040.14)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_single_senior_with_gains.

Taxable income

Line 15 is AGI less the deductions, not below zero. The deductions reduce ordinary income first; what is left over (the unused deduction) reduces the long-term gain that enters the capital-gains worksheet.

Form lines (2025 forms): Form 1040 line 15 (Taxable income, 1040.15)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_unused_deduction; test_federal_tax.c test_identities.

Tax: the brackets and the capital-gains worksheet

Tax: the brackets and the capital-gains worksheet

Ordinary taxable income is taxed on the 2026 brackets of the filing status (10% to 37%). Long-term gain, and qualified dividends (§1(h)(11)), are stacked on top of it and taxed at 0%, 15% and 20% by where they fall on the 2026 capital-gains bands (the Qualified Dividends and Capital Gain Tax Worksheet). The worksheet's line 25 applies on every return (engine 1.3.0; before it, only on returns with interest, dividends or the capital-loss rules): the tax is never more than the regular tax on the same taxable income. It lowers the tax only where the 0% band ends inside the 12% bracket: by at most 3% (15% instead of 12%) of the gain between the top of the 0% band and the top of the 12% bracket. Line 16 is the sum. On the federal tax API, below the Tax Table's ceiling line 16 and the worksheet's lines 22 and 24 come from the table instead (the next step, engine 1.5.0).

Form lines (2025 forms): Form 1040 line 16 (Tax, 1040.16)

Code: backend/src/tax_calculator.c compute_ordinary_income_tax, compute_capital_gains_tax. Tests: test_tax_calculator.c test_ordinary_bracket_edges_2026; test_tax_calculator.c test_cg_stacking_15pct; test_tax_calculator.c test_cg_boundary_all_statuses; test_federal_tax.c test_single_senior_with_gains; test_federal_r1r2.c test_r1_qdcg_line_25; test_federal_tax.c test_r13_qdcg_line25; test_federal_tax.c test_r13_line25_property.

Tax: the Tax Table below $100,000

On POST /api/federal-tax and in the library (taxTable, default true; engine 1.5.0) Form 1040 line 16 is computed as filed: when taxable income is less than $100,000 the tax is the Tax Table's. IRC §3 imposes the table tax in lieu of the §1 tax, and the 1040 instructions require the table for every return under the ceiling, itemized or not. The row is read on taxable income to the cent, as line 15 is entered (the 1040 instructions allow rounding to whole dollars; cents are the finest amount on the return), so a sum that carries binary residue below a row edge reads the right row. Each row's tax is the rate-schedule tax at the row's midpoint, rounded to the nearest dollar with a half dollar rounding up; the rows are 0-5, 5-15 and 15-25, then 25 dollars wide up to 3,000 and 50 dollars wide up to 100,000 (verified on every row of the 2025 table, with no mismatch; the table's own example, a joint return in the 25,300-25,350 row, is $2,562). The Qualified Dividends and Capital Gain Tax Worksheet reads the table the same way on line 22 (the ordinary part) and line 24 (all taxable income), and line 25 then takes the smaller of lines 23 and 24 on every return with preferential income. From $100,000 the rate schedule applies (the step above). taxTable: false computes every dollar on the rate schedule. The planner and the ACA bridge use the rate schedule in every year: the tables of future years are not published and their solvers need a continuous tax, and the table moves a year's tax by at most half a row times the marginal rate plus rounding.

Form lines (2025 forms): Form 1040 line 16 (Tax, 1040.16)

Code: backend/src/federal_tax.c federal_tax_table_tax. Tests: test_federal_tax_forms.c test_f1_tax_table_2025_every_row; test_federal_tax_forms.c test_f1_tax_table_2026; test_federal_api.c test_f1_fields; test_federal_formmap.c test_fm1_effects; test_federal_formmap.c test_fm2_effects; test_federal_2_w3.c test_rc_tax_table_cents.

Tax: the Schedule D Tax Worksheet

When Schedule D line 18 or 19 is more than zero and lines 15 and 16 are both gains, line 16 comes from the Schedule D Tax Worksheet instead of the capital-gains worksheet (IRC §1(h)(1)). The unrecaptured section 1250 gain is taxed at no more than 25% and the 28% rate gain at no more than 28%; where the regular rate is lower they are taxed at the regular rate, so the worksheet can be below the capital-gains worksheet's tax. Qualified dividends and the other long-term gain keep 0%, 15% and 20%. Line 47 is the smaller of the worksheet total and the regular tax. The Form 4952 investment-interest election (lines 3 to 5 and 8) is not modelled. On the federal tax API lines 44 and 46 read the Tax Table below its ceiling, as line 16 does.

Form lines (2025 forms): Schedule D Tax Worksheet line 39 (Unrecaptured section 1250 gain taxed at 25%, 1040sdtw.39); Schedule D Tax Worksheet line 42 (28% rate gain taxed at 28%, 1040sdtw.42); Form 1040 line 16 (Tax, 1040.16)

Code: backend/src/federal_tax.c federal_sd_tax_worksheet. Tests: test_federal_2_w1.c test_w1_sdtw_case_a; test_federal_2_w1.c test_w1_sdtw_case_b; test_federal_2_w1.c test_w1_sdtw_case_c; test_federal_2_w1.c test_w1_sdtw_case_d; test_federal_2_w1.c test_w1_sdtw_case_e_tax_table; test_federal_2_w1.c test_w1_properties.

Qualified dividends (line 3a)

The qualified part of the ordinary dividends is taxed at the capital-gains rates: it joins the long-term gain in the Qualified Dividends and Capital Gain Tax Worksheet (line 2), after any deduction left over from ordinary income. The holding-period test (the 121-day period) is taken as met. API qualifiedDividends (part of ordinaryDividends).

Form lines (2025 forms): Form 1040 line 3a (Qualified dividends, 1040.3a)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_r1r2.c test_r1_qualified_dividends_sheltered.

The alternative minimum tax and the foreign tax credit

Foreign tax credit without Form 1116 (the section 904(j) election)

When all foreign income is passive (the fund dividends and interest the API takes) and reported on payee statements, and the foreign taxes are at most $300 ($600 on a joint return), the credit on Schedule 3 line 1 is the smaller of the foreign taxes or the tax on Form 1040 line 16. No limitation and no carryover. API foreignTaxPaid; ftcMethod auto takes whichever of this and Form 1116 gives the lower total tax, the alternative minimum tax included (under the election the AMT foreign tax credit is this credit; with Form 1116 it is the AMT Form 1116's); a tie: the election.

Form lines (2025 forms): Schedule 3 line 1 (Foreign tax credit, 1040s3.1); Form 1040 line 20 (Amount from Schedule 3, line 8, 1040.20)

Code: backend/src/federal_tax.c ext_ftc_amt. Tests: test_federal_2_w3.c test_w3_ftc_election; test_federal_2_w3.c test_w3_ftc_auto; test_federal_2_w3.c test_rc_ftc_auto_amt.

Foreign tax credit with Form 1116 (the section 904(a) limit, passive category)

The credit is the smaller of the foreign taxes (plus a carryover in) and the tax times foreign-source taxable income over worldwide taxable income. Foreign-source taxable income is the foreign gross income less the standard deduction or listed itemized deductions and the adjustments to income, apportioned by gross income; worldwide taxable income adds back the senior deduction (no deduction under section 151). Qualified dividends and capital gains are adjusted for the rate differential when the worksheet taxed them below the regular rate, unless the adjustment exception applies and is elected (it is an election: the engine takes the way with the lower total tax, the AMT included). The unused tax carries over (reported, not read back). API foreignTaxPaid, foreignSourceOrdinaryIncome, foreignSourceQualifiedIncome, foreignTaxCarryover.

How we read it (our interpretation, not settled guidance): Three readings. (1) The foreign qualified dividends are split among the 0%, 15% and 20% rates (and 25%/28%, which take Pub 514's 0.6757 / 0.7568 on line 1a) in the same shares as the worldwide qualified dividends and capital gains (the instructions do not say how; Pub 514 allows any reasonable method); the AMT Form 1116 splits them the same way over Form 6251 Part III's bands. (2) The adjustment exception's dollar test is the top of the 24% bracket of the year (the 2025 instructions print that year's 24% bracket tops; no 2026 figure has been published) and the exception, an election ("you can elect not to adjust"), is figured both ways: the engine keeps the way with the lower total tax, regular plus AMT (a tie: the exception elected), and the AMT Form 1116 follows the same election (i6251: "you must make the same adjustment exception election"). (3) Line 3a is the standard deduction, or medical expenses plus the share of the capped state and local taxes that is sales, real estate and personal property tax; line 3b is Schedule 1 Part II (the tips, overtime and QBI deductions are not apportioned to foreign income).

Read from: www.irs.gov/pub/irs-pdf/i1116.pdf (You qualify for the adjustment exception if you meet both); www.irs.gov/pub/irs-pdf/i1116.pdf (Include the following itemized deductions); www.irs.gov/pub/irs-pdf/i1116.pdf (you can elect not to adjust your foreign source capital gain distributions and qualified dividends); www.irs.gov/pub/irs-pdf/i6251.pdf (you must make the same adjustment exception election).

Form lines (2025 forms): Form 1116 line 21 (Maximum amount of credit (line 20 x line 19), 1116.21); Schedule 3 line 1 (Foreign tax credit, 1040s3.1); Form 1040 line 20 (Amount from Schedule 3, line 8, 1040.20)

Code: backend/src/federal_tax.c federal_form1116, ext_ftc_amt. Tests: test_federal_2_w3.c test_w3_form1116; test_federal_2_w3.c test_w3_form1116_adjusted; test_federal_2_w3.c test_w3_properties; test_federal_2_w3.c test_rc_adjustment_exception_election.

Alternative minimum tax (Form 6251)

AMTI is taxable income before the senior deduction (line 1b), plus the taxes of Schedule A or the standard deduction (2a), less a taxable refund (2b), plus private-activity-bond interest (2g), the incentive-stock-option bargain element (2i), the disposition and other adjustments (2k, 2d-2t, 3) the caller enters, less the section 68 reduction (section 68 does not apply for the AMT). The tips, overtime and QBI deductions are not added back. The exemption falls by 50% of AMTI over the phase-out threshold; a separate filer adds back up to the exemption above the zero point. The taxable excess is taxed at 26% and 28%, or through Part III with the 0/15/20% and 25% rates of the regular worksheets. The AMT is the tentative minimum tax (after the AMT foreign tax credit) over the regular tax less the foreign tax credit. Every API return gets Form 6251; the planner does not. The prior-year minimum tax credit (Form 8801) is not modelled.

How we read it (our interpretation, not settled guidance): Two readings of the 2026 draft Form 6251. (1) Section 56(b)(1)(E) ("Section 68 shall not apply"): the draft has no line for it, so the section 68 reduction comes back as a negative adjustment with line 3 (the pre-2018 form had it on its own line). (2) The capital gains of Part III are the regular worksheets' amounts, not refigured for the AMT: a disposition adjustment (line 2k) is taken as ordinary.

Read from: www.law.cornell.edu/uscode/text/26/56 (Section 68 shall not apply); www.irs.gov/pub/irs-dft/f6251--dft.pdf (subtract $4,890 ($2,445 if married filing separately)).

Form lines (2025 forms): Form 6251 line 4 (Alternative minimum taxable income, 6251.4); Form 6251 line 5 (Exemption, 6251.5); Form 6251 line 7 (Tax at 26%/28% or from Part III, 6251.7); Form 6251 line 9 (Tentative minimum tax, 6251.9); Form 6251 line 10 (Regular tax less the foreign tax credit, 6251.10); Schedule 2 line 2 (Alternative minimum tax, 1040s2.2); Form 1040 line 17 (Amount from Schedule 2, line 3, 1040.17)

Code: backend/src/federal_tax.c ext_ftc_amt, federal_amt_rate_tax, federal_amt_part3. Tests: test_federal_2_w3.c test_w3_amt_pab; test_federal_2_w3.c test_w3_amt_iso; test_federal_2_w3.c test_w3_amt_part3; test_federal_2_w3.c test_w3_amt_mfs; test_federal_2_w3.c test_w3_amt_phaseout; test_federal_2_w3.c test_w3_properties; test_federal_2_w3.c test_w3_guards.

The AMT foreign tax credit (Form 6251 line 8)

Under the section 904(j) election it is the regular credit. Otherwise a Form 1116 with AMT amounts: the foreign-source income less the deductions allowed for the AMT (no standard deduction, no taxes), apportioned by the AMT gross income (line 3e without a taxable refund, with private activity bond interest and the ISO bargain element), over Form 6251 line 4 (i6251: "Enter the amount from line 4 of Form 6251 on line 18 of the AMT Form 1116"), times line 7. When Part III taxed part of line 12 below the AMT rate (line 38 < line 39, line 17 > 0) outside the adjustment exception, the AMT Worksheet for Line 18 takes lines 23, 30 x 0.4643, 33 x 0.2857 and 36 x 0.1071 off line 4 and the foreign qualified dividends go on line 1a at 0.5357 (15%), 0.7143 (20%), 0.8929 (25%). The simplified limitation election (API amtFtcSimplifiedElection) keeps the regular foreign-source taxable income. Line 8 is left blank when line 10 is at least line 7.

How we read it (our interpretation, not settled guidance): One reading. Step 2 refigures Part I "using only income and deductions that are allowed for the AMT": the engine refigures line 3e (gross income from all sources) as the regular line 3e less a taxable state refund (not AMT income: Form 6251 line 2b) plus private activity bond interest (line 2g) and the incentive stock option bargain element (line 2i), the two income items the AMT adds; the disposition and other adjustments (lines 2k and 3) are net amounts, not gross income, and are left out. Line 3f is rounded to four places as on the regular form.

Read from: www.irs.gov/pub/irs-pdf/i6251.pdf (using only income and deductions that are allowed for the AMT).

Form lines (2025 forms): Form 6251 line 8 (Alternative minimum tax foreign tax credit, 6251.8)

Code: backend/src/federal_tax.c ext_ftc_amt. Tests: test_federal_2_w3.c test_w3_amt_ftc; test_federal_2_w3.c test_rc_amt_1116_line3f.

Credits: the credit for the elderly or disabled, the saver's credit, the child tax credit and the earned income credit

Form 1040 lines 18 to 22: the order of the nonrefundable credits

Line 18 is line 16 plus the AMT (line 17). The foreign tax credit comes first; then the credit for the elderly or disabled (Schedule R), the saver's credit (Form 8880) and the child tax credit with the credit for other dependents (Schedule 8812), each limited to line 18 less the credits before it (the forms' credit limit worksheets). Line 22 is line 18 less line 21, never below zero; line 24 adds Schedule 2 Part II. The refundable earned income credit (line 27a) and additional child tax credit (line 28) are payments: they do not change line 24 and are reported as refundableCredits. POST /api/federal-tax figures the credits on every return that has a credit input or earned income; the planner figures them in a year with wages or self-employment income (federal engine 2.2), the ACA bridge and the state API figure none.

Form lines (2025 forms): Form 1040 line 18 (Add lines 16 and 17, 1040.18); Form 1040 line 21 (Add lines 19 and 20, 1040.21); Form 1040 line 22 (Subtract line 21 from line 18. If zero or less, enter -0-, 1040.22)

Code: backend/src/federal_tax.c ext_credits. Tests: test_federal_2_w21.c test_w21_credits_order; test_federal_2_w21.c test_w21_properties; test_w5_planner.c test_planner_credits.

Credit for the elderly or the disabled (Schedule R)

A filer 65 or older at the end of the year (a person is that age on the day before the birthday), or under 65 with taxable disability income: line 10 is $5,000 ($7,500 when both spouses qualify on a joint return, $3,750 for a married filer filing separately who lived apart all year), limited for a disabled person under 65 to the taxable disability income (plus $5,000 for a spouse 65 or older). Lines 13a-13c subtract the nontaxable social security and the nontaxable pensions entered; line 17 subtracts half of AGI over $7,500 ($10,000 joint, $5,000 separate). The credit is 15% of the rest, at most line 18 less the foreign tax credit.

Form lines (2025 forms): Schedule R line 20 (Multiply line 19 by 15% (0.15), 1040sr.20); Schedule 3 line 6d (Credit for the elderly or disabled. Attach Schedule R, 1040s3.6d)

Code: backend/src/federal_tax.c ext_credits. Tests: test_federal_2_w21.c test_w21_credits_elderly; test_federal_2_w21.c test_w21_properties.

Saver's credit (Form 8880)

Each person 18 or older who is not a full-time student: the contributions entered less the distributions of the testing period (both entered by the caller), at most $2,000 each. The rate is 50%, 20% or 10% by AGI (Notice 2025-67: joint $48,500 / $52,500 / $80,500; head of household $36,375 / $39,375 / $60,375; others $24,250 / $26,250 / $40,250), 0 above. At most line 18 less the foreign tax credit and the credit for the elderly. The SECURE 2.0 Act replaces the credit with the Saver's Match from 2027: a projected year has none.

Form lines (2025 forms): Form 8880 line 10 (Multiply line 7 by line 9, 8880.10); Schedule 3 line 4 (Retirement savings contributions credit. Attach Form 8880, 1040s3.4)

Code: backend/src/federal_tax.c ext_credits. Tests: test_federal_2_w21.c test_w21_credits_savers; test_federal_2_w21.c test_w21_properties.

Child tax credit, credit for other dependents and additional child tax credit (Schedule 8812)

$2,200 per qualifying child under 17 and $500 per other dependent (Rev. Proc. 2025-32; section 24(h)(4)), less $50 for each $1,000 or fraction of AGI over $400,000 joint / $200,000 otherwise; the nonrefundable part is at most line 18 less the foreign tax credit, the credit for the elderly and the saver's credit (Credit Limit Worksheet A). The additional child tax credit is the rest, at most $1,700 per child and 15% of earned income over $2,500; with three or more children, Part II-B uses the larger of that and the social security and Medicare taxes (W-2 boxes 4 and 6 as entered; without them the employee taxes on boxes 3 and 5) plus the deductible part of self-employment tax, less the earned income credit and Schedule 3 line 11.

Form lines (2025 forms): Schedule 8812 line 12 (Subtract line 11 from line 8, 1040s8.12); Form 1040 line 19 (Child tax credit or credit for other dependents from Schedule 8812, 1040.19); Form 1040 line 28 (Additional child tax credit from Schedule 8812, 1040.28)

Code: backend/src/federal_tax.c ext_credits, federal_ctc_lines. Tests: test_federal_2_w21.c test_w21_credits_ctc; test_federal_2_w21.c test_w21_credits_actc_2b; test_federal_2_w21.c test_w21_properties.

Earned income credit (Form 1040 line 27a)

Earned income is wages plus net profit less the deductible part of self-employment tax. With no qualifying child a filer (or, on a joint return, either spouse) must be 25 to 64 at the end of the year; a married filer filing separately qualifies only under the separated-spouse rule (eitcSeparatedSpouse). Investment income (taxable and tax-exempt interest, ordinary dividends, capital gain net income, the positive rental net income) over $12,200 disqualifies. The credit is the credit percentage of earned income up to the maximum, less the phaseout percentage of the greater of AGI or earned income over the threshold (section 32(a)-(b), Rev. Proc. 2025-32). With taxTable (the API default) it is the EIC Table's: $50 brackets, the credit at each bracket's midpoint rounded to the dollar, looked up at earned income and, when AGI differs and is at least the threshold, at AGI, the smaller (EIC Worksheet A).

Form lines (2025 forms): Form 1040 line 27a (Earned income credit (EIC), 1040.27a)

Code: backend/src/federal_tax.c ext_credits, federal_eitc. Tests: test_federal_2_w21.c test_w21_credits_eitc; test_federal_2_w21.c test_w21_credits_eic_table; test_federal_2_w21.c test_w21_properties.

The premium tax credit (Form 8962) and the net credit (Schedule 3 line 9)

With marketplace coverage (marketplacePremiums and marketplaceSlcspPremiums, Form 1095-A columns A and B by month) the return figures Form 8962. Household income (line 3) is the modified AGI (AGI plus tax-exempt interest and the social security not included in income) plus dependentsModifiedAgi, not below zero. Line 5 is household income as a percentage of the 2025 HHS poverty line for the tax family (taxFamilySize, default the filer, the spouse on a joint return and the dependents given; povertyGuidelineState picks the Alaska or Hawaii table), its decimals dropped, 401 above 400%. A taxpayer from 100% to 400% is an applicable taxpayer (below 100% only with ptcEstimatedIncomeException and advance payments, 26 CFR 1.36B-2(b)(6); a married filer filing separately only with ptcMfsException). Line 7 is the applicable figure of that whole percentage from Rev. Proc. 2025-25's 2026 table (2.10% below 133%, 3.14%-4.19%, 4.19%-6.60%, 6.60%-8.44%, 8.44%-9.96%, 9.96% from 300%), linear within a tier and rounded to the nearest 0.01%. Line 8a = line 3 x line 7 and line 8b = line 8a / 12, each rounded to the dollar. With the same enrollment and SLCSP premium in all 12 months the annual line 11 applies; otherwise lines 12-23 month by month with line 8b. Each month's (or the year's) credit is the smaller of the premium and the SLCSP premium less the contribution, not below zero. Line 24 less the advance payments (line 25), when positive, is the net premium tax credit: a payment on Schedule 3 line 9, outside totalTax. The ACA bridge optimizer's subsidy is this same calculation.

Form lines (2025 forms): Form 8962 line 3 (Household income, 8962.3); Form 8962 line 4 (Federal poverty line, 8962.4); Form 8962 line 5 (Household income as a percentage of federal poverty line, 8962.5); Form 8962 line 7 (Applicable figure, 8962.7); Form 8962 line 8a (Annual contribution amount, 8962.8a); Form 8962 line 24 (Total PTC, 8962.24); Form 8962 line 25 (Advance payment of PTC, 8962.25); Form 8962 line 26 (Net PTC, 8962.26); Schedule 3 line 9 (Net premium tax credit. Attach Form 8962, 1040s3.9)

Code: backend/src/federal_tax.c federal_form8962, federal_ptc_poverty_percent, federal_ptc_applicable_figure, federal_ptc_poverty_line, ext_ptc. Tests: test_federal_2_w23.c test_w23_ptc_annual; test_federal_2_w23.c test_w23_ptc_monthly; test_federal_2_w23.c test_w23_ptc_eligibility; test_federal_2_w23.c test_w23_ptc_figure_table; test_aca_bridge_optimizer.c test_b1_bridge_is_form8962; test_federal_2_w23.c test_w23_ptc_properties.

Other taxes: §72(t) and the NIIT

The 10% additional tax on early distributions

10% of iraDistributions taken before age 59½. Without birthMonth the engine applies a whole-year rule: all of the year's distributions are charged when the filer reaches 59 or less in the year, and none from the year the filer reaches 60. That is an approximation: a filer born in January to June passes 59½ during the year they turn 59, and one born in July to December is still under 59½ early in the year they turn 60. With birthMonth, only the share of the year before 59½ is charged (the distributions taken as spread evenly over the year). Roth conversions are never charged. On the extended return the exceptions for disability, substantially equal periodic payments and separation from service at 55 (50 for a public safety employee) apply (Form 5329 line 2); the other §72(t)(2) exceptions are not modelled, and the planner applies none. Schedule 2 line 8.

Form lines (2025 forms): Schedule 2 line 8 (Additional tax on IRAs or other tax-favored accounts, 1040s2.8; 2026 draft: 5 (§72(t), §72(q), Form 5329 Part XI); 18 (the §4974 and §4973 excises))

Code: backend/src/tax_calculator.c compute_early_withdrawal_penalty, early_withdrawal_penalty_rate. Tests: test_tax_calculator.c test_early_withdrawal_59; test_tax_calculator.c test_early_withdrawal_60; test_federal_tax.c test_niit_short_term_and_penalty.

Net investment income tax

3.8% of the smaller of net investment income and MAGI over the threshold ($200,000 single and head of household, $250,000 joint, $125,000 separate; not indexed). Schedule 2 line 12. Net investment income is the whole of Form 8960 line 8 on every return (engine 1.3.0): interest, all dividends and the line 7a gain or allowed loss, never below zero; nonqualified annuities count too (line 3), and on an itemized return the investment interest and the state income tax allocable to it are subtracted (Form 8960 Part II, engine 1.5.0; the steps after line 8). The tax is 3.8% of the smaller of line 12 and the MAGI excess. Before 1.3.0 a return without interest, dividends or the capital-loss rules left out the long-term gain sheltered by an unused deduction, which under-charged the tax only when the deductions exceeded the NIIT threshold (a large itemized deduction in a large-gain year).

Form lines (2025 forms): Schedule 2 line 12 (Net investment income tax, 1040s2.12; 2026 draft: 6)

Code: backend/src/tax_calculator.c compute_niit. Tests: test_tax_calculator.c test_cg_niit; test_tax_calculator.c test_niit_threshold_2026; test_federal_tax.c test_niit_short_term_and_penalty; test_federal_r1r2.c test_r1_niit_on_yield; test_federal_tax.c test_r13_niit_whole_nii; test_federal_formmap.c test_fm3_effects.

Other taxes

Line 23 carries Schedule 2's total as the engine computes it: the §72(t) additional tax (with the Roth recapture of the extended return), the §4974 missed-RMD excise when an extended return sends rmdShortfall (Schedule 2 line 8 with the additional tax), and the NIIT (line 12). No other Schedule 2 tax is modelled: self-employment and household employment taxes, the Additional Medicare Tax, the HSA and other account additional taxes, credit recaptures, and the deferred-compensation and installment-sale interest taxes are absent (see what the engine does not compute).

Form lines (2025 forms): Form 1040 line 23 (Other taxes, from Schedule 2, line 21, 1040.23)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_niit_short_term_and_penalty.

Total tax

Line 24 adds line 16 and line 23. No credit is modelled (line 19 and Schedule 3 Part I: the child tax credit, the credit for the elderly, the foreign tax credit and every other) and neither is the alternative minimum tax, so line 22 equals line 16. result.totalTax is this line (with the §4974 excise on an extended return); result.incomeTax leaves out the §72(t) additional tax and the excise. The engine stops here: withholding and payments, refundable credits, the refund and the amount owed (lines 25 to 37) are not computed; the Form 2210 penalty (line 38) is, on request.

Form lines (2025 forms): Form 1040 line 24 (Total tax, 1040.24; 2026 draft: 24a)

Code: backend/src/federal_tax.c federal_tax_compute. Tests: test_federal_tax.c test_identities; test_federal_api.c test_response_shape; test_federal_2_w3.c test_rc_total_no_residue.

Total investment income (Form 8960 line 8)

Form 8960 line 8, on every return (engine 1.3.0): interest + all dividends + nonqualified annuities (line 3, engine 1.5.0) + the line 7a gain or allowed loss, never below zero. The NIIT is charged on line 12: line 8 less the Part II deductions (the steps below).

Form lines (2025 forms): Form 8960 line 8 (Total investment income, 8960.8)

Code: backend/src/federal_tax.c federal_tax_compute, federal_tax_compute_ext. Tests: test_federal_r1r2.c test_r1_r2_niit_net_of_the_loss; test_federal_tax.c test_r13_niit_whole_nii.

Net investment income: nonqualified annuities (Form 8960 line 3)

nonqualifiedAnnuity (engine 1.5.0) is the taxable part of payments under a nonqualified (commercial) annuity contract: ordinary income on Form 1040 line 5b, next to the pension, and net investment income on Form 8960 line 3 (§1411(c)(1)(A)(i)). An annuity from a §401(a), 403(a), 403(b), 408, 408A or 457(b) plan (the pension input) is not net investment income (§1411(c)(5)). The §72(q) additional tax on annuity payments before 59½ is not modelled, so the API refuses nonqualifiedAnnuity unless the filer is 59½ or older for the whole year or disabled.

Form lines (2025 forms): Form 8960 line 3 (Annuities, 8960.3)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_formmap.c test_fm3_effects.

Net investment income: rents (Form 8960 line 4a)

The rental income or allowed loss of Schedule E line 26 is net investment income (section 1411(c)(1)(A)(i), "rents"; Form 8960 line 4a): a loss reduces line 8. A real estate professional's rental income stays in it (the section 1.1411-4(g)(7) safe harbor is not modelled). With a K-1 amount (federal engine 2.3) line 4a is all of Schedule E line 41 and line 4b takes out the nonpassive K-1 amount (step irc_1411c1_k1).

Form lines (2025 forms): Form 8960 line 4a (Rental real estate, royalties, partnerships, S corporations, trusts, etc., 8960.4a)

Code: backend/src/federal_tax.c compose. Tests: test_federal_2_w21.c test_w21_rental_niit.

Form 8960 line 9a: investment interest

Engine 1.5.0: on a return that itemizes, the investment interest deducted on Schedule A (investmentInterest) reduces net investment income (§1411(c)(1)(B); Treas. Reg. §1.1411-4(f)(3)(i)). From 2026, when §68 reduces the itemized deductions, the deductions allowed against net investment income (lines 9a and 9b together) are the lesser of their own total and the itemized deductions allowed after §68 (Treas. Reg. §1.1411-4(f)(7)(ii)); when that cap binds, both lines are scaled down together. A return on the standard deduction deducts nothing here.

Form lines (2025 forms): Form 8960 line 9a (Investment interest expenses, 8960.9a)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_formmap.c test_fm3_effects.

Form 8960 line 9b: state income tax allocable to net investment income

Engine 1.5.0: on a return that itemizes, the state and local income tax actually deducted (the income-tax share of Schedule A line 5e after the SALT cap: saltIncomeOrSalesTax as a share of lines 5a to 5c) times Form 8960 line 8 over AGI, at most all of it; that ratio is the method the Form 8960 instructions name as reasonable (Reg. §1.1411-4(g)(1) allows any reasonable method). The §68 share applies as on line 9a. A general sales tax (saltSalesTaxElected) is not deductible in computing NII, and nothing is deducted on the standard deduction. Foreign income tax (Schedule A line 6) and property taxes attributable to NII are not allocated.

Form lines (2025 forms): Form 8960 line 9b (State, local, and foreign income tax, 8960.9b)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_formmap.c test_fm3_effects.

Form 8960 line 12: net investment income

Line 8 less the Part II deductions (lines 9a and 9b, line 11), never below zero: the base the 3.8% applies to (§1411(c)(1)(B)). Engine 1.5.0; before it no deduction reduced the base.

Form lines (2025 forms): Form 8960 line 12 (Net investment income, 8960.12)

Code: backend/src/federal_tax.c federal_tax_compute_ext. Tests: test_federal_formmap.c test_fm3_effects.

Excess advance premium tax credit repayment (Form 8962 line 29, Schedule 2 line 1a)

When the advance payments (marketplaceAdvancePayments, Form 1095-A column C) exceed the credit, the excess is added to the tax in full: from 2026 there is no repayment limitation (section 36B(f)(2)(B) struck by P.L. 119-21 section 71305). Line 29 is Schedule 2 line 1a and so part of line 1z: it is in Form 1040 line 17 and line 18 (the nonrefundable credits can offset it), in Form 6251 line 10 (it lowers the AMT) and in Form 1116 line 20 (the foreign tax credit limit). A taxpayer who is not an applicable taxpayer repays every advance payment. Form 2210 counts the repayment in the year's tax and subtracts the net credit as a refundable credit.

Form lines (2025 forms): Form 8962 line 29 (Excess advance PTC repayment, 8962.29); Schedule 2 line 1a (Excess advance premium tax credit repayment. Attach Form 8962, 1040s2.1a)

Code: backend/src/federal_tax.c federal_form8962, compose, ext_credits. Tests: test_federal_2_w23.c test_w23_ptc_excess; test_federal_2_w23.c test_w23_ptc_on_return; test_federal_2_w23.c test_w23_ptc_properties.

Net investment income: the K-1 trade or business amounts (Form 8960 line 4b)

Form 8960 line 4a takes all of Schedule 1 line 5 (Schedule E line 41); line 4b takes out the nonpassive trade or business income or loss of the K-1s (section 1411(c)(1)(A)(ii), (c)(2)(A)), unless the business is trading in financial instruments or commodities (k1NonpassiveTrading, section 1411(c)(2)(B)). Passive K-1 income (after Form 8582) and an estate's or trust's Part III amount stay net investment income; the Form 1041 K-1 box 14 code H adjustment (line 7) is not an input. An item taken into account in self-employment income is not net investment income (section 1411(c)(6)): a partner's box 14 code A amount is taken as the nonpassive income's first, and what is left of it, up to the passive K-1 result, comes out of the passive part on line 4b too.

Form lines (2025 forms): Form 8960 line 4b (Adjustment for net income or loss derived in the ordinary course of a non-section 1411 trade or business, 8960.4b)

Code: backend/src/federal_tax.c compose, ext_passive. Tests: test_federal_2_w23.c test_w23_k1_nonpassive.

Form 5329 Part III: excess traditional IRA contributions

Lines 9-17 per person (each spouse's own Form 5329 on a joint return): the limit (line 10) is the smaller of $7,500 ($8,600 at 50 or older by the year end) and the compensation (wages and the net self-employment earnings less the deductible half of SE tax and the plan deduction, a loss not subtracted); on a joint return the spouse with less compensation adds the other's compensation less the other's traditional (up to the other's limit) and Roth contributions (§219(c)). Line 10 = the limit less the traditional and Roth contributions; 13 = 10 + 11 + 12; 14 = 9 - 13 (not below 0); 15 = the contributions (less a corrective withdrawal made in time) over the limit; 16 = 14 + 15; 17 = 6% of the smaller of 16 and the December 31 value (traditionalIraValue; absent: the excess). Schedule 2 line 8 (2026 draft line 18); not in Form 2210's tax (i2210 line 2: line 8's "additional tax on distributions only"). The absorbed prior excess is a deemed contribution the IRA Deduction Worksheet would deduct: not modelled (the engine has no IRA deduction). 2026 amounts only (a projected year is refused).

Form lines (2025 forms): Form 5329 line 16 (Total excess contributions (traditional IRAs; both spouses' forms on a joint return), 5329.16); Form 5329 line 17 (Additional tax on excess traditional IRA contributions, 5329.17)

Code: backend/src/federal_tax.c ext_excess, excess_part. Tests: test_federal_2_w23.c test_w23_excess_ira; test_federal_2_w23.c test_w23_excess_properties; test_federal_2_w23.c test_w23_excess_guards; fm23.inc test_fm23_effects.

Form 5329 Part IV: excess Roth IRA contributions

Lines 18-25 per person: the Roth limit is Pub 590-A Worksheet 2-2's: line 6 the traditional limit, reduced when the MAGI is over $153,000 ($242,000 joint or QSS; 0 on a separate return living with the spouse) by its share of the $15,000 range ($10,000 joint, QSS or separate living together): line 8 rounded up to $10, not below $200, 0 at the end of the range; line 11 = the smaller of line 8 and line 6 less the traditional contributions. The MAGI is Worksheet 2-1's: AGI less the conversion income, refigured without it (the taxable social security, Form 8582's special allowance) when over the end of the range, as the worksheet's Note allows. Line 19 = the limit less the Roth contributions; 20 the Roth distributions (rothIraDistributions; the filer's default rothDistribution); 22 = 18 - 21; 23 the contributions over the limit; 25 = 6% of the smaller of 24 and the value.

Form lines (2025 forms): Form 5329 line 24 (Total excess contributions (Roth IRAs), 5329.24); Form 5329 line 25 (Additional tax on excess Roth IRA contributions, 5329.25)

Code: backend/src/federal_tax.c ext_excess, federal_roth_reduced_limit, ext_roth_magi. Tests: test_federal_2_w23.c test_w23_excess_ira; test_federal_2_w23.c test_w23_excess_properties; fm23.inc test_fm23_effects.

Form 5329 Part V: excess Coverdell ESA contributions

Lines 26-33 for the filer as the beneficiary: line 27 the limit (coverdellLimit, default $2,000) less the contributions, 28 the distributions, 30 = 26 - 29, 31 the excess, 33 = 6% of the smaller of 32 and the value. A corrective withdrawal before June 1, 2027 is not a contribution.

Form lines (2025 forms): Form 5329 line 32 (Total excess contributions (Coverdell ESAs), 5329.32); Form 5329 line 33 (Additional tax on excess Coverdell ESA contributions, 5329.33)

Code: backend/src/federal_tax.c ext_excess, excess_part. Tests: test_federal_2_w23.c test_w23_excess_accounts; fm23.inc test_fm23_effects.

Form 5329 Part VI: excess Archer MSA contributions

Lines 34-41 for the filer: the limit is the caller's (archerMsaLimit, Form 8853 lines 3-4); line 35 the unused limit, 36 Form 8853 line 8, 39 the excess (the employer's included), 41 = 6% of the smaller of 40 and the value. The contributions also reduce the HSA limit (§223(b)(4)).

Form lines (2025 forms): Form 5329 line 40 (Total excess contributions (Archer MSAs), 5329.40); Form 5329 line 41 (Additional tax on excess Archer MSA contributions, 5329.41)

Code: backend/src/federal_tax.c ext_excess, excess_part. Tests: test_federal_2_w23.c test_w23_excess_accounts; fm23.inc test_fm23_effects.

Form 5329 Part VII: excess HSA contributions

Lines 42-49 per person: the limit is Form 8889 line 8 when given (hsaLimit), else the statutory one of the coverage held all year ($4,400 self-only, $8,750 family, + $1,000 at 55 or older), less the Archer MSA contributions; spouses on a joint return, both covered and either with family coverage, share the family limit equally (Pub 969), each adding their own $1,000. Line 43 the unused limit, 44 Form 8889 line 16, 46 = 42 - 45, 47 the contributions (the employer's included, less a corrective withdrawal) over the limit, 49 = 6% of the smaller of 48 and the value. The absorbed prior excess (a Form 8889 line 13 deduction) is not modelled.

Form lines (2025 forms): Form 5329 line 48 (Total excess contributions (HSAs), 5329.48); Form 5329 line 49 (Additional tax on excess HSA contributions, 5329.49)

Code: backend/src/federal_tax.c ext_excess, excess_part, federal_hsa_statutory_limit. Tests: test_federal_2_w23.c test_w23_excess_accounts; test_federal_2_w23.c test_w23_excess_properties; fm23.inc test_fm23_effects.

Form 5329 Part VIII: excess ABLE contributions

Line 50: the contributions to the filer's ABLE account (less a return in time) over ableLimit (default $20,000 for 2026; plus an employed beneficiary's ABLE-to-work amount, the caller's); line 51 = 6% of the smaller of line 50 and the value. No carryover lines.

Form lines (2025 forms): Form 5329 line 50 (Excess contributions to the ABLE account, 5329.50); Form 5329 line 51 (Additional tax on excess ABLE contributions, 5329.51)

Code: backend/src/federal_tax.c ext_excess. Tests: test_federal_2_w23.c test_w23_excess_accounts; fm23.inc test_fm23_effects.

Form 5329 Part X: excess Trump account contributions

For the account beneficiary before the year they turn 18 (§530A(h)(5)): line 56 is 0 for 2026 (contributions began July 4, 2026), line 57 the caller's excess over $5,000, 59 the §530A(d)(5) distributions of it, 60 = 58 - 59, 61 = 6% of line 60. A filer 18 or older is refused (the account is then a traditional IRA).

Form lines (2025 forms): Form 5329 line 60 (2026 draft) (Trump account excess contributions after distributions, 5329.60; 2026 draft: 60); Form 5329 line 61 (2026 draft) (Additional tax on excess Trump account contributions, 5329.61; 2026 draft: 61)

Code: backend/src/federal_tax.c ext_excess. Tests: test_federal_2_w23.c test_w23_excess_accounts; test_federal_2_w23.c test_w23_excess_guards; fm23.inc test_fm23_effects.

Form 5329 Part XI: 100% of a distributed Trump account excess's earnings

Line 62 the earnings (Form 1099-R box 7d), line 63 = 100% of line 62 (§530A(d)(5)(C)): Schedule 2 line 8 (2026 draft line 5) and, as a tax on a distribution, in Form 2210's tax.

Form lines (2025 forms): Form 5329 line 63 (2026 draft) (Additional tax on the earnings of a distributed Trump account excess (100%), 5329.63; 2026 draft: 63)

Code: backend/src/federal_tax.c ext_excess. Tests: test_federal_2_w23.c test_w23_excess_accounts; fm23.inc test_fm23_effects.

Itemized deductions: Schedule A, §68 and the non-itemizer charitable deduction

Medical and dental expenses

Schedule A line 4: unreimbursed medical and dental expenses to the extent they exceed 7.5% of AGI (§213(a)).

Form lines (2025 forms): Schedule A line 4 (Medical and dental expenses over 7.5% of AGI, 1040sa.4)

Code: backend/src/federal_tax.c ext_deduction. Tests: test_federal_tax_forms.c test_itemize_mfj.

State and local taxes paid

Schedule A line 5d: state and local income (or general sales) tax, real estate tax and personal property tax paid in the year.

Form lines (2025 forms): Schedule A line 5d (State and local taxes: add lines 5a through 5c, 1040sa.5d)

Code: backend/src/federal_tax.c ext_deduction. Tests: test_federal_tax_forms.c test_itemize_mfj.

The SALT cap and its phase-down

Schedule A line 5e: line 5d up to the cap of §164(b)(6)-(7): $40,400 for 2026, reduced by 30% of MAGI over $505,000 but not below $10,000; a separate return gets half the threshold and half the amount. MAGI is AGI (the engine has no foreign or territory exclusions).

Form lines (2025 forms): Schedule A line 5e (State and local taxes after the cap, 1040sa.5e)

Code: backend/src/federal_tax.c federal_salt_cap, ext_deduction. Tests: test_federal_tax_forms.c test_salt_cap; test_federal_tax_forms.c test_section_68.

Interest you paid

Schedule A line 10: home mortgage interest and points and Form 4952 investment interest, as deductible amounts the caller supplies (the §163(h)(3) debt limit is applied by the caller).

Form lines (2025 forms): Schedule A line 10 (Interest you paid: add lines 8e and 9, 1040sa.10)

Code: backend/src/federal_tax.c ext_deduction. Tests: test_federal_tax_forms.c test_itemize_mfj; test_federal_tax_forms.c test_charity_limits.

Gifts to charity: the percentage limits and the 0.5% floor

Schedule A line 14, in the order of Pub 526 Worksheet 2 (engine 1.5.0): cash to public charities up to 60% of AGI; capital-gain property to public charities, taken into account after all other gifts, up to the smaller of 30% of AGI and 50% of AGI minus the cash gifts (§170(b)(1)(C), (G)(iii)); from 2026 only the amount above 0.5% of AGI is deductible, taken first from the property and last from the cash (§170(b)(1)(I)). Before 1.5.0 the property came first and the cash got only what the property left of 60%, which over-deducted when cash and property together exceeded half of AGI. Federal engine 2.2: carryovers (the cash and the capital-gain-property classes, by age) join their class: the year's own gifts first, then the carryovers oldest first, under the same limits; the 0.5% floor applies to the total, carryovers included (the statute's text, disclosed).

Form lines (2025 forms): Schedule A line 14 (Gifts to charity: add lines 11 through 13, 1040sa.14; 2026 draft: 13 (15 with a carryover))

Code: backend/src/federal_tax.c ext_deduction, ext_charity_carry. Tests: test_federal_tax_forms.c test_charity_limits; test_federal_tax_forms.c test_itemize_mfj; test_federal_formmap.c test_fm2_effects.

Gifts to charity: the five-year carryover

An amount over the percentage limits carries to each of the 5 succeeding years in its class (§170(d)(1), (b)(1)(C)(ii), (G)(ii)): in a later year the year's own gifts of the class come first, then the carryovers, oldest first; what the limits leave moves one year older, and a carryover not used by its fifth year expires. A carryover is used up in a year the standard deduction is taken (26 CFR 1.170A-10(a)(2)). From 2026 the 0.5% floor's disallowance is carried only by a class whose own gifts of the year are carried, added to them (§170(d)(1)(C)); otherwise it is lost. §68 does not create a carryover.

Form lines (2025 forms): Schedule A line 13 (Carryover from prior year (used this year), 1040sa.13)

Code: backend/src/federal_tax.c ext_charity_carry, ext_deduction. Tests: test_federal_2_w22.c test_a3_carryovers; test_federal_2_w22.c test_a3_properties.

The §68 limitation on itemized deductions

From 2026 (OBBBA §70111) itemized deductions are reduced by 2/37 of the smaller of the itemized total and the taxable income (before §68, plus the itemized total) above the start of the 37% bracket: in that bracket each itemized dollar saves 35 cents. It applies to all itemized deductions, after every other limit. Federal engine 2.0: taxable income before the reduction is after the Schedule 1-A deductions and the QBI deduction (the 2026 draft Schedule A line 18 test: line 11b minus lines 13a and 13b), the QBI deduction being the one of the return figured without the reduction.

How we read it (our interpretation, not settled guidance): Section 68 reduces itemized deductions by reference to taxable income "determined without regard to this section". Since federal engine 2.0 that taxable income can also carry the Schedule 1-A tips and overtime deductions and the QBI deduction, and the QBI deduction itself depends on the itemized deductions after section 68. We read the statute as: taxable income before section 68 is Form 1040 line 11b less lines 12e (itemized deductions before the reduction), 13a and 13b, as the 2026 draft Schedule A line 18 frames its test, with the QBI deduction of the return figured without the section 68 reduction; the reduction is then applied once and the QBI deduction refigured on the reduced itemized deductions. The final 2026 Itemized Deductions Worksheet had not been published when this was written; a different official ordering would move the tax of an itemizer in the 37% bracket who also has qualified business income by a few dollars.

Read from: www.law.cornell.edu/uscode/text/26/68 (determined without regard to this section); www.irs.gov/pub/irs-dft/f1040sa--dft.pdf (line 11b, minus the amounts on lines 13a and).

Form lines (2025 forms): Schedule A line (2026) (Section 68 reduction (2025: no line of its own; 2026 draft: the Itemized Deductions Worksheet behind Schedule A line 18), 1040sa.68; 2026 draft: 18 (Itemized Deductions Worksheet))

Code: backend/src/federal_tax.c ext_deduction. Tests: test_federal_tax_forms.c test_section_68; test_federal_2_w2.c test_w2_s68_qbi; test_federal_2_w3.c test_rc_s68_standard.

Total itemized deductions

Schedule A line 17: lines 4 through 16 after §68. This is the figure the state engine's itemized-conformity states read.

Form lines (2025 forms): Schedule A line 17 (Total itemized deductions (to Form 1040 line 12e), 1040sa.17; 2026 draft: 18)

Code: backend/src/federal_tax.c ext_deduction. Tests: test_federal_tax_forms.c test_itemize_mfj.

Itemize or take the standard deduction

§63(e): itemizing is an election, so the filer takes the choice with the lower tax. itemizeMode auto (engine 1.5.1) figures the return both ways when Schedule A has amounts and keeps the lower total tax; on a tie (a difference of at most half a cent; engine 1.5.2) it takes the larger deduction, as the 1040 instructions say ("your federal income tax will be less if you take the larger of your standard deduction or itemized deductions"), so taxable income, which the capital-loss carryover worksheet reads, follows the larger deduction; the trace states both totals (1040.12e.auto_itemized_tax, 1040.12e.auto_standard_tax). The larger deduction is not always the lower tax: Form 8960 Part II (investment interest, state income tax) exists only on an itemized return. itemize elects it anyway (Schedule A line 18); standard never itemizes. A separate filer whose spouse itemizes has a standard deduction of zero (§63(c)(6)(A)) and no choice. Federal engine 2.0: with the AMT on the return the comparison also runs when nothing is itemized (i6251: itemizing can lower the total tax even when the itemized deductions are less than the standard deduction), and so it does on a return with a Form 1116 credit, whose line 3a apportions the standard deduction but only the listed itemized deductions (a separate filer with foreign dividends can pay less itemizing nothing).

Form lines (2025 forms): Form 1040 line 12e (flag) (1 = line 12e carries itemized deductions, 0 = the standard deduction, 1040.12e.itemized); Form 1040 line 12e (auto: itemized) (itemizeMode auto: the total tax of the return with Schedule A (compared with the standard-deduction return; the lower is kept), 1040.12e.auto_itemized_tax); Form 1040 line 12e (auto: standard) (itemizeMode auto: the total tax of the return with the standard deduction (on a tie the larger deduction is kept), 1040.12e.auto_standard_tax)

Code: backend/src/federal_tax.c ext_deduction, ext_itemize_auto. Tests: test_federal_tax_forms.c test_itemize_mfj; test_federal_tax_forms.c test_mfs_spouse_itemizes; test_federal_api.c test_f3_itemize_auto; test_federal_2_w3.c test_w3_amt_ftc.

Charitable deduction for non-itemizers

From 2026 a filer who does not itemize deducts cash gifts to public charities (not donor-advised funds or supporting organizations) up to $2,000 on a joint return, less otherwise; no 0.5% floor (§170(p), §63(b)(4)).

Form lines (2025 forms): Form 1040 line (2026) (Charitable deduction for non-itemizers, §170(p) (new for 2026: no 2025 line; line 12f on the 2026 draft), 1040.170p; 2026 draft: 12f)

Code: backend/src/federal_tax.c ext_deduction. Tests: test_federal_tax_forms.c test_nonitemizer_charity.

Retirement accounts: Form 8606 basis, Roth distributions, Form 5329 and the RMD

Form 8606: the nontaxable part of a conversion

Form 8606 line 11: all traditional IRAs are one contract and the year's distributions one distribution (§408(d)(2)), so basis is recovered pro rata: line 10 = basis / (December 31 value + distributions + conversions), at most 1; line 11 = the conversion times line 10.

Form lines (2025 forms): Form 8606 line 11 (Nontaxable portion of the amount converted to Roth IRAs, 8606.11)

Code: backend/src/federal_tax.c ext_prepare. Tests: test_federal_tax_forms.c test_form_8606.

Form 8606: the nontaxable part of all distributions

Form 8606 line 13: line 11 plus the IRA distributions times line 10. Employer-plan dollars carry no basis here.

Form lines (2025 forms): Form 8606 line 13 (Nontaxable portion of all distributions, 8606.13)

Code: backend/src/federal_tax.c ext_prepare. Tests: test_federal_tax_forms.c test_form_8606.

Form 8606: basis carried forward

Form 8606 line 14: the basis left for later years.

Form lines (2025 forms): Form 8606 line 14 (Total basis in traditional IRAs carried forward, 8606.14)

Code: backend/src/federal_tax.c ext_prepare. Tests: test_federal_tax_forms.c test_form_8606.

Roth IRA distributions: ordering and the 5-year rules

A Roth distribution comes first from contributions, then from conversions oldest first (each conversion's taxable part first), then from earnings (§408A(d)(4)(B)). A qualified distribution (59½ or disabled, and 5 taxable years since the first Roth contribution) is tax-free. Otherwise the earnings are taxable (Form 8606 line 25c), and a conversion's taxable part taken within 5 years of that conversion is subject to the §72(t) additional tax (§408A(d)(3)(F)). On the age clock, with the 5-year clock met, only the share of the year before 59½ is nonqualified.

Form lines (2025 forms): Form 8606 line 25c (Roth IRA distributions: taxable amount, 8606.25c)

Code: backend/src/federal_tax.c ext_prepare. Tests: test_federal_tax_forms.c test_roth_ordering; test_federal_tax_forms.c test_age_clock_birth_month.

Form 5329: early distributions

Form 5329 line 1: the taxable traditional-account withdrawal before 59½ plus nonqualified Roth earnings and recaptured conversions, and (federal engine 2.3) a nonqualified annuity's taxable payments before 59½ (§72(q); trace row 5329.1.annuity).

Form lines (2025 forms): Form 5329 line 1 (Early distributions includible in income, 5329.1)

Code: backend/src/federal_tax.c ext_penalty. Tests: test_federal_tax_forms.c test_72t_exceptions.

Form 5329: the exceptions to the additional tax

Form 5329 line 2: a distribution to a beneficiary on or after the owner's death (§72(t)(2)(A)(ii), beneficiaryDistribution, engine 2.0.1; Form 5329 exception 04), from an IRA or an employer plan; disability (iii); substantially equal periodic payments (iv), their taxable part; employer-plan distributions after separation from service in or after the year the filer reaches 55, or 50 for a qualified public safety employee ((v), §72(t)(10)), never for an IRA (§72(t)(3)(A)); and, at any age, a distribution from a governmental §457(b) plan (governmental457bDistribution, engine 1.5.0): §72(t) reaches only the qualified plans of §4974(c), which do not include §457(b) plans (Form 5329 exception 13), except the part attributable to a rollover from a qualified plan (§72(t)(9)), which the caller leaves out of that field. The 10% applies to the rest at the age clock's rate.

Form lines (2025 forms): Form 5329 line 2 (Early distributions not subject to the additional tax, 5329.2)

Code: backend/src/federal_tax.c ext_penalty. Tests: test_federal_tax_forms.c test_72t_exceptions; test_federal_tax_forms.c test_age_clock_birth_month; test_federal_formmap.c test_fm3_effects; test_federal_api.c test_f2_sepp_overlap; test_federal_api.c test_beneficiary_distribution.

Form 5329: the missed-RMD excise tax

Form 5329 line 55: 25% of a required minimum distribution not taken, or 10% when it is corrected within the correction window (§4974(a), (e)). It is part of Schedule 2 line 8 and of the total tax, but not of the tax Form 2210 uses.

Form lines (2025 forms): Form 5329 line 55 (Additional tax on excess accumulation (missed RMD), 5329.55)

Code: backend/src/federal_tax.c federal_missed_rmd_excise, ext_penalty. Tests: test_federal_tax_forms.c test_missed_rmd.

The RMD divisor: Uniform Lifetime or Joint and Last Survivor

From the SECURE 2.0 applicable age for the birth year (the tax year minus the age reached), the divisor is the Uniform Lifetime Table's, or the Joint and Last Survivor Table's when the spouse is the sole beneficiary all year and more than 10 years younger (26 CFR 1.401(a)(9)-5(c)(2), -9(d)); ages are those reached in the year.

Form lines (2025 forms): 26 CFR 1.401(a)(9) line divisor (RMD divisor (Uniform Lifetime or Joint and Last Survivor Table), rmd.divisor)

Code: backend/src/federal_tax.c rmd_joint_life_divisor, ext_prepare. Tests: test_federal_tax_forms.c test_rmd; test_federal_tax_forms.c test_joint_life.

The required minimum distribution

The December 31 balance of the prior year divided by the divisor. The planner divides the balance at the start of the plan year, before the year's returns (engine 1.5.0; before it the grown balance). The planner can take the first RMD by its required beginning date (federal engine 2.2, API firstRmdTiming "aprilFollowingYear"; default: by December 31 of the first year): the first year's floor is 0 and what the owner withdraws that year counts toward the first RMD; the rest is due in the next year with that year's own RMD, figured on its own December 31 balance (two RMDs in one year); no Roth conversion in the deferral year. A single-year request takes the year's distributions as given. The still-working exception for an employer plan is not modelled.

Form lines (2025 forms): 26 CFR 1.401(a)(9) line RMD (Required minimum distribution for the year, rmd.required)

Code: backend/src/federal_tax.c ext_prepare. Tests: test_federal_tax_forms.c test_rmd; test_w5_planner.c test_first_rmd_april; test_w5_planner.c test_first_rmd_request.

An inherited account: the payout rule and the distribution period

The beneficiary of an inherited IRA or plan account: whether the decedent died before or on or after the required beginning date (April 1 of the year after the year the decedent reached the applicable age; a Roth IRA has none), then the rule by the beneficiary. A designated beneficiary who is not an eligible one: the 10-year rule, with annual distributions in years 1-9 only when the death was on or after the required beginning date. An eligible designated beneficiary (the surviving spouse, a minor child of the decedent, a disabled or chronically ill person, someone not more than 10 years younger): life expectancy, or the 10-year rule by election when the death was before the required beginning date; a minor child to 21, then 10 years. No designated beneficiary (an estate, a charity, a trust that is not a see-through trust): the 5-year rule, or the decedent's remaining life expectancy. A death before 2020: life expectancy for every designated beneficiary. The period is the Single Life Table at the beneficiary's age in the year after the death, reduced by one each year; the surviving spouse's is read again each year; after the required beginning date, the greater of that and the decedent's remaining life expectancy.

Form lines (2025 forms): 26 CFR 1.401(a)(9) line inherited divisor (Inherited account: the distribution period of the year (0 = none), rmd.inherited.divisor)

Code: backend/src/federal_tax.c federal_inherited_rmd, inh_divisor, inh_applicable_year, inh_reduced. Tests: test_federal_2_w22.c test_a1_ten_year_annual; test_federal_2_w22.c test_a1_spouse; test_federal_2_w22.c test_a1_minor; test_federal_2_w22.c test_a1_no_designated; test_federal_2_w22.c test_a1_eligible; test_federal_2_w22.c test_a1_rbd; test_federal_2_w22.c test_a1_properties.

An inherited account: the year's required distribution

The December 31 balance of the prior year divided by the year's distribution period; the whole account in the last year of a 10-year or 5-year rule, or when the period has run down to 1 or less. In the year of death, when the decedent died on or after the required beginning date, the decedent's own RMD less what the decedent took. The annual distributions of 2021 to 2024 under the 10-year rule after the required beginning date were waived by IRS notices (no excise). A traditional account's distribution is ordinary income on Form 1040 line 4b and is excepted from the 10% additional tax as a beneficiary's (unless the spouse treats the IRA as their own); the shortfall against the minimum is charged the 25% excise (10% corrected). An inherited Roth IRA's distributions are taken as qualified.

Form lines (2025 forms): 26 CFR 1.401(a)(9) line inherited RMD (Inherited account: the year's required distribution, rmd.inherited.required)

Code: backend/src/federal_tax.c federal_inherited_rmd, federal_inherited_schedule, ext_inherited, ext_penalty. Tests: test_federal_2_w22.c test_a1_ten_year; test_federal_2_w22.c test_a1_death_year; test_federal_2_w22.c test_a1_roth; test_federal_2_w22.c test_a1_engine; test_federal_2_w22.c test_a1_equivalence.

§72(q): the 10% on a nonqualified annuity before 59½

Form 5329 line 1 (with §72(t)'s early distributions; Pub 575): the taxable part of a nonqualified annuity's payments (nonqualifiedAnnuity) before 59½, at the age clock's share of the year as for an IRA withdrawal (§72(q)(2)(A)); disability (§72(q)(2)(C), disabled) excepts all of it. The 10% is on Schedule 2 line 8 (2026 draft line 5) with the §72(t) amount. Federal engine 2.3 (B3); before, the API refused the annuity before 59½. Not modelled: the §72(q)(3) recapture with interest when a series of payments is modified, the 5% rate under a pre-March 1, 1986 election, modified endowment contracts (§72(v)).

Form lines (2025 forms): Form 5329 line 1 (part) (Early distributions includible in income: the nonqualified annuity's (§72(q)), 5329.1.annuity)

Code: backend/src/federal_tax.c ext_penalty. Tests: test_federal_2_w23.c test_w23_72q; test_federal_2_w23.c test_w23_excess_properties; fm23.inc test_fm23_effects.

§72(q)(2): the annuity's exceptions

Form 5329 line 2: the caller's parts of nonqualifiedAnnuity paid after the holder's death ((B), nonqualifiedAnnuityDeath), as substantially equal periodic payments ((D), nonqualifiedAnnuitySepp), and under (F), (G), (I) or (J) (investment before August 14, 1982, a qualified funding asset, an immediate annuity, an annuity bought by an employer on a plan's termination; nonqualifiedAnnuityOtherException), together at most the annuity. (E) and (H) cannot arise: money from a qualified plan or an IRA goes in the pension and IRA inputs (§72(t)).

Form lines (2025 forms): Form 5329 line 2 (part) (Early distributions not subject to the additional tax: the annuity's exceptions, 5329.2.annuity)

Code: backend/src/federal_tax.c ext_penalty. Tests: test_federal_2_w23.c test_w23_72q; test_federal_2_w23.c test_w23_excess_properties; fm23.inc test_fm23_effects.

Estimated tax: the §6654 safe harbors and the Form 2210 penalty

Form 2210: the required annual payment

Form 2210 line 9: the smaller of 90% of this year's tax (the income tax including the NIIT, plus the additional tax on distributions; not the missed-RMD excise) and 100% of last year's tax, 110% when last year's AGI exceeded $150,000 ($75,000 on a separate return); the prior-year harbor only when last year was a full 12-month year with a return (§6654(d)). No penalty when the tax less withholding is under $1,000 (§6654(e)(1)) or last year's 12-month return showed no tax (§6654(e)(2)).

Form lines (2025 forms): Form 2210 line 9 (Required annual payment, 2210.9)

Code: backend/src/federal_tax.c federal_est_compute. Tests: test_federal_tax_forms.c test_est_harbours; test_federal_tax_forms.c test_2210_on_return.

Form 2210: the underpayment by installment

Form 2210 line 17: a quarter of the required annual payment is due on each of April 15, June 15 and September 15, 2026 and January 15, 2027; withholding counts as paid in four equal parts on those dates (§6654(g)(1); the Part II box D election to use the actual withholding dates is not modelled); payments go to the oldest unpaid installment and an overpayment carries forward.

Form lines (2025 forms): Form 2210 line 17 (Underpayment (total of the four installments), 2210.17)

Code: backend/src/federal_tax.c federal_est_compute. Tests: test_federal_tax_forms.c test_est_ledger; test_federal_tax_forms.c test_2210_on_return.

Form 2210: the penalty

Form 2210 line 19: simple interest on each installment's underpayment at the §6621 rate of each quarter, days x rate / 365, from the due date to the earlier of the payment date and April 15, 2027 (the regular installments, or Schedule AI's when the request splits its income by period and that lowers the penalty). The first quarter of 2027 carries the last announced rate forward and the response flags it.

Form lines (2025 forms): Form 2210 line 19 (Penalty, 2210.19)

Code: backend/src/federal_tax.c federal_est_compute, ext_annualized. Tests: test_federal_tax_forms.c test_est_nothing_paid; test_federal_tax_forms.c test_2210_on_return.

Form 2210 Schedule AI: the annualized income installment method

With an item's amounts by installment period (Jan-Mar, Apr-May, Jun-Aug, Sep-Dec), each period's return is figured on its income through the period's end times 4, 2.4, 1.5 and 1 (an item not split accrues evenly; the standard deduction is the year's, not annualized; itemized deductions, the AMT, the NIIT, the Additional Medicare Tax and the credits on the annualized amounts), the self-employment tax by Part II (the period's net earnings, 0 under $400, against the prorated social security limit, at 12.4% and 2.9% times the factor), times 22.5%, 45%, 67.5% and 90%; each required installment is the smaller of that less the earlier installments and the regular installment plus what earlier installments saved. The penalty is figured both ways and the lower one is charged (Schedule AI is used for every installment or none). Withholding by period is credited as withheld (box D).

Form lines (2025 forms): Form 2210 line AI 27 (Schedule AI: the required installments, added (the method charged is the lower penalty), 2210ai.27)

Code: backend/src/federal_tax.c federal_schedule_ai, ext_annualized, federal_est_compute. Tests: test_federal_2_w22.c test_a2_december_conversion; test_federal_2_w22.c test_a2_part2; test_federal_2_w22.c test_a2_withholding; test_federal_2_w22.c test_a2_properties.

Later tax years: the projection beyond 2026

One amount in a later year

Each federal dollar amount has one rule in research/data/federal-tax-indexing.json. Fixed in law (the NIIT and Social Security thresholds, the capital-loss limit): the 2026 amount in every year. Indexed (the brackets, the standard deduction and its age-65 and blind amounts, the capital-gain breakpoints, the QCD limits, the IRMAA floors): the statute's base-year amount times the index level of the year over the level of the base year, the increase (or the amount, where the statute says so) rounded the statute's way; the level of a later year is the 2026 level times the factor. The C-CPI-U level for 2026 is recovered from the Rev. Proc. 2025-32 amounts (every one of them is reproduced exactly), because the statute reads values that BLS has since revised. Scheduled: the amount the statute enacts for the year (the senior deduction ends after 2028). Derived: an amount the statute defines from another (a joint amount twice the individual one). Not established: held, and the API refuses a law-mode result that depends on it.

Code: backend/src/federal_tax.c federal_index_amount, fix_round. Tests: test_federal_2_projection.c test_e_hand_parameters; test_federal_2_projection.c test_c_properties; test_federal_2_projection.c test_a_registry_matches_engine.

The year's brackets and deductions

federal_tax_project_config moves the ordinary and capital-gain bracket edges and the standard deduction of the filing status by their rules; the rates and the NIIT threshold stay. federal_tax_config_for_year_mode adds the age-65 amount per 65+ filer and spouse at the year's amount and the senior deduction on its schedule, the one builder the planner's later years, the ACA bridge, POST /api/federal-tax and computeFederal + projection use. At factor 1 every later year is the 2026 configuration byte for byte. Indexing "inflation" is the pre-2.0 planner's scaling, exactly: each edge, the standard deduction and the age-65 amount times the factor, unrounded.

Code: backend/src/federal_tax.c federal_tax_project_config, federal_tax_config_for_year_mode, fix_project_law. Tests: test_federal_2_projection.c test_b_identities; test_federal_2_projection.c test_d_inflation_is_legacy; test_federal_2_projection.c test_e_hand_returns.

The IRMAA income floors in a later year

The planner's IRMAA floors: the individual amounts from the 12 months ending August 2018 by the CPI-U, each rounded to the nearest multiple of $1,000; the top tier held through 2027, then indexed from August 2026; joint returns twice the individual amounts and 150 percent of the top tier; a separate filer who lived with the spouse the individual amounts less the individual threshold. The Part B and D amounts move by the plan's medical inflation in both modes.

Code: backend/src/federal_tax.c federal_irmaa_project_config. Tests: test_federal_2_projection.c test_e_hand_parameters; test_federal_2_projection.c test_d_inflation_is_legacy.

The QCD limits in a later year

The section 408(d)(8)(A) limit per IRA owner and the one-time split-interest limit, indexed from 2022 and rounded to the nearest multiple of $1,000; indexing "inflation" scales the 2026 amounts, rounded the same way.

Code: backend/src/federal_tax.c federal_qcd_limit_for_year, federal_qcd_split_interest_limit_mode. Tests: test_federal_2_projection.c test_e_hand_parameters; test_federal_2_projection.c test_d_inflation_is_legacy.