Add excluded foreign earnings to Massachusetts gross income

[MaxGhenis]

Massachusetts adds back earnings excluded under IRC §911 under M.G.L. c.62 §2(a)(1)(C). This change restores the gross exclusions to Massachusetts gross income and its Part B residual. It preserves the loss adjustment and main's filer-only Social Security, state/local refund and exempt public-pension subtractions from #9699. Main's #9954 capital-loss allocation is also preserved: capital losses offset the applicable capital schedules, while the foreign-income add-back enters Part B. The independent property-test oracle now derives capital income from the raw fixture inputs rather than subtracting Part A and C from Massachusetts gross income; all existing assertions, generated households and differential coverage remain.

Max's d1051 ruling applies the 2026-10-07 principle, “make inputs as leaf-nodey as possible.” The TaxUnit/USD/YEAR inputs sum both spouses' forms:

Input	Form amount
foreign_earned_income_exclusion_amount	Form 2555 line 42
foreign_housing_exclusion	Form 2555 line 36
foreign_earned_income_exclusion_allocable_deductions	Form 2555 line 44
foreign_housing_deduction	Form 2555 line 50
foreign_earned_income_exclusion_disallowed_deductions	Foreign Earned Income Tax Worksheet line 2b

foreign_earned_income_exclusion_gross is line 43 = lines 36 + 42. Massachusetts uses its nonnegative value whenever applicable leaves were supplied, including carried inputs; explicit Massachusetts overrides still win, including zero. No applicable leaves retains the nonnegative legacy stacking-amount fallback, which cannot reconstruct the gross exclusion.

Main's #9817 separate section_911_excluded_income is preserved and derives Form 2555 lines 45 + 50 as gross - line44 + line50 when applicable leaves are supplied. It preserves a signed line 45 and does not subtract worksheet line 2b. Its explicit overrides and no-leaf fallback remain available. Federal foreign_earned_income_exclusion retains worksheet line 2c: max(0, gross - line44 + line50 - worksheet2b), with explicit legacy overrides and the original no-leaf carry/uprating behavior. Form 2555, Schedule 1-A, federal worksheet.

The shared elects_section_911_exclusion(tax_unit, period) helper recognizes positive legacy stacking amounts, the separate section_911_excluded_income amount, or any Form 2555 leaf amount. It supplies five election tests: the refundable CTC bar, federal EITC eligibility, the state EITC helper, New Jersey's childless age route, and filing propensity. This keeps the bars effective for a housing-exclusion-only filer, a leaf-only caller, or positive Form 2555 amounts whose deductions or explicit aggregate overrides reduce worksheet line 2c to zero. Section 911(a) permits separate earned-income and housing exclusion elections. The Schedule 8812 instructions, Line 13 and Part II-A, and Publication 596, Rule 5, restrict Form 2555 filers; the Form 2555 instructions, “Choosing the Exclusion(s),” expressly cover either exclusion or the housing deduction.

Worksheet B retains main's structure: it reads refundable_ctc_barred_by_section_911_exclusion, preserving explicit overrides of that variable and its existing year rules. The section 24(d)(3) bar begins in 2015 and remains disabled in the model's fully refundable year, 2021; Worksheet B's fully refundable-year exception is also preserved. The model still has no independent Form 2555 filing flag for filings with every amount zero.

US Simulation rejects ambiguous multi-tax-unit JSON histories with a clear error before Core fills omitted inputs with zeros. Core has whole-array provenance, so an aggregate override bypasses formulas for all units and cannot safely resolve mixed representations per unit. Where both aggregates and leaves are supplied, units must have matching aggregate and combined leaf input periods. A given leaf component must also have matching periods among units supplying that component; wholly absent components remain allowed. Different values, different leaf components, explicit zeros, and uniform aggregate overrides remain supported. The check conservatively rejects inconsistent future histories before calculations. Use consistent input coverage or calculate those units separately. Raw Core Simulation/SimulationBuilder bypass the US constructor and must continue to use consistent input coverage; dataset and setter arrays represent all entities explicitly.

