Give the additional_tax_bracket reform's unset bracket zero tax instead of NaN

[MaxGhenis]

Summary

The additional_tax_bracket contrib reform ships brackets 7 and 8 of its schedule (gov.contrib.additional_tax_bracket.bracket) with infinite thresholds for every filing status from 2018 on. Until a user sets bracket 7's threshold, its income_tax_main_rates and regular_tax_before_credits are NaN on main for every household at any income, and so is income_tax. I reproduced this on main for 2025, 2026 and 2027, at taxable incomes of $50,000 and $1 million, with and without long-term gains.

Cause. tax_at_main_rates is the bracket walk shared by the baseline and the reform. It took each bracket's amount as amount_between(x, bottom, top), which is np.clip(x, bottom, top) - bottom. Bracket 8's bottom is bracket 7's infinite threshold, so that amount is inf - inf = NaN.

#9792, merged in the meantime, added amount_taxed_below_rate, the amount behind 26 U.S.C. 1(h)(1)(A)(ii)(I), beside it. That function walks the same brackets with the same clip form, and #9792 made the reform use it for taxable_income_taxed_below_25_percent.

• With the fix to tax_at_main_rates alone, a bracket 8 rate below 25% with bracket 7 unset still gave NaN for that amount.
• The NaN then flows through capital_gains_excluded_from_taxable_income (max_/min_ of NaN) into income_tax_main_rates for every household. That last step follows from numpy's NaN semantics; I did not run it as a simulation.

Fix. A new generator, amounts_in_brackets, now produces each bracket's amount for both functions. It keeps the running-maximum clamp from #9084, so brackets never overlap, and computes max(0, min(x, top) - bottom), the form policyengine-core's MarginalRateTaxScale.calc uses.

• That form is zero for a bracket above an infinite threshold, and equals the clip form bit for bit whenever the bracket's bottom is finite.
• Sharing the walk keeps the amount taxed below a rate consistent with the tax by construction.

Baseline impact: none

• The baseline schedule's bracket bottoms are all finite; only its top threshold is infinite. Its tax, and its income taxed below 25 percent, are therefore bit-identical to before.
  • test_baseline_schedule_is_unchanged_in_every_year compares both functions with the old clip form on gov.irs.income.bracket, for every filing status and every year from 2018 to 2035.
  • The schedule properties check the same bitwise equality for any drawn schedule, wherever the clip form gave a number.
• No microsimulation was run. The contrib reform is off by default (in_effect is false) and has no baseline impact, and the shared walk's baseline outputs are bit-identical.

axiom: n/a: computation fix to a bracket walk for a contrib reform's unset bracket; enacted-law outputs are bit-for-bit unchanged, so rulespec-us has nothing to mirror

Invariants (property and differential tests)

Function properties. These hold for any thresholds, finite or infinite and in any order, for rates in [0, 1] and amounts in [0, $10 million]. Each test ran 300 Hypothesis examples plus explicit ones.

1. tax_at_main_rates is finite and non-negative.
2. Differential: it agrees with policyengine-core's MarginalRateTaxScale over the same brackets.
3. Differential: it is bit-identical to the old clip form wherever that form gave a number. The old form gave NaN exactly where some bracket bottom is infinite.
4. Identity: adding bracket 8 changes the tax by exactly (r8 − r7) × the income in bracket 8.
   • So the tax is at least the tax with the bracket removed (bracket 8's income taxed at bracket 7's rate) whenever r8 ≥ r7.
   • When r8 < r7 the added bracket cuts the tax. That violation is intended.
5. With bracket 7's threshold infinite, as shipped, the eight-bracket tax equals the seven-bracket tax bit for bit, whatever bracket 8's rate and threshold.
6. amount_taxed_below_rate, for any rate limit in [0, 1]:
   • it is finite, and lies between zero and the taxable amount;
   • it is bit for bit the tax at rates of 1 for the brackets below the limit and 0 for the others;
   • it agrees with MarginalRateTaxScale at those rates;
   • it is bit for bit the old clip form wherever that form gave a number.
     An explicit example puts a rate exactly at the limit, as the reform's 2026 bracket 3 rate of 25% is.

The reform in simulations. The grid has 50 tax units: 5 filing statuses × 5 ordinary taxable incomes × with or without $170,000 of long-term gains and qualified dividends.

7. With default parameters, five variables are finite in 2025 and 2026: income_tax_main_rates, regular_tax_before_credits, taxable_income_taxed_below_25_percent, income_tax_before_credits and income_tax.

8. Differential: with brackets 1 to 7 set to current law and the added bracket unset, the reform reproduces the baseline for those five variables.

9. For any thresholds of brackets 7 and 8 and r8 ≥ r7:

   • the reform's three variables are finite;
   • its two taxes are at least their values with the bracket removed.

   Thresholds are set per filing status, so one simulation covers five shapes: both infinite; finite bracket 7 with bracket 8 unbounded; bracket 8 below bracket 7; a zero bracket 7 threshold; and bracket 7 unbounded above a finite bracket 8. Three explicit and three generated examples run.

   Removing the bracket can move bracket 8 across the 25% limit, which changes the amount taxed below 25%. These households have no 28%-rate or unrecaptured section 1250 gain, so that amount changes neither dwks19 nor capital_gains_excluded_from_taxable_income for them, and the inequality concerns only the schedule.

No simulation sets a foreign earned income exclusion. The reform's subtraction of the tax on the excluded amount is covered only through invariants 1 to 6, not end to end.

Tests

