Apply the Form 4952 election in Schedule D Tax Worksheet lines 3-10

[MaxGhenis]

Summary

The Schedule D Tax Worksheet lines in the model did not apply the Form 4952 line 4g investment income election the way the worksheet does, and read a different input from net_capital_gain. With a $50,000 election against a $300,000 long-term gain, net_capital_gain was $250,000 but dwks10 (worksheet line 10) $300,000. dwks10 feeds dwks13, dwks14, dwks19, regular_tax_before_credits and Form 6251 Part III (amt_tax_including_cg).

This PR makes dividend_income_reduced_by_investment_income, dwks09 and dwks10 follow worksheet lines 3 to 10, and makes net_capital_gain and adjusted_net_capital_gain apply the same election under 26 U.S.C. 1(h)(2) and 1(h)(11)(D)(i). Line 10 now equals net_capital_gain for the same inputs.

The law and the forms

2025 Schedule D Tax Worksheet (Instructions for Schedule D, page 15): line 2 qualified dividends; line 3 "the amount from Form 4952 ... line 4g"; line 4 "the amount from Form 4952, line 4e"; line 5 = line 3 − line 4, not below zero; line 6 = line 2 − line 5, not below zero; line 7 "the smaller of line 15 or line 16 of Schedule D"; line 8 "the smaller of line 3 or line 4"; line 9 = line 7 − line 8, not below zero; line 10 = lines 6 + 9.

2025 Form 4952: line 4d is "the excess, if any, of your total gains over your total losses from the disposition of property held for investment ... include capital gain distributions"; line 4e is "the smaller of line 4d or your net capital gain from the disposition of property held for investment", that is "the excess, if any, of your net long-term capital gain over your net short-term capital loss", with capital gain distributions "treated as long-term capital gains"; line 4g is "the amount from lines 4b and 4e that you elect to include in investment income". The line 4g instructions: the amount "is generally treated as being attributable first to net capital gain from property held for investment (line 4e), and then to qualified dividends (line 4b)", and "Don't reduce the amount of qualified dividends on Form 1040 ... line 3a ... by any part of the amount on line 4g."

26 U.S.C. 1(h)(2): "the net capital gain for any taxable year shall be reduced (but not below zero) by the amount which the taxpayer takes into account as investment income under section 163(d)(4)(B)(iii)."
26 U.S.C. 1(h)(11)(D)(i): "Qualified dividend income shall not include any amount which the taxpayer takes into account as investment income under section 163(d)(4)(B)."
26 U.S.C. 163(d)(4)(B): "(iii) so much of the net capital gain ... as the taxpayer elects to take into account under this clause. Such term shall include qualified dividend income (as defined in section 1(h)(11)(B)) only to the extent the taxpayer elects to treat such income as investment income".

The two inputs

• investment_income_elected_form_4952 (Person) is Form 4952 line 4g. The default dataset (populace_us_2024.h5@populace-us-2024-spm-20260909) fills it for 135 people (135 tax units), and it is uprated in default_uprating.py. net_capital_gain already read it.
• investment_income_form_4952 (TaxUnit) is filled by no dataset (zero for every unit in the default dataset). It is the input Tax-Calculator's e58990 port gave the worksheet; its only other reader, ca_investment_interest_deduction, uses it as FTB 3526 line 9, which is "the amount from federal Form 4952, line 8" (the deduction, not line 4g). The worksheet no longer reads it; its documentation now says so. California is unchanged.

Changes

• New helper schedule_d_tax_worksheet_form_4952_lines (worksheet lines 3, 4 and 7), shared by lines 6 and 9.
  • Line 3: Form 4952 line 4g, summed over the tax unit (not below zero).
  • Line 4: Form 4952 line 4e, the smaller of line 4d and the net capital gain from investment property. Assumption: every capital asset is property held for investment (the model has no split), and there is no input for the "Elec." amount a filer may write beside line 4e, so the election comes from gain first, as by default.
  • Line 7: the smaller of Schedule D lines 15 and 16. Capital gain distributions (non_sch_d_capital_gains) belong on Schedule D line 13 ("Enter on Schedule D, line 13, the total capital gain distributions"), so they enter lines 15 and 16.