AGI inputs retain their existing reported/net definitions. Form 2555 line 45 feeds Schedule 1 line 8d; the housing deduction on line 50 belongs on Schedule 1 line 24j. These leaves supply stacking and MAGI adjustments and do not subtract those amounts from AGI again. NIIT's legacy fallback remains approximate when housing/deduction components differ; its independent niit_magi_section_911_addition remains available.

Validation and invariants:

• Existing Massachusetts property/differential coverage is retained. The generated leaf property asserts line 43 equals lines 36 + 42, Massachusetts add-back is nonnegative, MAGI amount equals lines 45 + 50 without worksheet deductions, and stacking is its worksheet-deduction-adjusted nonnegative value.
• Generated differential tests assert each accepted uniform batch equals separate tax-unit calculations in the entered and carried years, including signed amounts and explicit zeros. Rejected regressions cover mixed legacy/leaf units, zero overrides, and swapped component-year histories.
• A generated CTC property asserts that deductions reducing stacking to zero cannot enable Worksheet B for a positive Form 2555 earned-income exclusion.
• Existing cache-order, setter, carry-over and future-only leaf coverage is retained.
• Constructor regressions cover matching and mismatched scalar input years for both keyword and positional default_input_period. The new Python batch file exercises JSON/Core provenance unavailable through the YAML runner and routes once to the existing Rest remaining group. No runner, concurrency or CI-job changes are made.

Historical regression evidence from the earlier approved-head work was captured before each formula/guard fix:

Regression	Before	After
Mixed aggregate/leaf and component-year batch histories	5 failed, 5 passed at reviewed head 687ac6668d	14 passed, including the expanded constructor and generated differential cases
Worksheet B with positive Form 2555 leaves but zero stacking	2 failed, 6 passed at 687ac6668d	8 passed
Leaf identities, signed line 45, pre-worksheet MAGI and senior MAGI	5 failed, 10 passed after integrating main and before the formula fix	12 Python cases passed; the three literal regressions were moved unchanged to their existing policy YAML files and passed

The earlier main merge also exposed two stale Massachusetts property-test expectations under #9954 (2 failed, 8 passed). Correcting the independent capital-income oracle, while retaining main's model, produced 10 passing cases; a focused two-tax-unit YAML regression also verifies that capital losses do not absorb the foreign-income Part B add-back. Failure evidence is retained outside the committed source.

Validation of the conflict repair at merge commit 0aabd69:

• Housing-exclusion-only filer: failed with main’s aggregate-only predicates (CTC bar false and EITC eligible true), then passed with the shared helper (bar true and EITC eligible false). Both the refundable CTC bar and EITC denial are checked with zero earned-income exclusion.
• Leaf-only caller with no aggregates: failed for both credit checks with main’s predicates, then passed after the shared helper; allocable deductions cancel both derived aggregates without undoing the election.
• Housing-only leaves with an explicit zero stacking override, and a separate positive MAGI amount with zero stacking: both cases failed for the CTC and EITC checks before the helper, then passed afterward.
• Existing Deny the refundable CTC and the EITC to section 911 filers (26 U.S.C. 24(d)(3), 32(c)(1)(C), 6012(c)) #9750 and Add excluded foreign earnings to Massachusetts gross income #9976 coverage: 229 collected tests passed across the union of 23 files: 17 YAML and 6 Python. Each file runs separately, serially, in the foreground. No folder runs, full suites, or microsimulations run in this repair round.
• Formatting and static checks: make format, Ruff checks, and git diff --check passed.

The following table records the required single-file validation of the repaired head. All invocations passed on macOS/Python 3.13.9/Core 3.32.15. Elapsed times include fresh-process startup, model construction, and shutdown.

