Add structural federal mortgage interest deduction

[MaxGhenis]

Summary

• add structural federal MID inputs for mortgage balances, interest amounts, and origination years
• compute deductible and non-deductible mortgage interest at the tax-unit level using pre-TCJA grandfathering and filing-status caps
• allocate deductible and non-deductible mortgage interest back to filers and add focused federal baseline tests

Testing

• uv run ruff format --check policyengine_us/variables/household/expense/person/deductible_mortgage_interest.py policyengine_us/variables/household/expense/person/non_deductible_mortgage_interest.py policyengine_us/variables/household/expense/person/home_mortgage_interest_share.py policyengine_us/variables/household/expense/tax_unit/mortgage_interest_structure.py
• uv run ruff check policyengine_us/variables/household/expense/person/deductible_mortgage_interest.py policyengine_us/variables/household/expense/person/non_deductible_mortgage_interest.py policyengine_us/variables/household/expense/person/home_mortgage_interest_share.py policyengine_us/variables/household/expense/tax_unit/mortgage_interest_structure.py
• uv run python -m py_compile policyengine_us/variables/household/expense/person/deductible_mortgage_interest.py policyengine_us/variables/household/expense/person/non_deductible_mortgage_interest.py policyengine_us/variables/household/expense/person/home_mortgage_interest_share.py policyengine_us/variables/household/expense/tax_unit/mortgage_interest_structure.py
• uv run python -m policyengine_core.scripts.policyengine_command test policyengine_us/tests/policy/baseline/gov/irs/income/taxable_income/deductions/deductible_mortgage_interest.yaml -c policyengine_us
• uv run python -m policyengine_core.scripts.policyengine_command test policyengine_us/tests/policy/baseline/gov/states/ms/tax/income/deductions/itemized/integration.yaml policyengine_us/tests/policy/baseline/gov/states/nc/tax/income/deductions/nc_itemized_deductions.yaml policyengine_us/tests/policy/baseline/gov/territories/pr/tax/income/taxable_income/deductions/pr_mortgage_deduction.yaml -c policyengine_us

Related

• Paired with Add structural mortgage interest data support policyengine-us-data#633
• This is the model-side PR that turns the new structural mortgage inputs in us-data into actual MID reform behavior.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (941b142) to head (e3ff221).
⚠️ Report is 132 commits behind head on main.

Additional details and impacted files

@@             Coverage Diff              @@
##             main     #7875       +/-   ##
============================================
+ Coverage   71.46%   100.00%   +28.53%     
============================================
  Files        4099         4     -4095     
  Lines       59132       146    -58986     
  Branches      288         0      -288     
============================================
- Hits        42257       146    -42111     
+ Misses      16869         0    -16869     
+ Partials        6         0        -6     

Flag	Coverage Δ
unittests	100.00% <100.00%> (+28.53%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 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]

Reviewed and approved. The MID math checks out against §163(h)(3)(F) for multiple scenarios (grandfathered, post-TCJA, mixed-vintage, MFS half-caps).

Original code written by Codex; Claude Code reviewed, verified the statutory logic, and pushed minor improvements:

• Added clarifying comments to _mortgage_balance_cap (sentinel year=0 behavior) and _limited_mortgage_balance (explaining the mathematical equivalence to the statutory formula)
• Added an edge case test for when no structural mortgage inputs are provided
• Confirmed Hawaii reference removal from cap.yaml is safe (no state code references that parameter)