• dividend_income_reduced_by_investment_income is line 6; dwks09 is line 9; dwks10 adds lines 6 and 9 (the old no-gains branch gave the same result for every valid input).
• net_capital_gain: section 1222(11) gain (distributions netted as long-term gain), less the gain part of the election (1(h)(2)), plus qualified dividends less the rest of the election (1(h)(11)(D)(i)). Before, an election above the gain was ignored, and distributions sat outside the netting and the election.
• adjusted_net_capital_gain adds back the qualified dividends left after 1(h)(11)(D)(i), min(max(0, QDI), net_capital_gain), not all of them. capital_gains_tax's max_(0, net_cg - qualified_dividends) already equals the gain after the election, so it is unchanged.
• dwks09 no longer drops Schedule D gains when capital gain distributions are also positive. Before, it was where(distributions > 0, distributions, Schedule D gain).
• Documentation and references on both inputs.

Invariants (stated and tested)

For every combination of long-term and short-term gains and losses, capital gain distributions, qualified dividends, elections, unrecaptured section 1250 gain and 28-percent rate gain:

1. dwks10 == net_capital_gain (worksheet route = statute route).
2. dwks13 == adjusted_net_capital_gain (worksheet line 13 = section 1(h)(3)).
3. Lines 6, 9 and 10 equal an independent line-by-line transcription of the worksheet and Form 4952 lines 4d and 4e.
4. Bounds: max(0, G + Q − E) <= line 10 <= G + Q, where G is the Schedule D gain before the election, Q the dividends and E the election.
5. Monotonicity: line 10 never rises as the election rises, and falls by at most the extra amount elected.

Intended exception. With amounts in cents, 1 and 2 hold to within single-precision storage rounding: lines 6 and 9 are each stored as float32 before dwks10 adds them. On the default dataset 738 tax units differ by at most $0.25. All 738 are among the 819 units where the two differ on main, the other 81 being units this PR fixes. The tests use whole dollars up to $2,000,000, where every sum is exact, and compare exactly.

Tests: policyengine_us/tests/test_form_4952_election_worksheet.py (Hypothesis differential and property tests plus a 240-case grid), and capital_gains/schedule_d_tax_worksheet_form_4952.yaml (13 cases with worksheet line comments, including the $300,000 / $50,000 example and a 2025 tax and Form 6251 Part III case). All four Python tests fail on main and pass here. Locally, 2,699 YAML tests pass in gov/irs plus states HI, VT, ID and CA income tax.

Microsimulation (default dataset, 2026, policyengine-core 3.32.12)

