PolicyEngine / PolicyEngine/policyengine-us

Formalize spouse-level income ownership for joint filers in state tax logic

Open
#7,993 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Python
Stars
162
Forks
212
Avg merge
3d 3h
Merged PRs (30d)
97

Description

## Context

Several open mismatch reports point to a broader modeling gap around who owns income within a joint return, especially when states optimize or compare separate-vs-joint filing paths.

Relevant symptoms:
- policyengine-taxsim#665: microsimulation runner and situation mapper disagree on spouse allocation for investment income
- policyengine-taxsim#669: pension / Social Security ownership matters when spouses differ by age
- policyengine-us#7931: Delaware Filing Status 4 nonrefundable credits must be allocated per spouse, not pooled
- policyengine-us#7292: DC married separate-combined deduction allocation not optimized
- policyengine-us#6961: Mississippi separate-combined filing splits exemptions 50/50 instead of allocating optimally
- policyengine-us#7869: Delaware joint AGI floors per-person before summing

## Why this matters

For many state calculations, total tax does not just depend on total unit income. It depends on which spouse owns:
- interest/dividends/gains
- pension and Social Security income
- pass-through income and losses
- credits and deductions with spouse-level eligibility or phaseouts

Right now the model and comparison stack appear to rely on a patchwork of implicit assumptions (all-to-primary, 50/50 split, or state-specific logic), which makes one-off fixes brittle.

## Proposed work

- Document a shared convention for spouse-level income ownership on joint returns.
- Distinguish between:
- actual spouse-owned income when the input/source provides ownership
- fallback split assumptions when ownership is unavailable
- optimization logic used only for separate-combined filing comparisons
- Centralize the allocation helper(s) used by state tax logic and comparison layers.
- Audit states where spouse ownership changes filing status, taxable income, or credit treatment.
- Add cross-state regression coverage for representative cases (for example DE, DC, PA, MS, and age-asymmetric pension / Social Security scenarios).

## Desired outcome

A single, explicit contract for spouse income ownership that downstream state logic and taxsim comparison code can rely on, instead of state-by-state ad hoc fixes.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.