Export CPS parent pointers as person-level parent ids

[MaxGhenis]

Closes microcosm#884.

What this does

Exports the CPS ASEC parent pointers as two person columns, parent_1_id and parent_2_id: each is the person_id of the co-resident member that the person's PEPAR1/PEPAR2 pointer names within PH_SEQ, and 0 when the pointer is absent or names no co-resident line. Until now Microcosm exported only the count behind them (own_children_in_household), so a rules engine could ask how many children an adult has but not whose child a person is. policyengine-us#9406 consumes the ids for Medicaid MAGI household composition (42 CFR 435.603(f)(3)).

• Eligibility stage (eligibility_inputs.py): one pointer normalization behind both the count and the ids; int64 storage. Where relationships are measured (the stage's own derivation) the count must equal the number of ids naming each person, exactly.
• Release gate: every nonzero id names a co-resident person (exact int64 household comparison), nobody is their own parent, nobody is named by more people than own_children_in_household counts (ACS rows impute the count with pointers declared unknown, so the gate checks this bound rather than equality), and every person_id in a household carrying a link fits PolicyEngine-US's int32 storage. Parent ids may be all zero ("unknown"), so they are not in the non-constant release set.
• Existing frames: a frame that already carries the pre-Export CPS parent pointers (PEPAR1/PEPAR2) as person-level parent ids #884 outputs with signal (a --base-h5 input, an existing pool) passes through untouched, without parent ids. The ids are optional end to end: the release gate asserts their identities only when both are present, so existing pools still feed releases, and PolicyEngine-US uses its count-based proxy where they are absent.
• Stored-input register (microcosm-data stored_inputs.py): parent_1_id/parent_2_id are registered stored non-variable columns (the pinned engine, policyengine-us 2.2.1, does not define them), naming their producer and the removal condition: drop the entries when the pin moves to a policyengine-us release with #9406. Without this, main's stored-input contract (Refuse US releases that store model inputs the certified engine does not define (#1026) #1031) refuses every release that carries them.
• ACS spine (acs_inputs.py, operator_boundary.py): declares the pointers unknown (0) natively.
• Multispine pool (multispine_pool.py): the ids are native-complete on both arms and never enter the QRF transfer plan.
• Clones (puf_support.py, puf_capital_gains_tail.py): the support clone and the capital-gains tail clone shift parent ids with person_id, leaving 0 alone; rows that never had a pointer carry 0.
• Input mass (input_mass.py, shared): PERSON_REFERENCE_COLUMNS are skipped as structural, like entity ids.
• Pool resume (tools/build_us_multispine_pool.py): a transferred/simulated checkpoint whose recorded person schema lacks an eligibility output is ignored as stale, since the byte-stable legacy identity cannot see new outputs.

How this branch was built

The work was done on 9/7 on parent-ids-export (pushed unchanged as a backup at 7ec9eafc1), which fell ~797 commits behind main. This branch is fresh from origin/main (31315687d) with the three substantive commits cherry-picked (ccce48cc9, 806f780a4, 29a7b71fd); the lane-journal commits (ade4b5cb4, 2361549cb, 7ec9eafc1) and the journal/checkpoint files are dropped.

Conflicts were only digest pins. Re-pinned at observed values after the rebuild, each for the stated reason:

pin	why it moves
source_stages.json asset sha256 (sources.yaml, generate_us_bundle_from_constants.py, test_us_bundle_core_contracts.py, test_us_spec_bundle.py)	the eligibility stage gains two outputs
US bundle spec_sha256 → d3469f47… (test_us_multispine_pool_tool.py, us-f0-coverage.json)	follows from the stage asset
field-usage counts 42,180 → 42,184 and 32,400 → 32,404; source_stages pointer claim; pointer inventory	four new authored fields (two outputs, two nonnegative outputs)
seed-protocol, seed-map, resource-semantics, source-manifest and full-checkpoint identity digests (inventory_coverage.py); the loader golden vector	puf_support and puf_capital_gains_tail are attested kernel modules (spec_engine/seeds.py _DIRECT_KERNEL_MODULES)

tools/generate_us_bundle_from_constants.py --check and tools/spec_engine_coverage.py --check pass (42,184/42,184 fields; 41/41 inventory checks). docs/evidence/spec-engine/us-f0-coverage.json was regenerated by the tool, not edited.

Effect on certified builds

A build from this code gains two person columns. For existing columns the intent is no change, and the round-1 review's one counterexample (a --base-h5 frame whose carried veterans_benefits was overwritten by re-derivation) is fixed by passing such frames through untouched (as main does), covered by test_legacy_frame_passes_through_untouched. Draw sites seed from seed/salt/stable-key material; the moved digests attest source and are not seed inputs. The QRF transfer targets are unchanged.

A PolicyEngine-US version without these variables loads such a build unchanged: policyengine_core skips dataset columns that match no variable and logs a warning. The latest published populace_us_2024.h5 has person_id 4–1,432,502, inside int32; the gate now enforces that for linked households instead of assuming it.

Publishing a build with these columns is a separate, deliberate release step and is not part of this PR.

Verification

• Rebased on origin/main 2bce66156. tools/generate_us_bundle_from_constants.py --check and tools/spec_engine_coverage.py --check pass (42,184/42,184 fields; 41/41 inventory checks); every pin was recomputed from the tools, not hand-edited.
• Local: the eligibility, input-mass, ACS, capital-gains-tail, L0 export, stored-input register, spec-engine and affected multispine-pool tests, and the whole microcosm-data test package, pass; tools/ci_test_groups.py --verify ok; ruff check clean. The full suite runs in CI.
• Independent review: round 1 request-changes (7 findings), all addressed in 808ee8feb. Round 2 confirmed those resolved, answered "no" on whether a completing build changes existing columns, and found the stored-input register gap and the existing-frame key problem, addressed in 813978feb. Round 3 confirmed those and asked that the register entries rest on their producer in the microcosm-data tests (the parent ids postdate the H5 files the register was built from), addressed in dd372e109. Round 4 approved (no new correctness bug; existing output columns unchanged), with nits carried under known limits.
• Known limits, documented rather than fixed: after derivation the gate's count check is an upper bound (a remap that wrongly zeroes a pointer cannot be seen), and the int32 check covers only households that carry a link.

🤖 Generated with Claude Code