Exclude input dependents from tax unit head and spouse inference

[MaxGhenis]

Summary

is_tax_unit_head picks the oldest non-child in the tax unit, and is_tax_unit_spouse picks the next oldest adult. Neither reads an input is_tax_unit_dependent. So a person the caller explicitly marks as a dependent can become the filer or the filer's spouse:

• An elderly parent marked as a dependent becomes the head. The real head becomes the spouse, and the real spouse ends up as neither.
• An adult child marked as a dependent becomes a single parent's spouse, and the return files JOINT.

This PR makes head and spouse inference skip people input as tax-unit dependents. The fallback: if a tax unit has no adult who isn't an input dependent, every adult stays a candidate, exactly as before. Without dependent inputs, the rule is unchanged.

Changed expectations (CI found these at 9b2c416)

Two existing tests had an 18-year-old input dependent whom main inferred as the filer's spouse, so the unit filed jointly. With this fix the parent files alone as head of household:

• ma/dta/tcap/tafdc/integration.yaml Case 2: the dependent care deduction is no longer halved for a joint filer. Countable earned income is 7,600 × 50% − 528 = 3,272 for the year, times 6/12 after the full disregard, so 1,636 (was 1,768). TAFDC is 6,439 (was 6,307).
• contrib/congress/afa/afa_other_dependent_credit.yaml: the head-of-household higher threshold is 300,000, not the joint 400,000. The "without limited phase-out" case now uses 290,000 of wages to keep its intent. The "fully phased out" case's phase-out is ceil(150,000 / 1,000) × 50 = 7,500.

Reproduction

Period 2015, AR. People: head 40, spouse 40, parent 70 with is_tax_unit_dependent: true. All three are in one tax unit, with explicit marital units and no role inputs.

	is_tax_unit_head	is_tax_unit_spouse	age_head	filing_status
main (ca1805c)	[F, F, T]	[T, F, F]	70	JOINT
this PR	[T, F, F]	[F, T, F]	40	JOINT

Households shaped exactly like the web app's payloads (2026, TX, primary earner $50,000), federal income_tax:

Household	main	this PR
Single 40 + "dependent" aged 19	dependent is spouse, JOINT, $1,280	HEAD_OF_HOUSEHOLD, $2,248
Married 40/40 + "dependent" aged 70	70-year-old is head, $515	couple is head/spouse, $1,280

Who this reaches

Findings below come from code read on each repo's origin/main for this PR.

• Web app (policyengine-app-v2 @ 0c41dbf8). Household.addChild sets is_tax_unit_dependent: {year: true} on every US dependent (app/src/models/Household.ts:1105-1117). No runtime code sets is_tax_unit_head or is_tax_unit_spouse. Age is an editable basic input for every person, and HouseholdValidation.ts only checks that it is present. The v1 API (policyengine-api @ aac95d3b) adds None placeholders for formula variables, so the roles stay computed, and then builds Simulation(situation=household) (policyengine_api/country.py:542). Result: any app user who gives a "dependent" an age of 18 or over hits this bug. Default households (children aged 10) are unaffected.
• policyengine.py (6.1.1 @ 4dc59596). calculate_household passes caller dicts through verbatim and never adds role variables (src/policyengine/tax_benefit_models/us/household.py:99-131). Callers who flag an adult dependent are affected. This includes the docstring pattern (head flagged, dependent flagged, spouse not flagged), where an older dependent becomes the spouse. It pins policyengine-us 2.2.1, which has the same formulas.
• policyengine-household-api (@ cbc588a0). Passes situations through without touching roles (libs/household-api/policyengine_household_api/country.py:885-911).
• Partner contract fixtures (tests/policy/baseline/partners/). Unchanged. Across 143 files and 620 cases, 26 adults are input as dependents. Every case containing one also inputs is_tax_unit_head and is_tax_unit_spouse, so neither formula runs for them.
• Microsimulation. Unchanged with DEFAULT_DATASET. The pinned populace_us_2024.h5 (sha256 6496cc43…, matching DEFAULT_DATASET_SHA256) has no is_tax_unit_* column in any table. Its person table carries tax_unit_role_input instead, and that is not a policyengine-us variable on main. With no stored dependent input, the helper returns the same ~is_child mask as before.

Prior reports: #9132 worked around this in the childless EITC age test ("an older adult dependent is itself classified as the unit 'head'"). #9612 lists it as a pre-existing issue.

Design

is_tax_unit_dependent's formula is ~is_tax_unit_head & ~is_tax_unit_spouse. So head and spouse can't call person("is_tax_unit_dependent", period): when the flag isn't input, that call raises CycleError (head → dependent → head).

The new helper head_or_spouse_candidates (_head_or_spouse_candidates.py) reads the stored value with person.simulation.get_array("is_tax_unit_dependent", period). That core call is branch-aware and never runs a formula (policyengine_core/simulations/simulation.py:1233-1241).

