Apply Arizona's $1,500 member capital loss limit and allow negative household income in the property tax credit

[MaxGhenis]

Summary

Stacked on #9762. The first two commits are #9762's; this PR's change is the last two. I'll rebase onto main once #9762 merges. This fixes the two departures from Arizona's household income rules that #9762 left under "Not changed here".

1. Capital loss limit. az_property_tax_credit_agi took capital gains and losses from federal AGI: non-dependents' net gains less a capital loss limited to $3,000 per return. Arizona limits each household member's net loss to $1,500 (A.A.C. R15-2C-502(C)(3), ITR 12-1 item (7), Form 140PTC line D). The federal amounts are now replaced by each member's line D amount.
2. Negative line J. az_property_tax_credit_agi floored federal AGI less taxable Social Security at 0 before the tax-exempt interest and pensions were added, so a loss could not offset them. The 2023-2025 instructions let line J go negative and use zero only for the Schedule 1 and 2 lookup. The floor now sits at that lookup.

2025, Arizona renters aged 70 paying $5,000 rent (the YAML cases below):

Household	#9762: line J	#9762: credit	this PR: line J	this PR: credit
Single: wages $4,000, net capital loss $2,000	$2,000	$435	$2,500	$323
Single: net capital loss $1,500, Arizona public pension $3,000	$3,000	$212	$1,500	$502
Couple: wages $3,000 and a net loss of $4,000; spouse's gain $2,000	$2,000	$502	$3,500	$345
Couple: net losses of $1,500 and $2,500, public pension $1,000 ($4,000 rent)	$1,000	$502	-$2,000	$502

The credit can fall (a loss beyond $1,500 no longer lowers household income) or rise (a loss now offsets tax-exempt income).

What Arizona counts

• A.A.C. R15-2C-502(C) (LII): "For purposes of arriving at adjusted gross income for each member of the household, all of the following apply: ... 3. Income from capital gains is the net capital gains and losses for each member of the household. Net losses are limited to $1,500 for each household member."
• ITR 12-1 item (7) (page 2) nets the year's losses against the year's gains, limits a net loss to $1,500, and says a prior year's capital loss carryover cannot be used. The $1,500 maximum "is applicable to each household member" whose net result is a loss.
• Form 140PTC instructions, Part 1 line D, worded the same for 2021 through 2025 (page 4 each year): "For each member of the household, combine gains and losses from the sale or exchange of property. If the result is a gain, enter the gain. If the result is a loss, enter the amount of the loss up to a maximum of ($1,500)."
• The 2023, 2024 and 2025 instructions add a note under line J (page 5): "If the total household income from all members of the household results in a negative amount due to claiming a (loss) on line D, you may still make a claim for this credit. Enter the negative amount on Line J, column 4, and on line 10. In this case, your total household income is considered to be zero ($0) for determining the amount of your tax credit on line 11a or 11b." The 2021 and 2022 instructions have no such note. Both schedules start at $0, so the model applies the same floor in every year.

ITR 12-1 items (3) to (5) also count business, farm, rental and K-1 losses in the year they occur, so line J can be negative for reasons other than line D. The model lets any negative total through and floors only at the schedules.

Changes

• New parameter gov.states.az.tax.income.credits.property_tax.capital_loss_limit: $1,500, citing R15-2C-502(C)(3), ITR 12-1 and the 2021-2025 line D instructions.
• New Person variable az_property_tax_credit_capital_gains (line D for one member): max(capital_gains, -capital_loss_limit). The model has no capital loss carryover variable, so line D's no-carryover rule holds.
• az_property_tax_credit_agi: subtracts federal AGI's capital component (non-dependents' max(0, capital_gains) from irs_gross_income, less limited_capital_loss from loss_ald), adds non-dependents' line D amounts, and is no longer floored at 0.
• az_property_tax_credit_dependent_income: skips the capital_gains gross income source (each source was floored at 0) and adds dependents' line D amounts instead.
• az_property_tax_credit: passes max(income, 0) to the Schedule 1 and 2 scales. This floor is needed: policyengine-core's SingleAmountTaxScale.calc (3.32.12) pads the amounts with a 0 below the first threshold, so a negative income passed straight to calc returns a $0 credit. Run against Count capital gains once in Arizona property tax credit income #9762, the new credit test returns 0 instead of 502. The variable now cites ARS 43-1072(B) and the 2025 instructions, page 5.
• income_sources.yaml and the variable documentation say where line D is counted and that line J can be negative.

Dependents

Line D and R15-2C-502(C)(3) apply "for each member of the household", and #9762 already counts every member's income whether or not a dependent. So a dependent's net capital loss counts, limited to $1,500 for that dependent, as it does for the claimant and spouse. Dependents' line D amounts sit in az_property_tax_credit_dependent_income with the rest of their income, and non-dependents' in az_property_tax_credit_agi, matching who federal AGI covers. Before this PR a dependent's gain counted (floored at 0), and a dependent's loss reduced household income in full through federal limited_capital_loss, which sums capital_losses over every tax unit member. That second behavior also lowers the filer's federal AGI, a separate federal-model issue (see "Not changed here").

