Prioritize CTC fiscal target calibration

packages/populace-build/src/populace/build/us/fiscal_targets.py

@@ -1213,6 +1213,12 @@ def _str_at(obj: object, *path: str) -> str:
         accepted_families=("irs_soi",),
         required_metadata=(("target_role", "refundable_ctc_total"),),
     ),
+    TargetCoverageRequirement(
+        requirement_id="ctc_total",
+        label="Child Tax Credit total",
+        accepted_families=("irs_soi",),
+        required_metadata=(("target_role", "ctc_total"),),
+    ),
     TargetCoverageRequirement(
         requirement_id="aca_marketplace",
         label="ACA marketplace spending and enrollment",

packages/populace-build/tests/test_us_fiscal_refresh_builder.py

@@ -24,6 +24,8 @@ def _load_builder_module():
 
 
 def _passing_critical_diagnostics(builder) -> tuple[SimpleNamespace, ...]:
+    ctc_target = 82_863_353_000.0
+    ctc_final = 92_000_000_000.0
     return (
         SimpleNamespace(
             name=(
@@ -55,6 +57,15 @@ def _passing_critical_diagnostics(builder) -> tuple[SimpleNamespace, ...]:
             final_estimate=1_541_540_768_722.367,
             relative_error=0.047815394099604024,
         ),
+        SimpleNamespace(
+            name=(
+                f"irs_soi.ty2022.historic_table_2.us.all.ctc_amount@{builder.PERIOD}"
+            ),
+            target=ctc_target,
+            initial_estimate=132_000_000_000.0,
+            final_estimate=ctc_final,
+            relative_error=(ctc_final - ctc_target) / ctc_target,
+        ),
     )
 
 
@@ -419,6 +430,70 @@ def test_target_value_loss_weights_prioritize_large_targets() -> None:
     assert weights[1] > weights[0] * 10_000
 
 
+def test_target_value_loss_weights_boost_ctc_total_role() -> None:
+    builder = _load_builder_module()
+    registry = TargetRegistry(
+        (
+            TargetSpec(
+                name="ctc_total",
+                entity="tax_unit",
+                value=100.0,
+                source="fixture",
+                metadata={"target_role": "ctc_total"},
+            ),
+            TargetSpec(
+                name="other_same_value",
+                entity="tax_unit",
+                value=100.0,
+                source="fixture",
+                metadata={"target_role": "eitc_total"},
+            ),
+            TargetSpec(
+                name="legacy_named_ctc_without_role",
+                entity="tax_unit",
+                value=100.0,
+                source="fixture",
+            ),
+        ),
+        country="us",
+    )
+
+    weights = builder._target_value_loss_weights(registry)
+
+    assert weights.mean() == 1.0
+    assert weights[0] == weights[1] * builder.US_CTC_TARGET_LOSS_WEIGHT_MULTIPLIER
+    assert weights[2] == weights[1]
+
+
+def test_release_gate_failures_reject_bad_ctc_fit() -> None:
+    builder = _load_builder_module()
+    ctc_target = 82_863_353_000.0
+    ctc_final = 132_511_000_000.0
+    diagnostics = list(_passing_critical_diagnostics(builder))
+    diagnostics[-1] = SimpleNamespace(
+        name=(f"irs_soi.ty2022.historic_table_2.us.all.ctc_amount@{builder.PERIOD}"),
+        target=ctc_target,
+        initial_estimate=132_000_000_000.0,
+        final_estimate=ctc_final,
+        relative_error=(ctc_final - ctc_target) / ctc_target,
+    )
+    result = SimpleNamespace(
+        skipped=(),
+        diagnostics=tuple(diagnostics),
+        initial_loss=10.0,
+        final_loss=5.0,
+    )
+
+    failures = builder._release_gate_failures(
+        result,
+        {"dropped_target_names": []},
+    )
+
+    assert len(failures) == 1
+    assert "Child Tax Credit amount" in failures[0]
+    assert "relative_error=0.599151" in failures[0]
+
+
 def test_health_input_signal_gate_rejects_degenerate_aca_inputs() -> None:
     builder = _load_builder_module()
 

packages/populace-build/tests/test_us_fiscal_targets.py

@@ -45,6 +45,7 @@
     "ssa_dependents_total",
     "eitc_total",
     "refundable_ctc_total",
+    "ctc_total",
     "aca_spending",
     "aca_enrollment",
     "medicaid_enrollment",
@@ -587,6 +588,7 @@ def test_us_fiscal_requirements_include_reference_program_and_tax_controls() ->
     assert "ssa_social_security_components" in ids
     assert "eitc_total" in ids
     assert "refundable_ctc_total" in ids
+    assert "ctc_total" in ids
     assert "aca_marketplace" in ids
     assert "medicaid_spending" not in ids
     assert "medicaid_enrollment" in ids

packages/populace-data/src/populace/data/contract.py

@@ -88,6 +88,14 @@
         "families": ("ssa",),
         "target_roles": ("social_security_total",),
     },
+    {
+        "requirement_id": "ctc_amount",
+        "label": "Child Tax Credit amount",
+        "max_abs_relative_error": 0.20,
+        "names": ("irs_soi.ty2022.historic_table_2.us.all.ctc_amount@2024",),
+        "families": ("irs_soi",),
+        "target_roles": ("ctc_total",),
+    },
 )
 
 

