Model the claim of right repayment deduction and credit (26 U.S.C. 1341) and North Carolina's rules that depend on it

changelog.d/federal-claim-of-right-1341.added.md

@@ -0,0 +1 @@
+Add the federal claim of right repayment deduction and section 1341 credit (26 U.S.C. 1341), North Carolina's bar on its claim of right deduction when federal tax is computed under section 1341(a)(5), and North Carolina's tax payment for restored income (G.S. 105-266.2).

changelog.d/nc-claim-of-right-deduction.added.md

@@ -0,0 +1 @@
+Add North Carolina's itemized deduction for repaying income received under a claim of right (G.S. 105-153.5(a)(2)d), with a new claim_of_right_repayment input.

policyengine_us/parameters/gov/household/household_refundable_credits.yaml

@@ -27,7 +27,7 @@ values:
     - mo_refundable_credits  # Missouri.
     - ms_refundable_credits  # Mississippi.
     - mt_refundable_credits  # Montana.
-    # Skip NC which has no refundable credits.
+    - nc_refundable_credits  # North Carolina.
     - nd_refundable_credits  # North Dakota.
     - ne_refundable_credits  # Nebraska.
     - nh_refundable_credits  # New Hampshire.

policyengine_us/parameters/gov/household/household_refundable_state_credits.yaml

@@ -26,7 +26,7 @@ values:
     - mo_refundable_credits  # Missouri.
     - ms_refundable_credits  # Mississippi.
     - mt_refundable_credits  # Montana.
-    # Skip NC which has no refundable credits.
+    - nc_refundable_credits  # North Carolina.
     - nd_refundable_credits  # North Dakota.
     - ne_refundable_credits  # Nebraska.
     - nh_refundable_credits  # New Hampshire.

policyengine_us/parameters/gov/household/household_tax_before_refundable_credits.yaml

@@ -29,7 +29,7 @@ values:
     - mo_income_tax_before_refundable_credits
     - ms_income_tax_before_credits_unit
     - mt_income_tax_before_refundable_credits_unit
-    - nc_income_tax  # NC has no refundable credits.
+    - nc_income_tax_before_refundable_credits
     - nd_income_tax_before_refundable_credits
     - ne_income_tax_before_refundable_credits
     - nh_income_tax_before_refundable_credits

policyengine_us/parameters/gov/irs/credits/refundable.yaml

@@ -6,6 +6,7 @@ values:
     - refundable_ctc
     - recovery_rebate_credit
     - refundable_payroll_tax_credit
+    - claim_of_right_credit
     # Currently, the premium tax credit is not included in the refundable tax credits.
   # Add CDCC in 2021.
   2021-01-01:
@@ -14,6 +15,7 @@ values:
     - refundable_ctc
     - recovery_rebate_credit
     - refundable_payroll_tax_credit
+    - claim_of_right_credit
     # Currently, the premium tax credit is not included in the refundable tax credits.
     - cdcc
   # Remove CDCC in 2022.
@@ -23,6 +25,7 @@ values:
     - refundable_ctc
     - recovery_rebate_credit
     - refundable_payroll_tax_credit
+    - claim_of_right_credit
     # Currently, the premium tax credit is not included in the refundable tax credits.
 metadata:
   unit: list

policyengine_us/parameters/gov/irs/deductions/itemized/claim_of_right/threshold.yaml

@@ -0,0 +1,16 @@
+description: The IRS computes tax for the year of repayment as the lesser of the tax with a deduction for the repayment and the tax without it less the resulting decrease in prior-year tax, when the repayment of income held under a claim of right exceeds this amount.
+values:
+  1954-01-01: 3_000
+metadata:
+  unit: currency-USD
+  period: year
+  label: Claim of right repayment threshold
+  reference:
+    - title: 26 U.S. Code § 1341(a)(3)
+      href: https://www.govinfo.gov/content/pkg/USCODE-2024-title26/html/USCODE-2024-title26-subtitleA-chap1-subchapQ-partV-sec1341.htm
+    - title: 26 U.S. Code § 67(b)(9)
+      href: https://www.law.cornell.edu/uscode/text/26/67#b_9
+    - title: 26 CFR 1.1341-1(a)(3)
+      href: https://www.ecfr.gov/current/title-26/chapter-I/subchapter-A/part-1/subject-group-ECFR4c74bc8cf7c11fb/section-1.1341-1
+    - title: "Publication 525 (2025), Repayments #page 36-37"
+      href: https://www.irs.gov/pub/irs-prior/p525--2025.pdf#page=36

