Preserve supplied marital units and infer missing units from explicit relationships #9999

Problem

PolicyEngine US has two related gaps at the boundary between supplied household relationships and inferred roles:

1. When an entity-form household situation omits marital_units, core's generic add_default_group_entity puts all people into one group. For a couple with children, this creates a marital unit containing the children as well. SSI and other marital-unit calculations can consequently pool unrelated members' amounts.
2. When a situation or dataset supplies marital membership but no tax-unit role inputs, is_tax_unit_spouse still picks the next-oldest eligible adult. It can make an adult child the spouse even when the supplied marital units explicitly keep parent and child separate.

Microcosm already constructs marital membership from CPS A_SPOUSE pointers in packages/microcosm-frame/src/microcosm/frame/units.py, and carries person_marital_unit_id and marital_unit_id. The consumer must preserve that structure. Tax-unit membership and marital-unit membership are separate: a supplied married couple can belong to separate tax units.

Proposed contract

• Preserve explicitly supplied marital_units, including empty mappings and singleton units, and preserve dataset membership IDs. Do not overwrite them with age-based or tax-role inference.
• When an entity-form household omits marital units, infer a pair only from an unambiguous explicitly supplied head/spouse pair within the same tax unit and household. Put other people in singleton units. Do not infer a marriage from age alone.
• Keep construction independent of calculated tax roles, so spouse inference and marital-unit inference cannot recurse into each other.
• Record whether the marital grouping was supplied or synthesized. A generic/default population is not evidence of a relationship.
• Where marital membership was supplied and tax roles were not, infer a tax-unit spouse only within the head's marital unit. Existing direct role overrides remain inputs. Preserve the existing age-based tax-role fallback when relationship information is absent.
• Reject ambiguous/time-varying explicit pairs for automatic construction with an instruction to provide marital units explicitly; the simulation membership graph is static across calculation periods.

Acceptance coverage

• Explicit couples, explicit singletons, omitted units, and an explicit empty mapping.
• A couple with a child and an elderly dependent: only the couple shares marital income.
• Multiple couples/tax units in one household; no pairing across households.
• An adult child in a separate supplied marital unit never becomes an inferred spouse.
• A supplied couple spanning separate tax units retains marital membership without manufacturing a tax spouse.
• Dataset membership IDs, including zero and nonsequential IDs, survive loading and year extension unchanged.
• Caller input is not mutated; YAML construction and the Python simulation API use the same rule; clones retain membership provenance.

Coordination

• Marital units must be explicitly defined in test cases for SSI calculations to work correctly #6434 is the earlier report about missing marital-unit definitions in SSI tests (currently closed).
• Age-ordered tax-unit roles make an unmarried adult child the spouse (enhanced CPS 1.78.2): joint filing, lost EITC child, zero CDCC #9868 is Pavel's open report about an adult child being assigned as a spouse despite supplied marital membership.
• Exclude input dependents from tax unit head and spouse inference #9630 is merged and excludes explicit dependents from inferred head/spouse candidates; preserve that behavior.
• Honor dataset-supplied tax-unit roles #9617 is open and adds tax_unit_role_input. Its current contract preserves roles only, with filing status computed by the model. Compose the marital-membership restriction with its fallback, not its supplied-role branch.
• Ignore a dependent's separation when inferring the tax unit spouse (26 U.S.C. 7703) #9932 is open and corrects the separation gate in the same spouse formula; avoid replacing that fix on integration.
• Register tax_unit_role_input and filing_status_input as preserved engine inputs when moving past pe-us 2.2.1 microcosm#1027 tracks preserving role inputs after the engine upgrade. Its filing-status text predates the current roles-only decision in Honor dataset-supplied tax-unit roles #9617.

A small core construction hook is needed so country-specific defaults also apply to the YAML runner. Keep both the core prerequisite and the US implementation in draft until their integration and the overlap with #9617/#9932 are resolved.

Implementation drafts

• PolicyEngine US: Preserve supplied marital units and infer missing explicit couples #10000.
• Core construction hook and membership provenance: Add country situation preprocessing and supplied membership provenance policyengine-core#600.