Project the softmax parametrization exactly onto the capped simplex each step

README.md

@@ -334,7 +334,11 @@ calibrates to the SOI `state` surface by default, the 4,459-target contract of
 Build O and Build P; `--soi-mode totals` and `--soi-mode full` are explicit
 opt-ins. See
 [the ACS local-area SOI target surface](docs/us-acs-local-soi-target-surface.md)
-for what each mode contains and where the build records it.
+for what each mode contains and where the build records it. Its
+`--l2-basis chi_square` and `--mass-parametrization softmax` options (defaults:
+the historical `record` and `projection`) penalize distance from the design
+weights; see [penalized calibration toward the design weights](docs/calibration-l2-basis.md)
+for the algebra, the evidence and the measured frontier.
 
 National and ACS local-area builds now use the same typed schema-8 calibration
 diagnostics writer. The local builder adds its Census population marginals to a

changelog.d/calibrate-chi-square-l2-basis.added.md

@@ -0,0 +1 @@
+Add two opt-in options to Adam calibration and the ACS local-area tool. `l2_basis="chi_square"` (`--l2-basis chi_square`) makes the `l2_lambda` penalty GREG's design-weighted chi-square distance `sum(d * (w / d - 1) ** 2) / sum(d)`, which pulls toward the design weights themselves; the historical record-weighted `mean((w / d) ** 2)`, whose mass-conserved optimum is `w ∝ d ** 2`, stays the default. `mass_parametrization="softmax"` (`--mass-parametrization softmax`) conserves mass through `w = total * softmax(log_w)`; the historical per-step uniform shift, still the default, can stall away from the constrained optimum when every record's gradient shares a sign (on the ACS local release it does not). Defaults reproduce the previous solver's bytes. Results record both settings and `CalibrationResult.chi_square_distance`; the tool records them in its calibration summary and build manifest, names all three penalty flags in the manifest's refresh recipe, and refuses to resume a checkpoint solved under other settings. See docs/calibration-l2-basis.md.

changelog.d/calibrate-softmax-exact-cap.changed.md

@@ -0,0 +1 @@
+`mass_parametrization="softmax"` now projects the log-weights exactly onto the capped simplex after every Adam step: one common shift, then a clamp to each cap, with the shift found in float64 by active-set rounds that a sort finishes if they run long. It replaces a renormalize/clamp loop of at most 32 rounds, which ran out on most epochs of the ACS local release because of float32 rounding (the overshoot it left was float32-sized, measured in `experiments/us-acs-local-l2-basis-20260928/results/exact_cap.md`). Softmax solves record `options["iterate_selection_receipt"]["softmax_in_loop_max_cap_ratio"]`, the largest in-loop weight over its cap, in place of the exhaustion count, and the ACS local-area tool carries it in its calibration summary and build manifest. The default `"projection"` parametrization is unchanged.

docs/evidence/spec-engine/us-f0-coverage.json

@@ -1656,13 +1656,13 @@
           "compiler_ir.node_slices"
         ],
         "expected": {
-          "map_sha256": "3cf10a524310ea0ada18ddc65cfa585d1d0652d23e7d7a180c050ac686224e28",
-          "protocol_sha256": "91989ed5e366e19598f86335b2e66723dcb2b6481a78d0dbeb83183a1aa09bd4"
+          "map_sha256": "292ad19c691876eecd8d4b36458b2b7e6f0ec14a51a2e3ab3fdf0d2e6986a98f",
+          "protocol_sha256": "5795dc072b958dcafb6ba5c37e6124181ce37479f96cd4ca2dec3755d4e476f8"
         },
         "failures": [],
         "observed": {
-          "map_sha256": "3cf10a524310ea0ada18ddc65cfa585d1d0652d23e7d7a180c050ac686224e28",
-          "protocol_sha256": "91989ed5e366e19598f86335b2e66723dcb2b6481a78d0dbeb83183a1aa09bd4"
+          "map_sha256": "292ad19c691876eecd8d4b36458b2b7e6f0ec14a51a2e3ab3fdf0d2e6986a98f",
+          "protocol_sha256": "5795dc072b958dcafb6ba5c37e6124181ce37479f96cd4ca2dec3755d4e476f8"
         },
         "status": "covered"
       },
@@ -1677,7 +1677,7 @@
           "compiler_ir.seed_stream_map"
         ],
         "expected": {
-          "implementation_sha256": "91989ed5e366e19598f86335b2e66723dcb2b6481a78d0dbeb83183a1aa09bd4",
+          "implementation_sha256": "5795dc072b958dcafb6ba5c37e6124181ce37479f96cd4ca2dec3755d4e476f8",
           "protocol": "legacy-v1",
           "streams": [
             "build_model",
@@ -1698,7 +1698,7 @@
         },
         "failures": [],
         "observed": {
-          "implementation_sha256": "91989ed5e366e19598f86335b2e66723dcb2b6481a78d0dbeb83183a1aa09bd4",
+          "implementation_sha256": "5795dc072b958dcafb6ba5c37e6124181ce37479f96cd4ca2dec3755d4e476f8",
           "protocol": "legacy-v1",
           "streams": [
             "build_model",
@@ -2599,7 +2599,7 @@
       "country": "us",
       "schema_id": "country_spec",
       "schema_version": 1,
-      "spec_sha256": "ffbb93ed5ae22a95536ae475d6912a42628568609b442360dc1cd3bcf26772cd"
+      "spec_sha256": "edcd647524b51dd2fbcb417576a7421d2429ed7b51beb6756579ef3911e86d52"
     }
   },
   "report_schema_version": 3,
@@ -2609,7 +2609,7 @@
     "country": "us",
     "schema_id": "country_spec",
     "schema_version": 1,
-    "spec_sha256": "ffbb93ed5ae22a95536ae475d6912a42628568609b442360dc1cd3bcf26772cd"
+    "spec_sha256": "edcd647524b51dd2fbcb417576a7421d2429ed7b51beb6756579ef3911e86d52"
   },
   "status": "pass"
 }