• No stored value: candidates are ~is_child, as before.
• Stored input: candidates are adults not flagged. A unit with no such adult keeps all its adults.
• Stored value that the formula computed: this can only exist after head and spouse were computed for the period. It flags exactly the people who are neither, so excluding them leaves the ranking unchanged. test_computed_dependents_do_not_change_roles covers this.
• Scope is the exact period. Core never carries a formula variable's input into other periods, so a 2015 dependent input doesn't affect 2016 inference.

Invariants

These hold for every input and are checked in tests/core/test_tax_unit_role_inference.py. That file enumerates every tax unit of up to three people drawn from ages {10, 18, 40, 70} × dependent input {true, false}: 584 units, including age ties and the age-18 boundary.

1. Reference agreement. Head and spouse equal a pure-Python reference of the rule: rank candidates by age, oldest first, with ties going to the earlier person. Candidates are adults not input as dependents, or all adults if there are none.
2. Differential vs. the previous rule. With no dependent inputs, or with only false inputs, roles are identical to the previous oldest-adult rule.
3. Structure.
   • Exactly one head when the unit has an adult, and none otherwise.
   • At most one spouse.
   • Head and spouse are disjoint, and both are adults.
   • An input dependent is never head or spouse while the unit has an adult who isn't one.
4. Inputs are kept. is_tax_unit_dependent returns its input unchanged.
5. No cycle, order-independent. Computing is_tax_unit_dependent before head and spouse works, and gives the same roles when head and spouse are recomputed.
6. Branches. A dependent input set only in a branch is honoured in that branch, and not in the parent.

The invariant test fails on main in checks 1, 3 and 6, and 5 of the 9 new YAML cases fail on main. The rest are controls that pass on both.

Tests

• New YAML cases in household/demographic/tax_unit/is_tax_unit_head.yaml and is_tax_unit_spouse.yaml:
  • Elderly dependent parent with a couple (the 2015 AR reproduction).
  • Single filer with a dependent parent (HEAD_OF_HOUSEHOLD).
  • Single parent with a dependent 20-year-old student (no spouse, HEAD_OF_HOUSEHOLD).
  • Head input plus an elderly dependent (the policyengine.py docstring pattern).
  • Dependents of several ages.
  • Controls: no dependent inputs, explicit false inputs, a lone adult input as a dependent, and every adult input as a dependent.
• Local runs: pending (household and IRS shards, tests/core); results to follow in a comment.

Overlap with #9617

#9617 (dataset-supplied tax_unit_role_input) edits the same lines. The two compose: its age fallback (oldest_adult / next_oldest_adult) should rank head_or_spouse_candidates(person, period) instead of ~is_child. Whichever PR merges second takes that one-line change per formula.

axiom: n/a: household role inference (which input person is the filer), not a legal provision

🤖 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 (191a8ae).
⚠️ Report is 51 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##              main     #9630   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            4         3    -1     
  Lines           76        36   -40     
  Branches         2         1    -1     
=========================================
- Hits            76        36   -40     

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]

Merged by the US + core hub on its merge gates. Audit:

• Head: 17dbd8cd6fd968aefd933d3a46c3c96db883d7d4.
• Independent review (Opus 5.5, files in ~/reviews/us-hub/reviews-gen/us-9630/):
  • r1b approved 9b2c41605b, the PR plus a main merge, with no P1 or P2.
  • Methodology: r1b flagged a methodology choice without naming one. An independent adjudication (adjudication.md) ruled MAX_CALL: no. The legal touchpoints (IRC §152(b)(1), §152(d)(2)(H) and §152(b)(2)) have one defensible reading each, and the rest are prior-behavior conventions.
  • CI fix and r2: CI at 9b2c41605b failed two existing tests. Each had an 18-year-old input dependent whom main inferred as the filer's spouse, so the unit filed jointly. The hub's commit 17dbd8cd6f changes expectations only, in two YAML files:
    • MA TAFDC countable earned income is 1,636 (was 1,768), and TAFDC is 6,439.
    • The AFA head-of-household threshold of 300,000 applies. The phase-out is 7,500, and case 1's wages are lowered to 290,000 to keep its intent.
  • r2 approved that delta. It re-derived each number from 106 CMR 704.281 and 704.275 and from the AFA bill (p. 5, "$300,000, in any other case").
• CI: every check passed at this head. The full suite runs all roughly 150 test files with adult input dependents.
• Impact: the default microsimulation has no stored is_tax_unit_dependent, so its output is unchanged. Households that input adult dependents now get the correct head and spouse.
• Overlap: Honor dataset-supplied tax-unit roles #9617 edits the same two formulas. If it merges after this, it should rank head_or_spouse_candidates(...) in place of ~is_child.