Net losses against 28 percent rate gain and unrecaptured section 1250 gain (26 U.S.C. 1(h)(4), 1(h)(6))

[MaxGhenis]

Summary

26 U.S.C. 1(h)(4) and 1(h)(6)(A) define the 28 percent rate gain and unrecaptured section 1250 gain by netting losses: collectibles loss, the net short-term capital loss and the long-term capital loss carryover come off collectibles gain and section 1202 gain, and what they do not absorb comes off unrecaptured section 1250 gain. The model had no way to apply that netting. Its only inputs, long_term_capital_gains_on_collectibles, long_term_capital_gains_on_small_business_stock and unrecaptured_section_1250_gain, are Schedule D lines 18 and 19 as reported, after the netting; the microdata fill them from the PUF's lines 18 and 19. A household that entered $10,000 of collectibles gain and an $8,000 short-term loss had all $10,000 taxed as 28 percent rate gain instead of $2,000.

This PR adds inputs for the amounts before netting and nets them as the 2025 28% Rate Gain Worksheet and Unrecaptured Section 1250 Gain Worksheet do. The existing inputs keep their meaning and pass through unchanged, so no existing dataset changes.

Follow-up 3 of #9792. Lands after the Schedule D Tax Worksheet regular-tax fix (branch fix-dwks-regular-tax-lines, PR to come); the US hub sets the order. The only textual overlap is test_section_911_tax_stacking.py.

The law and the worksheets

• 1(h)(4): "the term 28-percent rate gain means the excess (if any) of— (A) the sum of— (i) collectibles gain; and (ii) section 1202 gain, over (B) the sum of— (i) collectibles loss; (ii) the net short-term capital loss; and (iii) the amount of long-term capital loss carried under section 1212(b)(1)(B) to the taxable year."
• 1(h)(6)(A): unrecaptured section 1250 gain is the excess of (i) the gain that would be ordinary income if section 1250 took all depreciation over (ii) "the excess (if any) of— (I) the amount described in paragraph (4)(B); over (II) the amount described in paragraph (4)(A)."
• 28% Rate Gain Worksheet (2025 Instructions for Schedule D): lines 1, 3 and 4 collectibles gain or (loss), line 2 section 1202 gain, line 5 long-term carryovers (Schedule D line 14 and Schedule K-1 (Form 1041) box 11 code D), line 6 the Schedule D line 7 loss; line 7, if more than zero, is Schedule D line 18.
• Unrecaptured Section 1250 Gain Worksheet: line 13 the gain before losses; lines 14 to 16 are the 28% worksheet's lines 1 to 4, the line 7 loss and the carryover; line 17 is their combination as a positive amount if a loss; line 18 = line 13 − line 17, if more than zero, is Schedule D line 19.
• Form 2555 (2025 Form 1040 instructions, Foreign Earned Income Tax Worksheet footnote): modification 3 reduces Schedule D line 18 by the capital gain excess; modification 4 enters the excess as a loss on line 16 of the second worksheet.

The change

• New inputs, before netting (all zero unless entered; memo items that long_term_capital_gains already includes; uprated with the other capital gain components):
  • collectibles_gain_or_loss (Person): 28% worksheet lines 1, 3 and 4, negative for a net loss;
  • section_1202_gain (Person): line 2;
  • unrecaptured_section_1250_gain_before_losses (TaxUnit, like the reported input): 1250 worksheet line 13;
  • long_term_capital_loss_carryover (Person): Schedule D line 14 plus K-1 (1041) box 11 code D, worksheet lines 5 and 16.