• New YAML cases in contrib/additional_tax_bracket:
  • 2026 joint, $1 million taxable income, under the reform's own 2026 schedule: $324,821, computed by hand in the file.
  • 2026 single with no taxable income: $0.
  • 2025 joint, $1 million: $294,062.50, from the 2025 joint rate table (Rev. Proc. 2024-40, section 2.01, Table 1: $202,154.50 plus 37% of the excess over $751,600).
• On main, before the fix:
  • At 81a3e40, the tests alone on the pre-Tax 28% rate and unrecaptured 1250 gain at regular rates below the 24% bracket top, and use Schedule D Tax Worksheet line 21 on Form 6251 line 27 #9792 main: 10 failed and 5 passed. The 3 new YAML cases and the 7 Python tests then in the file failed with NaN. The baseline-unchanged check passed, as it should.
  • A standalone harness runs the four function-level properties against the real tax_at_main_rates.py and policyengine-core, with the package imports stubbed. All four fail on upstream/main's version, including the amount_taxed_below_rate property, and all four pass on this branch.
• On the fix (local runs at af420d4; later commits change only tests, comments and the changelog, and the folder was re-run at the head as noted):
  • contrib/additional_tax_bracket: 18 passed (9 YAML cases, 9 Python tests).
  • Related tests: 266 passed. These are the IRS alternative_minimum_tax, before_credits, capital_gains and foreign_earned_income_exclusion folders, non_sch_d_capital_gains.yaml, the contrib watca, Biden capital_gains_tax_increase and Harris capital_gains YAML files, test_negative_main_rates_inverted_brackets.py, test_form_6251_part_iii.py and test_form_4952_section_911_interaction.py.
  • tests/code_health: 136 passed.

The new Python file runs in two CI steps: make test-policy-contrib-python, and the contrib YAML batch, because test_batched.py hands policyengine-core test the whole subdirectory. Other contrib folders with Python tests, such as contrib/local/ny, already run that way. That is why the simulation property is kept to six examples.

The new YAML cases reuse the reform combo of #9792's case, so they add no cached system. The file's combo weight is 2.25, within the 5.0 budget.

Memory.

• At a42a678, CI's YAML batch for this folder peaked at 10,719 MB (run 37389800915, job 112033537450). A main-based PR run whose folder holds only the YAML file peaked at 6,578 MB (run 37388221916).
• The tests had built a module-level reformed system and cloned it for each simulation with parameter changes.
• From 80f291b, each reformed simulation instead applies the reform to a clone of the already loaded default system, and the tests collect each simulation before building the next.
• Locally (macOS, Python 3.14t), the folder's peak resident set fell from 14.5 GB to 9.45 GB for the two changes together, with the same 18 tests passing.
• Every simulation call also asserts that the shared default system's reform variables and schedule values are unchanged afterwards. So the reform and parameter changes reach only the clone.

Review

Two independent Opus reviews.

• First review: requested changes. All were made in dd18085:
  • suppress Hypothesis's too_slow health check, after a loaded host stalled one draw for 180 seconds;
  • make the simulation property cheaper;
  • make the docstring accurate about foreign earned income;
  • add notes on the stale 2026 schedule.
• Second review, after the merge and the shared walk: approved. It checked the refactor against the merge and main versions in a 6,000-case differential, with 0 bit mismatches wherever the old form was defined. It also showed the new property kills a <=-for-< mutant, a mutant without the clamp, and the clip-form version. Its wording nits are made in a42a678.

Not changed here (follow-ups, filed as #9832)

• Stale 2026 schedule. The reform's parameter file sets its own schedule from 2026: rates of 10, 15, 25, 28, 33, 35 and 39.6%, with thresholds marked "CBO forecast". Current law's 2026 rates are 10, 12, 22, 24, 32, 35 and 37%.
  • Its 2026 married-filing-separately thresholds are non-monotone: bracket 5's 541,550 is above bracket 6's 305,875.
  • So turning the reform on for 2026 or later changes brackets 1 to 7 as well as adding bracket 8.
  • The new 2026 YAML case pins that schedule and will move when the schedule is refreshed.
• Finite bracket 8 threshold. A finite threshold for bracket 8 leaves income above it untaxed, because the walk taxes nothing above the last threshold.

🤖 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 (1e30280).
⚠️ Report is 217 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #9831   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            4         1    -3     
  Lines           76        19   -57     
  Branches         2         4    +2     
=========================================
- Hits            76        19   -57     

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 on its merge gates. Audit:

• Head: 1e302805cdb1db73a50b8df71d4beb7db1e7626b.
• Independent review (Opus 5.5, Subfleet; files in ~/reviews/us-hub/atb-nan/):
  • Reviews 1 and 2 requested changes, all of which were addressed in dd18085a25, af420d432d and a42a67842e.
  • Review 3 approved the code and tests at 80f291bd79.
  • Review 4 approved the 80f291bd79..1e302805cd delta. That delta is test-only: one file, +24 lines, adding a check that reformed simulations leave the default system unchanged. Review 4 has no blocking findings.
• Tests: the reviewer asked for a run of the changed test file at this head. CI's other-shard-1 job runs the contrib test folder, and every check passed at this head before merging.
• Impact: the contrib additional_tax_bracket reform is off by default. A 6,000-case differential showed the shared bracket walk's baseline outputs are bit-identical to main, so there is no baseline microsimulation change.
• Follow-ups: additional_tax_bracket reform: from 2026 its brackets 1-7 are not current law, and a finite bracket 8 threshold untaxes income above it #9832 covers the reform's post-2025 bracket schedule. The stray root PROGRESS.md on main and the double run of contrib Python tests are noted in the build report.
• Decisions: none.