policyengine_us/parameters/gov/irs/deductions/itemized_deductions.yaml

@@ -7,6 +7,7 @@ values:
     - medical_expense_deduction
     - casualty_loss_deduction
     - misc_deduction
+    - claim_of_right_deduction
   2020-01-01:
     - charitable_deduction  
     - charitable_deduction_for_non_itemizers
@@ -15,13 +16,15 @@ values:
     - medical_expense_deduction
     - casualty_loss_deduction
     - misc_deduction
+    - claim_of_right_deduction
   2022-01-01:
     - charitable_deduction
     - interest_deduction
     - salt_deduction
     - medical_expense_deduction
     - casualty_loss_deduction
     - misc_deduction
+    - claim_of_right_deduction
 metadata:
   unit: list
   label: itemized deductions

policyengine_us/parameters/gov/states/household/state_income_tax_before_refundable_credits.yaml

@@ -27,7 +27,7 @@ values:
     - mo_income_tax_before_refundable_credits
     - ms_income_tax_before_credits_unit
     - mt_income_tax_before_refundable_credits_unit
-    - nc_income_tax
+    - nc_income_tax_before_refundable_credits
     - nd_income_tax_before_refundable_credits
     - ne_income_tax_before_refundable_credits
     - nh_income_tax_before_refundable_credits

policyengine_us/parameters/gov/states/household/state_refundable_credits.yaml

@@ -26,7 +26,7 @@ values:
     - mo_refundable_credits  # Missouri.
     - ms_refundable_credits  # Mississippi.
     - mt_refundable_credits  # Montana.
-    # Skip NC which has no refundable credits.
+    - nc_refundable_credits  # North Carolina.
     - nd_refundable_credits  # North Dakota.
     - ne_refundable_credits  # Nebraska.
     - nh_refundable_credits  # New Hampshire.

policyengine_us/parameters/gov/states/mo/tax/income/deductions/federal_income_tax/ignored_credits.yaml

@@ -4,23 +4,27 @@ description: Missouri ignores the following credits in federal income tax deduct
 # Part I Line 3, and the net premium tax credit (Schedule 3 Line 9). Credits
 # claimed on Line 28 (refundable CTC) and Line 30 (recovery rebate), and the
 # 2021 refundable CDCC (Schedule 3 Line 13g), never reduce Line 22, so they
-# are added back here. The EIC is not added back: the Line 9 instructions say
+# are added back here. So is the section 1341 credit for repaid claim of right
+# income (Schedule 3 Line 13b). The EIC is not added back: the Line 9 instructions say
 # "If you have an earned income credit, you must subtract the credit from the
 # tax on your federal return."
 values:
   2018-01-01:
     - recovery_rebate_credit
     - refundable_ctc
+    - claim_of_right_credit
   # The CDCC is a refundable credit only in 2021 (ARPA); in other years it
   # already reduces income tax before refundable credits, so adding it back
   # would overstate the base.
   2021-01-01:
     - recovery_rebate_credit
     - refundable_ctc
+    - claim_of_right_credit
     - cdcc
   2022-01-01:
     - recovery_rebate_credit
     - refundable_ctc
+    - claim_of_right_credit
 metadata:
   unit: list
   label: Missouri ignored credits in federal income tax deduction

policyengine_us/parameters/gov/states/mt/tax/income/deductions/itemized/misc_deductions.yaml

@@ -6,13 +6,17 @@ description: Montana counts these sources as miscellaneous deductions.
 values:
   2021-01-01:
     - casualty_loss_deduction
+    # Form 2 itemized deductions line 18 follows federal Schedule A line 16.
+    - mt_claim_of_right_deduction
   2024-01-01: []
 
 metadata:
   unit: list
   label: Montana miscellaneous deductions 
   period: year
   reference:
