Support state-specific other additions and subtractions for CA, NY, DE, and CO (Phase 1 pilot)

[jindal-git]

Description

This PR implements Phase 1 (Pilot States) of #10197, introducing standardized state-level <state>_other_additions and <state>_other_subtractions input variables for California, New York, Delaware, and Colorado.

Resolves part of #10197.

Changes Included

1. California (CA):
   • Added ca_other_additions (TaxUnit, default 0.0) and wired into ca_additions.
   • Added ca_other_subtractions (TaxUnit, default 0.0) and added to California AGI subtractions parameter list.
2. New York (NY):
   • Added ny_other_additions (TaxUnit, default 0.0) and converted ny_additions to compute adds = ["ny_other_additions"].
   • Added ny_other_subtractions (TaxUnit, default 0.0) and added to New York AGI subtractions sources parameter list.
3. Delaware (DE):
   • Added de_other_additions (Person, default 0.0) and converted de_additions to compute adds = ["de_other_additions"].
   • Added de_other_subtractions (Person, default 0.0) and added to Delaware AGI subtractions parameter list.
4. Colorado (CO):
   • Added co_other_additions (TaxUnit, default 0.0) and added to Colorado taxable income additions parameter list.
   • Added co_other_subtractions (TaxUnit, default 0.0) and added to Colorado taxable income subtractions parameter list.
5. Testing:
   • Added variable-named YAML unit tests for all 8 new variables verifying zero default behavior and correct positive/negative adjustment effects.
   • Verified that all existing state integration tests (39 tests) and partner contract tests (e.g., my_friend_ben CO tests) pass with zero baseline regression.
   • Verified program registry with test_programs_registry.py.

axiom: n/a: unmodeled user-input adjustment variables

[hua7450]

Thanks. The wiring is right:

• Every new input is in each dated block of its list and reaches state AGI or taxable income.
• The entities fit each return.
• Setting ny_additions or de_additions directly still works.

Keeping these as empty inputs is fine for now. What needs fixing is the documentation: six of the eight docstrings point to the wrong line. In NY and CO, following them double-counts amounts the model already computes. Please replace documentation and reference in each file with the following.

ny_other_additions.py (PolicyEngine models no New York additions, so lines 20 to 22 need this input too)

    documentation = "New York additions to federal adjusted gross income not otherwise modeled (Form IT-201 lines 20 through 23), entered as a positive amount. PolicyEngine models no New York additions, so this covers interest on other states' bonds (line 20), 414(h) contributions (line 21), New York 529 nonqualified withdrawals (line 22) and Form IT-225 additions (line 23), including alimony received under agreements executed after 2018."
    # PDF pages 7-8
    reference = "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf#page=7"

ny_other_subtractions.py (line 30 is the 529 deduction, which is already modeled)

    documentation = "New York subtractions from federal adjusted gross income not otherwise modeled (Form IT-201 line 31, from Form IT-225 line 18), entered as a positive amount. Do not include lines 25 through 30, which PolicyEngine computes. Alimony paid under agreements executed after 2018 and the disability income exclusion (IT-225 code S-124) are not yet modeled and can be entered here."
    reference = "https://www.tax.ny.gov/pdf/2025/inc/it201i_2025.pdf#page=10"

ca_other_additions.py (Section B line 8 covers only other income)

    documentation = "California additions to federal adjusted gross income not otherwise modeled, entered as a positive amount: Schedule CA (540), Part I, column C amounts in Sections A and B, and column B amounts in Section C (federal adjustments California disallows). Do not include the HSA and educator expense additions, which PolicyEngine computes. Interest on other states' bonds and alimony received under agreements executed from 2019 through 2025 are not yet modeled and can be entered here."
    reference = "https://www.ftb.ca.gov/forms/2025/2025-540-ca-instructions.html"

ca_other_subtractions.py (Section B has no line 22; Section C line 22 is reserved)

    documentation = "California subtractions from federal adjusted gross income not otherwise modeled, entered as a positive amount: Schedule CA (540), Part I, column B amounts in Sections A and B, and column C amounts in Section C (adjustments California allows beyond federal law). Do not include subtractions PolicyEngine computes, such as taxable Social Security, unemployment compensation, U.S. obligation interest and state income tax refunds. Alimony paid under agreements executed from 2019 through 2025 (Section C line 19a, column C) is not yet modeled and can be entered here."
    reference = "https://www.ftb.ca.gov/forms/2025/2025-540-ca-instructions.html"

de_other_additions.py (the current URL returns 404, and Form 200-01/200-02 is the old form)

    documentation = "Delaware additions to federal adjusted gross income not otherwise modeled (Form PIT-RES lines 2 and 3), entered as a positive amount: interest on other states' obligations, fiduciary adjustments and oil depletion. PolicyEngine models no Delaware additions."
    reference = "https://revenuefiles.delaware.gov/2025/PITForms_Instructions/Instructions/PIT-RES_Instructions_2025-01.pdf#page=5"

de_other_subtractions.py (line 15 is the charitable mileage deduction)

    documentation = "Delaware subtractions from federal adjusted gross income not otherwise modeled (Form PIT-RES lines 7 and 8), entered as a positive amount. Do not include U.S. obligation interest, the pension exclusion, the Delaware tax refund, taxable Social Security, 529 contributions or 2021 unemployment compensation, which PolicyEngine computes. ABLE contributions (line 8b) are not yet modeled and can be entered here."
    # PDF pages 6-7
    reference = "https://revenuefiles.delaware.gov/2025/PITForms_Instructions/Instructions/PIT-RES_Instructions_2025-01.pdf#page=6"

