Add the UK national calibration step over ledger-backed target references

changelog.d/623-uk-national-calibration.added.md

@@ -0,0 +1 @@
+Added a fail-closed UK national calibration stage that resolves activated Chronicle-backed target references, prepares their declared measures, calibrates household weights and records target diagnostics and solve evidence.

packages/microcosm-build/src/microcosm/build/country_spec.py

@@ -106,6 +106,7 @@
 ALLOWED_GATE_FUNCTIONS = frozenset(
     {
         "aggregate_admin",
+        "calibration_reference_coverage",
         "degenerate_release_surface",
         "enum_domain",
         "export_surface",

packages/microcosm-build/src/microcosm/build/uk/gates.json

@@ -253,6 +253,14 @@
       },
       "notes": "The household BRMA assignment must remain inside the PolicyEngine-UK brma enum domain."
     },
+    {
+      "id": "uk_calibration_reference_coverage",
+      "gate": "calibration_reference_coverage",
+      "phase": "terminal",
+      "criticality": "release_blocking",
+      "parameters": {},
+      "notes": "Every activated UK national target reference must resolve and enter the calibration matrix; count mismatch blocks release."
+    },
     {
       "id": "uk_target_surface",
       "gate": "target_surface",

packages/microcosm-build/src/microcosm/build/uk/target_references.json

@@ -252,6 +252,38 @@
         "contract_target_id": "ons.public_sector_employment",
         "measure_kind": "prepared_column"
       }
+    },
+    {
+      "name": "dwp.uc.households",
+      "ledger_selector": {
+        "source_name": "dwp",
+        "source_concept": "dwp.uc_benefit_units",
+        "geography_level": "country"
+      },
+      "entity": "benunit",
+      "measure": "dwp/uc/households",
+      "family": "dwp_universal_credit",
+      "period": 2025,
+      "metadata": {
+        "contract_target_id": "dwp.uc.households",
+        "measure_kind": "prepared_column"
+      }
+    },
+    {
+      "name": "obr.universal_credit_in_cap",
+      "ledger_selector": {
+        "source_name": "obr",
+        "source_concept": "obr.universal_credit_in_cap",
+        "geography_level": "country"
+      },
+      "entity": "benunit",
+      "measure": "obr/universal_credit_in_cap",
+      "family": "obr",
+      "period": 2025,
+      "metadata": {
+        "contract_target_id": "obr.universal_credit_in_cap",
+        "measure_kind": "prepared_column"
+      }
     }
   ]
 }

packages/microcosm-build/src/microcosm/build/uk_runtime/battery_bindings.py

@@ -209,6 +209,28 @@ def _evaluate_source_coverage(
     )
 
 
+def _evaluate_calibration_reference_coverage(
+    context: EvidenceContext, parameters: Mapping[str, Any]
+) -> GateResult:
+    if parameters:
+        raise ValueError("calibration_reference_coverage takes no parameters.")
+    evidence = context.artifacts["national_calibration"]
+    declared = int(evidence["activated_reference_count"])
+    resolved = int(evidence["resolved_reference_count"])
+    matrix = int(evidence["matrix_target_count"])
+    passed = declared == resolved == matrix
+    return GateResult(
+        name="calibration_reference_coverage",
+        passed=passed,
+        failures=()
+        if passed
+        else (
+            f"Activated/resolved/matrix target counts differ: {declared}/{resolved}/{matrix}.",
+        ),
+        details={"activated": declared, "resolved": resolved, "matrix": matrix},
+    )
+
+
 def _evaluate_nonnegative_columns(
     context: EvidenceContext, parameters: Mapping[str, Any]
 ) -> GateResult:
@@ -729,6 +751,12 @@ def _evaluate_tail_concentration(
         needs_frame=False,
         evidence=_stage_names_evidence,
     ),
+    "calibration_reference_coverage": UKGateBinding(
+        name="calibration_reference_coverage",
+        evaluator=_evaluate_calibration_reference_coverage,
+        artifact_keys=frozenset({"national_calibration"}),
+        needs_frame=False,
+    ),
     "nonnegative_columns": UKGateBinding(
         name="nonnegative_columns",
         evaluator=_evaluate_nonnegative_columns,

packages/microcosm-build/src/microcosm/build/uk_runtime/national_build.py

@@ -544,6 +544,9 @@ def build_uk_national_dataset(
     fit_weight_records = _stage_fit_weight_records(materialized_stages)
     if fit_weight_records is not None:
         artifacts["fit_weight_records"] = fit_weight_records
+    calibration_evidence = _stage_calibration_evidence(materialized_stages)
+    if calibration_evidence is not None:
+        artifacts["national_calibration"] = calibration_evidence
     if input_mass_reference is not None:
         artifacts["input_mass_reference"] = input_mass_reference
     if reviewed_input_mass_exclusions is not None:
@@ -811,6 +814,16 @@ def _stage_fit_weight_records(
     return tuple(collected)
 
 
+def _stage_calibration_evidence(
+    stages: tuple[PlanStage, ...],
+) -> Mapping[str, object] | None:
+    for stage in stages:
+        if stage.name == "national_calibration":
+            manifest = getattr(stage.transform, "manifest", None)
+            return dict(manifest) if isinstance(manifest, Mapping) else {}
+    return None
+
+
 def _brma_enum_domain(engine: object) -> tuple[str, ...] | None:
     variable_getter = getattr(engine, "_variable", None)
     if not callable(variable_getter):