+    - title: 2023 Montana Form 2 instructions, itemized deductions line 18
+      href: https://revenue.mt.gov/files/forms/Montana-Individual-Income-Tax-Return-Form-2-Instructions/2023_Montana_Individual_Income_Tax_Return_Form_2_Instructions.pdf#page=39
     - title: Montana Individual Income Tax Return (Form 2) 2024
       href: https://revenuefiles.mt.gov/files/Forms/Montana-Individual-Income-Tax-Return-Form-2-Instructions/2024_Montana_Individual_Income_Tax_Return_Form_2_Instructions.pdf#page=8
     - title: Montana Individual Income Tax Return (Form 2) 2022

policyengine_us/parameters/gov/states/nc/tax/income/credits/refundable.yaml

@@ -0,0 +1,13 @@
+description: North Carolina provides these refundable income tax credits and payments.
+values:
+  1995-01-01:
+    - nc_claim_of_right_payment
+metadata:
+  unit: list
+  period: year
+  label: North Carolina refundable income tax credits
+  reference:
+    - title: N.C. Gen. Stat. § 105-266.2
+      href: https://www.ncleg.gov/EnactedLegislation/Statutes/HTML/BySection/Chapter_105/GS_105-266.2.html
+    - title: S.L. 1997-213, Section 2 (effective for taxable years beginning on or after January 1, 1995)
+      href: https://www.ncleg.gov/EnactedLegislation/SessionLaws/HTML/1997-1998/SL1997-213.html

policyengine_us/parameters/gov/states/nc/tax/income/deductions/itemized/claim_of_right/nc_modified_income_basis.yaml

@@ -0,0 +1,13 @@
+description: North Carolina limits the claim of right repayment deduction to repayments of amounts included in adjusted gross income, as modified for North Carolina, in the earlier year, if this is true.
+values:
+  2014-01-01: false
+  2026-01-01: true
+metadata:
+  unit: bool
+  period: year
+  label: North Carolina claim of right repayment deduction uses North Carolina modified income
+  reference:
+    - title: N.C. Gen. Stat. § 105-153.5(a)(2)d
+      href: https://www.ncleg.gov/EnactedLegislation/Statutes/HTML/BySection/Chapter_105/GS_105-153.5.html
+    - title: "S.L. 2026-31, Section 1.8.(a) and (b) (effective for taxable years beginning on or after January 1, 2026) #page 5-6"
+      href: https://www.ncleg.gov/EnactedLegislation/SessionLaws/PDF/2025-2026/SL2026-31.pdf#page=5

policyengine_us/parameters/gov/states/nc/tax/income/deductions/itemized/claim_of_right/threshold.yaml

@@ -0,0 +1,16 @@
+description: North Carolina allows the whole repayment of claim of right income as an itemized deduction when the repayment exceeds this amount; smaller repayments are reduced by the federal two percent floor on miscellaneous itemized deductions.
+values:
+  2014-01-01: 3_000
+metadata:
+  unit: currency-USD
+  period: year
+  label: North Carolina claim of right repayment threshold
+  reference:
+    - title: N.C. Gen. Stat. § 105-153.5(a)(2)d
+      href: https://www.ncleg.gov/EnactedLegislation/Statutes/HTML/BySection/Chapter_105/GS_105-153.5.html
+    - title: S.L. 2016-5, Section 2.1.(a) and (d) (effective for taxable years beginning on or after January 1, 2014)
+      href: https://www.ncleg.gov/EnactedLegislation/SessionLaws/PDF/2015-2016/SL2016-5.pdf#page=4
+    - title: 2021 Form D-401 instructions, Form D-400 Schedule A line 8, Repayment of Claim of Right Worksheet
+      href: https://www.ncdor.gov/2021-d-401-individual-income-tax-instructions/open#page=20
+    - title: 2025 Form D-401 instructions, Form D-400 Schedule A line 8, Repayment of Claim of Right Worksheet
+      href: https://www.ncdor.gov/2025-d-401-individual-income-tax-instructions/open#page=20

policyengine_us/parameters/gov/states/nc/tax/income/deductions/itemized/other_sources.yaml