Test file	Passed	Elapsed (s)
integration.yaml	19	265.37
ctc_credit_limit_worksheet_b_applies.yaml	11	250.91
refundable_ctc.yaml	15	353.39
refundable_ctc_barred_by_section_911_exclusion.yaml	10	337.47
eitc_eligible.yaml	11	273.53
section_911_excluded_income.yaml	5	170.22
additional_senior_deduction_magi.yaml	6	90.22
tax_unit_is_filer.yaml	15	467.83
co_refundable_ctc.yaml	12	547.21
foreign_earned_income.yaml	28	381.81
ma_part_b_gross_income.yaml	9	461.51
nj_childless_eitc_age_eligible.yaml	8	272.90
nj_eitc.yaml	9	266.88
section_911_state_eitc.yaml	6	221.86
pr_refundable_ctc.yaml	6	345.08
afa_other_dependent_credit.yaml	15	303.55
test_afa_section_911.py	1	205.01
ctc_expansion.yaml	4	197.90
test_ctc_foreign_earned_income_exclusion.py	2	151.95
test_ctc_foreign_earned_income_exclusion_property.py	1	218.71
test_foreign_earned_income_exclusion_leaves.py	12	178.37
test_ma_foreign_earned_income_addback.py	10	322.54
test_section_911_batch_inputs.py	14	33.17

Historical approved-head validation at 72adfa3f6e88457070de2f15109309186f33c915 reported 111 collected tests passing (46 Python and 65 YAML cases), including focused Massachusetts partner signature coverage whose contract expectations were unchanged. Those results describe the earlier head and do not validate this conflict repair. The earlier Linux CI run 37618140995 used head b859c5b5ec724c5b7e84720722aeae28c114b949 and likewise does not validate the repaired head. Exact-head CI must pass before merge.

CI cost: this repair adds 14 policy YAML regressions and retains the existing Python coverage and routing. The batch file exercises JSON/Core input provenance that YAML cannot represent; the Python properties and differentials retain their independent invariants. Local per-file elapsed times include fresh interpreter/model setup and process shutdown. Peak memory was not measured in this repair. Historical Rest remaining Linux CI run 37618140995, artifact 11485104048, at b859c5b5ec724c5b7e84720722aeae28c114b949 measured 17:01.36 elapsed and 11,062,232 KiB peak RSS. Neither those historical group results nor passing local files establish combined timing or memory use at the repaired head.

Impact: the historical hub microsimulation below compared main at 8b8ae4cc12 with approved head 72adfa3f6e for 2025 and 2026, and every compared output was identical. No microsimulation has run at the repaired head; the hub will handle that validation.

Open follow-ups and HOLD:

• LR 84-40's allocable moving/travel deduction treatment still has no dedicated Massachusetts Part B outlet. Line 44 aggregates categories with different state restrictions and underlying expenses may already be represented; a generic extra deduction could double count them. This remains a separate evidence-based follow-up. LR 84-40.
• Inclusion of the housing exclusion in the Massachusetts gross add-back remains the reviewed methodology choice; broader housing-deduction treatment remains separate.
• The existing input-provenance and held-flat uprating implementation depends on private Core helpers; the Core floor is retained. Replacing those helpers requires a supported Core interface and is not a safe one-line change.
• HOLD: the signed encoder remains blocked on ingestion of the missing official §2 provision. Axiom issue 1541 retains the law, outputs and companion cases.

axiom: TheAxiomFoundation/rulespec-us#1541 queued

Partner contract files and expected outputs are unchanged by this repair. Main at 0a8c3c2c43e12bef720aba38dbb33b2acdada1fb is integrated in merge commit 0aabd69, retaining approved PR head 72adfa3f6e88457070de2f15109309186f33c915 in its history. The conflict is resolved by preserving main's Worksheet B consumer and sharing this PR's widened section 911 election detection across all five election tests. The PR is draft for this repair round. This updates the PR branch with a merge commit and a fast-forward push, without rebasing, rewriting history, or merging the PR.

Hub microsimulation impact (current head)

A real microsimulation on the default dataset, main at the merge base 0a8c3c2c43 against this PR's head 0aabd69bfb, for 2025 and 2026. The runs went one at a time under the shared heavy-job lock. Sums are weighted.