packages/populace-data/tests/test_contract.py

@@ -30,7 +30,7 @@
 SOURCE_COVERAGE_SHA = "9" * 64
 TARGET_SURFACE_SHA = "e" * 64
 REGISTRY_VERSION = "registryabc123"
-TARGET_COUNT = 4
+TARGET_COUNT = 5
 
 
 def _model_package(release_id: str) -> tuple[str, str]:
@@ -201,6 +201,16 @@ def _calibration_diagnostics() -> dict:
                 family="ssa",
                 target_role="social_security_total",
             ),
+            _target_row(
+                "irs_soi.ty2022.historic_table_2.us.all.ctc_amount@2024",
+                target_name="irs_soi.ty2022.historic_table_2.us.all.ctc_amount",
+                target=82_863_353_000.0,
+                initial_estimate=132_000_000_000.0,
+                final_estimate=92_000_000_000.0,
+                relative_error=(92_000_000_000.0 - 82_863_353_000.0) / 82_863_353_000.0,
+                family="irs_soi",
+                target_role="ctc_total",
+            ),
         ],
     }
 
@@ -278,7 +288,7 @@ def _source_coverage_diagnostics() -> dict:
             },
             "irs_soi": {
                 "label": "IRS Statistics of Income",
-                "target_count": 2,
+                "target_count": 3,
                 "sources": ["IRS SOI Historic Table 2"],
                 "reference_urls": ["https://example.test/soi"],
             },
@@ -389,6 +399,32 @@ def test_us_release_recomputes_critical_target_fit(release_dir: Path) -> None:
     assert "relative_error=-0.650806" in failures
 
 