@@ -0,0 +1,17 @@
+description: North Carolina adds these deductions to the capped mortgage interest and property tax deduction to compute itemized deductions.
+values:
+  2021-01-01:
+    - charitable_deduction
+    - medical_expense_deduction
+    - nc_claim_of_right_deduction
+metadata:
+  unit: list
+  period: year
+  label: North Carolina itemized deductions other than mortgage interest and property taxes
+  reference:
+    - title: N.C. Gen. Stat. § 105-153.5(a)(2)
+      href: https://www.ncleg.gov/EnactedLegislation/Statutes/HTML/BySection/Chapter_105/GS_105-153.5.html
+    - title: 2021 Form D-401 instructions, Form D-400 Schedule A lines 6 through 10
+      href: https://www.ncdor.gov/2021-d-401-individual-income-tax-instructions/open#page=20
+    - title: "2025 Form D-401 instructions, Form D-400 Schedule A lines 6 through 10 #page 20-21"
+      href: https://www.ncdor.gov/2025-d-401-individual-income-tax-instructions/open#page=20

policyengine_us/parameters/gov/states/va/tax/income/deductions/itemized/reduction/applicable.yaml

@@ -7,11 +7,15 @@ values:
     - real_estate_taxes
     - casualty_loss_deduction
     - va_capped_state_and_local_sales_or_income_tax
+    # Schedule A line 16b, other itemized deductions.
+    - claim_of_right_deduction
 metadata:
   unit: list
   period: year
   label: Virginia itemized deductions reduction applicable deduction sources
   reference:
+    - title: "2025 Virginia Schedule A Itemized Deductions, line 16b and Limited Itemized Deduction Worksheet line 1 #page 1-2"
+      href: https://www.tax.virginia.gov/sites/default/files/taxforms/individual-income-tax/2025/schedule-2025.pdf#page=1
     - title: 2024 Virginia Schedule A Itemized Deductions
       href: https://www.tax.virginia.gov/sites/default/files/taxforms/individual-income-tax/2024/schedule-2024.pdf#page=2
     - title: 2023 Virginia Schedule A Itemized Deductions

policyengine_us/reforms/states/nc/cdcc/nc_cdcc_reform.py

@@ -23,41 +23,35 @@ class nc_refundable_credits(Variable):
         unit = USD
         definition_period = YEAR
         defined_for = StateCode.NC
+        # Baseline computes this via `adds`; replacing it with a
+        # formula requires clearing the inherited computation mode
+        # (the core engine rejects `formula` + `adds`/`subtracts`).
+        adds = None
+        subtracts = None
 
         def formula(tax_unit, period, parameters):
+            # Preserve the baseline refundable credits and ADD the new
+            # CDCC (see #8775). Baseline nc_income_tax subtracts
+            # nc_refundable_credits and excludes nc_use_tax, which
+            # state_use_tax already counts, so no override of it is needed.
+            baseline_credits = parameters(
+                period
+            ).gov.states.nc.tax.income.credits.refundable
+            total = add(tax_unit, period, list(baseline_credits)) + tax_unit(
+                "nc_cdcc", period
+            )
             # Stack with nc_eitc when the NC EITC contrib reform is also
             # active, so enabling both NC contrib credits sums rather than
             # overwrites.
-            total = tax_unit("nc_cdcc", period)
             variables = tax_unit.simulation.tax_benefit_system.variables
             if "nc_eitc" in variables:
                 total = total + tax_unit("nc_eitc", period)
             return total
 
-    class nc_income_tax(Variable):
-        value_type = float
-        entity = TaxUnit
-        label = "North Carolina income tax"
-        unit = USD
-        definition_period = YEAR
-        defined_for = StateCode.NC
-
-        def formula(tax_unit, period, parameters):
-            tax_before_credits = add(
-                tax_unit, period, ["nc_income_tax_before_credits", "nc_use_tax"]
-            )
-            non_refundable_credits = tax_unit("nc_non_refundable_credits", period)
-            tax_before_refundable = max_(0, tax_before_credits - non_refundable_credits)
-
-            refundable_credits = tax_unit("nc_refundable_credits", period)
-
-            return tax_before_refundable - refundable_credits
-
     class reform(Reform):
         def apply(self):
             self.update_variable(nc_cdcc)
             self.update_variable(nc_refundable_credits)
