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

changelog.d/soi-cd-family-vintage-free.fixed.md

@@ -0,0 +1 @@
+Match the IRS SOI congressional-district file by family, not by its pinned 2022 package: the next district release still never keys a taxable-interest control, never compiles a PTC amount target, stays on the target-parity red line and keeps its manifest note. No target value or registry version moves on the pinned feed.

packages/microcosm-build/src/microcosm/build/us_runtime/fiscal_targets.py

@@ -2945,9 +2945,38 @@ def _soi_return_universe_from_record_set_id(record_set_id: str) -> str:
     return "all_returns"
 
 
+def _soi_record_set_family(record_set_id: str) -> str:
+    """An SOI record set's table family, without period or data vintage.
+
+    ``irs_soi.ty2023.table_1_4`` is ``table_1_4``,
+    ``irs_soi.ty2022.historic_table_2.state_broad`` is ``historic_table_2`` and
+    ``irs_soi.ty2023.congressional_district_2022.all_returns`` is
+    ``congressional_district``.
+    """
+    parts = record_set_id.split(".")
+    if parts[0] != "irs_soi":
+        return ""
+    rest = parts[2:] if len(parts) > 1 and _is_period_token(parts[1]) else parts[1:]
+    if not rest:
+        return ""
+    family = rest[0]
+    if family.startswith("congressional_district"):
+        return "congressional_district"
+    return family
+
+
 def _is_soi_congressional_district_record_set(fact: object) -> bool:
-    record_set_id = _str_at(fact, "layout", "record_set_id")
-    return ".congressional_district_2022." in record_set_id
+    """Whether a fact comes from an IRS SOI congressional-district file.
+
+    Matched by family, at any data vintage: the next IRS release
+    (``congressional_district_2024``) must meet the same guards as the pinned
+    ``congressional_district_2022`` package — never an interest control
+    (microcosm#489) and no PTC amount target.
+    """
+    return (
+        _soi_record_set_family(_str_at(fact, "layout", "record_set_id"))
+        == "congressional_district"
+    )
 
 
 def _is_soi_cd_premium_tax_credit_amount_conflict(

packages/microcosm-build/src/microcosm/build/us_runtime/release_target_parity.py

@@ -73,6 +73,7 @@
     "us_release_target_parity_gate",
     "us_release_target_parity_reviewed_exclusions",
     "us_target_family_id",
+    "us_target_family_vintage_free_id",
 ]
 
 US_TARGET_PARITY_MANIFEST_RESOURCE = "target_parity_manifest.json"
@@ -111,14 +112,17 @@
 #:   including nonfilers, the ~$12.4T universe that tax-return / CPS-reported
 #:   wages undercount by two-thirds. Silent loss of it is the exact failure the
 #:   Chesterton's-fence audit surfaced.
-#: - ``irs_soi.congressional_district_2022``: the CD target family is ordinary
+#: - ``irs_soi.congressional_district``: the CD target family is ordinary
 #:   geography inside the one US target surface. Artifact record count may
-#:   change L0, never whether these constraints compile (microcosm#449).
+#:   change L0, never whether these constraints compile (microcosm#449). The
+#:   entry is vintage-free (``us_target_family_vintage_free_id``): it holds for
+#:   ``irs_soi.congressional_district_2022`` on the pinned feed and for the
+#:   next IRS release after a repin, and every declared vintage must compile.
 RED_LINE_COMPILED_FAMILIES = (
     "ssa_ssi_monthly.ssi_federal_payment_recipients",
     "ssa_supplement.ssi_recipients",
     "bea_nipa.total_wages_salaries",
-    "irs_soi.congressional_district_2022",
+    "irs_soi.congressional_district",
 )
 
 
@@ -169,6 +173,21 @@ def us_target_family_id(source_record_id: str) -> str:
     return namespace
 
 
+def us_target_family_vintage_free_id(family_id: str) -> str:
+    """A target-family id without the IRS data vintage its concept may carry.
+
+    The SOI congressional-district package names its data year, so its family
+    is ``irs_soi.congressional_district_2022`` on the pinned feed and would be
+    ``irs_soi.congressional_district_2024`` after a repin to the next release.
+    Both map to ``irs_soi.congressional_district``, the id the red line and the
+    manifest notes key on. Every other family id is returned unchanged.
+    """
+    namespace, _, concept = family_id.partition(".")
+    if namespace == "irs_soi" and concept.startswith("congressional_district"):
+        return "irs_soi.congressional_district"
+    return family_id
+
+
 @dataclass(frozen=True)
 class TargetFence:
     """The Chesterton's-fence record behind one reviewed exclusion.
@@ -577,18 +596,23 @@ def assert_target_parity_manifest_current(
         )
 
     for family in RED_LINE_COMPILED_FAMILIES:
-        entry = manifest.by_name.get(family)
-        if entry is None:
+        entries = [
+            entry
+            for entry in manifest.families
+            if us_target_family_vintage_free_id(entry.name) == family
+        ]
+        if not entries:
             failures.append(
                 f"{family}: red-line administrative target family must be declared "
                 "and compiled (the target-parity red line)."
             )
-        elif entry.status != COMPILED_STATUS:
-            failures.append(
-                f"{family}: red-line administrative target family must stay status="
-                f"{COMPILED_STATUS!r}, not {entry.status!r} — it can never be "
-                "quietly downgraded to a reviewed exclusion."
-            )
+        for entry in entries:
+            if entry.status != COMPILED_STATUS:
+                failures.append(
+                    f"{entry.name}: red-line administrative target family must stay "
+                    f"status={COMPILED_STATUS!r}, not {entry.status!r} — it can never "
+                    "be quietly downgraded to a reviewed exclusion."
+                )
 
     if registry is not None:
         present = registry_target_family_ids(registry)

packages/microcosm-build/tests/engine_free/shared/test_release_target_parity.py

@@ -39,6 +39,7 @@
     registry_target_family_ids,
     us_release_target_parity_gate,
     us_target_family_id,
+    us_target_family_vintage_free_id,
 )
 from test_support.paths import paths_for
 
@@ -247,7 +248,8 @@ def test_red_line_downgrade_is_rejected(self) -> None:
                 evidence="none",
                 fence=_FENCE,
             )
-            if family.name in RED_LINE_COMPILED_FAMILIES
+            if us_target_family_vintage_free_id(family.name)
+            in RED_LINE_COMPILED_FAMILIES
             else family
             for family in _CONTRACT.families
         )
@@ -287,7 +289,13 @@ def test_every_reviewed_exclusion_carries_reason_evidence_and_fence(self) -> Non
     def test_red_line_families_are_compiled(self) -> None:
         manifest = load_target_parity_manifest()
         for family in RED_LINE_COMPILED_FAMILIES:
-            assert manifest.by_name[family].status == COMPILED_STATUS
+            entries = [
+                entry
+                for entry in manifest.families
+                if us_target_family_vintage_free_id(entry.name) == family
+            ]
+            assert entries, family
+            assert all(entry.status == COMPILED_STATUS for entry in entries)
 
     def test_congressional_district_family_declares_one_surface_doctrine(self) -> None:
         family = load_target_parity_manifest().by_name[