co_other_additions.py (line 2 is the state income tax addback, which is already modeled)

    documentation = "Colorado additions to federal taxable income not otherwise modeled (Form DR 0104 lines 5 through 7 and Other Additions, line 9 in 2025 and line 8 in 2024), entered as a positive amount: the business meals addback, the CollegeInvest and ABLE non-qualifying distribution addbacks, and other additions such as interest on non-Colorado state and local bonds. Do not include the state income tax, QBI or federal deduction addbacks, or from 2026 the overtime deduction addback, which PolicyEngine computes."
    reference = (
        # PDF pages 9-10
        "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf#page=9",
        "https://tax.colorado.gov/sites/tax/files/documents/DR0104_book_2024.pdf#page=10",
    )

co_other_subtractions.py (line 4 is the federal deduction addback, and the DR 0104AD total includes modeled subtractions)

    documentation = "Colorado subtractions from federal taxable income not otherwise modeled (Schedule DR 0104AD, such as Other Subtractions on line 20 in 2025 and line 23 in 2024), entered as a positive amount. Do not include the state income tax refund, U.S. government interest, Social Security, pension and annuity, military retirement, CollegeInvest, ABLE or charitable contribution subtractions, which PolicyEngine computes."
    reference = (
        "https://tax.colorado.gov/sites/tax/files/documents/Book104_2025.pdf#page=23",
        "https://tax.colorado.gov/sites/tax/files/documents/DR0104_book_2024.pdf#page=23",
    )

Tests

• Rename cases to Case 1, … in all eight files, and head to person1 in the two DE files.
• In de_other_subtractions.yaml case 2, add de_pre_exclusions_agi: 48_000.
• Cover the other dated blocks: add a 2021 case to de_other_subtractions.yaml, 2021 and 2026 cases to co_other_additions.yaml, and a 2021 case to co_other_subtractions.yaml.

[jindal-git]

Thanks for the thorough review, @hua7450! We've pushed an update addressing all points:

Tests

• Case naming: Renamed test cases to Case 1, … across all 8 YAML test files.
• DE entity naming: Renamed head to person1 in both de_other_additions.yaml and de_other_subtractions.yaml.
• Pre-exclusions AGI verification: Added de_pre_exclusions_agi: 48_000 in de_other_subtractions.yaml Case 2 (and 50_000 in Case 1).
• Dated parameter coverage: Added a 2021 case to de_other_subtractions.yaml, 2021 and 2026 cases to co_other_additions.yaml, and a 2021 case to co_other_subtractions.yaml.

Documentation and Form References

We updated the references and URLs to the latest official 2025/2024 forms across all 8 variables.

For the docstrings, we opted for a narrow scope tied directly to the dedicated "Other" lines on each state form (e.g., CA Schedule CA Line 8z Column C/B; NY IT-201 Line 23 / IT-225 Line 9 and Line 31 / IT-225 Line 18; DE PIT-RES Lines 3 and 7; CO DR 0104 Line 9/8 and DR 0104AD Line 20/23).

Rationale: Several state forms have specific, individually labeled lines (e.g., non-Colorado state bond interest, business meal addbacks, out-of-state bond interest in CA, ABLE contributions, etc.). Because these specific lines may be modeled as distinct first-class variables in PolicyEngine in future additions/subtractions PRs, defining <state>_other_additions/<state>_other_subtractions to represent those specific lines could cause double-counting or user confusion once they are modeled. Keeping the <state>_other_* variables strictly 1:1 with the residual "Other" lines maintains exact form line fidelity and preserves clean runway for future line item modeling.

[hua7450]

Thanks, the narrow scope works, and the tests look good.

One fix: PIT-RES line 7 also includes the Delaware state tax refund ("If some or all of your Delaware state tax refund was included in federal adjusted gross income, include the amount on line 7", 2025 instructions). For 2021 it also includes unemployment compensation. PolicyEngine already subtracts both through salt_refund_income and taxable_unemployment_compensation in the same list, so a user who enters the full line 7 amount gets them subtracted twice. For example, a $300 refund plus a $500 fiduciary adjustment gives $1,100 of subtractions instead of $800.

Please add the exclusion to de_other_subtractions:

    documentation = (
        "Delaware subtractions from federal adjusted gross income reported on "
        "Form PIT-RES, line 7 (fiduciary adjustments, wages disallowed federally "
        "because of the work opportunity credit, and Delaware NOL carryovers), "
        "entered as a positive amount. Do not include the Delaware state tax "
        "refund or, for 2021, unemployment compensation, which PolicyEngine "
        "subtracts separately."
    )

Also, the branch is 98 commits behind main. Please run git pull upstream main and push, so CI runs on current main. I'll approve once CI passes.

[jindal-git]

@hua7450 Added the requested exclusion warning to de_other_subtractions and merged upstream main into the branch. All YAML policy tests and partner contract tests pass cleanly. Thanks!

[hua7450]

Thanks. The Delaware exclusion is in and CI passes after the main merge. Approving.