Output	2025 change	2026 change	2025 records changed (weighted)	2026 records changed (weighted)
foreign_earned_income_exclusion	+0	+0	0 (0)	0 (0)
ma_gross_income	+0	+0	0 (0)	0 (0)
ma_part_a_gross_income	+0	+0	0 (0)	0 (0)
ma_part_b_taxable_income	+0	+0	0 (0)	0 (0)
ma_income_tax	+0	+0	0 (0)	0 (0)
eitc	+0	+0	0 (0)	0 (0)
refundable_ctc	+0	+0	0 (0)	0 (0)
state_income_tax	+0	+0	0 (0)	0 (0)
income_tax	+0	+0	0 (0)	0 (0)
household_net_income	+0	+0	0 (0)	0 (0)
household_benefits	+0	+0	0 (0)	0 (0)

The zero is by construction. The default dataset has no foreign earned income or Form 2555 inputs, so no record elects section 911: the Massachusetts add-back, the refundable CTC bar and the EITC denial all leave every record unchanged. The change reaches only household calculations that enter Form 2555 amounts, and this PR's YAML and property tests cover those.

Comparison files are in fixes/9976-impact/ on the hub host.

Historical hub microsimulation impact (approved head 72adfa3f6e)

This historical real microsimulation used the default dataset, comparing main at merge base 8b8ae4cc12 against approved PR head 72adfa3f6e, for 2025 and 2026. It predates this conflict repair and does not establish its impact. Sums are weighted.

Output	2025 change	2026 change	2025 records changed (weighted)	2026 records changed (weighted)
foreign_earned_income_exclusion	+0	+0	0 (0)	0 (0)
ma_gross_income	+0	+0	0 (0)	0 (0)
ma_part_a_gross_income	+0	+0	0 (0)	0 (0)
ma_part_b_taxable_income	+0	+0	0 (0)	0 (0)
ma_income_tax	+0	+0	0 (0)	0 (0)
state_income_tax	+0	+0	0 (0)	0 (0)
income_tax	+0	+0	0 (0)	0 (0)
household_net_income	+0	+0	0 (0)	0 (0)
household_benefits	+0	+0	0 (0)	0 (0)

The zero is by construction: the default dataset carries no foreign earned income or Form 2555 inputs, so foreign_earned_income_exclusion is $0 on both sides and the Massachusetts add-back has nothing to add back. The change reaches only household calculations that enter Form 2555 amounts; the YAML and property tests in this PR cover those.

[MaxGhenis]

US + core hub merge audit, us#9976 at 0aabd69bfb851c0ddc08afc8a4f8b75c05cc6d16 (squash): Massachusetts gross income adds back excluded foreign earned income, built from Form 2555 leaf inputs.

• Ruling: Max's d1051 required separate leaf inputs for the foreign earned income and housing exclusions, with line 43 and the federal exclusion derived from them, before merging. This head does that.
• Reviews:
  • r4 APPROVED 72adfa3f6e.
  • The hub then merged main, which brought in Deny the refundable CTC and the EITC to section 911 filers (26 U.S.C. 24(d)(3), 32(c)(1)(C), 6012(c)) #9750's section 911 bar, using one shared election helper for every election test.
  • Delta review r5 APPROVES this exact head (Opus via Subfleet; static read).
  • The P3s go to a follow-up: the §6012(c) threshold amount, a duplicated leaf list, and the docstring.
• Gates checked live at merge:
  • gh pr checks exits 0;
  • the latest Pull request run at the head concluded success;
  • MERGEABLE;
  • not a draft;
  • no CHANGES_REQUESTED review;
  • the semantic-overlap guard;
  • head pinned.
• Impact: a hub microsim, merge base 0a8c3c2c43 against this head (also covering eitc and refundable_ctc), for 2025 and 2026. Every output is identical. The zero is by construction: the default dataset has no Form 2555 inputs.
• --admin: used only because a required approving review is the sole block.