Dense-arm SSI swap runaway cap at 0.12 × fresh national (#447)

packages/populace-build/tests/test_us_fiscal_refresh_builder.py

@@ -428,12 +428,13 @@ def test_ssi_reconciliation_fails_closed_when_reassignment_swap_exceeds_bound(
     counts = {"assign": 0, "calibrate": 0, "stale": 0}
     allowance = 100.0
     fresh_selected = dict(band_targets)
-    # The frozen flags overshoot the national total by 800,000 (in under_18);
+    # The frozen flags overshoot the national total by 1,100,000 (in under_18);
     # the fresh re-assignment removes it, so the national swap delta exceeds
-    # the runaway sanity cap (a tenth of the ~7.4M fresh total) — the solve
+    # the runaway sanity cap on BOTH arms (0.10 sparse / 0.12 dense of the
+    # ~7.4M fresh total; populace#447) — the solve
     # abandoned the SSI family, which must still fail closed.
     stale_selected = {
-        "under_18": band_targets["under_18"] + 800_000.0,
+        "under_18": band_targets["under_18"] + 1_100_000.0,
         "18_64": band_targets["18_64"],
         "65_plus": band_targets["65_plus"],
     }
@@ -533,7 +534,7 @@ def fake_calibrate(*args, **kwargs):
 
     message = str(excinfo.value)
     assert "swap delta" in message
-    assert "800000.000" in message
+    assert "1100000.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
@@ -7235,3 +7236,42 @@ def test_checkpoint_identity_protection_key_and_stale_checkpoint_miss(
         builder._read_target_frame_checkpoint(path, identity=protected, target_specs=())
         is None
     )
+
+
+def test_ssi_swap_delta_dense_cap_ratio_admits_measured_dense_equilibrium() -> None:
+    """populace#447: the dense arm's reconcile equilibrium (measured trajectory
+    11.97% -> 11.64% -> 11.38%, decelerating toward ~10.6%) sits above the
+    sparse 10% runaway cap. The dense-specific 0.12 ratio admits the measured
+    equilibrium while both ratios still refuse a genuine runaway, and the
+    ratio used is recorded in the payload."""
+    builder = _load_builder_module()
+    fresh = {"under_18": 1_000_000.0, "18_64": 4_000_000.0, "65_plus": 2_400_000.0}
+    stale = dict(fresh)
+    # 11.42% of the 7.4M fresh national: inside 0.12, outside 0.10.
+    stale["18_64"] += 845_000.0
+
+    sparse = builder._ssi_take_up_swap_delta(
+        _ssi_diag_with_bands(stale, 40_000.0),
+        _ssi_diag_with_bands(fresh, 40_000.0),
+    )
+    dense = builder._ssi_take_up_swap_delta(
+        _ssi_diag_with_bands(stale, 40_000.0),
+        _ssi_diag_with_bands(fresh, 40_000.0),
+        sanity_cap_ratio=builder.SSI_TAKE_UP_SWAP_SANITY_CAP_RATIO_DENSE,
+    )
+
+    assert sparse["within_bound"] is False
+    assert sparse["national_swap_sanity_cap_ratio"] == 0.10
+    assert dense["within_bound"] is True
+    assert dense["national_swap_sanity_cap_ratio"] == 0.12
+    # A genuine runaway (>12%) is still refused on the dense ratio.
+    runaway = dict(fresh)
+    runaway["18_64"] += 1_000_000.0
+    assert (
+        builder._ssi_take_up_swap_delta(
+            _ssi_diag_with_bands(runaway, 40_000.0),
+            _ssi_diag_with_bands(fresh, 40_000.0),
+            sanity_cap_ratio=builder.SSI_TAKE_UP_SWAP_SANITY_CAP_RATIO_DENSE,
+        )["within_bound"]
+        is False
+    )

tools/build_us_fiscal_refresh_release.py

@@ -282,6 +282,20 @@
 DEFAULT_US_FISCAL_CALIBRATION_EPOCHS = 1_500
 SSI_TAKE_UP_RECONCILIATION_MAX_PASSES = 3
 
+#: Runaway sanity caps on the SSI swap delta, as a share of the fresh national
+#: recipient total (#431: the delta is the solve's equilibrium residual on the
+#: SSI family, recorded in the manifest; the cap exists only to catch a solve
+#: that abandoned the family). The dense arm's equilibrium is structurally
+#: larger than the sparse arm's on the same #424-undercounted candidate
+#: universe: measured sparse deltas run 7.1-8.0% (attempts 9-16) while the
+#: dense trajectory converges monotonically 11.97% -> 11.64% -> 11.38% with
+#: decelerating decrements (asymptote ~10.6%), so 0.10 is unreachable there
+#: while remaining the right bar for sparse (populace#447 adjudication,
+#: 2026-07-18; trajectory recorded in the reconciliation pass_history). Both
+#: caps converge back to one number when #424 restores the candidate universe.
+SSI_TAKE_UP_SWAP_SANITY_CAP_RATIO = 0.10
+SSI_TAKE_UP_SWAP_SANITY_CAP_RATIO_DENSE = 0.12
+
 
 def _collect_batch_garbage() -> None:
     """Keep batch loops tidy without traversing the full object graph."""
@@ -5101,6 +5115,8 @@ def _replay_ssi_dependent_inputs(
 def _ssi_take_up_swap_delta(
     stale_diagnostics: Mapping[str, object],
     fresh_diagnostics: Mapping[str, object],
+    *,
+    sanity_cap_ratio: float = SSI_TAKE_UP_SWAP_SANITY_CAP_RATIO,
 ) -> dict[str, object]:
     """National SSI-recipient mass moved by the post-refit re-assignment.
 
@@ -5144,8 +5160,9 @@ def _ssi_take_up_swap_delta(
         fresh_total += fresh_selected
         national_bound += band_allowance
     national_delta = abs(fresh_total - stale_total)
-    sanity_cap = 0.10 * fresh_total
+    sanity_cap = sanity_cap_ratio * fresh_total
     return {
+        "national_swap_sanity_cap_ratio": sanity_cap_ratio,
         "stale_selected_recipient_weight_total": stale_total,
         "fresh_selected_recipient_weight_total": fresh_total,
         "national_swap_delta": national_delta,
@@ -5272,6 +5289,7 @@ def _ssi_take_up_fresh_pair_exit(
     medicaid_enrollment_substitutions: Sequence[Mapping[str, object]],
     maximum_microsim_batch_size: int | None,
     selected_support: Frame,
+    sanity_cap_ratio: float = SSI_TAKE_UP_SWAP_SANITY_CAP_RATIO,
 ) -> _SSITakeUpFreshPairExit:
     """Re-assign SSI take-up under the returned weights and gate the fresh pair.
 
@@ -5322,7 +5340,9 @@ def _ssi_take_up_fresh_pair_exit(
         medicaid_gate=us_medicaid_take_up_gate(dict(exit_medicaid_diagnostics)),
         other_health_gate=us_other_health_insurance_signal_gate(exit_support),
         ssi_swap_delta=_ssi_take_up_swap_delta(
-            stale_ssi_diagnostics, exit_ssi_diagnostics
+            stale_ssi_diagnostics,
+            exit_ssi_diagnostics,
+            sanity_cap_ratio=sanity_cap_ratio,
         ),
         medicaid_swap_delta=_medicaid_enrollment_swap_deltas(
             stale_medicaid_diagnostics, exit_medicaid_diagnostics
@@ -5502,6 +5522,11 @@ def _reconcile_ssi_take_up_and_refit(
             medicaid_enrollment_substitutions=medicaid_enrollment_substitutions,
             maximum_microsim_batch_size=maximum_microsim_batch_size,
             selected_support=selected_support,
+            sanity_cap_ratio=(
+                SSI_TAKE_UP_SWAP_SANITY_CAP_RATIO_DENSE
+                if dense_default_dataset
+                else SSI_TAKE_UP_SWAP_SANITY_CAP_RATIO
+            ),
         )
         pass_history.append(
             {