-            self.update_variable(nc_income_tax)
 
     return reform
 

policyengine_us/reforms/states/nc/eitc/nc_eitc_reform.py

@@ -23,35 +23,28 @@ class nc_refundable_credits(Variable):
         unit = USD
         definition_period = YEAR
         defined_for = StateCode.NC
+        # Baseline computes this via `adds`; replacing it with a
+        # formula requires clearing the inherited computation mode
+        # (the core engine rejects `formula` + `adds`/`subtracts`).
+        adds = None
+        subtracts = None
 
         def formula(tax_unit, period, parameters):
-            return tax_unit("nc_eitc", period)
-
-    class nc_income_tax(Variable):
-        value_type = float
-        entity = TaxUnit
-        label = "North Carolina income tax"
-        unit = USD
-        definition_period = YEAR
-        defined_for = StateCode.NC
-
-        def formula(tax_unit, period, parameters):
-            # Mirror baseline nc_income_tax, which uses
-            # nc_income_tax_before_credits and does NOT add nc_use_tax. This
-            # reform's only change is subtracting the new refundable EITC;
-            # adding use tax here would raise tax for every filer (even those
-            # with no EITC). See #8775.
-            tax_before_credits = tax_unit("nc_income_tax_before_credits", period)
-            non_refundable_credits = tax_unit("nc_non_refundable_credits", period)
-            tax_before_refundable = max_(0, tax_before_credits - non_refundable_credits)
-            refundable_credits = tax_unit("nc_refundable_credits", period)
-            return tax_before_refundable - refundable_credits
+            # Preserve the baseline refundable credits and ADD the new
+            # EITC. Baseline nc_income_tax subtracts nc_refundable_credits
+            # and excludes nc_use_tax, so no override of it is needed.
+            # See #8775.
+            baseline_credits = parameters(
+                period
+            ).gov.states.nc.tax.income.credits.refundable
+            return add(tax_unit, period, list(baseline_credits)) + tax_unit(
+                "nc_eitc", period
+            )
 
     class reform(Reform):
         def apply(self):
             self.update_variable(nc_eitc)
             self.update_variable(nc_refundable_credits)
-            self.update_variable(nc_income_tax)
 
     return reform
 

policyengine_us/tests/core/test_override_branches.py

@@ -29,7 +29,10 @@
    on the seeded sample and on random households (Hypothesis).
 3. Each comparison branch equals a fresh simulation that sets the overridden
    input before anything is calculated (a differential test of the branch
-   against the reference path).
+   against the reference path). These households repay no claim of right
+   income; with a qualifying repayment the itemizing branches also fix the
+   claim of right method, so a reference must fix it too
+   (``test_claim_of_right_section_1341_properties.py`` covers that case).
 4. The same holds when the parent has already calculated the overridden
    input, and when an earlier year was calculated first.
 5. When the branch drops what it copied, it keeps exactly the values set as

policyengine_us/tests/policy/baseline/gov/irs/credits/claim_of_right/claim_of_right_credit.yaml

@@ -0,0 +1,26 @@
+- name: Case 1, the credit is the prior-year decrease when tax is computed under section 1341(a)(5).
+  period: 2025
+  input:
+    claim_of_right_section_1341_eligible: true
+    claim_of_right_credit_applies: true
+    claim_of_right_prior_year_tax_decrease: 1_234
+  output:
+    claim_of_right_credit: 1_234
+
+- name: Case 2, no credit under section 1341(a)(4).
+  period: 2025
+  input:
+    claim_of_right_section_1341_eligible: true
+    claim_of_right_credit_applies: false
+    claim_of_right_prior_year_tax_decrease: 1_234
+  output:
+    claim_of_right_credit: 0
+
+- name: Case 3, no credit without a qualifying repayment.
+  period: 2025
+  input:
+    claim_of_right_section_1341_eligible: false
+    claim_of_right_credit_applies: true
+    claim_of_right_prior_year_tax_decrease: 1_234
+  output:
+    claim_of_right_credit: 0