[MaxGhenis]

This PR builds on #10693. Until #10693 merges, GitHub also shows #10693's nine files in this diff.

What changes

After #10693, railroad_benefits counts in household and SPM income but in no tax. This PR splits the benefits into parts with different tax rules and taxes each part. It adds three person inputs:

• railroad_social_security_equivalent_benefits: the social security equivalent benefit (SSEB) on Form RRB-1099, box 5.
• taxable_railroad_pension_benefits: the rest of the annuity on Form RRB-1099-R (the non-social security equivalent part of tier 1, tier 2, vested dual benefits and supplemental annuities), less the employee contributions the annuitant recovers tax free.
• tax_exempt_railroad_pension_benefits: that tax-free recovery.

railroad_benefits becomes their sum. If a user enters only the total, it counts in income totals but in no tax.

Federal

• Under section 86(d)(1)(B) and (d)(4), the SSEB counts as a social security benefit. tax_unit_section_86_benefits and tax_unit_taxable_section_86_benefits run section 86 once on title II benefits and the SSEB together. taxable_social_security keeps the title II share, so the programs and states that read it see no railroad benefits. taxable_railroad_social_security_equivalent_benefits takes the SSEB's share, and a dependent's own return splits the same way.
• Under section 72(r)(1), the rest of the annuity counts as a benefit from a section 401(a) plan, so taxable_railroad_pension_benefits joins gov.irs.gross_income.sources. Under section 72(r)(2), the tier 2 taxes employees paid count as employee contributions, which the annuitant recovers tax free.
• medicaid_magi and aca_magi add back the nontaxable SSEB, as section 36B(d)(2)(B)(iii) requires for any benefit that counts as a social security benefit under section 86(d).
• The calculations that recompute section 86 or build modified AGI around it now treat title II benefits and the SSEB alike. They include ira_219g_magi and ira_219g_taxable_social_security for the IRA deduction limit, taxable_ss_magi, the dependent IRA deduction and the tuition deduction cap. taxable_social_security_tier_1 (section 86's 50 percent tier) and tax_unit_taxable_social_security_pre_1993 run on both benefits and keep the title II share.
• The model now reduces the section 22 amount by the head's and spouse's nontaxable SSEB and the tax-free part of the rest of their annuities. Section 22(c)(3)(A)(i)(II) requires the reduction for any pension or annuity "which is excluded from gross income and payable under ... the Railroad Retirement Act of 1974", and both amounts qualify. In its Schedule R instructions, the IRS has filers enter the nontaxable SSEB on line 13a. At line 13b, the IRS adds "Don't include amounts that are treated as a return of your cost of a pension or annuity," so a filer who follows the instructions leaves out the tax-free part. The model follows the statute, and this PR logs the conflict in source_conflicts/candidates.yaml as us:elderly-credit-railroad-tier-2-return-of-cost.

States

Under 45 U.S.C. 231m(a), no state, territory or the District of Columbia may subject a Railroad Retirement Act annuity to "any tax". taxable_railroad_benefits holds the Railroad Retirement Act benefits in the head's and spouse's federal AGI. The model builds income for 38 jurisdictions from federal gross income, AGI or taxable income, and now subtracts taxable_railroad_benefits in each: AZ, CA, CO, CT, DC, DE, GA, HI, IA, ID, IL, IN, KS, KY, LA, MA, MD, ME, MI, MN, MO, MT, NC, ND, NE, NM, NY, OH, OK, OR, PA, RI, SC, UT, VA, VT, WI and WV. For most of them, this PR adds taxable_railroad_benefits to a parameter list of subtractions; the KS, MA, ME and UT formulas subtract it directly.

The model builds income for Alabama, Arkansas, Mississippi and New Jersey from each state's own list of sources. None of those lists holds railroad benefits, so they need no change.

Virginia filers subtract the taxable SSEB on Form 760 line 5 and the taxable rest of the annuity on Schedule ADJ. Under Va. Code 58.1-322.03(5), Virginia's age deduction phases out with federal AGI less the benefits that enter federal AGI only under IRC 86, so the SSEB leaves that test and the rest of the annuity stays in it.

Where railroad benefits still move state tax

• The model charges Idaho's $10 permanent building fund tax when federal gross income exceeds the standard deduction (id_income_tax_liable), and federal gross income includes taxable railroad benefits.
• Alabama and Missouri let filers deduct federal income tax, and Oregon lets them subtract it (ORS 316.680(1)(b)), so railroad benefits lower these states' bases.
• New Mexico's low- and middle-income exemption (NMSA 7-2-5.8) and, from 2026, South Carolina's income adjusted deduction (SCIAD, H.4216) phase out with federal AGI. Through 2023, Kansas limited its Social Security subtraction to filers with federal AGI of $75,000 or less. The model applies each of these limits as the state writes it. This PR doesn't take up whether 231m(a) bars a state from counting railroad benefits in such a limit.
• Colorado and South Carolina (before the SCIAD) start from federal taxable income, which floors at zero. When the standard deduction absorbs some of the benefits, the full subtraction exceeds what federal taxable income gained, so the state base can only fall. The model's Social Security subtractions work the same way.
• Minnesota reduces its alternative Social Security subtraction by 20 percent of provisional income over a threshold. Under Minn. Stat. 290.0132, subd. 26(i), provisional income starts from section 86(b)(2)'s modified AGI, which leaves out the taxable amount of every section 86 benefit. Its benefits term counts Social Security benefits as section 86(d)(1) defines them, the SSEB included. The model still builds provisional income from title II amounts in mn_social_security_subtraction, so for a filer with both kinds of benefits it counts the taxable SSEB and leaves the SSEB out of the benefits term. This PR leaves that worksheet, and the other state Social Security worksheets that read title II amounts, to a follow-up.

Reforms

tax_unit_taxable_social_security and taxable_social_security now hold only the title II share of taxable benefits. Parameter reforms to section 86 reach both benefits through tax_unit_taxable_section_86_benefits. A reform that replaces tax_unit_taxable_social_security changes title II benefits only and leaves the SSEB on baseline section 86. These reforms and tools read the title II variables, so they leave the SSEB out:

• the CRFB non-refundable Social Security credit (reforms/crfb/non_refundable_ss_credit.py);
• the Minnesota HF 1938 and Rhode Island Social Security exemption reforms, though the model already subtracts railroad benefits in both states;
• PolicyEngine/crfb-tob-impacts, which materializes tax_unit_taxable_social_security.

Invariants

These hold for every input, and test_railroad_retirement_taxation.py checks them with Hypothesis.

1. Moving benefits between title II and the SSEB leaves AGI, federal income tax, the taxable section 86 amount and Medicaid MAGI unchanged.
2. Moving an amount between a private pension and the taxable rest of the annuity leaves AGI and federal income tax unchanged.
3. A household with no income but railroad benefits owes no state income tax before refundable credits in the 41 income tax jurisdictions other than Idaho, and has no Idaho taxable income.
4. For a wage earner under 65, railroad benefits leave state AGI unchanged. In CO, MI, MN, MT, NC, ND and SC, whose state AGI in the model equals federal AGI, and in Utah, whose total income includes the benefits, they leave state taxable income unchanged instead. In Colorado and South Carolina, when the wage earner has no federal taxable income before the benefits, the base can only fall. The test leaves out Oregon, which subtracts federal income tax, and New Mexico, whose low- and middle-income exemption phases out with federal AGI.
5. railroad_benefits equals the sum of its three parts, and the title II and SSEB shares sum to the taxable section 86 amount. For a head or spouse, taxable_railroad_benefits equals their taxable SSEB plus taxable_railroad_pension_benefits; dependents get zero.
6. Section 86 gives the same taxable amount on a dependent's own return as on a filer's return with the same income.

Tests

• YAML cases, whose comments derive each expected value from the law:
  • irs_gross_income/social_security/railroad_social_security_equivalent_benefits.yaml (7 cases)
  • irs_gross_income/taxable_railroad_benefits.yaml (4)
  • elderly_and_disabled/section_22_railroad_retirement.yaml (3)
  • medicaid/income/medicaid_magi_railroad_retirement.yaml (2)
  • va/tax/income/subtractions/va_railroad_retirement.yaml (2)
  • states/railroad_retirement_benefits.yaml (42), one filer with only railroad benefits in each income tax jurisdiction
• The new cases and the suites around them pass locally: 2,022 cases across irs_gross_income, elderly_and_disabled, hhs/medicaid/income, the cross-state file, and the Colorado, Montana, North Carolina, Oregon and Virginia tax/income folders.
• test_railroad_retirement_taxation.py quantifies over amounts, filing status and every state, which YAML cannot. Locally, its six tests take 148 s (184 s with imports) at 1.9 GB peak memory, and I4, which loops over 40 states, takes 85 s of that.
• test_household_spm_resource_parity.py fails when a federal gross income source has neither an SPM resource that counts its cash nor a documented reason to leave it out. This PR maps both new sources, taxable_railroad_pension_benefits and taxable_railroad_social_security_equivalent_benefits, to railroad_benefits. That file and test_railroad_retirement_taxation.py pass locally, 69 tests in all.

Impact

I'll add the 2026 results on hf://datasets/policyengine/populace-us/populace_us_2024.h5@populace-us-2024-spm-20260909 when the run finishes.

axiom: us:statutes/26/86#tier_1_railroad_retirement_benefit encoded-correct (companion test married_separate_not_apart_with_repayments_substituted_benefits_and_lump_sum_election in us/statutes/26/86.test.yaml); TheAxiomFoundation/rulespec-us#2071 queued (26 U.S.C. 72(r), 45 U.S.C. 231m(a), and companion tests for section 22's railroad reduction and section 86's tier 1 benefit).

🤖 Generated with Claude Code