• capital_gains_28_percent_rate_gain (Schedule D line 18) = the reported amounts + max(0, collectibles gain or loss + section 1202 gain − net short-term capital loss − carryover). The net short-term capital loss is the one net_capital_gain already subtracts, max(0, −sum of short_term_capital_gains).
• New schedule_d_unrecaptured_section_1250_gain (Schedule D line 19) = the reported amount + max(0, gain before losses − line 17); line 17 is zero whenever there is a 28 percent rate gain. The five direct readers of the reported input read it: adjusted_net_capital_gain, dwks13, section_911_unrecaptured_section_1250_gain, schedule_d_tax_worksheet_after_capital_gain_excess (Form 6251 Part III) and amt_part_iii_required. The reforms reach it only through those.
• The existing three inputs are documented as what they are: Schedule D lines 18 and 19 as reported, already netted, with a pointer to the new inputs. Enter one family or the other for a return.
• Massachusetts is unchanged: its 50 percent collectibles deduction still reads long_term_capital_gains_on_collectibles, and collectibles_gain_or_loss is federal only. Its collectibles treatment has a separate defect (M.G.L. c.62 §2(b)(1)(C) puts long-term collectibles gain in Part A, the model has it in Part C, and the §2(c)(2) loss ordering before the §2(c)(3) deduction is not modeled), left to its own PR.
• The section 911 formulas are unchanged. With lines 18 and 19 netted (or reported), reducing line 18 by the excess and line 19 by the part line 18 does not absorb equals the worksheets with the excess added to the losses (shown for both signs of lines 14 to 16, and tested).

Why not give the existing inputs the before-netting meaning: the datasets fill them with PUF E24518 and E24515, Schedule D lines 18 and 19 (Tax-Calculator records), next to short-term losses already netted against them. Netting them again would double-count: on the legacy enhanced CPS 2024 (local copy of the archived policyengine-us-data file), which is still loadable, 3,398 tax units have a Schedule D line 7 loss and a second netting would take $25.5M of line 18 and $1.27B of line 19, weighted. And not a formula on unrecaptured_section_1250_gain itself: policyengine-core uprates a dataset value only when a variable has no formula, so a formula there would replace uprated 2024 data with zero from 2025.

Invariants

Every existing dataset is unchanged. The datasets fill only the reported inputs; with the new inputs at zero, line 18 is the reported amount plus max(0, −losses) = 0, and line 19 the reported amount plus max(0, 0 − line 17) = 0, so every downstream amount is the same value (bit for bit, except that a stored −0 would read as +0). The default dataset has none of the new inputs (checked from the h5). The microsimulation below must show, and shows, zero differences.

Executed as Hypothesis properties (policyengine_us/tests/test_capital_gain_rate_group_netting.py) for random batches of single and joint returns, each entering one family. Properties 1 to 3 are for returns entering amounts before netting:

1. Bounds: 0 ≤ line 18 ≤ the gains before netting (if positive); 0 ≤ line 19 ≤ the gain before losses.
2. Conservation: line 18 + line 19 = max(0, gains + gain before losses − losses). Losses absorb the 28 percent rate gain first, then unrecaptured section 1250 gain, and nothing else.
3. Order: losses reach line 19 only when line 18 is zero.
4. Pass-through: reported lines 18 and 19 are unchanged whatever the losses; amounts before netting are unchanged without losses.
5. Monotonicity: more short-term loss or carryover never raises line 18 or 19; more collectibles gain never lowers either; more section 1250 gain never lowers line 19 or changes line 18.
6. Netting is on the return: moving amounts between spouses changes nothing.
7. Identities: adjusted net capital gain = max(0, net capital gain − qualified dividends − lines 18 − 19) + qualified dividends (26 U.S.C. 1(h)(3); the test households have no dividends); worksheet line 13 = line 10 − min(line 9, line 18 + line 19).
8. Results do not depend on batch order.

Differential: an independent line-by-line transcription of both 2025 worksheets, and of Form 2555 modifications 1 to 4, must equal capital_gains_28_percent_rate_gain, schedule_d_unrecaptured_section_1250_gain, section_911_28_percent_rate_gain, section_911_unrecaptured_section_1250_gain, and the worksheet helper's excess and lines 13 and 19 (the test builds the helper's taxable base and expected excess itself).

