Repository navigation
Build omitted household marital units from explicit couples and the tax-role fallback - #10000
Conversation
|
@hua7450 — a question about this draft. #9868 still reproduces on main (4c65c82, 2.72.3): with enhanced CPS 1.78.2, which supplies marital units but no Keeping the inferred spouse inside the head's marital unit, as this PR does, would fix it. The branch is from before #9617 (merged 2026-10-08) and needs the draft policyengine-core#600. Could you rebase it onto main, or split out the spouse restriction so it can land without the Core change? We will not open a parallel PR. 🤖 Posted by Claude Code |
|
Thanks, splitting makes sense. The spouse restriction doesn't need Core's provenance on its own: when a situation omits marital_units, Core puts everyone in one marital unit, so limiting the inferred spouse to the head's marital unit changes nothing there. It only takes effect when membership is supplied, as in enhanced CPS. I'll open a separate PR from main with just that check in the is_tax_unit_spouse fallback, alongside #9617's supplied-role branch, plus YAML cases for #9868. This PR stays a draft for filling in missing marital units, which does need policyengine-core#600. I'll merge main into it after the split lands. |
…into preserve-marital-unit-inputs # Conflicts: # policyengine_us/system.py # policyengine_us/variables/household/demographic/tax_unit/is_tax_unit_spouse.py # pyproject.toml # uv.lock
PolicyEngine/policyengine-core#600 now includes Core's main (3.34.0) and delegates the hook through reforms, so main's policyengine-us imports against it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When marital units are omitted, pair the two adults of a tax unit whose family has an explicit is_married input, so role-less couples marked married keep SSI couple treatment (DC OSSP Cases 2 and 5). Source-input snapshots now record which groups the caller supplied, so a reloaded simulation keeps inferred marital units as inferred and its tax spouse. Count NumPy and numeric true inputs, pair role inputs with overlapping periods, and leave malformed input to Core's validation. Move the new SSI cases to the end of their file, document the rules after the page introduction, and regenerate uv.lock with uv 0.13.4. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
When nothing marks a couple, the marital-unit hook now pairs the head and spouse that is_tax_unit_head and is_tax_unit_spouse infer from age order, reading the same inputs and dependent age limits, after explicit role inputs, a complete tax_unit_role_input and a married family. Couples sent without marriage information keep SSI and Medicaid couple treatment, and a parent's adult child who meets the qualifying child age test stays out. Drop the supplied-membership provenance (policyengine-core PR 600 no longer records it), the snapshot provenance fields, the spouse gate that PolicyEngine#10555 replaced and the git pin on Core, which becomes a released minimum once Core ships the hook. Replace the SSI cases with helper tests and two end-to-end YAML cases. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…it-inputs # Conflicts: # policyengine_us/system.py # policyengine_us/tests/policy/baseline/gov/ssa/ssi/ssi_claim_is_joint.yaml # policyengine_us/tests/policy/baseline/household/demographic/tax_unit/is_tax_unit_spouse.yaml
The tax-role comments and docs said a situation that omits marital units puts everyone in one unit. The hook now builds those units by the same rules as the role fallback, so say so. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PavelMakarchuk
left a comment
There was a problem hiding this comment.
Verdict: REQUEST_CHANGES. The pairing rules match the tax-role formulas when the builder's default period equals the input year, but through Simulation(situation=...) with inputs dated in any other year, step 4 drops real couples and changes SSI and SNAP. Two CI checks also fail because of this PR's own tests.
I reviewed head 389f95cf90 with policyengine-core at the head of PolicyEngine/policyengine-core#600 (f37aef5). I did not review PolicyEngine/policyengine-core#600 or #10850.
Critical
1. Step 4 un-pairs real couples when the default period is not an input year
_fallback_years (policyengine_us/tools/marital_units.py:356-368) always adds the builder's default period to the years it checks. Simulation passes default_input_period, which is CURRENT_YEAR = 2024 (policyengine_us/system.py:71, :341). The Household API builds with country_package.Simulation(situation=...) and no default period, so it gets 2024 too.
A payload dated 2026 has no 2024 inputs, and _value_in_year does not carry a later value back. So in 2024 every person, children included, has the default age 40, and the "couple" for 2024 is the first two people listed in the tax unit. If that differs from the 2026 couple, _tax_fallback_pair (:384-400) sees two different pairs and pairs no one. The tax roles still pair the couple in 2026, so the marital units and the roles disagree, which is the thing step 4 exists to prevent.
The result depends on the order of people. A couple is kept only if the two spouses are the first two members listed.
Reproduction, 2026, Texas, no marital_units, all inputs dated "2026", Simulation(situation=...):
| Household (listing order) | Main | This PR |
|---|---|---|
| Grandchild 10, husband 70, wife 68, $6,000 Social Security each | One marital unit; joint SSI claim; SSI $3,066 each; SNAP $4,803; net income $25,356.60 | Three single units; ssi_claim_is_joint false; SSI $6,168 each; SNAP $2,943; net income $29,700.60; filing_status still JOINT |
| Adult 40, child 8, adult 38 | One marital unit | Three single units; filing_status still JOINT |
| Same couple and child listed adult, adult, child | One marital unit | {adult, adult}, {child}, as intended |
This is the same symptom the PR body gives as the reason for adding step 4 (an aged couple's SSI doubling), now for any couple not listed first.
Scale: over 3,000 random households (1-5 people, inputs dated 2026), the hook returned a different result with default period 2024 than with 2026 in 893, and each of those lost a couple. In 150 random simulations, the marital couples disagreed with the calculated head and spouse in 48 with the default period at 2024, and in 0 with it at 2026. So the rules themselves are right; the extra year is the fault.
The tests miss it because _fallback_pairs passes "2024" with undated ages (policyengine_us/tests/microsimulation/test_marital_unit_inputs.py:239), the Simulation tests date inputs "2024", and the YAML runner sets the default period to the test period.
Suggested fix: add the default-period year only when some step-4 input is undated or when no input is dated at all. Please add a Simulation(situation=...) test with inputs dated in a year other than 2024 and the couple not listed first (child first, and child between the spouses).
2. Two CI checks fail on tests this PR adds
Run 43277363125, started about 1:13pm EST on 2026-11-12. Both failures come from this PR; neither test exists on main.
- "Baseline tests / Full Suite - Baseline (household)":
policyengine_us/tests/policy/baseline/household/demographic/tax_unit/is_tax_unit_spouse.yaml, case "With marital units omitted, a parent's 18-year-old is a dependent rather than the spouse."is_tax_unit_spouseis[0, 1], expected[0, 0]. - "Quick Feedback (Selective Tests + Coverage)": the same YAML case, plus
test_marital_unit_inputs.py::test_household_construction_does_not_mutate_input_and_expands_axes([0, 0, 0, 1, 1, 1] == [0, 0, 1, 2, 2, 3]). It is a test failure, not the coverage gate.
Cause: CI installs released policyengine-core 3.34.10, which has no preprocess_situation hook, so the override in policyengine_us/system.py:118 never runs. The PR body says this. With Core at the PolicyEngine/policyengine-core#600 head, both pass. The PR cannot merge until Core releases the hook and this PR raises the policyengine-core floor in pyproject.toml and regenerates uv.lock (now >=3.33.1, lock at 3.34.2). Without the floor, an install with an older Core silently keeps the old one-unit behavior while the docs and comments changed here say otherwise.
"Python tests / Full Suite - Microsimulation" was still pending when I checked.
Should address
3. Payloads that computed on main now raise ValueError
The hook raises at policyengine_us/tools/marital_units.py:32, :253, :265 and :302. These three situations return filing_status JOINT on main and raise at this head:
- two true
is_tax_unit_headinputs plus a trueis_tax_unit_spousein one tax unit; - a family
is_marriedinput that changes between years ({2026: true, 2027: false}); - an
is_tax_unit_spouseinput that changes between years.
For a Household API caller that is a failed request in place of a result. Either fall back to single units in these cases, or list the new errors in the PR body and changelog so partners know.
4. Missing tests for claimed behavior
- A household with two tax units, each with a couple (the "at most one couple in each tax unit and household" claim). I ran it and it gives two couples and a single child, but no test holds it.
- Two couples in one tax unit: only the older couple is paired and the younger couple become two single units while on main they shared a unit. No test, and the PR body's limitations do not name it.
- Non-string person ids.
{1, 2, 3}works (I ran it), with no test. - A false
is_tax_unit_spouseinput. Withis_tax_unit_spouse: falseon two adults, the roles give no spouse, but step 4 still puts them in one marital unit, so the units do not agree with the roles as the docs claim (docs/usage/microsimulation.md, "the units it builds agree with the inferred tax roles"). Results equal main for this household (main also has one unit), so it is not a regression, but step 4 should respect an explicit false, or the docs should say it does not.
Suggestions
- The new
ssi_claim_is_joint.yamlcase passes on main and on released Core without the hook (everyone in one unit also gives a joint claim), so it does not test this PR. A version with a child listed first would, and would have caught finding 1. - A married couple who file separately in two tax units get two single marital units even when their family has
is_married: true, because every step works inside one tax unit. On main they shared a unit. Worth a line under "Known limitations". _is_minorand_ADULT_AGE = 18copy theis_childthreshold. A comment pointing atis_childexists; a test that fails if the two drift would be safer.
What I verified
- Hook contract. Core calls the hook only in
build_from_entities, on a deep copy, beforeaxesis popped; aReformdelegates to its baseline. Dataset and variable-only builds do not reach it. The dataset test in this PR passes and keeps IDs[0, 17, 42, 42, 99, 99]through year extension. - No circular dependency. Step 4 reads raw situation inputs and
gov.irs.dependent.ineligible_agefrom the system's parameters; it calculates no variable. I compared it line by line withis_tax_unit_head,is_tax_unit_spouseandhead_or_spouse_candidates: oldest non-dependent adult, then the next-oldest who fails the age test, no spouse with a separated member. With the default period equal to the input year, 150 of 150 random households agree with the calculated roles. - Invariants. In 3,000 random households every person is in exactly one unit, every unit has 1 or 2 members, and no one under 18 is in a couple. The caller's dict is not mutated. Order is deterministic (insertion order; age ties go to the first listed).
- Situations run through the hook and a simulation (2026). Single adult: one unit. Explicit head and spouse: paired. Couple plus two children: couple paired, children single. Two adults 30 and 28 with no information: paired, as on main (documented limitation). Second adult input as dependent: not paired.
filing_status: SINGLEinput: still paired (documented). Two adults in two tax units: not paired. Completetax_unit_role_input: HEAD and SPOUSE paired, DEPENDENT single. Partialtax_unit_role_input: single units, then the existing role error. Familyis_marriedtrue: its two adults paired; false: not paired. Parent 45 with child 18: not paired; with child 19: paired (documented). Parent 50 with student 22: not paired. Two under-18s: not paired. Suppliedmarital_units(partial or{}): untouched; Core gives unlisted people their own unit.marital_units: null: treated as omitted.axes: units replicate per axis point. Onlypeople, no other groups: works. - What changes for existing callers. Main put everyone in one marital unit. Mother 45 earning $20,000 with son 18: JOINT to HEAD_OF_HOUSEHOLD, EITC $521.71 to $4,427, net income $19,282.71 to $23,188. Parent 70 with a permanently and totally disabled child 40: JOINT to HEAD_OF_HOUSEHOLD, no dollar change in the variables I checked. Aged couple 70 and 68 listed first: no change (joint SSI, $3,066 each). Couple 40 and 38 with child 8 listed last: units change, no change in
filing_status,eitc,income_tax,ssi,snap,medicaidorhousehold_net_income. - Partner contract tests. The PR edits none. All 623 cases under
policyengine_us/tests/policy/baseline/partnerspass at this head with the Core hook active. Seven cases (amplifi, impactica, my_friend_ben) omitmarital_units; each has one adult, so they go from one shared unit to single units with no asserted value changing, and the result is the same with default period 2024. Finding 1 does not show in them because none has a couple. The "Household API Partners" check passes in CI, but there the hook does not run. - PR tests.
test_marital_unit_inputs.py: 26 passed. The YAML tests underhousehold/demographic/tax_unitandgov/ssa/ssi: 451 passed. Both with the Core hook. - Repo rules. Changelog fragment
changelog.d/preserve-marital-unit-inputs.fixed.mdis top level. Theaxiom: n/a: ...line is present. No# pragma: no cover. - Mergeability.
git merge-tree --write-tree origin/main HEADis clean against181c697bfd.
Not verified: the full test suites beyond those named, the pending microsimulation check, Medicaid medically needy values from the PR body's table, and behavior under a reform that changes the dependent age limits.
Check only the years the inputs are dated for, so a payload dated for a year other than Simulation's default input year keeps its couple wherever it is listed, and read a person's first input for earlier years. Give everyone in a tax unit and household their own unit, instead of raising, when inputs can't settle one static couple. Respect false head and spouse inputs in the role fallback. Use the reform's dependent age limits. Add tests for dated payloads, two couples, integer ids, false role inputs and the adult age, list the grandchild first in the SSI couple case, add a parent and disabled adult child who aren't a joint claim, and give the four people in the home equity Case 21 separate marital units. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Raise the policyengine-core floor to 3.35.0, the first release with TaxBenefitSystem.preprocess_situation, and regenerate uv.lock with CI's uv 0.13.4. Without the floor, an older Core would skip the hook and keep one marital unit. Document that marital units follow the years the inputs are dated for, so a calculation for another year can give roles the units don't match, and pin the undated case with a test. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…tal unit The first CI run with the hook active showed that it split couples whose filing status says they are married, and that six existing tests depended on Core putting everyone in one marital unit. - A JOINT filing_status input skips step 4's qualifying child age test, since only a married couple files jointly (26 USC 6013(a)). - The two separate filers of a household are paired, since only married people file separately (26 USC 1(d)); filers in different households stay apart because a marital unit is a married, co-habiting couple. - Step 4 reads an is_child input, as head_or_spouse_candidates does. - HUD case sends its couple's marital unit; the role-inference reference applies the age test; the Arkansas property test puts its two filers in one household; three Montana elderly credit cases count the individual SSI that the single default unit hid. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PavelMakarchuk
left a comment
There was a problem hiding this comment.
Verdict: REQUEST_CHANGES. The three open items from the last review are resolved, and CI is green with the hook active. The new filing-status logic has one case that gives a wrong value, and most of its documented rules have no test.
I re-reviewed head dd5b94b0ba with policyengine-core 3.36.0 (the version in uv.lock, and the version CI installed) and again with 3.35.0 (the new floor).
Resolved since the last review
| # | Round-3 item | Status |
|---|---|---|
| 1 | CI fails, and the Core floor is not raised | Resolved. pyproject.toml:26 requires policyengine-core>=3.35.0, and uv.lock has 3.36.0. Run 43446431924 (9:49am to 11:10am EST on 2026-11-13) passes all 39 checks that ran (the documentation deploy is skipped, as on every pull request). The job logs show + policyengine-core==3.36.0 on Python 3.14.10, so CI ran with the hook. |
| 2 | California "deducts a dependent child's premiums" case fails with the hook | Resolved. #10855 merged at 8:35am EST on 2026-11-13 and is in this branch. All 52 cases of medicaid_optional_senior_or_disabled_countable_income.yaml pass with the hook, and the case gives [23,880, 23,880, 0]. |
| 3 | A role input dated for a year other than the calculation year splits the couple | Resolved as requested. The limitation is in docs/usage/microsimulation.md:76-81 and in the docstring (policyengine_us/tools/marital_units.py:171-173), and test_undated_role_inputs_set_units_for_the_default_input_year pins the undated row. The four witness rows give the same values as before, as expected. |
Critical
1. A filing status that changes between years removes every couple in the tax unit, including explicit ones
_filing_status raises _Ambiguous when a tax unit has more than one status across periods (policyengine_us/tools/marital_units.py:252-254). _infer_units evaluates it inside the try that wraps _group_pair (:214-227), so the exception also cancels steps 1 to 3, which do not read the filing status at all. Only the JOINT age-test skip depends on the status.
Husband 70, wife 68, $6,000 Social Security each, Texas, one tax unit, no marital_units, inputs dated 2026, calculated for 2026:
filing_status input |
Other inputs | main |
Previous head 4500aee8f8 |
This head |
|---|---|---|---|---|
{2025: JOINT, 2026: SEPARATE} |
is_tax_unit_head: true on the husband, is_tax_unit_spouse: true on the wife |
One unit; joint claim; SSI $3,066 each; SNAP $1,914 | Couple shares a unit | Own units; no joint claim; SSI $6,168 each; SNAP $291; is_tax_unit_spouse still true for the wife |
{2025: JOINT, 2026: SEPARATE} |
tax_unit_role_input HEAD and SPOUSE, or a family with is_married: true, or none |
Same as above | Couple shares a unit | Own units |
{2025: SINGLE, 2026: HEAD_OF_HOUSEHOLD} |
None | Joint claim; SSI $3,066 each; SNAP $1,914 | Couple shares a unit | Own units; SSI $6,168 each; SNAP $291; is_tax_unit_spouse still true |
{2025: SINGLE, 2026: SINGLE} or {2025: JOINT, 2026: JOINT} |
None | Joint claim; SSI $3,066 each | Couple shares a unit | Same as main |
Three points:
JOINTandSEPARATEare both statuses of married people, by the two citations this PR adds (26 USC 6013(a) and 1(d)). A change from one to the other says the couple is still married, but the hook reads it as "no couple".- The docs give the rule as "inputs that can't settle one static couple" (
docs/usage/microsimulation.md:57-61). Constant head and spouse inputs do settle one couple, and the status change does not unsettle it. - The result is twice the individual SSI rate for a couple that the tax roles still treat as head and spouse.
A small fix: read a status that changes between periods as no status. Then joint is false, the age test applies, and steps 1 to 3 run as before. I checked this change locally: all seven households above pair again, and all 46 tests in test_marital_unit_inputs.py still pass, including the {"2024": "JOINT", "2025": "SINGLE"} case at :390 (the age test alone already keeps that 20-year-old student unpaired). So that case does not test the changing-status rule today. Please add a case that does, such as the first row above.
Should address
2. Most rules of the separate-filer pairing have no test
test_the_two_separate_filers_of_a_household_pair (policyengine_us/tests/microsimulation/test_marital_unit_inputs.py:415) covers two filers, three filers, and two households. I removed each of the rules below from _separate_filer_pairs (policyengine_us/tools/marital_units.py:258-303) in turn, and all 46 tests still passed each time:
| Rule in the docs or docstring | Where | Test fails when removed? |
|---|---|---|
| No pair when either filer is separated | :297-300, docs/usage/microsimulation.md:41 |
No |
No pair when a shared family has is_married: false |
:300, docs/usage/microsimulation.md:42 |
No |
A SEPARATE unit with no clear filer blocks the pairing in its household |
:294, docstring :264-266 |
No |
The filer is the one true is_tax_unit_head input |
:276-278, :287 |
No |
| An adult input as a dependent is not the filer | :283-285 |
No |
| A separate-filer pair does not replace a step-4 couple | :233 |
No |
An is_child input decides who is a minor in steps 3 and the separate-filer rule (_is_minor) |
:54-58 |
No |
The code does what the docs say in the cases I ran by hand (see "What I checked"). Please add one case for each documented rule, at least for the first three rows, which are in the user docs.
Suggestions
SINGLE,HEAD_OF_HOUSEHOLDandSURVIVING_SPOUSEinputs. The hook now readsJOINTas "married", but it does not read these three as "unmarried". Two adults 70 and 68 in one tax unit withfiling_status: SINGLE(or either of the other two) still share a unit, with a joint SSI claim and $3,066 each. This is the same asmain, so it is not a regression. A line under the known limitations would make the asymmetry clear.- Docs for the filer rule.
docs/usage/microsimulation.md:38-43says "their two filers" but does not say who the filer is (the one trueis_tax_unit_headinput, or the only adult not input as a dependent), or that a unit with no clear filer blocks the pair. The docstring has both. - The separate-filer pair has no age or relation test. A 66-year-old and a 24-year-old, each in their own
SEPARATEtax unit, with a third tax unit in the household, become a couple. The 66-year-old's SSI goes from $3,168 onmain(three people in one unit, no couple) to $2,022 (spousal deeming). A parent and an adult child who each file separately from an absent spouse get this result. It follows the documented rule (exactly two tax units whosefiling_statusinput isSEPARATE), so I do not rate it as a defect. Either apply the step-4 age test to the pair, or name the case under the known limitations.
What I checked
-
The hook runs. With Core 3.35.0 and 3.36.0, husband 70, wife 68 and grandchild 10 get units
{husband, wife},{grandchild}. With Core 3.34.10 all three share one unit. -
JOINT(2026, Texas). One adult and a child 10: no couple. Three adults 70, 68 and 66: the two oldest pair, and SSI is $3,066, $3,066 and $6,168, as onmain. Mother 45 and son 18, a 22-year-old and a 20-year-old college student, and a 70-year-old with a permanently and totally disabled 60-year-old: each pair shares a unit and equalsmain. Without theJOINTinput the same three households get their own units (the intended change). Parents 45 and 44 with a student 20 and a child: the parents pair. AJOINTinput dated 2025 or undated, with ages dated 2026: the same couple. TwoJOINTtax units: one couple in each. With axes (3 copies): one couple in each copy. -
JOINTagainst other inputs. A falseis_tax_unit_spouseon the second adult, a completetax_unit_role_inputwith no spouse, an input dependent, a separated member, or a family withis_married: false: no couple, as documented. A true spouse input on the youngest of three adults: that person pairs with the head. An explicitmarital_unitsmapping stands as supplied. -
SEPARATE. TwoSEPARATEunits with one aged filer each in one household: one unit, joint claim, SSI $3,066 each, as onmain. The same with a child in the first unit: the filers pair (SSI $3,066 each; onmainthe three shared one unit, with no joint claim and $6,168 each). ThreeSEPARATEunits,SEPARATEwithSINGLE, two households, a separated filer, or a family withis_married: false: no pair.SEPARATEstatuses dated 2025: the pair stands in 2026. A minor in their ownSEPARATEunit is not paired. With axes: one pair in each copy. One tax unit with two adults andSEPARATE: step 4 pairs them, as onmain. -
Agreement with the tax roles. In every
JOINTandSEPARATEhousehold above, the units match the calculatedis_tax_unit_headandis_tax_unit_spouse(for two separate filers, each is the head of their own unit and no one is a spouse), except the documented cases and item 1. -
Fuzz with filing status. 1,000 random households (1 to 5 people, one to three tax units, random role, dependent, separated, student, disability and
is_childinputs dated 2026; 791 with afiling_statusinput, 338 withJOINT, 328 withSEPARATE, 35 with a status that changes between years; 63 with two households). No errors. Calculated for 2026, 46 have a couple that differs from the calculated head and spouse: 26 are a tax unit that spans two households, 7 are a lone true spouse input, 2 are a dependent also marked head or spouse (all three documented), and 11 are a status that changes between years (item 1). None comes from theJOINTorSEPARATErule with a constant status. Againstmain, 25 households differ in SSI (9), SNAP (9) orfiling_status(15). All 25 follow from documented rules: an adult child who meets the age test is no longer the spouse (17), two people in two tax units with noSEPARATEpair are no longer a couple (4), two separate filers beside a third person now pair (2), a lone true spouse input pairs with the next adult (1), and anis_childinput (1). -
Edited existing tests. Since the previous head the PR edits five existing test files:
File Edit Expected values hud_annual_income.yamlAdds explicit marital_unitsfor a head 30 and a student spouse 20Unchanged test_ar_medical_expense_deduction_properties.pyPuts the two filers in one household Unchanged test_tax_unit_role_inference.pyThe reference rule now skips a spouse who meets the qualifying child age test Changed, and right: it is the rule of 26 USC 152(c)(3) that is_tax_unit_spousealready applies onmainto people in their own unitsmt_elderly_homeowner_or_renter_credit.yaml(3 cases)None to inputs Changed, and right: two siblings in two tax units are not an SSI couple. Individual SSI is $943 × 12 − ($10,000 − $240) = $1,556, and Montana counts SSI payments in gross household income (MCA 15-30-2337(9)(a); Schedule 2EC instructions). The credits $382.20, $22.20 and $332.20 follow. test_marital_unit_inputs.pyNew cases only Not applicable is_medicaid_long_term_care_home_equity_eligible.yaml(explicitmarital_units: {}, values unchanged) was already in the previous head. -
Partner contract tests. The PR edits no file under
policyengine_us/tests/policy/baseline/partners. All 623 cases pass with the hook, and the Household API Partners job passes in CI. -
Tests with Core 3.36.0, at the PR head. The three Python test files: 96 passed. The five changed YAML files: 122 passed.
gov/hhs/medicaid: 1,228 passed.gov/usda/snap: 1,255 passed. Partners: 623 passed.household: 819 passed.gov/irs: 3,137 passed.gov/ssa/ssi,gov/ssa/ssandgov/ssa/social_security: 397 passed.gov/ssa/oasdiand four of the eight files ingov/ssa/revenue: 43 passed. No failure in any of these runs. -
Tests with Core 3.35.0.
test_marital_unit_inputs.py: 46 passed. -
The PR merged into current
main(5cc0d58afa, 13 commits ahead of the merge base). The merge is clean. With Core 3.36.0: the three Python test files, 96 passed; the five changed YAML files, 122 passed; the 23 YAML test filesmainchanged since the merge base, 506 passed;gov/ssa/ssi, 336 passed. Partners: 623 passed. -
CI. All 39 checks that ran pass at
dd5b94b0ba, including the four baseline state shards, the household, IRS and SSA/USDA shards, the contrib shards, the microsimulation job and the partner job. No failure to classify. -
Repo rules. The changelog fragment is updated for the filing-status rule. The
axiom:line is present.
Not verified
- I ran the tests on Python 3.13. CI uses 3.14.
- I did not run the baseline
gov/statestree, the contrib tests or the dataset microsimulation tests locally. CI ran all of them at this head with Core 3.36.0, and they pass. - On the merge with current
mainI ran only the files listed above, not the full suite. - I stopped the local
gov/ssa/revenuerun before the fourtob_*files finished. CI's SSA/USDA shard ran them and passes. - I did not check the coverage report for
marital_units.py. - The filing-status witnesses and the fuzz use Texas and 2026 only.
…ler rule
A filing_status input that changed between periods raised the ambiguity
exception inside the same try as steps 1 to 3, so it cancelled explicit
head and spouse inputs too: an aged couple with {2025: JOINT, 2026:
SEPARATE} lost their joint SSI claim. A changing status now counts as no
status, leaving the steps that don't read it to settle the couple.
Each separate-filer rule now has a test that fails when the rule is
removed: a separated filer, a family with is_married false, a return with
no clear filer, a head input naming the filer, an input dependent or child
not being the filer, and a filer already in a couple. The docs say who the
filer is and add two limitations: the separate-filer pairing reads no age
or relationship, and SINGLE, HEAD_OF_HOUSEHOLD and SURVIVING_SPOUSE inputs
aren't read as unmarried.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…into preserve-marital-unit-inputs
PavelMakarchuk
left a comment
There was a problem hiding this comment.
Verdict: REQUEST_CHANGES. The critical item and the test item from the last review are resolved, all three suggestions are taken, and CI is green with the hook active. One small item is open: no test fixes how a changing filing status is read, because the case that did was removed in this commit.
I re-reviewed head f177b22378 with policyengine-core 3.36.0 (the version in uv.lock, the newest release, and the version CI installed), and ran the PR's own test file again with 3.35.0 (the floor).
Resolved since the last review
| # | Round-4 item | Status |
|---|---|---|
| 1 | Critical: a filing status that changes between years removes every couple in the tax unit | Resolved as suggested. _filing_status returns no status when the input changes (policyengine_us/tools/marital_units.py:246-259). All seven witness households pair again and equal main (table below). test_a_changing_filing_status_counts_as_no_status pins it: with the old raise _Ambiguous restored, both of its cases fail (2 failed, 53 passed). |
| 2 | Should address: seven rules of the separate-filer pairing and _is_minor have no test |
Resolved. test_the_separate_filer_rules (seven cases) and test_a_married_family_skips_a_person_input_as_a_child cover them. I removed each rule in turn, and a test now fails every time (table below). |
| S1 | Suggestion: SINGLE, HEAD_OF_HOUSEHOLD and SURVIVING_SPOUSE inputs |
Taken. Known limitation at docs/usage/microsimulation.md:81-84 and in the PR body. |
| S2 | Suggestion: docs for who the filer is | Taken. docs/usage/microsimulation.md:43-45 gives the filer rule and the blocking rule. |
| S3 | Suggestion: the separate-filer pair has no age or relation test | Taken as a known limitation (docs/usage/microsimulation.md:78-80 and the PR body). No age test was added, so the behaviour is the same: a 66-year-old with $6,000 Social Security and a 24-year-old with $15,000 wages, each in a SEPARATE tax unit beside a third tax unit, become a couple, and the 66-year-old's SSI is $5,022 against $6,168 on main. Real separate filers still pair: 70 and 68 give a joint claim and $3,066 each, as on main; 45 and 43 with a child in the first unit pair. |
Item 1 witness: husband 70, wife 68, $6,000 Social Security each, Texas, one tax unit, no marital_units, inputs dated 2026, calculated for 2026.
filing_status input |
Other inputs | main |
Previous head dd5b94b0ba |
This head |
|---|---|---|---|---|
{2025: JOINT, 2026: SEPARATE} |
is_tax_unit_head: true on the husband, is_tax_unit_spouse: true on the wife |
One unit; joint claim; SSI $3,066 each; SNAP $1,914 | Own units; SSI $6,168 each; SNAP $291 | Same as main |
{2025: JOINT, 2026: SEPARATE} |
tax_unit_role_input HEAD and SPOUSE |
Same | Own units | Same as main |
{2025: JOINT, 2026: SEPARATE} |
A family with is_married: true |
Same | Own units | Same as main |
{2025: JOINT, 2026: SEPARATE} |
None | Same | Own units | Same as main |
{2025: SINGLE, 2026: HEAD_OF_HOUSEHOLD} |
None | Same | Own units; SSI $6,168 each | Same as main |
{2025: SINGLE, 2026: SINGLE} |
None | Same | Same as main |
Same as main |
{2025: JOINT, 2026: JOINT} |
None | Same | Same as main |
Same as main |
Item 2: each rule removed from a copy of marital_units.py, then test_marital_unit_inputs.py run (55 tests at the head).
| Rule | Result with the rule removed |
|---|---|
| No pair when either filer is separated | 1 failed |
No pair when a shared family has is_married: false |
1 failed |
A SEPARATE unit with no clear filer blocks the pairing |
1 failed |
The filer is the one true is_tax_unit_head input |
1 failed |
| An adult input as a dependent is not the filer | 1 failed |
| A separate-filer pair does not replace a couple from the earlier steps | 1 failed |
An is_child input decides who is a minor (_is_minor) |
2 failed |
(also) JOINT skips the age test |
1 failed |
| (also) Separate filers must share a household; three separate filers pair no one | 1 failed each |
Should address
1. No test fixes how a changing filing status is read
The rule is in the docs (docs/usage/microsimulation.md:47-48) and the docstring (policyengine_us/tools/marital_units.py:168-169, :249-251): "A filing_status input that changes between periods counts as no status." The rule has two effects on the result: a JOINT in one year does not skip the age test, and a SEPARATE in one year does not count toward the separate-filer pairing. No test reaches either effect.
test_a_changing_filing_status_counts_as_no_status (policyengine_us/tests/microsimulation/test_marital_unit_inputs.py:422-443) has two cases. The first pairs through explicit head and spouse inputs, which never read the status. The second uses SINGLE and HEAD_OF_HOUSEHOLD, which the hook reads the same as no status. So both cases pass under any reading of the changing status. I changed _filing_status in three ways, and all 55 tests passed each time:
Change to _filing_status |
Tests |
|---|---|
A changing status with JOINT in any year reads as JOINT |
55 passed |
A changing status with SEPARATE in any year reads as SEPARATE |
55 passed |
| A changing status reads as its last value | 55 passed |
The case that did fix the first effect was ({"2024": "JOINT", "2025": "SINGLE"}, []) in test_a_joint_return_pairs_a_spouse_the_age_test_would_not, and this commit removes it (:383-390). That is on me: in the last review I said this case did not test the rule. That was true for the old rule, where the status raised. With the new rule it is the case that tells "no status" from "JOINT wins".
The values these two effects control (Texas, inputs dated 2026, calculated for 2026):
| Household | main |
This head | If the changing status counted |
|---|---|---|---|
Head 22 with $20,000 wages, college student 20, one tax unit, filing_status {2025: SINGLE, 2026: JOINT} |
One unit; the student is the spouse; income tax $0 | Own units; no spouse; income tax −$4,427 | One unit, as on main and as with a constant JOINT (income tax $0) |
70 and 68, $6,000 Social Security each, two tax units in one household, SEPARATE and {2025: SEPARATE, 2026: SINGLE} |
One unit; joint claim; SSI $3,066 each; SNAP $1,914 | Own units; SSI $6,168 each; SNAP $291 | One unit, as on main |
Both results on this head follow the documented rule, so I do not ask for a code change. Please add the two cases:
- Put
({"2024": "JOINT", "2025": "SINGLE"}, [])back (head 22, college student 20): no couple. - In the separate-filer tests, two filers in one household where one status is
SEPARATEand the other is{"2024": "SEPARATE", "2025": "SINGLE"}: no couple.
I ran both households against the head and against the first two changes above: the head gives no couple in each, and each change gives a couple in one of them. So the two cases fail when the rule changes.
Suggestions
- A lone spouse input on a dependent.
docs/usage/microsimulation.md:62-66says "a dependent also marked head or spouse" gives everyone their own unit. That holds when the tax unit has both a head and a spouse input (step 1). With only a spouse input, on a person also input as a dependent, step 4 pairs them with the oldest other adult. Example: a 66-year-old, and a 70-year-old withis_tax_unit_spouse: trueandis_tax_unit_dependent: true, share a unit; addis_tax_unit_head: trueon the 66-year-old and each gets their own unit. This code did not change in this commit, and the units agree with the calculated roles. One more clause in the docs would make it exact. - A status that is
JOINTin the calculation year but not in another year. The first row of the table in item 1 is the documented result, and it is the same as a household with no status. A reader may still expect the calculation year'sJOINTto pair the two. A line under the known limitations (a filing status dated for more than one year must be constant to count) would help.
What I checked
-
The hook runs. With Core 3.36.0, husband 70, wife 68 and grandchild 10 get units
{husband, wife},{grandchild}at the head. Onmainwith Core 3.36.0, and at the head with Core 3.34.10, all three share one unit. -
Side effects of "a changing status counts as no status" (Texas, 2026):
- Head 22 and college student 20, one tax unit.
{2025: JOINT, 2026: SINGLE},{2025: SINGLE, 2026: JOINT},{2025: JOINT, 2026: SEPARATE}and{2025: JOINT, 2026: JOINT, 2027: SINGLE}: own units in each, the same as with no status. A constantJOINT: one unit, equal tomain. - A status for one of several years. Ages dated 2025 and 2026 with
JOINTdated only 2026, or only 2025, or{2025: null, 2026: JOINT}: the status counts asJOINT, the couple shares a unit, and all values equalmain. - Monthly keys.
{"2026-01": JOINT}andJOINTin all 12 months count asJOINT.JOINTfor January to June withSEPARATEfor July to December counts as no status; the aged couple then pairs through step 4, equal tomain. TwoSEPARATEunits dated"2026-01"pair, equal tomain. No errors. - Two tax units where one status changes. An aged couple with
{2025: JOINT, 2026: SEPARATE}beside aJOINTcouple 45 and 44: both couples pair, and SSI, SNAP and income tax equalmain. A student pair with a changing status beside a student pair with a constantJOINT: only the second pairs. The change in one tax unit does not reach the other. - Two separate filers where one status changes (second row of the table in item 1): no pair, the same as two tax units with no status, which is a listed limitation. Three tax units, two with a constant
SEPARATEand one with{2025: SEPARATE, 2026: SINGLE}: the two constant filers pair (SSI $3,066 each; onmainthe three share one unit, with $6,168 each).
- Head 22 and college student 20, one tax unit.
-
The diff since
dd5b94b0ba. I read every line._filing_statusand the removedtry/exceptin_separate_filer_pairsare consistent: nothing raises_Ambiguousfrom a status now. The docs, the docstring and the PR body match the code, except the two suggestions above. Thepyproject.tomlanduv.lockversion lines come from themainmerge. -
Fuzz with filing status. 1,000 random households (1 to 5 people, one to three tax units, random role, dependent, separated, student, disability and
is_childinputs dated 2026; 792 with afiling_statusinput, 328 withJOINT, 322 withSEPARATE, 40 with a status that changes between years; 75 with two households), at the head and onmain. No errors. Calculated for 2026, 35 have a couple that differs from the calculated head and spouse: 23 are a tax unit that spans two households and 12 are a lone true spouse input (both documented). None comes from a changing status; there were 11 of those at the previous head. Againstmain, 32 households differ in SSI (24), SNAP (18) orfiling_status(7). 31 follow from documented rules: a younger adult who meets the age or disability test is no longer the spouse (11), two people in two tax units with noSEPARATEpair are no longer a couple (15), aSEPARATEunit whose only adult is input as a dependent has no filer (1), two separate filers beside a third person now pair (1), and a lone true spouse input pairs with another adult (3). The last one is the lone spouse input on a dependent from the first suggestion: a 70-year-old with true spouse and dependent inputs shares a unit with the 66-year-old head, apart from three other adults, and each gets SSI of $3,066 (onmain, $9,168 and $3,168 with all five in one unit). -
A second fuzz for changing statuses. 400 more households with the same generator, 209 with a status that changes between years. No errors. 11 have a couple that differs from the calculated head and spouse, and all 11 are a tax unit that spans two households. 5 differ from
mainin SSI, SNAP orfiling_status: the age or disability test (4) and two people in two tax units (1). None comes from the changing-status rule. -
ACA tax family code from #10041.
is_aca_filerreads the calculated head, spouse and filing status, so it follows the hook's units. Eleven households withclaimable_as_dependent_on_another_returninputs and nomarital_units(Texas, 2026): in each one the ACA filers are the people the hook pairs, or the head alone when the hook pairs no one. A couple 30 and 28 with either spouse claimable, a couple 40 and 38 with a child and one or both spouses claimable, and a couple with an adult dependent:is_aca_tax_family_member,aca_tax_family_size,aca_magiandaca_ptcequalmain. Three households differ frommain, all through the age test (the intended change): a parent 45 and son 18 are no longer joint filers (family size 2, not 1; credit $7,766, not $7,007), and so are a 22-year-old with a claimable college student 20, and a couple 19 and 18. With aJOINTinput the last two equalmain. -
Tests with Core 3.36.0, at the PR head. No failure in any run.
Run Result The PR's three Python test files ( test_marital_unit_inputs.py,test_tax_unit_role_inference.py,test_ar_medical_expense_deduction_properties.py)105 passed The five YAML files the PR changes 122 passed policy/baseline/household819 passed policy/baseline/gov/ssa/ssi336 passed policy/baseline/gov/hhs/medicaid1,262 passed policy/baseline/gov/usda/snap1,282 passed policy/baseline/gov/aca502 passed The 22 other YAML files #10041 changed (state premium programs and policy/contrib/aca)463 passed The 4 Python test files #10041 changed 34 passed policy/baseline/partners623 passed -
Tests with Core 3.35.0.
test_marital_unit_inputs.py: 55 passed. -
Partner contract tests. The PR edits no file under
policyengine_us/tests/policy/baseline/partners. All 623 cases pass with the hook, and the Household API Partners job passes in CI. -
Merge state. The head contains current
main(a8ab4228b3), so the runs above are the merged state. -
CI. Run 43507317166 started at 4:04pm EST on 2026-11-13 with
policyengine-core==3.36.0on Python 3.14.10 (from the job log). The run finished at 5:12pm EST. All 38 checks that ran pass (the documentation deploy is skipped, as on every pull request). The passes include the four baseline state shards, the household, IRS, SSA/USDA, HHS, reform and rest shards, all ten Python shards, the microsimulation job, the partner job, the PR validation job and all nine contrib shards. No failure to classify. -
Repo rules. The changelog fragment is a top-level
changelog.d/preserve-marital-unit-inputs.fixed.mdand covers the filing-status rules. Theaxiom:line is present. The PR body describes the round-4 change and the two new limitations.
Not verified
- I ran the tests on Python 3.13. CI uses 3.14.10.
- I did not run the full suite locally. I did not run the baseline
gov/statestree (except the premium program files above),gov/irs, the contrib tests (exceptcontrib/aca) or the dataset microsimulation tests. CI ran them at this head with Core 3.36.0 and they pass. - I did not check the coverage report for
marital_units.py. - The witnesses and both fuzz runs use Texas and 2026 only.
- The fuzz does not draw monthly status keys,
familiesortax_unit_role_input; I checked those by hand only, in the households listed above.
Two tests now fix the documented rule that a filing_status changing between
periods counts as no status: a joint return dated {2024: SINGLE, 2025:
JOINT} with a 20-year-old student spouse pairs no one, and two separate
filers, one of them {2024: SEPARATE, 2025: SINGLE}, pair no one. Reading a
changing status as JOINT in any year, as SEPARATE in any year, or as its
last value each fails a test.
The docs now say that a dependent also marked head or spouse gives own
units only beside a head and spouse pair (a lone spouse input on a
dependent pairs through step 4, as the roles do), and that a filing status
dated for more than one year must be constant to count.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…into preserve-marital-unit-inputs
Main's PolicyEngine#9932 has is_tax_unit_spouse pick its spouse before checking separation, and drop that spouse only when the head or the spouse is separated, without promoting another adult (26 USC 7703(a)(2)). Step 4 now applies the same rule instead of pairing no one in any tax unit with a separated member, so a couple with a separated adult dependent still shares a marital unit and the units keep matching the roles. Two hook tests pin both parts of the rule. Conflicts were wording only: the head formula's comment, the tax_unit_role_input documentation and the microsimulation guide keep main's separation text with this PR's sentence on built marital units, and is_tax_unit_spouse.yaml keeps the cases from both sides. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…into preserve-marital-unit-inputs # Conflicts: # pyproject.toml # uv.lock
test_tax_unit_role_input_properties.py's _age_rule, which main's new test_tax_unit_spouse_separation_invariants.py also uses, made the next-oldest adult the spouse with no qualifying child age test, as Core's single default marital unit allowed. With marital units built for situations that omit them, an adult under 19 and younger than the head meets the age test (26 USC 152(c)(3)(A)(i)) and isn't the spouse. The reference now skips that candidate; the separation rule is unchanged. Both docstrings no longer say Core puts everyone in one marital unit. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…into preserve-marital-unit-inputs
PavelMakarchuk
left a comment
There was a problem hiding this comment.
Verdict: APPROVE (head ec20e1e425)
The round-5 test item is resolved, and both suggestions are taken. The hook follows the narrower separation rule from #9932 correctly. The CI failure at 6e27727ace is fixed in 47d0b59306. Nothing is open. Two optional suggestions are below.
I reviewed 6e27727ace in full with policyengine-core 3.36.0 (the floor in pyproject.toml, the version in uv.lock, and the version CI installs). Then I checked ec20e1e425: against 6e27727ace, the PR's own files differ only in the two test files of 47d0b59306. The rest of that range is the merge of main.
Resolved since the last review
| # | Round-5 item | Status |
|---|---|---|
| 1 | Should address: no test fixes how a changing filing status is read | Resolved. test_a_joint_return_pairs_a_spouse_the_age_test_would_not has the row ({"2024": "SINGLE", "2025": "JOINT"}, []) (policyengine_us/tests/microsimulation/test_marital_unit_inputs.py:406-408), and test_the_separate_filer_rules has a filer with {"2024": "SEPARATE", "2025": "SINGLE"} (:491-500). Each of the three other readings now fails a test (table below). The SINGLE then JOINT order is better than the row I asked for, because it also catches "last value wins". |
| S1 | Suggestion: docs for a lone spouse input on a dependent | Taken (docs/usage/microsimulation.md:65-69). A 66-year-old, and a 70-year-old with true spouse and dependent inputs, share a unit and the role formulas give the same couple. |
| S2 | Suggestion: known limitation for a status that is JOINT in one year only |
Taken (docs/usage/microsimulation.md:84-86). |
Item 1: _filing_status changed in a copy (policyengine_us/tools/marital_units.py:259), then test_marital_unit_inputs.py run (58 tests at the head).
Change to _filing_status |
Result |
|---|---|
A changing status with JOINT in any year reads as JOINT |
1 failed, 57 passed |
A changing status with SEPARATE in any year reads as SEPARATE |
1 failed, 57 passed |
| A changing status reads as its last value | 1 failed, 57 passed |
| (also) A changing status raises, as before round 4 | 4 failed, 54 passed |
The CI failure at 6e27727ace, now fixed
At 6e27727ace, "Python tests / Full Suite - Rest (Python shard 2)" failed on three cases of test_seeded_population in policyengine_us/tests/core/test_tax_unit_spouse_separation_invariants.py, a file that #9932 added to main. This PR caused the failure: the test omits marital_units, and its reference rule _age_rule had no age test. With the hook, an 18-year-old who is younger than the head is a dependent, which is the intended change of this PR. The model value was right, and the reference was out of date. The failure was deterministic (3 failed at that head with the hook, 3 passed on main and on the merge base).
47d0b59306 adds the qualifying child age test to _age_rule (policyengine_us/tests/core/test_tax_unit_role_input_properties.py) and updates both docstrings. This is the change that I would have asked for. At ec20e1e425 with Core 3.36.0, the two #9932 property files and test_marital_unit_inputs.py pass (66 passed). The same change, applied to 6e27727ace, also passed with more examples than CI draws: 60 batches for the separation invariants and 300 for the role-input property. So the two tests that share the reference do not hide a second failure.
Suggestions
- A hook test for a separated head. Step 4 forms no couple "when the head or that spouse is separated" (
docs/usage/microsimulation.md:30-31,policyengine_us/tools/marital_units.py:641). The hook tests cover a separated spouse candidate and a separated third member (test_marital_unit_inputs.py:279-297), but not a separated head. I changed the check to read only the spouse, and all 58 tests passed. One more row, such as({"first": {"age": 45, "is_separated": True}, "second": {"age": 43}}, []), closes this. The effect is on the units only: for three households (an aged couple, an aged person with a disabled 60-year-old, a parent with a second adult and a child, each with a separated head) SSI, SNAP, Medicaid, income tax and net income are the same with and without the head check, because those formulas readis_separatedthemselves. - A lone spouse input beside a separated adult. With one true
is_tax_unit_spouseinput and no head input, step 4 returns the pair before it checks separation (policyengine_us/tools/marital_units.py:609-610). So the oldest other adult is paired even when that adult is separated. Example (Texas, 2026): a 70-year-old with $9,000 Social Security andis_tax_unit_spouse: true, a 45-year-old with $15,000 wages andis_separated: true, and a 30-year-old. The 70-year-old and the separated 45-year-old share a unit, and the 70-year-old's SSI is $2,022 with deeming, against $3,168 onmain. Without the spouse input, nobody is paired and SSI is $3,168. This code did not change in this round, and these inputs contradict each other. Either move the separation check above the early return, or add a clause to the docs sentence about a lone spouse input (docs/usage/microsimulation.md:67-69).
What I checked
The witnesses, the mutations and the fuzz ran at 6e27727ace. The hook and the role variables are the same at ec20e1e425.
-
The hook runs. With Core 3.36.0, husband 70, wife 68 and grandchild 10 get units
{husband, wife},{grandchild}at6e27727ace. Onmainand on the merge base with Core 3.36.0, and at the head with Core 3.34.10, all three share one unit. -
What comes from
mainand what comes from this PR. #9932 ("Ignore dependent separation when inferring the tax unit spouse", merged 7:48pm EST on 2026-11-13) changed the formula inis_tax_unit_spouse.py, the comment inis_tax_unit_head.py, the documentation string intax_unit_role_input.py, and added 12 cases (the 243 lines) tois_tax_unit_spouse.yaml. Against the merge base, this PR's own diff on those three variable files is comments and one documentation sentence, and its own addition to the YAML file is the 23-line case for the 18-year-old son. The PR's own change for the rule is inmarital_units.py: the old check (no couple when any member is separated) is gone, and a check on the head and the picked spouse comes after the spouse is picked (:637-642). -
The separation rule and its source. The spouse candidate is picked first (oldest eligible adult after the age test; member order breaks ties). Then no spouse is inferred when the head or that candidate is separated, and no younger adult takes the place. Another member's separation has no effect. The source is 26 USC 7703(a)(2): a person legally separated under a decree of divorce or separate maintenance is not considered married. The rule concerns that person's own marriage, so a separated dependent cannot remove the filer's spouse. 26 CFR 1.7703-1(a) says the same. The hook applies the checks in the same order as the formula.
-
Mutations of the step-4 separation check (
test_marital_unit_inputs.py, 58 tests): any separated member blocks the couple, 1 failed; no separation check, 1 failed; only the head is checked, 1 failed; a younger adult replaces a separated candidate, 1 failed; only the spouse is checked, 58 passed (first suggestion). -
Separation witnesses (Texas, inputs dated 2026, calculated for 2026). 47 households at the head, on the merge base and on
main94054aa57e. The merge base andmaingive the same values in all 47. No errors.- Husband 70, wife 68, $6,000 Social Security each. Husband separated, wife separated, or both: own units at the head, no spouse, SSI $6,168 each, SNAP $291.
maingives the same roles and values. With no separation: one unit, joint claim, SSI $3,066 each, SNAP $1,914, as onmain. - The same couple with a separated third member (a son aged 40, a child, or a 66-year-old): the couple shares a unit, joint claim, SSI $3,066 each, as on
main. Parents 45 and 43 with a separated 18-year-old or a separated child of 10: the parents share a unit and file jointly, as onmain. - Head 70, separated 68-year-old, third adult 66: no couple, and the 66-year-old is not promoted. Separated head 70 with 68 and 66: no couple. Equal ages 68 and 68 in both orders: the first listed is the candidate. A separated 18-year-old who meets the age test does not block the 30-year-old spouse. All agree with the calculated roles and with
main. is_separateddated 2025 only: carried to 2026, no couple, as onmain.{2025: true, 2026: false}: own units (SSI $6,168 each against $3,066 onmain), by the documented rule for a step-4 couple that differs between years.- Explicit inputs with a separated wife: head and spouse inputs give own units (step 1 excludes a separated person; SSI $6,168 each against $3,066 on
main);tax_unit_role_inputHEAD and SPOUSE gives one unit, as onmain; a lone spouse input gives one unit, as onmain. - Two
SEPARATEtax units where one filer is separated: no pair (documented). With a separated dependent child in the first unit: the two filers pair. - The round-4 and round-5 witnesses are unchanged: the seven filing-status households equal
main; head 22 and college student 20 with a changing status get own units (income tax −$4,427) and with a constantJOINTequalmain;SEPARATEbeside{2025: SEPARATE, 2026: SINGLE}gives no pair.
- Husband 70, wife 68, $6,000 Social Security each. Husband separated, wife separated, or both: own units at the head, no spouse, SSI $6,168 each, SNAP $291.
-
Fuzz against the merge base. Three runs, 2,200 households, at the head and on the merge base. No errors in any run. Every difference is in a documented class; none comes from the separation rule.
Run Households Unit couple differs from the calculated head and spouse Differs from the merge base in SSI, SNAP or filing_statusFiling status (806 with a status, 33 changing, 36 with a separated person, 51 with two households) 1,000 25: a tax unit that spans two households (17), a lone true spouse input (8) 31: the age or disability test (22), two people in two tax units (8), a lone spouse input (1) Changing status (198 changing) 400 8: two households (5), a lone spouse input (3) 10: the age or disability test (6), two tax units (3), a lone spouse input (1) Separation (488 with a separated person) 800 20: two households (5), a lone spouse input (12), head and spouse inputs with one of them separated (3) 26: the age or disability test (12), two tax units (8), a lone spouse input (4), head and spouse inputs with one separated (1), two head inputs (1) Three of the lone-spouse-input households in the separation run pair a separated person (second suggestion).
-
The diff since
f177b22378. I read every line. The docs, the docstring and the PR body match the code, except the lone spouse input in the second suggestion. Thepyproject.tomlversion line comes from themainmerges; the Core floor>=3.36.0is the same as onmain, andmainneeds no other newer dependency. -
Tests with Core 3.36.0, at
6e27727ace. No failure except the last row, which47d0b59306fixes.Run Result The PR's three Python test files ( test_marital_unit_inputs.py,test_tax_unit_role_inference.py,test_ar_medical_expense_deduction_properties.py)108 passed The five YAML files the PR changes 134 passed policy/baseline/household862 passed policy/baseline/gov/ssa/ssi336 passed policy/baseline/gov/hhs/medicaid1,270 passed policy/baseline/gov/usda/snap1,289 passed policy/baseline/gov/aca502 passed policy/baseline/partners623 passed test_tax_unit_spouse_separation_invariants.pyandtest_tax_unit_role_input_properties.py3 failed, 5 passed (fixed in 47d0b59306) -
Partner contract tests. The PR edits no file under
policyengine_us/tests/policy/baseline/partners. All 623 cases pass with the hook atec20e1e425, and the Household API Partners job passes in CI. -
Tests with Core 3.36.0, at
ec20e1e425. The PR's three Python test files: 108 passed. The five changed YAML files: 134 passed.policy/baseline/household: 862 passed.gov/ssa/ssi: 353 passed.gov/hhs/medicaid: 1,270 passed.gov/usda/snap: 1,289 passed. The two #9932 property files withtest_marital_unit_inputs.py: 66 passed. No failure. -
CI. All 38 checks that ran pass at
ec20e1e425, the Rest Python shards and the microsimulation job included. The documentation deploy is skipped, as on every pull request. The last check finished on 2026-11-14 at 7:18pm EST. -
Merge state.
ec20e1e425containsmainup to94054aa57e. -
Repo rules. The changelog fragment is a top-level
changelog.d/preserve-marital-unit-inputs.fixed.md. Theaxiom:line is present. The PR body describes the round-5 tests and the #9932 merge.
Not verified
- I ran the tests on Python 3.13. CI uses 3.14.10.
- I did not run the full suite locally. I did not run the baseline
gov/statestree,gov/irs, the contrib tests or the dataset microsimulation tests. CI ran them atec20e1e425with Core 3.36.0, and they pass. - I did not run the tests with Core 3.35.0 this time, because the floor is now 3.36.0.
- The fuzz compares the head with the merge base, not with the newest
main. The 47 witnesses give the same values on both. - I did not check the coverage report for
marital_units.py. - The witnesses and the fuzz runs use Texas and 2026 only. The fuzz does not draw monthly status keys,
familiesortax_unit_role_input; I checked those by hand only.
…into preserve-marital-unit-inputs
…rated adult From Pavel's approval: no hook test failed when step 4 ignored a separated head, so one row now pins it. A lone true is_tax_unit_spouse input returns the pair before step 4 checks separation, so the oldest other adult is paired even when separated; these inputs contradict each other, and the limitation is now documented rather than changing the approved code. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Summary
Household API partners often send no
marital_units. Core then puts the whole household into one marital unit, so the model treats a parent and an adult child as a married couple: the tax-role fallback pairs them as head and spouse, Medicaid applies couple limits, and SSI looks for a couple. Datasets supply their own marital units, and those already stand.This PR uses the situation hook from PolicyEngine/policyengine-core#600 to build marital units for situations that omit them. Each tax unit and household gets at most one couple, from the first of these that applies, and everyone else gets their own unit:
is_tax_unit_headandis_tax_unit_spouseinputs for overlapping periods, neither input as a dependent or separated;tax_unit_role_inputsupplied for every member;is_marriedinput is true;filing_statusinput isJOINTskips the age test, since only a married couple files jointly (26 USC 6013(a)).Step 4 pairs no one when the head or the spouse it picks is separated (it picks the spouse first and promotes no one, as
is_tax_unit_spousedoes since #9932; another member's separation doesn't matter), when the two live in different households, when a family they share has a falseis_marriedinput, when either has a falseis_tax_unit_headoris_tax_unit_spouseinput for the role step 4 gives them, or when the couple would differ between the years the inputs are dated for. It reads the same inputs and dependent age limits asis_tax_unit_headandis_tax_unit_spouse(#10555), including anis_childinput and the defaults Core fills in: once anyone in a situation supplies a role, student, age oris_childinput for a year, everyone without one gets that variable's default for the year instead of its formula. So the units it builds agree with the inferred tax roles in the years the inputs are dated for. Suppliedmarital_units, including an empty mapping, and datasets never reach the hook.Only married people file separately (26 USC 1(d)), so when a household holds exactly two tax units whose
filing_statusinput isSEPARATE, the hook then pairs their two filers, unless either is separated, a family they share has a falseis_marriedinput, or either is already in a couple from the steps above. A unit's filer is its one trueis_tax_unit_headinput, or else its only adult who isn't input as a dependent; aSEPARATEunit with no such filer still counts toward the two, so it blocks the pairing. A marital unit is "an unmarried person, or a married and co-habiting couple" (entities.py), so separate filers in different households stay apart. Afiling_statusinput that changes between periods counts as no status: a change fromJOINTtoSEPARATEdoesn't say a couple split.Inputs that can't settle one static couple give everyone in that tax unit and household their own unit, instead of raising an error: two head or two spouse inputs, a dependent also marked head or spouse in a unit with both a head and a spouse input, or role or
is_marriedinputs that change between periods. With only a spouse input, on a person also input as a dependent, step 4 pairs that person with the oldest other adult, and the role formulas give the same couple.Fixes #9999
Marital unit assignment, before and after
marital_unitsmappingmarital_units: {}marital_units, with trueis_tax_unit_headandis_tax_unit_spouseinputsmarital_units, withtax_unit_role_inputfor every membermarital_units, with a family whoseis_marriedis truemarital_units, with aJOINTfiling_statusinputmarital_unitsand no marriage informationis_marriedis false, or the two live in different householdsmarital_units, with exactly twoSEPARATEtax units in one householdRows four to eight apply per tax unit and household, with at most one couple in each, and the first that applies wins. The last row pairs filers across tax units afterwards.
Example households, none sending
marital_units:is_marriedis true, child 4The last two rows follow the tax-role fallback's known limitation (see below).
Household results
Main
ac1962ca4fwith policyengine-core master against this PR with Core 600, 2026, Texas, no marital units sent. The comparison covered 15 households and the 120 variables that read marital units; these rows show the changes and the couples that stay the same.Known limitations
marital_unitsfor these households.is_marriedinput doesn't pair them, and neither do separate returns in different households or in a household with more than two. On main they shared a unit.filing_statusinput dated for more than one year counts only when it is the same in every year, so a status that isJOINTin the calculation year and different in another year reads as no status.JOINTandSEPARATEinputs say who is married, butSINGLE,HEAD_OF_HOUSEHOLDandSURVIVING_SPOUSEinputs don't say who isn't: two adults in one tax unit with any of them can still be paired by step 4, as on main.is_tax_unit_spouseinput on the oldest adult makes that person both head and spouse in the role formulas, as on main; step 4 pairs them with the next adult.is_tax_unit_spouseinput skips step 4's separation check: step 4 pairs that person with the oldest other adult even when that adult is separated. These inputs contradict each other; callers can sendmarital_units.is_tax_unit_spouse: falselands in the default input year (2024), so the grandparents get their own units, while a 2026 calculation still makes them head and spouse.Changes since the previous revision
input_group_entitiesgate on the spouse rule (Keep an inferred tax unit spouse in the head's marital unit #10555 replaced it), the snapshot fields insocial_security_inputs.pyand the git pin on Core.ssi_marital_earned_income.yamlare gone: since Apply 416.1163(e)(2) to deemed SSI and identify SSI couples by marriage, not tax roles #10141 that variable finds spouses through_ssi_spouse_index, so they no longer tested pairing.Simulation(situation=...)(default input year 2024) lost any couple not listed first. Over 3,000 random households, default years 2024 and 2026 now give the same units.ValueErrornow give everyone in the unit their own marital unit.is_tax_unit_headoris_tax_unit_spouseinput, so the units match the roles.is_tax_unit_spouse: falseleft the roles with no couple while step 4 still paired the grandparents (SSI $3,066 instead of $6,168 each). Over 300 random households with role and student inputs, the units now differ from the calculated head and spouse only where one person holds both roles (the limitation above).filing_statusinputs. CI showed that it split couples whose filing status said they were married. A Maine joint return with a 20-year-old student spouse lost the spouse to the age test. North Carolina's two separate filers in one household no longer shared the $20,000 mortgage and property tax cap. AJOINTinput now skips the age test, and the two separate filers of a household are paired. Step 4 also reads anis_childinput, ashead_or_spouse_candidatesdoes, so a joint return doesn't pair a person input as a child. Across the YAML tests, these changes alter the units of 21 cases in 10 files, all toward the couple the filing status or the role formulas give.filing_statusinput that changes between periods counts as no status. Before, it gave everyone in the tax unit their own unit, cancelling even explicit head and spouse inputs: an aged couple with{2025: JOINT, 2026: SEPARATE}got SSI $6,168 each instead of a joint claim at $3,066 each. Each separate-filer rule now has a test that fails when the rule is removed.{2024: SINGLE, 2025: JOINT}with a 20-year-old student spouse pairs no one, and two separate filers, one of them{2024: SEPARATE, 2025: SINGLE}, pair no one. With each documented rule disabled in turn, and with a changing status read asJOINTin any year, asSEPARATEin any year, or as its last value, at least one test fails. No code changed in this revision.main:is_tax_unit_spousenow picks its spouse before checking separation and drops that spouse only when the head or the spouse is separated, without promoting another adult (26 USC 7703(a)(2)). Step 4 follows the same rule, so a couple with a separated adult dependent still shares a marital unit. Against the previous head, this changes the units of 8 YAML cases, all among Ignore dependent separation when inferring the tax unit spouse #9932's newis_tax_unit_spouse.yamlcases, each toward the couple the formula picks.Effects on existing tests
is_medicaid_long_term_care_home_equity_eligible.yaml, Case 21, "agricultural and non-agricultural homes bracket their own limits after 2028", puts four separate people in one household with no ages or tax units. Step 4 pairs the first two, as the tax roles already do, somedicaid_home_equity_limit_family_exceptionsees a spouse in the home and exempts one of them. The case now setsmarital_units: {}, and every expected value stays as on main.Three more tests relied on Core's single unit:
hud_annual_income.yaml, "A full-time student spouse is not a HUD dependent…": a head of 30 and a 20-year-old full-time student, with no marriage information, now meet the age test as parent and dependent. The case describes a spouse, so it now sends theirmarital_units. The expected $2,000 stays.test_tax_unit_role_inference.py: the reference rule made an 18-year-old the spouse of an older head. With the hook, the head's spouse is the next-oldest adult who fails the age test, so the reference applies the test (26 USC 152(c)(3)(A)(i)).test_tax_unit_role_input_properties.py: its_age_rulereference, which Ignore dependent separation when inferring the tax unit spouse #9932's newtest_tax_unit_spouse_separation_invariants.pyalso uses, made the next-oldest adult the spouse with no age test, as Core's single unit allowed. It now skips a candidate under 19 and younger than the head (26 USC 152(c)(3)(A)(i)); the separation rule is unchanged. The seeded population in Ignore dependent separation when inferring the tax unit spouse #9932's test, with many 17- and 18-year-olds, failed on this at the first CI run after the merge.test_ar_medical_expense_deduction_properties.py: the two separate filers each had their own household, and only the single default unit made them spouses. They now share one household, which keeps the test's point: only two separate filers read each other's ages.mt_elderly_homeowner_or_renter_credit.yaml, three cases with two people in separate tax units, such as two siblings: the single default unit made them an SSI couple, whose combined pensions left no SSI. In their own units, the person aged 66 or 70 with a $10,000 pension receives individual SSI of $943 × 12 − ($10,000 − $240) = $1,556, which Montana counts as gross household income ("SSI payments", 2024 Form 2 instructions). The siblings' credit falls from $460 to $382.20, the second case's from $100 to $22.20, and the third case's from $410 to $332.20. Inputs are unchanged.In
medicaid_optional_senior_or_disabled_countable_income.yaml, "California deducts a dependent child's premiums from a couple budget" expects $23,880 each because, on main, the couple budget took a dependent's premiums only when the dependent shared the couple's marital unit. #10855, now merged and merged in here, counts them whatever the dependent's marital unit (22 CCR 50555.2(a)), so the case keeps $23,880 with the hook. (#10640 already changed the same file's "another couple's dependent" case on main, and it passes with the hook unchanged.)Run locally with the hook active, over every baseline file in which the hook changes a case's marital units, outside reforms and contrib: tax roles, SSI, Medicaid eligibility and state supplements (68 files, 1,348 cases), and the other state programs under
gov/statesexcept tax (1,209 files, 11,418 cases). Case 21 was the only failure. After the latest main merge, the 14 hook-affected files that main changed since were also run: 12 pass, and the other is the California file above. State tax files (478) and the remaining baseline folders weren't run locally. All 623 partner contract cases pass with the hook.Dependencies
All done: #10850 gave the Social Security state test backend the hook, #10855 counts a couple's dependents' premiums whatever their marital unit, and Core 600 shipped in policyengine-core 3.35.0. The hook needs
policyengine-core>=3.35.0.mainnow requires>=3.36.0for base-mode uprating (#10783), which this branch takes from the merge, anduv.lockresolves 3.36.0, so CI runs with the hook. Without the floor, an older Core would skip the hook and keep one marital unit.Tests
test_marital_unit_inputs.py:is_married, separate households, a falseis_tax_unit_spouse, two tax units with a couple each, two couples in one tax unit, and integer person ids;Simulation(situation=...)with inputs dated 2026 (default input year 2024), listing the grandchild before and between the spouses, and checks the couple share a unit;is_marriedinputs give everyone their own unit, and that the hook's adult age matchesis_child;is_full_time_studentinput gives a college student the default, and thatSimulation(reform=...)with a higher dependent age limit stops a parent and their 25-year-old being paired;JOINTinput pairs a 20-year-old student spouse the age test would leave out; that a status changing between periods leaves explicit roles and step 4 to pair the couple, and neither skips the age test nor counts as a separate return; that the two separate filers of a household pair, but not three filers or filers in different households; that a separated filer, a family withis_married: false, a return with no clear filer, or an existing couple stops the separate-filer pairing; that a head input names the filer and an input dependent or child isn't one; and that anis_childinput keeps a 30-year-old out of a couple and out of a married family's adults; that a separated head or spouse candidate leaves the unit without a spouse and a separated candidate promotes no one, while another member's separation doesn't stop the couple;is_tax_unit_spouse.yaml: with marital units omitted, a mother's 18-year-old son is a dependent and she files as head of household. Fails on main.ssi_claim_is_joint.yaml: with marital units omitted, an aged couple listed after their grandchild makes a joint claim, and an aged parent and their permanently and totally disabled child aren't a joint claim. The second fails on main, which makes them a couple.test_marital_unit_inputs.py,test_tax_unit_role_inference.pyandtest_ar_medical_expense_deduction_properties.py(96 tests).axiom: n/a: household entity construction for situations, not a change to a legal provision.
🤖 Generated with Claude Code