Consolidate the US survey graph build and enrichment pipeline

[MaxGhenis]

Status (15 September, Max): draft until the certified default builds from raw sources and passes preflight and certification on this tree. The complete native dataset is not the merge gate. See docs/us-uk-release-path.md, "15 September decisions".

Construct one US population through ACS+ASEC harmonization, complete initial support clones, household Census-block assignment, derived geographies, financial enrichment and a PUF alternative on the combined survey frame. National, state and congressional-district analyses use this population with explicit calibration and pruning. The release path and review guide describe the architecture and remaining release work.

The graph retains source observations, reporting universes, unresolved values, design weights, relationships and geography. Prior wages are excluded. Financial and property-income stages precede the PUF alternative; subsequent amount, health and housing stages retain checked parent populations. Country models own benefit awards and caps. Unknown inputs remain unknown, and incomplete tax inputs refuse PUF qualification.

This integration includes optional child property-income completion, person-status and household-role stages. The completion host now distinguishes private donor/recipient support frames from the full US population while retaining frame, manifest and mutation checks. It also incorporates current main, including María's UK target changes in #904. The UK specification fingerprint was computed from the actual merged source/resource set before resolving the conflict. Shared calibration snapshots, best-iterate selection, fiscal measurement, geography primitives and UK lineage remain included.

Validation is scoped to the source and run recorded in the dated evidence:

• Child property-income component: 58 pure tests and all 14 actual-owner cases pass across bounded invented-input runs. Corrected support custody: all 50 small cases pass, including mutation and permanent-revocation checks.
• The combined 45-node cold/required-replay test stopped at its original 1,800-second CPU limit without a completion receipt. It remains unsuccessful; the 49/51-node variants are held. A separate real-function experiment passes seven correctness controls and measures per-call costs on 128/512/2,048 invented people. It does not establish whole-build attribution or an optimization benefit.
• Property 35-node cold/replay and the corrected focused PUF handoff pass. The 38-node option passes 11 actual invented-source integration controls plus 40 smaller controls. Completion routing has 29 pure, 27 focused and three actual host tests; incomplete inputs remain incomplete.
• Housing: 64 focused and nine actual invented full-host controls pass, including 277 replay hits and retained-population checks. Root and Fable approved that component. Earlier PUF/amount/health acceptance exercised 271 nodes and required all 271 cache hits; its 74-of-161 name inventory is not a release-coverage verdict.
• Retirement detail: 62 controls; conservative candidate ledger: 80 controls, with no fiscal input assignment. UK lineage: 43 controls. Final observation mutation repair: five controls. Calibration parity repin: five tests covering 15 phases, followed by a byte-identical second repin.
• Merged UK identity diagnostic and the separately executed maintained compiler/golden test each pass, with all 245 source files and 113 resource seals unchanged. The resolved UK fingerprint is 81099c1986b54ec92a3efceb72867938887cd4e7e3c9a81bb21630154824e1d9. The maintained case completed in 11.33 seconds wall time and 9.78 seconds CPU; its receipt is 2d81ad311965fb795038c1cbf9d7656b9f3e0566c44b3cc228e209ac0409b796. This validates compilation and identity, not a UK population release.
• The installed-wheel fixture correction is incorporated but its focused runtime check remains unverified after a collection failure. The separate diagnostic/finalization repair passes 31 invented controls; that does not fix collection. Earlier six-wheel install and engine-free HDF smoke checks remain scoped evidence, not a substitute for the full wheel suite.
• Mutation regression tests now recognize the node-population integrity check, which rejects changed inputs before the broader run-level checks. They retain the original mutation, refusal and restoration assertions. The test-only correction passed independent source review, Ruff and formatting; its expensive module fixtures were not rerun locally, and exact-head CI is pending.
• CI file inventory verification passes for 544 tracked test files. Ruff and formatting pass on the eight files in the new correction set. Whole-module fixtures, existing process isolation and disjoint file shards remain intact. New-head CI is pending.

The latest native property/tax attempt also stopped at its 21,600-second CPU limit without a final acceptance receipt. Neither that attempt nor the 45-node test certifies a native PUF result. Repeated verification is under investigation; no larger native budget or automatic retry is implied.

Release work still includes measuring applicable missing-input routes, choosing any necessary completion models, the retirement measurement bridge, a complete small native build, held-out evaluation, national/state/CD calibration, progressive scale, full/compact exports and a dashboard tied to the accepted bytes. Historical native financial replay is useful evidence for the earlier prefix only. This draft PR publishes source and review evidence; it does not release a dataset, promote a default or deploy the site.

Reconcile with main (17 September)

Two merges bring the branch level with main at d1196af10 (74 commits, including the US engine lock at policyengine-us 2.2.1 / spm-calculator 1.0.0 / policyengine-core 3.32.5 from #936 and UK #927, #934, #937): 8ce9224e7 and e47adc6db. Six files conflicted, all identity pins or tests; pins were regenerated from the merged tree rather than taken from either side. Before the push: ruff clean; tools/ci_test_groups.py --verify ok; tools/spec_engine_coverage.py --check 42156/42156 fields and 41/41 inventory checks; the identity and pin test set 354 passed; the three lock-binding tests 13 passed (sha256(uv.lock) equals the approved lock digest in worker_identity.py and tools/spec_seed_identity_diagnostics.py).

An independent read-only review of the two merge commits found nothing lost from main (its non-text county_fips gate and tests are present beside this branch's own nine ladder tests; the branch carried no edits of its own under us/spec/, so taking main's values for those four inventory hashes dropped nothing), no 1.819 residue outside three historical comments, the eight engine parameter-file pins equal to the installed 2.2.1 RECORD, and the 15 September decisions text intact. The review's open notes are closed on the branch. graph_fiscal_measurement.py now binds the release SPM selection ({"geography_kind": "county"}, asserted equal to reform_validation.US_RELEASE_SPM_SELECTION) into the model contract and passes it to the engine adapter. The static dependency closure is blind to what the calculator-generated measurement variables read (spm_unit_spm_threshold has no input leaves in the index, although the provider reads the household county, the unit's tenure and each member's age), so a root that reaches one of those variables now declares age, county_fips and spm_unit_tenure_type as leaves: an undeclared one refuses the node declaration (UNDECLARED_MODEL_LEAF) and a missing value refuses the kernel, both before the engine runs. A test pins the measurement roster against the installed engine and calculator, so an upgrade that adds a consumer moves it. DISTRIBUTIONS in tools/spec_seed_identity_diagnostics.py now lists spm-calculator. The loader golden vector is a value neither side had because it binds the seed protocol implementation hash, which both sides moved; the test now asserts that tie.

[MaxGhenis]

Closing as superseded: this head (a402dfc) is an ancestor of #1011's head (3de7348, branch native-integration-20260923), so nothing here is lost. The branch is kept. Whether the graph-native US line itself continues is decision US-2 in the 2026-10-09 consolidation review.