Build the 117th->119th CD vintage crosswalk from Census sources

[MaxGhenis]

What

The congressional-district (CD) geography-vintage translation merged in #207 /
#208 / #209 consumed a crosswalk passed as an external CLI path — there was
no versioned, reproducible, or Census-cited crosswalk artifact in the repo, and
the only file that existed (an ad-hoc validation CSV) had demonstrably wrong
weights (Montana split 39/61 rather than the equal-population ~50/50, and DC
keyed as …1198 rather than the repo-wide at-large/delegate …1100).

This PR ships the missing piece: a versioned, reproducible, population-weighted
117th → 119th CD crosswalk built from primary Census sources, its generator, and
its provenance, and makes it the packaged default. It closes #205.

The mechanics (translate_congressional_district_facts_to_current_vintage, the
state-total proxy for at-large states, the support-provenance guard) already
landed in #207–#209 and are unchanged here; the hole was the data artifact and
its lineage.

Method

A single-vintage block overlay, so no 2010↔2020 block relationship file is
needed:

Role	Census source	Format
Old (117th) district of each 2020 block	2020 Block Assignment Files, CD layer (BlockAssign_ST{fips}_{usps}_CD.txt) — the 116th-Congress plan (identical district geography to the 117th) on 2020 blocks	BLOCKID|DISTRICT
Current (119th) district of each 2020 block	119th Congressional District BEF (NationalCD119.txt) — the same source the block ladder (#277) already uses	GEOID,CDFP
Weight	2020 P.L. 94-171 POP100 per block (parse_pl_geo_blocks convention)	pipe-delimited

Both district assignments are read on the same 2020 blocks and weighted by the
same 2020 block populations, so each old district's population is redistributed
across the current districts it overlaps and never invented. Population is the
correct default basis (apportionment and equal-population redistricting are
population operations); ACS income/tax proxy weights for fiscal targets are the
documented next refinement noted in #205.

The committed national crosswalk

• 1,444 rows; 436 source districts → 436 current 119th-Congress districts
  (including one-district states and DC).
• Exact per-state population conservation across all 50 states + DC:
  331,449,281 people, zero unmatched or cross-state population.
• Apportionment-shrunk districts (CA-53, IL-18, MI-14, NY-27, OH-16, PA-18,
  WV-03) appear only as sources; new districts (CO-08, FL-28, MT-02, NC-14,
  OR-06, TX-37, TX-38) appear as populated targets.
• Montana's at-large district splits ~50/50 into MT-01/MT-02.

Every source file's URL + SHA-256, the crosswalk SHA-256, the source/target
vintages, and the full per-state conservation table are recorded in
congressional_district_vintage_crosswalk.csv.provenance.json; the human-readable
recipe and citations are in CONGRESSIONAL_DISTRICT_VINTAGE_CROSSWALK.md.

Fit with the Ledger schema direction

The translated CD targets are derived build artifacts, never Ledger facts —
the fact-vs-computed boundary of PolicyEngine/ledger#71. The crosswalk is a
declared consumer-side transform over facts with its own lineage, exactly the
pattern #71 prescribes and that #280 mirrors for period aging. The same mechanism
is called out for the Belgian NIS-code vintage crosswalk in PolicyEngine/ledger#69.

Files

• packages/populace-build/src/populace/build/us_runtime/congressional_district_vintage_crosswalk.py — pure, tested parsers (BAF CD layer, CD BEF) and the population-weighted join with conservation diagnostics.
• tools/build_us_congressional_district_vintage_crosswalk.py — download + cache + provenance orchestration, mirroring build_us_block_ladder_artifact.py.
• packages/populace-build/src/populace/build/us/congressional_district_vintage_crosswalk.csv (+ .provenance.json, + .md) — the committed artifact, per-source SHA-256s, and the data-source doc.
• packages/populace-build/src/populace/build/us_runtime/congressional_district_vintage.py — packaged-default loader helpers (load_default_…, default_…_path).
• tools/build_us_fiscal_refresh_release.py — default to the packaged crosswalk when CD targets are requested and no path is passed (explicit paths still override).

Verification

• pytest test_us_congressional_district_vintage_crosswalk.py → 14 passed (parsers, at-large/delegate normalization, conservation math, uncovered-population reporting, and integration tests that load the real packaged crosswalk: 436/436, MT ~50/50, extra-only-as-source / new-only-as-target, exact fact-value conservation).
• pytest test_us_congressional_district_vintage.py test_us_congressional_district_geography.py test_us_block_ladder_sources.py test_us_fiscal_targets.py → all green (no regressions).
• pytest --extra us test_us_fiscal_refresh_builder.py → all green (provenance-guard path).
• The committed CSV and provenance JSON are byte-reproducible from the generator over the cached Census sources; ruff check, ruff format --check, and git diff --check all clean.

Closes #205. Refs PolicyEngine/ledger#69, PolicyEngine/ledger#71.

🤖 Generated with Claude Code