Tests

YAML, with Form 140PTC line comments:

• az_property_tax_credit_income.yaml: six cases. They cover a single filer with wages $4,000 and a net loss of $2,000 (line J $2,500), a couple with each spouse at -$1,500, one spouse's loss over the limit next to the other's gain, a line D loss offsetting a tax-exempt pension, a negative line J with a tax-exempt pension, and a dependent's loss.
• az_property_tax_credit_capital_gains.yaml (new): line D for a gain, a loss within, at and over the limit, 2021, and outside Arizona.
• az_property_tax_credit_agi.yaml: "Capped at zero when Social Security exceeds other income" becomes "Negative when losses leave other income below taxable Social Security" (-$1,000). Two new cases cover the federal $3,000 limit being replaced and a dependent's loss moving to dependent income.
• az_property_tax_credit.yaml: a negative household income gets the zero-income amount.

Nine of these fail on #9762's head. The tenth, each spouse at -$1,500, passes there, because the $3,000 federal limit happens to agree; it stays as a regression guard. The Arizona folders (baseline and contrib) pass: 525 cases. Code-health, parameter and property tests: 133 pass.

Invariants

test_az_property_tax_credit_income.py checks a seeded sample of 80 Arizona tax units: 27 couples, 31 with a dependent who has income, 32 members whose net gain is below -$1,500 (3 of them dependents), and 10 units whose line J is negative.

1. Differential: az_property_tax_credit_income equals an independent Form 140PTC line A + B + D + E sum over every member. Social Security is excluded and each member's line D is floored at -$1,500.
2. Counted once: adding d to a member's long-term gains changes household income by exactly the change in that member's line D, which is d while the member's net gain stays at or above -$1,500. The credit never rises.
3. Loss limit: lowering a member's gains changes household income by the change in line D, which is 0 once the member is at or below -$1,500. Every member's line D is at least -$1,500.
4. Schedule floor: the credit is unchanged when household income is replaced by max(line J, 0). A negative line J gets min($502, renter's property taxes).
5. Household income does not read capital_gains_excluded_from_taxable_income.

On #9762's head, 1 to 5 fail (the differential misses on 29 of 80 units). On this branch all pass.

Microsimulation

Default dataset (populace_us_2024.h5@populace-us-2024-spm-20260909), policyengine-core 3.32.12, one process per year. Compared per tax unit (79,729) with #9762's head (7b5013b) on the same dataset and core:

	2025	2026
az_property_tax_credit	$40,666,618 on both; no tax unit changes	$40,957,022 on both; no tax unit changes
Records whose household income changed	8, all lower; 7 now negative	8, all lower; 7 now negative
Eligible records (141) whose income changed	0	0

The data holds no net capital losses: limited_capital_loss is $0 for every tax unit in both years, and no Arizona tax unit has a negative line D. So the $1,500 member limit moves nothing in the default data. The 8 records move because the floor came off: their above-the-line deductions exceed their income other than Social Security. None is eligible for the credit, so no credit changes. Dependent income is unchanged. Peak memory was 9.0 GB (2025) and 9.2 GB (2026).

Not changed here

• Schedule 2 (lived with others) thresholds are one dollar low. The 2025 form reads "$0 - 2,500 → $502, 2,501 - 2,650 → $479, ..., 5,501 and up → $0", but amount/cohabitating.yaml starts each band at 2,500, 2,650, ..., 5,500. So income of exactly $2,500 gets $479 and $5,500 gets $0 instead of $56. The tests here avoid those edges.
• The federal model subtracts dependents' business and capital losses from the filer's AGI: loss_ald and limited_capital_loss sum every tax unit member, while irs_gross_income leaves out dependents' income.
• az_property_tax_credit_dependent_income floors each of a dependent's other income sources at 0, while R15-2C-502(C)(1)-(2) and ITR 12-1 items (3) to (5) count business, farm, rental and K-1 losses.

axiom: TheAxiomFoundation/rulespec-us#1483 queued (extended for the $1,500 member limit and negative household income)

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (909176a) to head (0450a28).
⚠️ Report is 146 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #9770   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            4         5    +1     
  Lines           76        84    +8     
  Branches         2         2           
=========================================
+ Hits            76        84    +8     

Flag	Coverage Δ
unittests	100.00% <100.00%> (ø)

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

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

Folded into #9762 (head 21cb189): merge commit c47e4ae brings this branch in, and 7d69e82 fixes this PR's r1 blocking finding (the AGI swap now removes only the capital amounts federal AGI actually holds: membership guards plus min(limited_capital_loss, loss_ald)) and adds capital gain distributions to line D. All 31 income cases and the widened property tests pass there. Axiom parity is tracked on TheAxiomFoundation/rulespec-us#1483 (companion tests K-M added). Closing as folded.