Main (3c336f251d, after #9761) and this branch (ea06980c86); re-run 2026-10-04 with the same result as the first run on 6b0e773868 / 72b76cb258 (per-unit table identical), run one at a time under the shared heavy-job lock and a 24 GB watchdog (peak footprint 14.4 GB each). 135 of 79,729 tax units change: 132 that elect, and 3 with capital gain distributions alongside Schedule D gains. Every other unit is bitwise identical on all 29 measured variables.

	main	branch	change
dwks10 (weighted)	$1,816.11B	$1,818.47B	+$2.36B
net_capital_gain	$1,819.88B	$1,818.47B	−$1.40B
income_tax_main_rates			+$397.8M
capital_gains_tax			−$230.6M
alternative_minimum_tax	$11.904B	$11.211B	−$692.8M
income_tax	$2,592.280B	$2,591.755B	−$525.6M
state_income_tax			−$0.22 (one unit, $0.11)

By cause:

• Electing units (132 changed): income tax +$174.3M. Elected dividends lose the capital gains rates in net_capital_gain (63 units), and Form 6251 Part III now sees the election: AMT +$7.1M across 2 units.
• Distributions alongside Schedule D gains (3 units): income tax −$699.9M, all from one record (weight 6,610; long-term gain $1,554,762, short-term $209,132, distributions $40,164, dividends $465,786). Main's dwks09 used only the $40,164 of distributions, so Part III taxed the $1.55M long-term gain at 26/28%. That gave an AMT of $112,099 per unit, $6,210 on this branch.

Per-unit table of all 135 changed units, scripts and logs: ~/reviews/pe-us-dwks-4952-2026-10-03/microsim/ (diff_2026.txt, breakdown_2026.txt).

Interaction with #9761 (merge gate)

#9761 (section 911(f) stacking) measures the worksheet's capital gain excess from dwks10 and the section 1(h) excess from net_capital_gain, and its helper's docstring says the two "can disagree (they read different Form 4952 inputs)". After both merge they agree, apart from the storage rounding above. Its two synthetic cases (amt_section_911_capital_gain_excess.yaml, capital_gains/dwks14.yaml) set dwks10 and net_capital_gain apart by direct input and stay valid. #9761 has merged; ea06980c86 carries the follow-up: it updates that docstring and starts section_911_qualified_dividend_income from the dividends after 1(h)(11)(D)(i), min(max(0, QDI), net_capital_gain). Otherwise an excluding filer who elects dividends gets them back at the capital gains rates: all three reviews found this. Example: long-term gain 20,000, dividends 30,000, election 35,000 and capital gain excess 5,000 give 25,000 of section 911 dividends, where 10,000 is right. On the merged head, the capital gains, AMT and FEIE YAML folders pass (149 tests), as do this PR's and #9761's Python tests (14). This PR carries the same hypothesis dev dependency hunk as #9761, so either can merge first.

Reviews

Round 1, at 72b76cb258: three APPROVEs.

• GPT-6.1 Sol, hard tier: review-r1-sol.md.
• Opus 5.5, standard tier, two runs: review-r1-opus.md and review-r1b-opus.md.

All are in ~/reviews/pe-us-dwks-4952-2026-10-03/. Their one Medium finding is the #9761 interaction above. The Lows are fixed in 9a158d2ded:

• the 2025 tax case now notes the Tax Table rounding;
• the label and documentation of investment_income_form_4952 and adjusted_net_capital_gain are corrected;
• this body is corrected.

Pre-existing gaps the reviews raised are listed below.

Not in this PR

• The federal model deducts investment interest in full (investment_interest_expense → non_mortgage_interest → deductible_interest_expense), without the section 163(d)(1) net investment income limit. The election exists to raise that limit, so in the model it has only its capital gains side, and electing units are over-benefited on the deduction side. This is unchanged.
• The loss limitation (loss_limited_net_capital_gains) still keeps capital gain distributions out of Schedule D netting. The default dataset has no capital losses, so there is no effect.
• The QBID taxable income limit subtracts adjusted_net_capital_gain, where section 199A(a)(2)(B) says net capital gain. This is separate.
• capital_gains_tax taxes 28-percent rate gain in full even when the election leaves no gain to tax at 28% (worksheet line 12 caps it). This is pre-existing and part of the 1(h) 25%/28% follow-up from Tax Form 2555 filers' income at stacked rates (26 U.S.C. 911(f)) #9761.
• Form 6251 line 27 asks for Schedule D Tax Worksheet line 21; amt_tax_including_cg uses line 14. This is pre-existing.

axiom: us:statutes/26/1/h#net_capital_gain encoded-correct for the 1(h)(2) gain election (companion test investment_income_reduces_net_capital_gain); TheAxiomFoundation/rulespec-us#1488 queued for 1(h)(11)(D)(i), the dividend part

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (909176a) to head (a3371b8).
⚠️ Report is 158 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #9781   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            4         8    +4     
  Lines           76       105   +29     
  Branches         2         0    -2     
=========================================
+ Hits            76       105   +29     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[MaxGhenis]

Merged by the US + core hub at head ea06980c865262a2d29450b4d2be7da780674ca0 (squash, --admin --match-head-commit). The only block was the required approving review, which no one else can give on Max's PRs.

Gates:

• Round 1: three independent approvals at 72b76cb258 (two Opus 5.5, one GPT-6.1 Sol).
• Delta review: a GPT-6.1 Sol review approved this exact head with no blocking findings (~/reviews/us-hub/9781/delta-review.md). It covers:
  • 9a158d2ded, the round-1 low fixes;
  • the merges of main, including Tax Form 2555 filers' income at stacked rates (26 U.S.C. 911(f)) #9761 (all 53 of Tax Form 2555 filers' income at stacked rates (26 U.S.C. 911(f)) #9761's paths preserved byte for byte);
  • ea06980c86, the section 911 qualified-dividend follow-up. It is legally required under §1(h)(11)(D)(i) before §911(f), and the review re-derived it independently.
• Impact: the review re-derived the −$699.9M AMT record by hand, as a correction. Main's dwks09 dropped that record's $1.55M long-term gain when distributions were present. The PR body's absolute income_tax totals were stale; the hub corrected them to the re-run ($2,592.280B → $2,591.755B). The −$525.6M change was already right.
• Election allocation: the review flagged the gain-first allocation of the Form 4952 line 4g election as a modeling assumption. It follows the form's own line 4g Note ("attributable first to net capital gain"), and all three round-1 reviewers judged it the form's default. Filers may allocate otherwise, but no dataset records that choice. This is the source's stated default, not a choice between readings of the law, and the PR body documents it.
• CI: gh pr checks exits 0, with all 35 check runs on ea06980c86 successful, including the Hypothesis tests.
• State: MERGEABLE against current main, not a draft, no CHANGES_REQUESTED review.

Non-blocking follow-up: no end-to-end property test covers a Form 4952 election together with §911 stacking on generated inputs.