Add excluded foreign earnings to Massachusetts gross income

changelog.d/foreign-earned-income-leaves.added.md

@@ -0,0 +1 @@
+Add TaxUnit leaf inputs for the section 911 earned-income and housing exclusions, allocable deductions, housing deduction, and federal tax worksheet adjustments.

changelog.d/ma-gross-income-feie-addback.fixed.md

@@ -0,0 +1,2 @@
+Add section 911 gross foreign earned income and housing exclusions to Massachusetts gross income, derived from Form 2555 leaf inputs while preserving legacy federal stacking inputs and explicit Massachusetts overrides.
+Share section 911 election detection across refundable CTC, federal and state EITC, and filing tests so housing-only and leaf-only Form 2555 filers remain recognized when aggregate amounts are zero.

changelog.d/section-911-leaf-integration.fixed.md

@@ -0,0 +1 @@
+Derive the section 911 MAGI add-back from Form 2555 leaves before worksheet deductions, recognize Form 2555 filers with zero stacking amounts for CTC Worksheet B, and reject ambiguous mixed-input tax-unit batches.

policyengine_us/data/economic_assumptions.py

@@ -26,6 +26,7 @@
     "employment_income": "calibration.gov.irs.soi.employment_income",
     "employment_income_last_year": "calibration.gov.irs.soi.employment_income",
     "energy_efficient_home_improvement_credit": DEFAULT_MICRODATA_UPRATING,
+    "foreign_earned_income_exclusion": DEFAULT_MICRODATA_UPRATING,
     "foreign_tax_credit": DEFAULT_MICRODATA_UPRATING,
     "interest_deduction": DEFAULT_MICRODATA_UPRATING,
     "long_term_capital_gains": "calibration.gov.irs.soi.long_term_capital_gains",

policyengine_us/system.py

@@ -35,6 +35,7 @@
     uprate_parameters,
 )
 from .tools.default_uprating import add_default_uprating