Mutation checks, each failing the tests: no short-term netting; no 1250 netting; reported amounts netted again; adjusted_net_capital_gain, dwks13, section_911_unrecaptured_section_1250_gain or the worksheet helper reading the reported input; the helper reporting no excess; the helper's line 13 skipping modification 3; the line 18 shortcut inverted (caught by YAML).

Tests

• New YAML: capital_gains_28_percent_rate_gain.yaml (13 cases), schedule_d_unrecaptured_section_1250_gain.yaml (12), and five cases in capital_gains_tax.yaml worked by hand through the 2025 Schedule D Tax Worksheet (one for 2026). Two cases pin the pass-through: default-dataset tax unit 1053056 (2025), and reported lines 18 and 19 of 2,000 and 20,000 beside an 8,000 short-term loss.
• Before (main) / after (branch): against main ea79c39fb7, 30 of the 36 cases in those three files fail and the 6 existing ones pass; on the branch all 36 pass. On main the before-netting inputs and Schedule D line 19 variable do not exist; entered through main's only inputs, the same amounts are never netted (the 28 percent rate gain stays 10,000 instead of 2,000, adjusted net capital gain 24,000 instead of 30,000, the gains tax 17,000 instead of 13,250). The property file fails on main for the same reason.
• Worked examples, single filer in Texas, 2025, taxed at the rate schedule; "before" is the same amounts entered through the reported inputs, which are not netted: $300,000 wages, 50,000 long-term gain including 20,000 collectibles gain, 10,000 short-term loss: gains tax 8,600 → 7,300. $100,000 wages, 50,000 long-term gain including 10,000 collectibles gain, 8,000 short-term loss: tax 20,449 → 19,889. $100,000 wages, 50,000 long-term gain including 20,000 section 1250 gain, 6,000 short-term loss: 21,467 → 21,029. $300,000 wages, 100,000 long-term gain including 30,000 collectibles and 40,000 section 1250 gain, 35,000 short-term loss: gains tax 17,000 → 13,250.
• Updated: test_section_911_tax_stacking.py compares the section 911 amounts with Schedule D line 19 (schedule_d_unrecaptured_section_1250_gain); test_uprating_series.py lists the new inputs.
• Suites run, one process at a time, all passing: federal capital_gains (79), alternative_minimum_tax (88), before_credits (7), foreign_earned_income_exclusion (43) and the loose federal income files (31); contrib additional_tax_bracket (18), biden/budget_2025 (1), harris/capital_gains (5); Massachusetts income tax (116, unchanged); and the Python tests that touch these variables or all inputs (379, at this head: the new property file, Form 6251 Part III, section 911 stacking, the Form 4952 tests, uprating series, input-variable definitions, per-capita uprating, aggregate list integrity, code health).

Impact

Default dataset (populace_us_2024.h5@populace-us-2024-spm-20260909), this PR's base main ea79c39fb7 against its head f77ccfea40, 2025 and 2026, with the #9792 measurement scripts (measure.py, microsim_diff.py):

	2025	2026
tax units (weighted)	79,729 (164.2M)	79,729 (165.4M)
units with 28% rate or unrecaptured 1250 gain (weighted)	784 (1.83M)	784 (1.84M)
tax units with any saved output changed	0	0
weighted income tax, main = branch	$2,415.75B	$2,589.50B
weighted AMT, main = branch	$5.38B	$10.31B

Saved and compared bit for bit for every tax unit: taxable_income, has_qdiv_or_ltcg, net_capital_gain, adjusted_net_capital_gain, unrecaptured_section_1250_gain, capital_gains_28_percent_rate_gain, dwks10, dwks13, dwks14, dwks19, capital_gains_excluded_from_taxable_income, income_tax_main_rates, capital_gains_tax, regular_tax_before_credits, amt_income_less_exemptions, amt_part_iii_required, amt_base_tax, amt_tax_including_cg, alternative_minimum_tax, income_tax_before_credits, income_tax, state_income_tax, and household household_net_income; all equal. On the branch, schedule_d_unrecaptured_section_1250_gain equals unrecaptured_section_1250_gain bit for bit for every unit. This is the invariant above: the default dataset fills only the reported inputs. The change affects households that enter the new before-netting inputs (household calculations, the API, and any future dataset that carries those components).

