Test a Form 4952 election with section 911(f) stacking end to end

[MaxGhenis]

Adds policyengine_us/tests/test_form_4952_section_911_interaction.py, an end-to-end property test of a Form 4952 line 4g election (#9781) together with section 911(f) stacking (#9761) on generated households. Until now, test_form_4952_election_worksheet.py tested elections without an exclusion, and test_section_911_tax_stacking.py tested exclusions without an election. The only combined check was a YAML case with supplied excess values (low finding 2 of the #9781 delta review).

Test-only. No formula, parameter or expected output changes.

How it checks the interaction

On a return the two meet in the Schedule D Tax Worksheet. A filer with an amount on Form 4952 line 4g must use it (2025 Instructions for Schedule D, p. 15). The Foreign Earned Income Tax Worksheet measures the capital gain excess from worksheet line 10 and takes it from line 9 before line 6 (2025 Instructions for Form 1040, p. 37). The AMT does the same from Form 6251 line 6 (2025 Instructions for Form 6251, Part III, "Form 2555").

The model reaches these amounts by two routes:

• the worksheet route: dwks09, dwks10 and schedule_d_tax_worksheet_after_capital_gain_excess;
• the section 1(h) route: net_capital_gain and the section_911_* variables.

The test reuses the existing transcriptions instead of copying them: the Schedule D Tax Worksheet lines 2–10 from the #9781 test, and the Foreign Earned Income Tax Worksheet, Qualified Dividends and Capital Gain Tax Worksheet and Form 6251 from the #9761 test. I read the 2025 Schedule D Tax Worksheet before relying on that. With Schedule D lines 18 and 19 zero, its lines 14–47 match the QDCG worksheet line for line, with worksheet line 6 as line 2 and line 9 as line 3. Form 6251 line 27 (worksheet line 21) then equals line 20 (worksheet line 14).

Invariants

Notation: G is the section 1222(11) gain (capital gain distributions included), D qualified dividends, E the election, X the exclusion, T taxable income, and N = max(0, G − E) + max(0, D − max(0, E − G)).

1. Closed forms.
   • net_capital_gain = dwks10 = N.
   • Worksheet line 6 = min(D, N).
   • With an exclusion, the capital gain excess is max(0, N − T), section_911_net_capital_gain is min(N, T) and section_911_qualified_dividend_income is min(D, N, T).
   • Without an excess, section_911_qualified_dividend_income = min(D, net_capital_gain), bit for bit.
   • The gain other than dividends plus the dividends left equals section_911_net_capital_gain (§911(f)(2)(A)(i)–(ii) ordering).
2. The two routes agree.
   • The worksheet's excess, line 10, line 9, line 10 − line 9, line 13 and Schedule D line 19 equal the section 1(h) excess, net capital gain, gain other than dividends, qualified dividends, adjusted net capital gain and unrecaptured §1250 gain.
   • The reduced lines 6 and 9 equal footnote modifications 1 and 2 applied to the transcribed worksheet.
   • The AMT excess is max(0, N − max(0, Form 6251 line 6)).
3. Zero inputs change nothing.
   • A household that elects nothing matches the situation with no election input (Tax Form 2555 filers' income at stacked rates (26 U.S.C. 911(f)) #9761's), bit for bit.
   • A household that excludes nothing matches the situation with no exclusion input (Apply the Form 4952 election in Schedule D Tax Worksheet lines 3-10 #9781's), bit for bit.
   • Both hold whatever the other households in the batch elect or exclude.
   • With no excess, every amount §911(f) replaces equals its original, bit for bit.
   • Both amounts are inputs without formulas, so the zero-input check mainly guards against one household's amounts leaking into another's results. Property 1 checks the no-election and no-exclusion paths themselves.
4. Monotonicity.
   • E and X change taxable income only through the itemization choice (see below).
   • As E rises, net_capital_gain and dwks10 never rise, and net capital gain falls by at most the extra amount elected.
   • While the itemization choice holds, the section 911 net capital gain, the section 911 dividends and both excesses never rise either.
   • While the choice holds, the regular tax and income_tax_before_credits never fall as X rises, and stacking never lowers them.
   • income_tax, the amount the itemization choice minimizes, never falls as X rises, even when the choice flips, for households without dependents.
5. Worksheet lines. dwks10 == net_capital_gain, exactly for whole dollars and within single-precision rounding with cents. The model's lines 6, 9 and 10 equal the Apply the Form 4952 election in Schedule D Tax Worksheet lines 3-10 #9781 transcription.
6. End to end against the 2025 forms. The regular tax matches the Foreign Earned Income Tax Worksheet fed by Schedule D Tax Worksheet lines 6 and 9. The AMT matches Form 6251 line 7 through its own worksheet.

Found by the test: the election and the exclusion can change taxable income, through the itemization choice. tax_unit_itemizes picks whichever choice gives the lower income_tax. A filer in the AMT can lower the tax by itemizing deductions smaller than the standard deduction, because they reduce AMTI. Minimized example (2025, single, Texas, $971,091 long-term gain, $1 charitable gift):

• With no election, the filer itemizes $1,915 (Texas sales tax plus the gift), and taxable income is $969,176.
• Electing $1,917 raises the regular tax above the tentative minimum tax, so the filer takes the standard deduction and taxable income falls to $955,341.
• income_tax_before_credits still rises, from $159,912.70 to $159,912.89.

This is the model working as designed, but it means a "taxable income never changes" assertion is too strong. #9761's test makes that assertion across exclusion variants, so it may be latently fragile for itemizers near the AMT. Property 4 compares amounts that depend on taxable income only between variants with the same itemization choice. It checks income_tax across a flip, for households without dependents. For them no credit applies except the EITC. Neither the EITC (eitc_relevant_investment_income) nor the net investment income tax (net_investment_income, niit_magi) reads the election or the itemization choice, and today neither reads the exclusion. The property still holds if the exclusion later denies the EITC or raises NIIT MAGI. This example and a joint filer with split cents dividends are pinned as @hypothesis.examples.

Intended exception, not a bug: the tax is not monotone in the election. From the 0% capital gains threshold to the top of the 12% bracket (2025: $48,350 to $48,475 single), gain is taxed at 15% and ordinary income at 12%. Electing a dollar there lowers the tax by 3 cents, on the return as in the model. test_election_can_lower_the_tax_where_15_percent_exceeds_12 shows $125 more elected lowering both the model's tax and the worksheet's line 47 by exactly $3.75, with and without an exclusion. The property test asserts the bound instead: the tax falls by at most (15% − 12%) × the overlap width, which rate_overlap computes from the parameters ($3.75 single, $7.50 joint, $3.00 head of household in 2025). The same bound replaces #9761's fixed $7.50 allowance for the omitted worksheet line 47 cap.

Scope

The tax comparisons (4 and 6) use households without 28-percent rate or unrecaptured §1250 gain, as in #9761's test. The gain-level properties (1–3, 5) include them.

While writing this I confirmed a pre-existing bug, which this PR does not fix. capital_gains_tax taxes 28-percent rate gain at 28% in full, even where it exceeds taxable income or the gain an election leaves; Schedule D Tax Worksheet line 12 limits it to line 9. Examples (2025, single):

Case	Model income_tax	Correct
$10,000 collectibles gain, no other income	$2,800	$0
$100,000 of wages and a $100,000 collectibles gain, all elected	$65,067	$37,067

The fix is tracked as a separate follow-up.

Tests

• Grid (439 households × 5 variants, 2,195 tax units in one simulation): coverage assertions confirm it reaches an excess that cuts into dividends, an election that reaches dividends, AMT, the AMT excess, the capital gains tax and zero taxable income, all with both an election and an exclusion.
• Three Hypothesis tests (derandomize=True, like Apply the Form 4952 election in Schedule D Tax Worksheet lines 3-10 #9781's test): invariants over 2018, 2022, 2025 and 2026; the 2025 forms differential; and the zero-input bitwise check. Strategies target elections at G and G + D, and include cents and itemizers.
• Runtime: the file takes about 60 s locally on a heavily loaded machine (grid 18 s, invariants 16 s, zero inputs 5 s, forms 3 s, overlap example 1 s). It runs in the Makefile's remaining Rest group.

axiom: n/a: test-only change; no policy logic modified

🤖 Generated with Claude Code

[MaxGhenis]

Hand-off to the US + core hub.

• Head: 33f7ef802d83fef1dd830d3eb8fa947318c72cc6. The PR is test-only: one new test file and a changelog fragment.
• Independent review (Opus 5.5 on Subfleet, read-only; files in ~/reviews/us-hub/form-4952-911-combined-property/):
  • r1 approved 3ec4d6851a with six non-blocking findings. All six were addressed in 143a9dcef8.
  • r2 approved 143a9dcef8.
  • r3 approved 8253050b31 and r4 approved 33f7ef802d. Both of those commits are docstring-only and apply the reviewer's own wording.
  • Review files: review-r1.md, review-r2-delta.md, review-r3-delta.md, review-r4-delta.md.
• Passed locally:
  • The new file: 5 tests, about 60 s.
  • In one pytest process with test_form_4952_election_worksheet.py, test_section_911_tax_stacking.py and code_health/test_rest_python_groups.py: 29 passed.
  • ruff format and ruff check are clean.
• Pending: CI. The Pull request workflow is queued for a runner. Earlier runs were cancelled by later pushes; none failed.
• Depends on: nothing. There is no hold and no decision for Max (test-only; axiom: n/a).
• Follow-ups (not part of this PR): writing these tests surfaced two pre-existing model bugs, each confirmed with a reproducer and queued as a separate task:
  • capital_gains_tax taxes 28-percent rate gain in full beyond taxable income or the gain an election leaves. Example: a $10,000 collectibles gain with $0 taxable income is taxed $2,800.
  • niit_magi doesn't add back the §911 exclusion (§1411(d)). Example: $150k wages, $50k dividends and $100k excluded give $0 NIIT instead of $1,900.

[MaxGhenis]

Landed by the US + core hub, after session 0b809666 handed it off, at head 33f7ef802d83fef1dd830d3eb8fa947318c72cc6. Squash merge, --admin --match-head-commit; the only block was the required approving review, which no one else can give on Max's PRs.

Gates:

• Reviews: independent Opus 5.5 reviews approved r1 through r4. r4 is at this head; r3 and r4 covered docstring-only commits. The reviews are in ~/reviews/us-hub/form-4952-911-combined-property/.
• CI: the first full run sat in the queue about two hours, and 12 jobs were cancelled without a runner; none was a test failure. The hub re-ran the cancelled jobs on this head, and gh pr checks now exits 0 with every check run successful.
• Combined with main: main took Use the married-filing-separately breakpoint on Form 6251 Part III line 18 #9780 (Part III line 18) and Use Louisiana's RIB 26-019 2026 standard deduction and retirement exemption #9791 after this PR's CI started. The hub ran the new file plus test_form_4952_election_worksheet.py, test_section_911_tax_stacking.py and test_rest_python_groups.py on the tree GitHub's merge produces: 29 passed, Hypothesis included.
• Scope: test-only (one test file and a changelog fragment), so there is no model impact and no Axiom item.

The two pre-existing bugs these tests surfaced (capital_gains_tax on 28-percent gain beyond taxable income, and niit_magi missing the §911 add-back) are queued as separate tasks by the authoring session.