[hua7450]

Behavior

Fixes #9999 and addresses #9868. When a caller supplies separate marital units for a parent and adult child, the child no longer becomes an inferred tax-unit spouse. When a household omits marital units, an explicit head/spouse pair, or otherwise the two adults of a family with an explicit is_married input, forms one unit and other people get singleton units, so their SSI marital income is not pooled with the couple.

• Preserve explicit household marital mappings, including empty mappings and singletons, and all dataset membership IDs. Microcosm's marital structure passes through unchanged; no data rebuild or Microcosm code change is included.
• Infer missing household pairs only from explicit inputs within the same tax unit and household: an unambiguous is_tax_unit_head / is_tax_unit_spouse pair whose true inputs overlap in period, or, without one, the two adults of a family whose is_married input is true when exactly two of its adults there are neither dependents nor separated. Conflicting dependent inputs or changing roles or is_married require explicit membership; separated people are left unpaired. Calculated tax roles never construct marriages, and ages only set a married family's children aside.
• Restrict tax-spouse inference to the head's marital unit only when membership was supplied. Core provenance distinguishes supplied groups from generated defaults. Direct role inputs keep their normal precedence; the existing age/dependent/separation fallback remains when marital membership is absent.
• Share the construction rule between the Python API and YAML runner, including YAML cases with reforms or inline parameters, through the core hook. Supplied couples may span separate tax units without acquiring a tax-unit spouse.
• Source-input snapshots record which groups the caller supplied, so a reloaded simulation keeps inferred marital units as inferred and its tax spouse unchanged. Snapshots without the record keep every group as supplied.

Draft dependencies and scope

• Depends on Add country situation preprocessing and supplied membership provenance policyengine-core#600, which now includes Core's main (3.34.0) and delegates the hook through reforms. This draft pins that exact core commit in pyproject.toml and uv.lock (generated with uv 0.13.4) so reviewers can run it. Replace the Git dependency with the released minimum, regenerate the lock with uv 0.13.4, and remove allow-direct-references before merge.
• Honor dataset-supplied tax-unit roles #9617's supplied-role branch is on main and composed here. Keep an inferred tax unit spouse in the head's marital unit #10555 adds an unconditional marital-unit check to the same fallback; when it lands, keep this PR's provenance guard instead, because an unconditional check would also restrict the singletons this PR synthesizes and end the age fallback for role-less tax units. Ignore a dependent's separation when inferring the tax unit spouse (26 U.S.C. 7703) #9932's separation fix still needs composing. Filing status remains computed; no filing_status_input is added.
• The conservative missing-input rule intentionally changes households that previously relied on core grouping every person into one marital unit. Such callers should supply their actual relationships. Singletons synthesized from unknown relationships do not assert that the person is unmarried, but SSI and other programs that read marital units treat them as individuals: a couple sent with neither roles nor is_married keeps filing jointly but loses the SSI couple rate, spousal deeming and state couple rates. For example, a California parent with a disabled child sent without marital units no longer has the parent's earnings deemed to the child as a spouse's (child SSI 6,327 on main, 11,928 here, for 2026).
• Several existing comments still say omitted marital units put everyone in one unit (for example _ssi_spouses.py, _medicaid_parents.py, _non_filer_household.py); they are left for a comment-only follow-up.
• Full population impacts and the full policy/partner suite have not been measured locally. Partner fixtures are unchanged. Broader compatibility remains a draft review item.

Validation

The results below predate the latest round (main merge, Core 3.34.0 pin, is_married pairing and snapshot provenance), which was not run locally; CI validates it. By code trace, dc_ossp.yaml Cases 2 and 5, which mark a role-less couple married only through families.is_married, keep their couple rates through the new pairing.

• 117 tax-unit YAML cases pass (29 files, one bounded batch).
• SSI YAML suite: 167 cases pass in two sequential batches; the subsequently added multiple-couple case also passes (all seven cases in its variable-named file), for 168 unique SSI cases covered.
• 16 Python tests pass: the existing tax-role inference invariants plus nine new construction/data-contract cases. These cover caller isolation, axis expansion, clone provenance, explicit versus missing groups, ambiguous/changing role inputs, and a six-person dataset whose zero/nonsequential marital IDs survive loading and year extension.
• make format and git diff --check pass.

Policy calculations are tested in variable-named YAML files. The new Python module covers construction and dataset contracts unavailable to YAML, and runs in the existing Microsimulation job; no runner or parallel heavy process is added. Local macOS timing including imports, using the existing six dataset-copy tests as a control: 10.81 seconds / 925,057,024 bytes peak RSS before adding the nine new tests, 11.07 seconds / 841,220,096 bytes after. The lower RSS is run-to-run variation, not a claimed memory improvement. Linux CI resource reports were not downloaded; these small-fixture measurements do not certify the full runner's peak.

axiom: n/a: supplied relationship preservation and simulation entity construction, not a change to a legal provision.

[PavelMakarchuk]

@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 tax_unit_role_input, the age-ordered fallback makes an unmarried adult child the head's spouse, so the unit files jointly and loses the EITC child. In the PolicyEngine–PRD comparison this affects about 109 EITC units ($212K) and 29 CDCC units in 2025.

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

[hua7450]

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.