Match the SOI congressional-district file by family, at any vintage

[MaxGhenis]

Every check that asks "is this the IRS SOI congressional-district file?" matched the pinned package literally: ".congressional_district_2022." in record_set_id, or the family id irs_soi.congressional_district_2022. The next IRS district release will arrive as a new package, e.g. irs_soi.ty2024.congressional_district_2024.all_returns, and it would pass straight through the guards:

• Taxable-interest rebase control (Taxable-interest HT2 national row exceeds its AGI-bin partition by 9.8%: HT2-vs-CD-table source discrepancy #489, Rebase stale HT2 taxable-interest rows onto the Pub 1304 national actual (#489 adjudication) #518). A ty2024-stamped district US row out-dates the ty2023 Table 4.3 control, so it would have become the national interest rebase control. The test test_district_taxable_interest_never_controls_the_rebase[hypothetical-cd-2024] fails on main's predicate. It rebases the Historic Table 2 band onto the district row instead of Table 4.3.
• District PTC amount. The A85530 amount, which is not what assigned_aca_ptc measures, would compile as a target.
• The target-parity red line named the exact family. A clean repin failed the anti-rot check. A feed with two district vintages let the second be downgraded with no complaint.
• The manifest generator's one-surface note would silently drop off the regenerated district family.

No target value and no registry version moves. Evidence is below.

Changes

Site	Before	After
fiscal_targets._is_soi_congressional_district_record_set (gates _soi_taxable_interest_control_key_from_fact and _is_soi_cd_premium_tax_credit_amount_conflict, its only callers)	".congressional_district_2022." in record_set_id	_soi_record_set_family(record_set_id) == "congressional_district". The helper is copied verbatim from #1036/#1040, which are not merged.
release_target_parity.RED_LINE_COMPILED_FAMILIES	"irs_soi.congressional_district_2022", looked up by exact manifest key	"irs_soi.congressional_district". At least one district family must be declared and every declared vintage must compile. New public us_target_family_vintage_free_id.
tools/build_us_target_parity_manifest.py _COMPILED_FAMILY_NOTES	keyed irs_soi.congressional_district_2022	keyed and looked up by vintage-free id

Left exact on purpose, and now tied to the pinned feed scope so a repin fails loudly at them:

• SOI_CONGRESSIONAL_DISTRICT_RECORD_SET_ID. The household CD sampling distribution (tools/build_us_puf_support_base.py) must read exactly one district file. A 2024-only feed raises No SOI congressional-district return-count facts. A two-vintage feed reads only the pinned file and never mixes rows; a vintage-free match there would raise on duplicate geoids.
• The soi-congressional-district-2022 source-coverage alias (source_coverage.py; CONGRESSIONAL_DISTRICT_SOURCE_ALIASES and REVIEWED_EXCLUDED_ALIASES in the release builder). These are package registries, not family checks.
• The generated packaged JSON (chronicle_feed_scope.json, target_parity_manifest.json, target_parity_feed_families.json). It describes the pinned feed and regenerates byte-for-byte; TestRegeneration passes locally with the feed present.

Already vintage-free, unchanged:

• us_critical_targets.is_congressional_district_target (.congressional_district_);
• the irs_soi.congressional_district_ spec prefix in tools/build_us_acs_local_release.py and tools/us_acs_local_cd_surface.py.

Invariants (property-tested)

test_us_soi_congressional_district_vintage.py::test_district_guards_hold_at_every_vintage generates 400 record-set ids. Period tokens are none, ty/cy/fy, a bare year, monthYYYY_MM or YYYY_MM; district data vintages run 1990–2099; any trailing segments are allowed. It checks:

1. A district file is a CD record set and its PTC amount conflicts. It never keys a taxable-interest control, while its Table 1.4 twin keys one and does not conflict.
2. No other SOI family, and no other source, is a CD record set.
3. Differential vs the replaced literal. Every id .congressional_district_2022. matched still matches, and the two agree on every non-district id.
4. Differential vs the other district checks. The family match holds exactly when each of these holds:
   • the period-free id starts with the release tools' irs_soi.congressional_district_ prefix;
   • the source record id's target family maps to the red line's vintage-free id;
   • us_critical_targets classifies the target as a district one.

Example tests:

• the 2022 and hypothetical 2024 record sets end to end (interest rebase, PTC amount);
• red-line cases: pinned, repinned, both vintages, a missing family, either vintage downgraded;
• a manifest regeneration round trip on a 2024-only feed: the note attaches and the red line passes;
• the exact pins match the pinned feed scope;
• the household distribution refuses a 2024-only feed and ignores a second vintage;
• a pinned-feed fact-by-fact equivalence test, which skips in CI where the feed is absent.

Evidence (executed locally)

Full compile fingerprint, main 7253402fb vs this branch. Each run replicates the pinned_feed_national_state_surface fixture: compile at 2024 with the canonical CD crosswalk and age targets, apply Medicaid substitutions, select national_state, and build the exclusion receipt. Every per-spec line is byte-identical.

feed	registry (after Medicaid subs)	national_state surface	receipt	fact decisions (raw / translated)
51aa40f (pinned)	33,250 specs, f5bd921d6b21, identical	6,102 specs, e1f9906bf0e0, identical	identical	40,178 / 40,986 facts, 26,880 / 27,328 CD, 0 disagree
c5e5bf8	33,148, 0f3f81d9dd28, identical	6,000, 07f5c476b41d, identical	identical	0 disagree
cf9ece2, f98acf4	(fact-level only)			0 disagree

The only district record set on any of these feeds is irs_soi.ty2023.congressional_district_2022.all_returns. Peak RSS was 3.0 GB.

Mutation. Running the new tests in-process with main's guards patched back in:

guard patched back	tests that fail
literal predicate	8, every 2024-vintage case (end-to-end interest rebase and PTC, property, table rows)
old red line	the repin and downgrade cases
old notes key	the regeneration and shipped-note tests

The pinned 2022 cases pass under all three mutants.

Tests. The new file plus test_release_target_parity.py gave 88 passed locally with the feed-dependent tests running.

Scripts and outputs: ~/PolicyEngine/_reviews/cd-vintage-free-20261012/ (pinned_feed_fingerprint.py, fp_*, feed_fact_equivalence.py, mutation_old_guards.py).

Interaction with open PRs

• Choose the capital-gains rebase control by concept and period, not feed order #1036, Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040. Both add the identical _soi_record_set_family elsewhere in fiscal_targets.py. Whichever lands second gets ruff F811 on the duplicate; delete one copy. Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 also deletes _is_soi_cd_premium_tax_credit_amount_conflict; that hunk is two unchanged lines below this PR's, so it merges without a conflict, and Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 then drops this PR's PTC-conflict assertions with the function.
• Rebase congressional-district taxable interest onto Table 4.3 as shares of the district file's US row #1229. It replaces the interest-gate caller with a .congressional_district_ substring, which is also vintage-free. Once Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040 and Rebase congressional-district taxable interest onto Table 4.3 as shares of the district file's US row #1229 both land, _is_soi_congressional_district_record_set has no callers and can go.

axiom: n/a: microsim target-compilation guard; no policy rule changes.

🤖 Generated with Claude Code

[MaxGhenis]

Merged at head c39b63e3f (merge 8fd39a21b), pinned with --match-head-commit. Gates:

• gh pr checks exit 0: all 10 checks pass, including engine-free, engine-us and engine-uk on 3.13 and 3.14.
• MERGEABLE/CLEAN, no change requests.
• Independent GPT-6.1 Sol review (subfleet run --task review --tier hard, job 20261012-142646-mc1244-review): APPROVE at c39b63e3f, no must-fix items. The review was a static read; its notes on Choose the capital-gains rebase control by concept and period, not feed order #1036/Rebase congressional-district capital gains onto Table 1.4 and drop mislabeled CD SALT and PTC columns on the full surface #1040/Rebase congressional-district taxable interest onto Table 4.3 as shares of the district file's US row #1229 are posted on those PRs.

Executed evidence is in the PR body: byte-identical compile fingerprints on feeds 51aa40f and c5e5bf8, fact-level equivalence on cf9ece2 and f98acf4, and the mutation runs.

None of the 63 commits main gained after CI ran touch the changed or dependent files, and the branch merges into current main without conflicts.