+from .tools.section_911 import validate_section_911_batch_inputs
 from .tools.per_capita_uprating import (
     add_per_capita_parameters_for_parameter_uprating,
     add_per_capita_uprating,
@@ -245,6 +246,10 @@ def __init__(self, *args, **kwargs):
         args, kwargs = self._prepare_spm_system(
             args, kwargs, kwargs.pop("spm", None), start_instant
         )
+        validate_section_911_batch_inputs(
+            kwargs.get("situation"),
+            kwargs.get("default_input_period") or self.default_input_period,
+        )
         super().__init__(*args, **kwargs)
 
         reform = create_structural_reforms_from_parameters(

policyengine_us/tests/policy/baseline/gov/irs/credits/ctc/refundable/ctc_credit_limit_worksheet_b_applies.yaml

@@ -20,6 +20,26 @@
   output:
     ctc_credit_limit_worksheet_b_applies: false
 
+- name: Form 2555 filer with a zero net stacking amount cannot use Worksheet B.
+  period: 2025
+  input:
+    ctc_qualifying_children: 2
+    foreign_earned_income_exclusion_amount: 1_000
+    foreign_earned_income_exclusion_allocable_deductions: 2_000
+  output:
+    foreign_earned_income_exclusion: 0
+    ctc_credit_limit_worksheet_b_applies: false
+
+- name: Housing deduction filer cannot use Worksheet B when worksheet deductions offset the stacking amount.
+  period: 2025
+  input:
+    ctc_qualifying_children: 2
+    foreign_housing_deduction: 500
+    foreign_earned_income_exclusion_disallowed_deductions: 500
+  output:
+    foreign_earned_income_exclusion: 0
+    ctc_credit_limit_worksheet_b_applies: false
+
 - name: Does not apply in 2021, when the CTC was fully refundable.
   period: 2021
   input:
@@ -61,3 +81,17 @@
     refundable_ctc_barred_by_section_911_exclusion: false
   output:
     ctc_credit_limit_worksheet_b_applies: true
+
+- name: A housing-only leaf election with zero aggregates skips Worksheet B.
+  period: 2025
+  input:
+    ctc_qualifying_children: 2
+    foreign_earned_income_exclusion_amount: 0
+    foreign_housing_exclusion: 5_000
+    foreign_earned_income_exclusion_allocable_deductions: 5_000
+  output:
+    foreign_earned_income_exclusion_amount: 0
+    foreign_earned_income_exclusion: 0
+    section_911_excluded_income: 0
+    refundable_ctc_barred_by_section_911_exclusion: true
+    ctc_credit_limit_worksheet_b_applies: false

policyengine_us/tests/policy/baseline/gov/irs/credits/ctc/refundable/refundable_ctc.yaml

@@ -189,3 +189,20 @@
     foreign_earned_income_exclusion: 30_000
   output:
     refundable_ctc: 6_000
+
+- name: Housing-only leaf election denies an otherwise positive refundable credit with zero aggregates
+  period: 2025
+  input:
+    ctc_refundable_maximum: 3_400
+    ctc: 4_400
+    ctc_phase_out: 0
+    ctc_phase_in: 10_000
+    ctc_limiting_tax_liability: 0
+    foreign_earned_income_exclusion_amount: 0
+    foreign_housing_exclusion: 5_000
+    foreign_earned_income_exclusion_allocable_deductions: 5_000
+  output:
+    foreign_earned_income_exclusion: 0
+    section_911_excluded_income: 0
+    # Without the section 911 bar, the same phase-in gives a $3,400 refund.
+    refundable_ctc: 0

policyengine_us/tests/policy/baseline/gov/irs/credits/ctc/refundable/refundable_ctc_barred_by_section_911_exclusion.yaml

@@ -47,3 +47,48 @@
     foreign_earned_income_exclusion: 30_000
   output:
     refundable_ctc_barred_by_section_911_exclusion: false
+
+# Section 911(a)(2) covers the housing exclusion even when the earned-income
+# exclusion is zero. Deductions can reduce the derived aggregates to zero
+# without undoing the Form 2555 election.
+- name: A housing-only leaf election is barred when deductions cancel both aggregates
+  period: 2025
+  input:
+    foreign_earned_income_exclusion_amount: 0
+    foreign_housing_exclusion: 5_000
+    foreign_earned_income_exclusion_allocable_deductions: 5_000
+  output:
+    foreign_earned_income_exclusion_amount: 0
+    foreign_earned_income_exclusion: 0
+    section_911_excluded_income: 0
+    refundable_ctc_barred_by_section_911_exclusion: true
+
+- name: A housing-only election is barred with an explicit zero stacking override
+  period: 2025
+  input:
+    foreign_earned_income_exclusion_amount: 0
+    foreign_housing_exclusion: 5_000
+    foreign_earned_income_exclusion: 0
+  output:
+    foreign_earned_income_exclusion_amount: 0
+    foreign_earned_income_exclusion: 0
+    refundable_ctc_barred_by_section_911_exclusion: true
+
+- name: An earned-income leaf election is barred when deductions cancel both aggregates
+  period: 2025
+  input:
+    foreign_earned_income_exclusion_amount: 5_000
+    foreign_earned_income_exclusion_allocable_deductions: 5_000
+  output:
+    foreign_earned_income_exclusion: 0
+    section_911_excluded_income: 0
+    refundable_ctc_barred_by_section_911_exclusion: true
+
+- name: A positive section 911 MAGI amount is barred with zero stacking
+  period: 2025
+  input:
+    foreign_earned_income_exclusion: 0
+    section_911_excluded_income: 5_000
+  output:
+    foreign_earned_income_exclusion: 0
+    refundable_ctc_barred_by_section_911_exclusion: true

policyengine_us/tests/policy/baseline/gov/irs/credits/earned_income/eitc_eligible.yaml

@@ -74,3 +74,63 @@
     foreign_earned_income_exclusion: 30_000
   output:
     eitc_eligible: false
+
+# Section 32(c)(1)(C) also denies the EITC for the housing exclusion under
+# section 911(a)(2), including leaf elections with zero derived aggregates.
+- name: A housing-only leaf election is ineligible when deductions cancel both aggregates.
+  period: 2025
+  input:
+    eitc_investment_income_eligible: true
+    eitc_demographic_eligible: true
+    filer_meets_eitc_identification_requirements: true
+    filing_status: JOINT
+    foreign_earned_income_exclusion_amount: 0
+    foreign_housing_exclusion: 5_000
+    foreign_earned_income_exclusion_allocable_deductions: 5_000
+  output:
+    foreign_earned_income_exclusion_amount: 0
+    foreign_earned_income_exclusion: 0
+    section_911_excluded_income: 0
+    eitc_eligible: false
+
+- name: A housing-only election is ineligible with an explicit zero stacking override.
+  period: 2025
+  input:
+    eitc_investment_income_eligible: true
+    eitc_demographic_eligible: true
+    filer_meets_eitc_identification_requirements: true
+    filing_status: JOINT
+    foreign_earned_income_exclusion_amount: 0
+    foreign_housing_exclusion: 5_000
+    foreign_earned_income_exclusion: 0
+  output:
+    foreign_earned_income_exclusion_amount: 0
+    foreign_earned_income_exclusion: 0
+    eitc_eligible: false
+
+- name: An earned-income leaf election is ineligible when deductions cancel both aggregates.
+  period: 2025
+  input:
+    eitc_investment_income_eligible: true
+    eitc_demographic_eligible: true
+    filer_meets_eitc_identification_requirements: true
+    filing_status: JOINT
+    foreign_earned_income_exclusion_amount: 5_000
+    foreign_earned_income_exclusion_allocable_deductions: 5_000
+  output:
+    foreign_earned_income_exclusion: 0
+    section_911_excluded_income: 0
+    eitc_eligible: false
+
+- name: A positive section 911 MAGI amount is ineligible with zero stacking.
+  period: 2025
+  input:
+    eitc_investment_income_eligible: true
+    eitc_demographic_eligible: true
+    filer_meets_eitc_identification_requirements: true
+    filing_status: JOINT
+    foreign_earned_income_exclusion: 0
+    section_911_excluded_income: 5_000
+  output:
+    foreign_earned_income_exclusion: 0
+    eitc_eligible: false

policyengine_us/tests/policy/baseline/gov/irs/income/taxable_income/adjusted_gross_income/section_911_excluded_income.yaml

@@ -37,3 +37,58 @@
     # Foreign Earned Income Tax Worksheet line 3: taxable income 85,400
     # (100,000 less the 14,600 standard deduction) plus line 2c, 15,000.
     taxable_income_plus_section_911_exclusion: 100_400
+
+- name: Worksheet deductions reduce stacking but not Form 2555 lines 45 and 50
+  period: 2025
+  input:
+    people:
+      person1:
+        age: 40
+        irs_gross_income: 50_000
+      person2:
+        age: 40
+        irs_gross_income: 50_000
+    tax_units:
+      tax_unit1:
+        members: [person1]
+        foreign_earned_income_exclusion_amount: 8_000
+        foreign_housing_exclusion: 2_000
+        foreign_earned_income_exclusion_allocable_deductions: 1_000
+        foreign_housing_deduction: 500
+        foreign_earned_income_exclusion_disallowed_deductions: 0
+      tax_unit2:
+        members: [person2]
+        foreign_earned_income_exclusion_amount: 8_000
+        foreign_housing_exclusion: 2_000
+        foreign_earned_income_exclusion_allocable_deductions: 1_000
+        foreign_housing_deduction: 500
+        foreign_earned_income_exclusion_disallowed_deductions: 700
+    households:
+      household1:
+        members: [person1]
+        state_code: MA
+      household2:
+        members: [person2]
+        state_code: MA
+  output:
+    # Schedule 1-A lines 2b and 2c add Form 2555 lines 45 and 50.
+    section_911_excluded_income: [9_500, 9_500]
+    # Foreign Earned Income Tax Worksheet line 2b affects stacking only.
+    foreign_earned_income_exclusion: [9_500, 8_800]
+
+- name: A negative Form 2555 line 45 remains signed before the stacking floor
+  period: 2025
+  input:
+    age: 40
+    irs_gross_income: 50_000
+    state_code: MA
+    foreign_earned_income_exclusion_amount: 1_000
+    foreign_housing_exclusion: 0
+    foreign_earned_income_exclusion_allocable_deductions: 2_000
+    foreign_housing_deduction: 0
+    foreign_earned_income_exclusion_disallowed_deductions: 0
+  output:
+    # Publication 54, How To Report Deductions, Example 4 permits line 44
+    # to exceed line 43. The zero floor belongs to worksheet line 2c.
+    section_911_excluded_income: -1_000
+    foreign_earned_income_exclusion: 0

policyengine_us/tests/policy/baseline/gov/irs/income/taxable_income/deductions/senior_deduction/additional_senior_deduction_magi.yaml

@@ -63,3 +63,28 @@
         puerto_rico_income: 10_000
   output:
     additional_senior_deduction_magi: 110_000
+
+- name: Senior MAGI adds Form 2555 lines 45 and 50 before worksheet deductions
+  period: 2025
+  input:
+    people:
+      person1:
+        age: 40
+        irs_gross_income: 50_000
+    tax_units:
+      tax_unit:
+        members: [person1]
+        adjusted_gross_income: 100_000
+        foreign_earned_income_exclusion_amount: 8_000
+        foreign_housing_exclusion: 2_000
+        foreign_earned_income_exclusion_allocable_deductions: 1_000
+        foreign_housing_deduction: 500
+        foreign_earned_income_exclusion_disallowed_deductions: 700
+    households:
+      household:
+        members: [person1]
+        state_code: MA
+  output:
+    # Schedule 1-A adds lines 45 and 50 (9,500), while the tax worksheet
+    # subtracts the 700 of related itemized deductions for stacking only.
+    additional_senior_deduction_magi: 109_500

policyengine_us/tests/policy/baseline/gov/irs/tax_unit/tax_unit_is_filer.yaml

@@ -185,3 +185,33 @@
   output:
     tax_unit_is_required_to_file: false
     tax_unit_is_filer: false
+
+- name: A housing-only leaf claimant with zero aggregates files according to tax-benefit propensity
+  period: 2025
+  input:
+    tax_unit_is_required_to_file: false
+    eligible_for_refundable_credits: false
+    would_file_if_eligible_for_refundable_credit: true
+    would_file_taxes_voluntarily: false
+    foreign_earned_income_exclusion_amount: 0
+    foreign_housing_exclusion: 5_000
+    foreign_earned_income_exclusion_allocable_deductions: 5_000
+  output:
+    foreign_earned_income_exclusion: 0
+    section_911_excluded_income: 0
+    tax_unit_is_filer: true
+
+- name: A housing-only leaf claimant with zero aggregates and no filing propensity does not file
+  period: 2025
+  input:
+    tax_unit_is_required_to_file: false
+    eligible_for_refundable_credits: false
+    would_file_if_eligible_for_refundable_credit: false
+    would_file_taxes_voluntarily: false
+    foreign_earned_income_exclusion_amount: 0
+    foreign_housing_exclusion: 5_000
+    foreign_earned_income_exclusion_allocable_deductions: 5_000
+  output:
+    foreign_earned_income_exclusion: 0
+    section_911_excluded_income: 0
+    tax_unit_is_filer: false