Carry the SSI reconcile per-pass trajectory through raise and record (#447)

packages/populace-build/tests/test_us_fiscal_refresh_builder.py

@@ -372,6 +372,13 @@ def to_target_set(self):
     )
     record = reconciliation.compilation["ssi_take_up_reconciliation"]
     assert record["exit_policy"] == "fresh_pair_under_returned_weights"
+    assert [entry["pass"] for entry in record["pass_history"]] == list(
+        range(1, len(record["pass_history"]) + 1)
+    )
+    assert all(
+        "national_swap_delta" in entry and "within_bound" in entry
+        for entry in record["pass_history"]
+    )
     assert record["target_alignment"][
         "registry_national_recipients_total"
     ] == pytest.approx(7_404_820.0)
@@ -527,6 +534,11 @@ def fake_calibrate(*args, **kwargs):
     message = str(excinfo.value)
     assert "swap delta" in message
     assert "800000.000" in message
+    # populace#447: the per-pass trajectory must survive the terminal raise —
+    # converging-but-over-cap vs oscillating is the adjudication evidence.
+    assert "Pass trajectory: pass 1: delta=" in message
+    assert "pass 2: delta=" in message
+    assert "within_bound=False" in message
     # Two passes: a stage assign and an exit assign each pass, one stale diag
     # each pass, one refit each pass.
     assert counts == {"assign": 4, "calibrate": 2, "stale": 2}

tools/build_us_fiscal_refresh_release.py

@@ -5395,6 +5395,10 @@ def _reconcile_ssi_take_up_and_refit(
     band_targets, ssi_target_alignment = _aligned_ssi_take_up_band_targets(target_specs)
 
     last_failures: tuple[str, ...] = ()
+    # populace#447: the per-pass swap-delta trajectory must survive a terminal
+    # raise (converging-but-over-cap vs oscillating is the whole adjudication)
+    # and ride the success record.
+    pass_history: list[dict[str, object]] = []
     for pass_number in range(1, max_passes + 1):
         uncapped_ssi = _ssi_person_uncapped_amount(
             current_support,
@@ -5499,6 +5503,18 @@ def _reconcile_ssi_take_up_and_refit(
             maximum_microsim_batch_size=maximum_microsim_batch_size,
             selected_support=selected_support,
         )
+        pass_history.append(
+            {
+                "pass": pass_number,
+                "national_swap_delta": exit_result.ssi_swap_delta.get(
+                    "national_swap_delta"
+                ),
+                "national_swap_sanity_cap": exit_result.ssi_swap_delta.get(
+                    "national_swap_sanity_cap"
+                ),
+                "within_bound": exit_result.ssi_swap_delta.get("within_bound"),
+            }
+        )
         if exit_result.gates_passed:
             reconciliation_compilation = {
                 **dict(compilation),
@@ -5521,6 +5537,7 @@ def _reconcile_ssi_take_up_and_refit(
                     "target_alignment": ssi_target_alignment,
                     "ssi_swap_delta": exit_result.ssi_swap_delta,
                     "medicaid_enrollment_swap_delta": exit_result.medicaid_swap_delta,
+                    "pass_history": pass_history,
                 },
             }
             calibration_result = (
@@ -5542,9 +5559,21 @@ def _reconcile_ssi_take_up_and_refit(
         last_failures = exit_result.failures()
         current_support = export_frame
 
+    trajectory = "; ".join(
+        "pass {pass_number}: delta={delta:,.3f} cap={cap:,.3f} "
+        "within_bound={within}".format(
+            pass_number=entry["pass"],
+            delta=float(entry["national_swap_delta"] or 0.0),
+            cap=float(entry["national_swap_sanity_cap"] or 0.0),
+            within=entry["within_bound"],
+        )
+        for entry in pass_history
+    )
     raise RuntimeError(
         "SSI take-up reconciliation did not remain count-faithful on returned "
-        f"weights after {max_passes} pass(es): " + "; ".join(last_failures)
+        f"weights after {max_passes} pass(es): "
+        + "; ".join(last_failures)
+        + (f" Pass trajectory: {trajectory}." if pass_history else "")
     )