+def test_us_release_rejects_bad_ctc_fit(release_dir: Path) -> None:
+    diagnostics = _calibration_diagnostics()
+    target = next(
+        row
+        for row in diagnostics["targets"]
+        if row["name"] == "irs_soi.ty2022.historic_table_2.us.all.ctc_amount@2024"
+    )
+    ctc_target = 82_863_353_000.0
+    ctc_final = 132_511_000_000.0
+    target["final_estimate"] = ctc_final
+    target["relative_error"] = (ctc_final - ctc_target) / ctc_target
+    _write_json_and_refresh_manifest_hash(
+        release_dir,
+        filename="calibration_diagnostics.json",
+        artifact_key="calibration_diagnostics",
+        payload=diagnostics,
+    )
+
+    with pytest.raises(ReleaseContractError) as excinfo:
+        validate_release_dir(release_dir)
+
+    failures = "\n".join(excinfo.value.failures)
+    assert "Child Tax Credit amount" in failures
+    assert "relative_error=0.599151" in failures
+
+
 def test_us_release_requires_critical_targets(release_dir: Path) -> None:
     diagnostics = _calibration_diagnostics()
     diagnostics["targets"] = [

packages/populace-data/tests/test_release.py

@@ -33,7 +33,7 @@
 CALIBRATION_SHA = "ac31f2be76a0f8dc4da89b6935aa4b8b1b2e1bd4eb3d03b809333084f25b376e"
 TARGET_SURFACE_SHA = "e" * 64
 REGISTRY_VERSION = "registryabc123"
-TARGET_COUNT = 4
+TARGET_COUNT = 5
 
 
 def _calibration_diagnostics() -> dict:
@@ -108,6 +108,16 @@ def _calibration_diagnostics() -> dict:
                 family="ssa",
                 target_role="social_security_total",
             ),
+            _target_row(
+                "irs_soi.ty2022.historic_table_2.us.all.ctc_amount@2024",
+                target_name="irs_soi.ty2022.historic_table_2.us.all.ctc_amount",
+                target=82_863_353_000.0,
+                initial_estimate=132_000_000_000.0,
+                final_estimate=92_000_000_000.0,
+                relative_error=(92_000_000_000.0 - 82_863_353_000.0) / 82_863_353_000.0,
+                family="irs_soi",
+                target_role="ctc_total",
+            ),
         ],
     }
 
@@ -185,7 +195,7 @@ def _source_coverage_diagnostics() -> dict:
             },
             "irs_soi": {
                 "label": "IRS Statistics of Income",
-                "target_count": 2,
+                "target_count": 3,
                 "sources": ["IRS SOI Historic Table 2"],
                 "reference_urls": ["https://example.test/soi"],
             },

tools/build_us_fiscal_refresh_release.py

@@ -68,7 +68,11 @@
 CALIBRATION_FILENAME = "populace_us_2024_calibration.npz"
 POST_EXPORT_ABSOLUTE_TOLERANCE = 1_000_000.0
 POST_EXPORT_RELATIVE_TOLERANCE = 5e-4
-US_FISCAL_TARGET_LOSS_WEIGHTING = "absolute_target_value"
+US_FISCAL_TARGET_LOSS_WEIGHTING = "absolute_target_value_with_ctc_priority"
+US_CTC_TARGET_LOSS_WEIGHT_MULTIPLIER = 10.0
+US_FISCAL_TARGET_ROLE_LOSS_MULTIPLIERS = {
+    "ctc_total": US_CTC_TARGET_LOSS_WEIGHT_MULTIPLIER,
+}
 US_CRITICAL_TARGET_FIT_REQUIREMENTS = (
     {
         "name": (
@@ -94,6 +98,11 @@
         "label": "Social Security benefits",
         "max_abs_relative_error": 0.05,
     },
+    {
+        "name": (f"irs_soi.ty2022.historic_table_2.us.all.ctc_amount@{PERIOD}"),
+        "label": "Child Tax Credit amount",
+        "max_abs_relative_error": 0.20,
+    },
 )
 
 DIRECT_ACTIVE_ALIASES = (
@@ -1279,6 +1288,17 @@ def _write_npz(path: Path, *, result, registry: TargetRegistry) -> None:
 def _target_value_loss_weights(registry: TargetRegistry) -> np.ndarray:
     values = np.asarray([abs(spec.value) for spec in registry.specs], dtype=np.float64)
     weights = np.maximum(values, 1.0)
+    multipliers = np.asarray(
+        [
+            US_FISCAL_TARGET_ROLE_LOSS_MULTIPLIERS.get(
+                spec.metadata.get("target_role", ""),
+                1.0,
+            )
+            for spec in registry.specs
+        ],
+        dtype=np.float64,
+    )
+    weights *= multipliers
     return weights / weights.mean()