PolicyEngine / PolicyEngine/policyengine-us
SALT: simulation taxable-income ceiling makes salt_deduction diverge from the §164(b)(7) amount at low AGI
- Dominant language
- Python
- Stars
- 162
- Forks
- 212
- Avg merge
- 3d 3h
- Merged PRs (30d)
- 97
Description
**Versions:** policyengine-us 1.767.3 (source pin `49d19b239a593dbac8920ac6fd80cfe33372343a`), policyengine-core 3.30.3, Python 3.13.
**Summary:** With the default `gov.simulation.limit_itemized_deductions_to_taxable_income = true`, the `salt_deduction` output is capped at AGI minus exemptions, so at low AGI it reports less than the §164(b)(7) deduction amount. For a 2026 single filer with AGI $5,000 and $10,000 of state and local income tax, `salt` computes $10,000 and `salt_cap` $40,400, but `salt_deduction` returns **$5,000**; the §164 component amount is **$10,000** (the cap at $40,400 does not bind, and §164 contains no AGI ceiling on the deduction amount itself).
**Repro:**
```python
from policyengine_us import Simulation
sim = Simulation(situation={
"people": {"p": {"age": {"2026": 40}}},
"tax_units": {"t": {"members": ["p"], "adjusted_gross_income": {"2026": 5_000},
"state_and_local_sales_or_income_tax": {"2026": 10_000}}},
"households": {"h": {"members": ["p"]}},
})
print(sim.calculate("salt", 2026), sim.calculate("salt_cap", 2026), sim.calculate("salt_deduction", 2026))
# [10000.] [40400.] [5000.]
```
**Code path:** `variables/gov/irs/income/taxable_income/deductions/itemizing/salt_deduction.py` applies `min_(salt, agi - exemptions)` when `parameters/gov/simulation/limit_itemized_deductions_to_taxable_income.yaml` is true (the default).
If the ceiling is an intentional whole-return modeling choice, consider scoping it out of the component variable (or documenting the divergence): downstream consumers reading `salt_deduction` as the §164 amount observe a value the statute does not produce. Found via Axiom Foundation cross-engine validation (`us-salt-deduction-grid`, case `salt-low-agi-engine-cap`).
Contributor guide
Research direction
Start with variables/gov/irs/income/taxable_income/deductions/itemizing/salt_deduction.py and parameters/gov/simulation/limit_itemized_deductions_to_taxable_income.yaml. Run the supplied low-AGI simulation to reproduce the divergence, then trace how the ceiling is used. Done means the component output either matches the §164(b)(7) amount or its intentional divergence is documented, with the reproduction covered by a regression check.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- backend
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 66/100