Axiom

axiom: 26 U.S.C. 1(h)(4), 1(h)(6)(A) — TheAxiomFoundation/rulespec-us#1499 queued (pe-parity; the signed encoder is the only path, and a billed dispatch is Max's approval)

CI cost

The new Python file runs in the remaining group. Measured locally at this head (macOS): 3 tests, 1.26 s of test calls and 4.5 s for the file with collection, after the import and system build the group already pays (18.4 s wall for the process); peak RSS 1.13 GB. No Linux CI measurement yet; the group's timing artifact will show it.

🤖 Generated with Claude Code

[MaxGhenis]

Hand-off to the US + core hub (from session 14937118, hub-dwks-netting).

• Head: f77ccfea40 (one commit on main ea79c39fb7).
• Independent review: GPT-6.1 Sol, five rounds; APPROVE at f77ccfea40 (r5).
  • r1 blocked the first design, which double-netted PUF-based datasets. That's why the existing inputs stay reported Schedule D lines 18/19 and four new before-netting inputs carry the netting.
  • r2 led to leaving Massachusetts unchanged.
  • r3 and r4 corrected description claims.
  • Reports: ~/reviews/us-hub/dwks-netting/review-r1.md … review-r5.md.
• Passed locally at this head:
  • YAML, before/after on main: 30 of 36 fail on main, 36 pass here.
  • Hypothesis property and differential tests; 10 mutations, all caught.
  • The affected YAML folders and Python groups.
  • Default-dataset microsimulation, ea79c39fb7 vs f77ccfea40, 2025 and 2026: 0 of 79,729 tax units changed on any saved output, bit for bit.
• Pending: CI (16 passed, 19 running at hand-off, none failed); merge order.
• Depends on: the Schedule D Tax Worksheet regular-tax fix (branch fix-dwks-regular-tax-lines), which lands first by the hub's order. If it lands first, test_section_911_tax_stacking.py may need a trivial rebase. No other overlap: its differential test takes lines 18 and 19 as entered, which this PR keeps.
• Axiom: Encode IRC §1(h)(4) and §1(h)(6)(A): derive 28-percent rate gain and unrecaptured section 1250 gain by netting losses (PE #9841 parity) TheAxiomFoundation/rulespec-us#1499 is queued. Decision d996 asks Max to approve the billed signed encode; it does not block this merge.
• Follow-ups: Massachusetts' long-term collectibles treatment (Part A placement and §2(c)(2)–(3) loss ordering) is a separate task.
• Build report: ~/reviews/us-hub/dwks-netting/build-report.md.

[MaxGhenis]

Merged by the US + core hub on its merge gates. Audit:

• Head: f77ccfea40, handed off by the netting session (14937118).
• Independent review: GPT-6.1 Sol, rounds r1 to r5. r5 APPROVES this head (~/reviews/us-hub/dwks-netting/review-r5.md). r1 blocked a design that would have double-netted PUF-based data. So the existing inputs keep their reported Schedule D lines 18 and 19, and four new before-netting inputs carry the §1(h)(4)(B) and (h)(6) netting.
• Tests: 30 of 36 YAML cases fail on main and all 36 pass here. The property and differential tests pass, and all 10 mutations are caught.
• Impact: default dataset, 2025 and 2026: 0 of 79,729 tax units change, bit for bit, because the dataset has none of the new inputs. Households that enter them get the statutory netting.
• Order: this lands before the Schedule D Tax Worksheet regular-tax PR, which is still being built and will take a trivial rebase of test_section_911_tax_stacking.py. d996, the Axiom encode, doesn't block this merge.