Skip to content

Project the softmax parametrization exactly onto the capped simplex each step - #1096

Merged
MaxGhenis merged 24 commits into
mainfrom
softmax-exact-cap-projection
Nov 15, 2026
Merged

MaxGhenis merged 24 commits into
mainfrom
softmax-exact-cap-projection

Conversation

@MaxGhenis

@MaxGhenis MaxGhenis commented Oct 2, 2026 •

Copy link
Copy Markdown
Contributor

What changes

Under mass_parametrization="softmax", every Adam step ended on a loop: renormalize so exp(log_w) sums to the total, clamp to the ratio cap, repeat, for at most 32 rounds. This pull request replaces that loop with the Kullback-Leibler projection onto {w : sum(w) = total, w <= cap * d} in log space (_project_softmax_log_weights_ in solve.py): log_w <- min(log_w + s, log cap), with one common shift s.

  • How the step finds s. _capped_log_shift runs active-set rounds, each one float64 pass over the records. With C the records already at their caps, the next shift solves sum(cap[C]) + exp(s) * sum(w[not C]) = total. That shift bounds the answer from below for every C, so C only grows, and a round that adds no record ends the search. The rounds stop at the current shift when the capped records' caps already hold the total.
  • Worst case. An adversarial input can need one round per record. After 8 rounds, _sorted_capped_log_shift finishes with one sort over the remaining records, so the worst case costs O(n log n). The sort sums in log space, so a weight that underflows float64 still counts. The rounds also hand over to the sort when the uncapped weights sum below float64's normal range. Both paths take the logarithm of a positive remainder total - sum(cap[C]) unchanged, so a remainder below that range still sets the shift.
  • Precision. The shift carries the float64 rounding of its sums. That rounding grows with how far below the total the uncapped weights sit and, in the sort, with their number. Three tests pin it. On 1,588,854 weights, the full-scale measurement's count, one holds the rounds within 1e-13 of the total and the sort within 1e-11. With the same count 690 nats below the total, another holds the rounds within 1e-12 and the sort within 1e-9. A million subnormal weights whose sum stays normal leave the total 1.5e-11 off by the rounds and 1.0e-11 by the sort on arm64 macOS. The solver rounds log_w to float32 after every projection, so no solve resolves these figures.
  • Receipt. options["iterate_selection_receipt"]["softmax_in_loop_max_cap_ratio"] records the largest ratio of a realized in-loop weight to its float64 cap, over every forward pass and the closing iterate, before the closing projection. It replaces softmax_cap_rounds_exhausted_epochs.
  • The ACS local-area tool. tools/build_us_acs_local_release.py renames that key in calibration_summary.json and in the build manifest's calibration block for every build. Under the default --mass-parametrization projection the tool writes null there, as it did under the old key. --stage package now refuses a summary that holds a count under the old key and lacks the new one. A softmax solve by the old loop wrote such a summary, and the two keys measure different things, so the tool cannot convert one to the other. The message says to run --stage calibrate again without --resume. With --stage all --resume, the calibrate stage skips such a checkpoint as finished, and the refusal comes at package.
  • The default path. Under the default "projection" parametrization, _optimize never calls the new step. Each line this pull request changes there either runs under softmax_mass alone or sets a variable only that branch reads. At 1568979, the default solves still reproduce optimizer_bda72cb02.py bit for bit in all seven cases of test_defaults_reproduce_the_pre_change_optimizer_bytes, and the best-iterate oracle pins in test_solve.py still pass. Outside solve.py, only the ACS local-area tool passes mass_parametrization among the packages and tools, and its flag defaults to projection. No weight in a build with default settings changes.

Invariants the tests hold

test_softmax_cap_projection.py checks the projection on every input Hypothesis draws, 300 examples per property. The inputs include zero design weights (zero caps), a cap of 1 (the caps sum to the total), and totals from 5% to 100% of the caps' sum.

  1. Conservation and caps. sum(exp(P(x))) == total (rel 1e-12), and P(x) <= log cap. A record with zero weight or a zero cap stays at zero.
  2. Idempotence and shift invariance. Projecting twice gives the result of projecting once, P(P(x)) == P(x), and so does adding a constant to every log-weight first, P(x + c) == P(x).
  3. Feasible inputs. An input already within its caps after the shift moves by the shift alone.
  4. KKT of the KL projection. Every uncapped record moves by one common shift, and every capped record would pass its cap under it.
  5. An independent reference. The result equals a 60-digit Decimal water-fill written from the definition. The step agrees with itself when limited to 0, 1 or 2 active-set rounds before the sort. A 14-record chain that needs 12 rounds goes to the sort and matches the reference.
  6. Float32, as the solver runs it. The clamp holds in log space, and the realized total * softmax(log_w) sits within its float64 caps to 1e-5.
  7. The measured step. The full-scale measurement on Modal ran the step at commit 4bddde6. Where that step settles in its rounds, the current step returns the same shift and round count bit for bit. The test loads a copy of that step and checks its SHA-256.
  8. Precision. Three tests, each on a million records or more, hold the total to the float64 rounding of the shift's sums by both paths.
  9. A remainder below float64's normal range. Where the caps leave the other records between 2**-1074 and 2**-1022, the projection matches a 50-digit decimal bisection on the shift that shares no code with the solver or the water-fill. Tests on the review's two inputs, through both entry points, a 12-case table at totals of 1e-300, 4e-308 and 1e-308, and a drawn property allow 1e-9 of each weight plus 1e-11 of the total. At totals below 2**-1037, 12 more cases and a second property, on remainders of 1 to 64 steps of 2**-1074, hold each weight to four steps per held cap plus 1e-9 of itself. Four cases each give totals of 1, 2, 3 and 7 steps to records under caps none reaches, and hold each weight to 1e-9 of itself.

In test_l2_basis.py:

  • Receipt bound. The receipt stays at or below 1 + 1e-5 for every capped softmax solve the two properties draw, and holds None without a cap. That includes caps of 1, 1.001 and 1.05, where the cap binds on nearly every record; at a cap of 1 the solve returns the design weights.
  • No receipt under projection. Projection solves record no softmax receipt.

In test_us_acs_local_release_tool.py: --stage package refuses a summary with a count of 713 or 0 under the old key and no new key, and leaves no release directory. It packages a summary whose old key holds null, one with the new key (a ratio or null), and one with both keys, and each manifest carries the new key alone.

Where items 1 to 8 compare weights, they use weight units (rtol 1e-9 and atol 1e-12 × total), not log units. When the caps nearly meet the total, the uncapped records hold a small remainder, and their float64 rounding amounts to a few ulps of the total: large in log space, small in weight space. Item 9 converts each weight's float64 log to a 50-digit decimal before taking its exponential, so a subnormal weight keeps its value in the comparison.

Full-scale measurement (Modal)

experiments/us-acs-local-l2-basis-20260928/exact_cap_modal.py reran the ACS local release surface on Modal: 1,588,854 households, 4,459 targets, a 5x cap and 800 epochs. It used two configurations whose earlier runs ran out of rounds. Each ran under the new step and under a copy of the old loop in the script, and recorded the largest in-loop ratio at every forward pass (results/exact_cap.md):

Configuration Cap step Largest in-loop weight / cap Steps out of rounds Cap step time Final loss National ESS
share 0.5, chi-square λ 0.03 exact projection 1 + 9.0e-6 0 of 800 12.7 ms 0.018991 21,834
share 0.5, chi-square λ 0.03 32-round loop 1 + 1.2e-5 713 of 800 53.8 ms 0.019169 21,835
share 0.9, no penalty exact projection 1 + 9.0e-6 0 of 800 22.5 ms 0.031293 93,609
share 0.9, no penalty 32-round loop 1 + 8.7e-6 705 of 800 48.7 ms 0.031365 93,598
  • The loop left the weights a float32-sized amount past the cap, about what the exact step leaves. No earlier run had recorded how far.
  • On projected vectors, a float64 normalizer removes most of the overshoot. exact_cap_float32.py moved a softmax run's final weights by a step-sized random perturbation and projected them, 12 times at full scale. The script realized them in float32, as the solve does: they reached 1 + 8.5e-6 of their caps, and the normalizer missed the total by up to 8.2e-6. With a float64 normalizer, the largest ratio fell to 1 + 4.9e-7 (results/exact_cap_float32.json). No run took the loop's overshoot apart this way.
  • Float32 also ran the loop out of rounds. Its shift subtracted a float32 logsumexp from log(total) in float64, which bottoms out at the float32 rounding residual of log(total) (7.8e-8). Each round, that shift lifts one to three capped records whose log caps fall below 2 in magnitude one float32 step over their caps. On vectors the projection had already settled, the loop still ran out in 10 of 12 trials.
  • The new step settles in one to three rounds on every step at full scale, costs 2.2 to 4.2 times less, and records the in-loop overshoot.
  • Final metrics. ESS agreed within 0.1%. At λ = 0.03, the loop run reproduced the grid's run (0.019169), and the earlier rerun gave 0.019104. The projection's 0.018991 falls 0.6% to 0.9% below those three, from one run.

docs/calibration-l2-basis.md replaces its "known limitation" section with this account, and the experiment README adds it. The doc still recommends projection at that scale: softmax's training loss at λ = 0.03 exceeds projection's by 5%.

Merges with main and re-pins

solve.py's bytes carry an attestation, so every edit to it, a docstring included, moves the same digests. A tool writes each one:

  • EXPECTED_HASHES seed_map and seed_protocol, the loader golden and the US spec_sha256: tools/repin_us_spec_engine_contracts.py.
  • docs/evidence/spec-engine/us-f0-coverage.json: tools/spec_engine_coverage.py (41 of 41 inventory checks).
  • The calibrate parity pins (implementation_hash and node_key): tools/graph_parity_repin.py calibrate, and the direct call's bytes still equal direct.csv.

9a89cf8 merges main at 68bbff7, and 1568979 merges main at 085672f. In each, five files conflicted, and each of them holds digests that a tool recomputes. Both merges take main's text in every conflicted block, keep this branch's three comment sentences beside it, and let the tools write the values. Outside those five files, 1568979 equals git's own merge of its parents.

Main's public solve (#1601) also edited solve.py, and that file merged without a conflict. calibrate, the one function both sides changed, carries main's body and this branch's docstring. Main's new solve_constraint_system passes mass_parametrization to _optimize, so a softmax call through it runs the exact step; it records no softmax_in_loop_max_cap_ratio, and no test calls it with softmax.

The fixture and the experiment README cite commit 4bddde6, so this lands as a merge commit, which keeps that commit in main's history.

What the reviews found

An independent review found that _sorted_capped_log_shift floored a positive remainder at float64's smallest normal value, 2.2e-308, before taking its logarithm. Where the caps left less than that, the floor inflated the remainder. On the review's two inputs, the projected total came out 10% over at a total of 1e-308, and 1.2e-8 of itself over at 1e-300. Every test test_softmax_cap_projection.py then held passed under the floor.

  • bbbae3c masks a nonpositive remainder before the logarithm, so a positive one, subnormal included, enters it unchanged. It adds the first 15 tests of item 9.
  • 03ee2ea corrects _capped_log_shift's docstring and docs/calibration-l2-basis.md: a remainder below the normal range reaches the sort only up to rounding, and the rounds also take its logarithm unchanged.
  • 6544a01 re-pins the digests that solve.py's new bytes move, with the same three tools.
  • 3a0b4f7 adds the other 17 tests of item 9, at totals small enough for float64 to resolve one step of 2**-1074. The first 15 allow 1e-11 of the total, at least 1e-319, so they cannot see a smaller floor. 74238ac prints the decimal values in the failure messages. Neither commit touches the source.

On 4,000 random inputs whose remainders all stay in float64's normal range, the softmax step at 6544a01 returns f728a31's results bit for bit.

A second independent review, at 1568979, raised one P2 finding and none more severe. The package refusal test looked for JSON files alone, so it would pass a refusal that left an empty release directory, and the next package would stop on that directory. 2c49e27 makes the test assert that the refusal leaves no release directory.

Tests

At 1568979, on macOS arm64 under Python 3.14.7, one pytest process per file:

  • Without policyengine-us, 11 files: 601 passed and 1 skipped. test_softmax_cap_projection.py 54, test_l2_basis.py 52, test_solve.py 82, test_solve_constraint_system.py 10, test_us_acs_local_release_tool.py 314, test_bakeoff_us_support_mix_tool.py 28, test_graph_parity_pins.py 11, test_spec_engine_loader.py 10, the engine-free test_spec_engine_inventory_coverage.py 13, test_spec_engine_seeds.py 13 and test_spec_engine_field_usage.py 14. The skipped test needs MICROCOSM_US_CHRONICLE_FACTS set to the pinned consumer-facts feed.
  • With policyengine-us 2.2.1, three files: 10 passed (test_spec_engine_coverage_tool.py 7, the engine-contract inventory test 2, and the one test in test_us_multispine_pool_tool.py that holds spec_sha256).
  • tools/repin_us_spec_engine_contracts.py --check, with and without --legacy-only, and tools/spec_engine_coverage.py --check exit 0. tools/ci_test_plan.py verify reports ok over 968 test files.
  • tools/graph_parity_repin.py has no check mode, so a script ran its repin with the write replaced by a comparison. pins.json matched, and the direct call reproduced direct.csv.
  • ruff check . passes, and so does ruff format --check on solve.py and the three re-pinned Python files. The projection test file passed both at 74238ac.
  • Mutants of one line of _sorted_capped_log_shift at 74238ac, each in a copy of the source, against the projection tests:
    • the old floor at 2**-1022, and twice that: all 32 tests of item 9 fail, and the 22 older ones pass;
    • an inner mask that sends every positive remainder to 1: 45 fail, 13 of them older;
    • floors at 2**-1060 and 1e-315: the 17 tests 3a0b4f7 added fail, and 9 more fail at 1e-315;
    • a floor of two steps of 2**-1074: the four few-step-total cases fail;
    • a floor of one step changes no input and passes, since no positive float64 lies below it.
  • Mutants at d57d336 and f728a31, whose step code differs only in docstrings, each in a scratch copy:
    • at d57d336, ten changes to the step that change a result (an off-by-one in the capped count, a wrong sort key, a dropped hand-off among them) each fail at least two of the projection tests;
    • at d57d336, five changes that leave every weight the same on 410 adversarial inputs (< for <= at the cap, for example) pass;
    • at f728a31, four changes against the three precision tests each fail at least one;
    • at f728a31, four changes to the package refusal each fail at least one of its tests.
  • Item 9's bounds held in scripts that moved every exp and log result by up to three ulps, a stand-in for other platforms' kernels. The first 15 tests went through those scripts at 6544a01, the other 17 at 74238ac.

At 2c49e27, which edits test_us_acs_local_release_tool.py alone, under the same setup:

  • That file, in its own process: 314 passed and 1 skipped. tools/repin_us_spec_engine_contracts.py --check exits 0 and tools/ci_test_plan.py verify reports ok over 968 test files, so no pin moved. ruff check and ruff format --check pass on the test file.
  • A scratch copy of the tool that runs the refusal after release_dir.mkdir passes the refusal test as it stood at 1568979 and fails both its cases at 2c49e27. An unchanged copy, loaded the same way, passes both.

CI runs the full suites on the pushed head, on Linux. solve.py counts as shared code, so tools/ci_test_plan.py select-countries turns on both countries. CI then runs lint, the engine-free suite on Python 3.13 and 3.14, the US and UK engine suites on both, UK integration, the wheel check and the installed-emitter check.

axiom: n/a: calibration solver and release tooling; no policy rule changes.

🤖 Generated with Claude Code

MaxGhenis and others added 24 commits October 2, 2026 08:14
…pped simplex

Each softmax step alternated a softmax-invariant renormalization with a
clamp to the ratio cap, for at most 32 rounds. Replace that loop with the
exact projection onto {w : sum(w) = total, w <= cap * d} in log space: one
common shift, then a clamp, with the shift found by active-set rounds (each
a lower bound that only adds records to the capped set) and finished by a
sort if they run long. The shift is computed in float64.

The selection receipt records softmax_in_loop_max_cap_ratio, the largest
ratio of a realized in-loop weight to its float64 cap before the closing
projection, in place of the exhaustion count. The projection parametrization
is untouched.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…scale cap-step launcher

The tool's calibration summary and build manifest carry
softmax_in_loop_max_cap_ratio in place of the exhaustion count. The sweep
harness records each batch's selection receipt. exact_cap_modal.py runs one
softmax configuration under the committed kernel and under microcosm#1078's
32-round loop, with the ratio at every forward pass, the cap step's rounds
and its wall time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… projection

Four Modal runs of the ACS local surface (1,588,854 households, 4,459
targets, a 5x cap, 800 epochs), at two softmax configurations whose earlier
runs ran out of cap rounds, each under the committed projection and under
microcosm#1078's 32-round loop (results/exact_cap.md, results/exact_cap/).
The projection never ran out (one to three active-set rounds per step,
12.7-22.5 ms); the loop ran out on 705-713 of 800 steps (48.7-53.8 ms). The
largest in-loop weight over its cap is 1 + 9.0e-6 under the projection and
1 + 8.7e-6 to 1.2e-5 under the loop.

exact_cap_float32.py measures where that residual comes from and why the loop
ran out; it runs on Modal from the sweep's volume.

The solve.py change is the active-set comment, now citing those runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…d loop ran out

On full-scale vectors the exact projection had already put within their
caps, microcosm#1078's loop still ran out of rounds in 10 of 12 trials: its
shift is log(total) in float64 minus a float32 logsumexp, which bottoms out
at log(total)'s float32 rounding residual (7.8e-8), and that lifts the 1-3
capped records with log caps below 2 in magnitude one float32 step over each
round. With a float64 normalizer the projected vectors sit within 1 + 4.9e-7
of their caps; the float32 softmax's own total error (up to 8.2e-6 here) is
the rest of the in-loop residual.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…ests solve.py moves

docs/calibration-l2-basis.md replaces the cap-rounds limitation with the
projection, its tested invariants and the full-scale measurement; the
experiment README adds the re-measurement; a changelog fragment records the
change and the #1078 fragment drops its exhaustion-count claims.

solve.py's bytes are attested by the US spec-engine seed protocol and the H1
calibrate parity case. Re-pinned on this tree:
- EXPECTED_HASHES seed_protocol be39eb6b -> 5795dc07, seed_map 085d8d39 -> 292ad19c
  (build_inventory_coverage; tools/spec_engine_coverage.py --check: 41/41)
- US spec_sha256 e0b757ce -> edcd6475 (docs/evidence/spec-engine/us-f0-coverage.json,
  test_us_multispine_pool_tool.py)
- loader golden fee5893a -> 5135dd79 (test_spec_engine_loader.py)
- calibrate parity pins (tools/graph_parity_repin.py calibrate; direct-call
  bytes unchanged)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings main 4a36edc in by merge (base b7b4c29). Both sides moved the
US seed protocol and seed map digests since the base, so the five pin
files conflicted. The merge regenerates them for the merged tree with the
repo's tools instead of taking either side's hash:

- tools/repin_us_spec_engine_contracts.py rewrites EXPECTED_HASHES
  seed_map and seed_protocol, the loader golden and the multispine
  spec_sha256. Its first pass reads the stale pins and counts 40 of 41
  inventory items covered, so a second pass restores 41; --check passes.
- tools/spec_engine_coverage.py regenerates us-f0-coverage.json
  (--check: 42305/42305 fields, 41/41 inventory checks). The multispine
  pin equals the JSON's spec_sha256.
- tools/graph_parity_repin.py calibrate re-pins the calibrate parity
  case; its direct.csv bytes did not move.

same_edit.py 16ff6eb 4a36edc flagged nothing. In the engine-free venv,
the pre-fix projection tests, test_l2_basis.py, the spec-engine inventory
and loader tests, the graph parity pins and the ACS tool's two penalty
tests pass on this tree (99 tests).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…w S2)

The softmax cap step's two exits lifted every record that could reach its
cap to that cap. The active-set rounds took that exit whenever rounding
left no room after the capped records' caps, or no uncapped mass; the sort
took it when no record met its test. Either way the total could end up to
the uncapped records' caps over. A finite log-weight that underflows
float64 also counted as no weight.

_capped_log_shift now returns the current shift when the room is not
positive: its lower bound keeps the room at least the uncapped records'
share, so a room at or below zero is float64 rounding, and those records
keep a rounding-sized share. When the uncapped weights sum below float64's
normal range, the rounds hand over to _sorted_capped_log_shift. The sort
sums weights in log space with logcumsumexp and includes every finite
log-weight. When room_k is not positive it caps exactly the first k
records, it clamps the answer to the previous record's cap shift so
rounding cannot uncap that record, and it caps every record that carries
weight only when their caps hold less than the total.
_cap_every_record_shift is gone. The common path's arithmetic is unchanged.

Invariants, each checked over up to 300 Hypothesis draws in
test_softmax_cap_projection.py: the projection conserves the total to
1e-12 and respects every cap; zero weights and zero caps, drawn
independently, stay at zero; it is idempotent and invariant to a constant
added to the log-weights; a feasible input moves by the shift alone; it
meets the KL projection's KKT conditions; it equals a 60-digit decimal
water-fill; the rounds and the sort agree; and in float32 the realized
weights stay within their caps to 1e-5. A new strategy lets the caps of a
held set meet the total, or nearly, while the other records sit 45 to
1,100 nats below their caps. A verbatim, SHA-checked copy of the measured
cap step (4bddde6, tests/fixtures/pre_cap_step_fix/) pins the new step
bit for bit wherever the measured one settles in its rounds (review S1).

The measured step fails 11 of the file's 19 tests; this one passes all 19.
Six mutants of the new code each fail at least one test: the sort treating
a non-positive room as +inf, the old all-capped exit, handing over only at
zero uncapped mass, no previous-cap clamp, dropping underflowed records,
and the no-k branch returning the lower bound.

The repo's tools re-pin what the new solve.py bytes move: EXPECTED_HASHES
seed_map and seed_protocol, us-f0-coverage.json (41/41 inventory checks),
the loader golden, the multispine spec_sha256 (equal to the JSON's) and
the calibrate H1 parity pins (direct.csv unchanged).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The experiment scripts' copies of microcosm#1078's cap step cited
b115745. They now cite b7b4c29, the #1078 head this branch started
from. solve.py is byte-identical at the two commits, so the copies match
either one.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings main 3a9c808 (#1484) in by merge. Both #1484 and this branch
moved the US spec hash, so us-f0-coverage.json and the multispine
spec_sha256 conflicted. The repo's tools regenerate both for the merged
tree: tools/repin_us_spec_engine_contracts.py rewrites the multispine pin
(--check passes), and tools/spec_engine_coverage.py rewrites the JSON
(--check: 42210/42210 fields, 41/41 inventory checks). The pin equals the
JSON's spec_sha256. This branch's seed protocol and seed map pins hold
unchanged, and neither solve.py nor the calibrate parity pins moved.

same_edit.py 8ae6934 3a9c808 flagged nothing. In the engine-free venv
the projection, L2-basis, spec-engine inventory, loader and field-usage
tests, the graph parity pin and H1 parity tests, and the ACS tool's eight
penalty tests pass on this tree (129 tests).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Brings main 3293730 (#1455, the emitter collector hostname) in by merge.
It merged cleanly and touches no attested module or pin: the repinner's
--check and tools/spec_engine_coverage.py --check (42210/42210 fields,
41/41 inventory checks) pass on this tree, and same_edit.py f86e9e1
3293730 flagged nothing.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, N5)

The measured-step differential holds only where every nonzero weight sits
in float64's normal range: below it the current step hands its rounds over
to the log-space sort, which the measured step lacked. The test docstrings
and docs/calibration-l2-basis.md now say so, and the test docstring names
the quantity that never fell more than 1% between passes: each forward
pass's largest weight-to-cap ratio.

N2: _IN_LOOP_CAP_TOLERANCE and the ACS tool test's matching bound say they
hold for test sizes only; the release surface reached 1 + 9.0e-6.
N4: the docs and the experiment README credit the float32 softmax only
with the projected vectors' residual, the one exact_cap_float32.py
decomposed.
N5: the README scopes "the softmax results stand" to the two rerun
configurations.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Merge main at 1e88319 (#1532), 1,016
commits past the merge base 3293730. Main has no commit on solve.py, the
calibrate tests, the cap-step fixture or the exact-cap evidence, so the
branch's 18 files that only it changed keep their bytes from 47c0625.
docs/calibration-l2-basis.md, the experiment README and sweep.py,
test_us_acs_local_release_tool.py and tools/build_us_acs_local_release.py
merged on their own and carry the branch's edits unchanged.

Five files conflicted. All five hold digests that a tool recomputes. Each
was resolved by taking main's side and then running the tool:
- docs/evidence/spec-engine/us-f0-coverage.json: main's side, rewritten
  by tools/spec_engine_coverage.py.
- packages/microcosm-build/src/microcosm/build/spec_engine/inventory_coverage.py:
  main's EXPECTED_HASHES (source_manifest dc387988 kept), the branch's
  microcosm#1096 comment restored after main's last comment line, then
  seed_map and seed_protocol re-pinned by
  tools/repin_us_spec_engine_contracts.py.
- packages/microcosm-build/tests/engine_free/shared/test_spec_engine_loader.py:
  main's golden and comment lines, the branch's microcosm#1096 line
  restored, then the golden re-pinned by the same repinner.
- packages/microcosm-build/tests/engine_workflow/us/test_us_multispine_pool_tool.py:
  main's spec_sha256 and comment lines, the branch's microcosm#1096 line
  restored, then spec_sha256 re-pinned by the same repinner.
- packages/microcosm-graph/tests/fixtures/parity/kernels/calibrate/pins.json:
  main's side, then re-pinned by tools/graph_parity_repin.py calibrate.

Pins that moved, and the tool that wrote each:
- EXPECTED_HASHES seed_map bcb012ed -> d216f75c and seed_protocol
  e1f88676 -> 2316aa41: tools/repin_us_spec_engine_contracts.py.
- Minimal-loader golden spec_sha256 d5c303a4 -> eeba65f7: the same tool.
- US multispine spec_sha256 3dabec5c -> c15471ae: the same tool.
- us-f0-coverage.json, two map_sha256, two protocol_sha256 and two
  implementation_sha256 to the seed values above, and two spec_sha256 to
  c15471ae: tools/spec_engine_coverage.py (42394/42394 configuration
  fields; 41/41 inventory checks).
- calibrate.adam@1 implementation_hash f6554bfe -> 19806a72 and node_key
  b6020102 -> c767438d on arm64/darwin/py3.14:
  tools/graph_parity_repin.py calibrate. direct.csv did not move.

The repinner and the coverage tool each ran twice. The first repinner
pass read stale pins and wrote covered_item_count 40 into
test_spec_engine_coverage_tool.py; the second pass, after the coverage
report was regenerated, restored 41, so that file equals main's. Both
tools then passed --check. ruff format on the three repinned .py files
changed the repinner's single quotes to double quotes and nothing else.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Main gained #1600, #1605, #1590, #1047, #1592, #1598 and #1545 since the
1e88319 this branch last merged. #1598 changed microcosm-calibrate
(hierarchy value ranks) and an attested kernel module and regenerated the
shared pins, so the five pin files conflicted. Each conflict hunk takes
main's text, with this branch's #1096 comment sentence kept after main's,
and the tools then wrote the values for the merged tree:

- docs/evidence/spec-engine/us-f0-coverage.json: main's five hunks, then
  rewritten by tools/spec_engine_coverage.py (two map, two protocol, two
  implementation and two spec digests; 42394/42394 fields, 41/41 checks).
- spec_engine/inventory_coverage.py: main's hunk and its hierarchy comment,
  plus the #1096 sentence; tools/repin_us_spec_engine_contracts.py wrote
  seed_map d29d95be and seed_protocol f3738669 (main: 0c19b903, 15e6cad1).
- test_spec_engine_loader.py: main's hunk plus the #1096 comment line; the
  repinner wrote the golden 0b417bfc (main: 99f9b82e).
- test_us_multispine_pool_tool.py: main's hunk plus the #1096 comment line;
  the repinner wrote spec_sha256 c79a1d3f (main: 98d58365).
- parity/kernels/calibrate/pins.json: main's line, then
  tools/graph_parity_repin.py calibrate wrote implementation_hash 20180a24
  and node_key 86ae2227 (main: 0c669ad2, fbab5f42). direct.csv, graph.json
  and inputs.csv did not move, so the default path's bytes are main's.

The repinner and the coverage tool ran twice each, then both passed
--check. ruff format changed only the quotes the repinner writes.

tools/build_us_acs_local_release.py and its test merged without conflict.
Main's #696 and this branch both changed do_package and _parse_args, in
separate statements: main swapped the refresh recipe's staging value and
added --block-ladder; this branch renamed one calibration key and reworded
the --mass-parametrization help.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
_capped_log_shift hands its rounds to the log-space sort when the uncapped
mass sums below float64's normal range, and its docstring said that every
uncapped weight had then lost its precision. The converse does not hold:
a sum still in the normal range can be made of subnormal terms. Where a
million records share one subnormal weight the total ends 1.5e-11 off,
past the 1e-12 the tests pin on up to 40 records.

Handing over whenever one uncapped weight is subnormal does not fix that.
The sort is 1.0e-11 off on the same input, and on a million distinct
subnormal weights it is about 270 times worse than the float64 sum it
would replace (9.9e-12 against 3.6e-14): logcumsumexp adds one record at
a time and rounds each step at the spacing of a float64 near -700. So the
code is unchanged and the claim is narrowed. The solver rounds log_w to
float32 after every projection, up to 5e-7 in a weight, so no solve
resolves any of this.

solve.py changes in docstrings only. _capped_log_shift says what the
hand-off is for and gains a precision note with two regimes: weights in
the normal range (the total within 1e-13 by the rounds and 1e-11 by the
sort on 1,588,854 records) and subnormal weights whose sum is still normal
(up to about 2**-53 of the sum per term). _sorted_capped_log_shift and
_project_softmax_log_weights_ point at it, and docs/calibration-l2-basis.md
says the same.

Two tests pin the note: one at the full-scale size with normal weights,
one on the million-record case, which also fails if the step becomes more
precise there and the figures go stale.

solve.py's bytes are attested, so the same pins move again:
tools/repin_us_spec_engine_contracts.py wrote seed_map 08a7dd1a,
seed_protocol 46955c95, the loader golden b310bf3a and the multispine
spec_sha256 eb2a8fe8; tools/spec_engine_coverage.py rewrote
us-f0-coverage.json; tools/graph_parity_repin.py calibrate wrote
implementation_hash 8496f213 and node_key f761929e. direct.csv did not
move.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…eview R4)

Before this branch a softmax solve's calibration_summary.json recorded
softmax_cap_rounds_exhausted_epochs, a count of epochs; since, it records
softmax_in_loop_max_cap_ratio, a weight-to-cap ratio. The ACS local-area
tool's package stage copies the new key into the build manifest with
dict.get, so a checkpoint calibrated by the old tool packaged with null
there. Null is the value of a solve with no softmax cap step, and that
checkpoint ran a capped softmax solve with the old step. The two receipts
measure different things, so one cannot be turned into the other.

do_package now refuses such a summary (the old key holds a value that is
not null and the new key is absent) before any release directory exists.
The message says the solve predates the exact cap step and how to
calibrate again. A projection solve from before the change recorded the
old key as null, and an older summary records neither key; both package
as before.

Tests: the refusal for a count of 713 and of 0, and four summaries that
still package (old key null, new key with a ratio, new key null, both
keys). docs/calibration-l2-basis.md and the changelog fragment describe
the refusal, and the fragment says that every build's summary and
manifest now name the new key, null under the default projection.

No attested module changes, so no pin moves.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…pass)

The note that 03035da added to _capped_log_shift gave its first regime
as "every uncapped weight in float64's normal range" and said that on
1,588,854 records the sort leaves the total within 1e-11. That does not
hold across the regime. With 1,588,854 uncapped weights 690 nats below
the total, each 2.2e-300 and well inside the normal range, the sort ends
2.9e-11 off: its running log-space sum rounds once per record at the
spacing of a float64 near -700, 1.1e-13. The rounding follows the size of
the log and the record count, not normal against subnormal.

The note now says that and pins three inputs in place of two regimes:
weights the size a solve's are (log-weights 9 to 24 nats below the
total's; rounds within 1e-13, sort within 1e-11), the same count 690 nats
down (rounds within 1e-12, sort 2.9e-11 measured and pinned within 1e-9),
and the million subnormal weights of the first pass.
docs/calibration-l2-basis.md says the same. solve.py again changes in
docstrings only (its syntax tree equals 6bb9c46's and d57d336's apart
from docstrings), so no solve changes.

One new test, test_normal_weights_far_below_the_total_cost_the_sort_digits,
pins the second input with upper bounds only: the sort's rounding is a
random walk there, so another platform draws another value.

solve.py's bytes are attested, so the same pins move again:
tools/repin_us_spec_engine_contracts.py wrote seed_map 5989ecc2,
seed_protocol 23932edc, the loader golden e4557719 and the multispine
spec_sha256 93dd4798; tools/spec_engine_coverage.py rewrote
us-f0-coverage.json; tools/graph_parity_repin.py calibrate wrote
implementation_hash 715d2a7a and node_key 589e1c6a. direct.csv did not
move.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…und 1, finding 1)

_sorted_capped_log_shift took log(room.clamp_min(float64 tiny)), so a
positive room below float64's smallest normal value (2.2e-308) became that
value and the shift and the projected total came out too large: 10% over
at a total of 1e-308 and 1.2e-8 of itself over at 1e-300 on the review's
inputs. Mask only the nonpositive rooms before the logarithm; the outer
where still gives them a candidate of -inf.

Tests: the review's two inputs through both entry points, a table of
rooms across the subnormal range (three totals, one or two held records,
one or five uncapped ones) and a property over drawn subnormal rooms, all
against a 50-digit decimal bisection on the shift. The docstrings and
docs/calibration-l2-basis.md say the sort takes the remainder's logarithm
as it is. The default projection path is untouched. Pins follow in the
next commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…w round 1, finding 1)

The docstring of _capped_log_shift and docs/calibration-l2-basis.md said a
remainder below float64's normal range comes only with an uncapped sum
below it, so it always reaches the sort. That holds in exact arithmetic;
float64 rounding can leave such a remainder to the active-set rounds (two
records, one capped at its own weight and one at float64's smallest normal
value, do it on 2,295 of 7,200 inputs). The rounds take math.log of the
remainder as it is, so the answer is right either way. Both now say "up to
rounding" and that the sort and the rounds both take the remainder's
logarithm as it is. The rest rewraps two paragraphs left with short lines.
No code changes; pins follow in the next commit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… round 1, finding 1)

solve.py's bytes feed the US seed protocol and the calibrate parity node,
so the two commits before this one move their pins. Every value below was
written by its tool; none by hand.

tools/repin_us_spec_engine_contracts.py (two passes, then --check rc 0):
- inventory_coverage.py seed_map 5989ecc2 -> cd5c2f2c, seed_protocol
  23932edc -> 75891f4d
- test_spec_engine_loader.py golden e4557719 -> a7b6a302
- test_us_multispine_pool_tool.py spec_sha256 93dd4798 -> b768e100
- test_spec_engine_coverage_tool.py: pass 1 moves its count, pass 2
  restores it; no change.
tools/spec_engine_coverage.py (two passes, then --check rc 0; 42394/42394
configuration fields, 41/41 inventory checks): us-f0-coverage.json's eight
digest lines to match.
tools/graph_parity_repin.py calibrate: pins.json implementation_hash
715d2a7a -> 1b3e2a71, node_key 589e1c6a -> f9472a28 (arm64/darwin/py3.14).
direct.csv, graph.json and inputs.csv are byte-identical before and after
and equal to main's.

ruff format changed only the quotes the repinner writes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…, check P3-1 and P3-2)

The section-8 tests of the softmax cap projection allowed 1e-11 of the
total, at least 1e-319 at their totals, so a floor of 2**-1060 on the sort's
remainder passed all 37 tests. Add a table and a property of rooms 1 to 64
steps wide at totals below 2**-1037, bounded at four steps per held cap plus
1e-9 of each weight, and a table of totals 1 to 7 steps wide that no positive
cap reaches, bounded at 1e-9 of each weight with no absolute part. Reword the
comment that gave the old floor's miss as an amount: 2**-1022 - room is an
upper bound on it.

Test code and comments only; no source file changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A failure message read each weight back through float, which rounds a
weight below one step of 2**-1074 to 0 or to 5e-324; print the decimal
values instead. Name the step table's totals to three digits (1e-320, not
9.99989e-321), give the exp bound its stated reach (four steps per held cap
hold for an exp three ulps off) and say the old floor raised only a
remainder below 2**-1022. Test code and comments only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Main gained #1612, #1596, #1603, #1601 and #1597 since the 68bbff7 this
branch last merged (45 commits, 174 files). #1601 ("US: one copy of each
shared helper") edited microcosm.calibrate.solve, an attested kernel
module, and regenerated the shared pins, so the five pin files conflicted.
No code or test file conflicted.

Each conflict block takes main's text, with this branch's #1096 comment
sentence kept after main's, and the tools then wrote the values for the
merged tree:

- docs/evidence/spec-engine/us-f0-coverage.json: main's five blocks (eight
  digest lines), then rewritten by tools/spec_engine_coverage.py (two map,
  two protocol, two implementation and two spec digests; 42395/42395
  fields, 41/41 checks).
- spec_engine/inventory_coverage.py: main's #1585 comment and digests, then
  the #1096 sentence after it; tools/repin_us_spec_engine_contracts.py
  wrote seed_map 8d0542f7 and seed_protocol 3ab23e82 (main: 270cf649,
  a696ad74; this branch before: cd5c2f2c, 75891f4d).
- test_spec_engine_loader.py: main's digest line under the #1096 comment
  line; the repinner wrote the golden fac42090 (main: 1ff3b42c; branch:
  a7b6a302).
- test_us_multispine_pool_tool.py: the #1096 comment line and main's
  digest line; the repinner wrote spec_sha256 fa75bd68 (main: bd526d8c;
  branch: b768e100).
- parity/kernels/calibrate/pins.json: main's line, then
  tools/graph_parity_repin.py calibrate wrote implementation_hash 07e4330f
  and node_key 2972c813 (main: 018974ad, 30ad70b1; branch: 1b3e2a71,
  f9472a28). direct.csv, graph.json and inputs.csv did not move and equal
  main's, so the default path's bytes are main's.

The repinner and the coverage tool ran twice each, then both passed
--check; the repinner's first pass moved test_spec_engine_coverage_tool.py's
count and its second restored main's. tools/ci_test_plan.py verify passes
with main's 968 test files. ruff format changed only the quotes the
repinner writes.

solve.py merged without conflict. #1601 and this branch both changed
calibrate: #1601 moved its option checks into _check_mass,
_check_epochs_and_weight_ratio, _checked_l2_options and
_check_l2_anchor_shape, and this branch rewrote the mass_parametrization
paragraph of its docstring. The merged function has #1601's code and this
branch's docstring. Every other definition is one side's alone: the merged
file is main's plus exactly this branch's edit. #1601's new
solve_constraint_system calls _optimize, which this branch changed, with
the signature it still has; under mass_parametrization="softmax" it now
runs the exact per-step projection.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
… (review round 2, P2)

The refusal test checked for no package_result.json and no JSON under
releases/, so a guard moved to just after release_dir.mkdir passed it: the
refusal would leave an empty release directory, and packaging the
checkpoint once it is calibrated again would stop at _new_release_dir.
Assert that the release directory the package stage writes
(RELEASE_DIR_PARTS under --out) does not exist. With the guard moved, both
cases (713 and 0) now fail; the tool as it stands passes.

Test code and a docstring only; no source file changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MaxGhenis
MaxGhenis merged commit 429d7a0 into main Nov 15, 2026
12 checks passed
MaxGhenis added a commit that referenced this pull request Nov 15, 2026
#1096's exact softmax cap projection in solve moved the shared spec
pins, so both conflicts were pin files. us-f0-coverage.json takes
main's version and is regenerated by spec_engine_coverage.py. In
test_us_multispine_pool_tool.py both pin comments are kept and the
tools recompute spec_sha256 (fa75bd68 on main, 1e727e1c here).

Repinned with the five-step sequence: repin --legacy-only, bundle
generation, repin twice, coverage. Then:
- repin, bundle and coverage --check: pass
- ci_test_plan.py verify: pass
- ruff check .: pass
- county focused suite (-n 4): 746 passed, 1 skipped
- spec-engine pin suites (-n 2): 116 passed
- national pin suites (-n 2): 481 passed

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis added a commit that referenced this pull request Nov 15, 2026
Main since 085672f: #1615 (the engine adapters read one year), #1618
and #1624 (reference documents trimmed to the keys their kernels read),
#1096 (solve's exact softmax cap projection) and #1602 (Belgium Child
rules bindings). None changes a file this branch changes except four
pin files, where #1096 re-pinned the digests solve.py moves:

- docs/evidence/spec-engine/us-f0-coverage.json (5 hunks)
- spec_engine/inventory_coverage.py (seed_map, seed_protocol,
  source_manifest)
- tests/engine_free/shared/test_spec_engine_loader.py (golden)
- tests/engine_workflow/us/test_us_multispine_pool_tool.py (spec_sha256)

Each hunk takes main's comment and values, with this branch's #776
comment lines after main's; then the tools write the values on the
merged tree:
- tools/repin_us_spec_engine_contracts.py: seed_map 2935a411...,
  seed_protocol e13541c1..., source_manifest ee208024... (this branch's
  value; main never moved it), loader golden 627e2563..., pool-tool
  spec_sha256 6fb922d2... (= the generator's printed digest).
- tools/spec_engine_coverage.py: the same digests in
  us-f0-coverage.json; 42457/42457 fields, 41/41 inventory checks.
- tools/generate_us_bundle_from_constants.py and
  tools/build_us_release_input_coverage_manifest.py rewrote nothing.

ruff format on the three repinned .py files (quote style). Every
--check mode (repinner, legacy repinner, coverage, generator, pool
engine contracts), ci_test_plan verify, the manifest comparison and
the transfer test's three contract digests agree with this tree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis added a commit that referenced this pull request Nov 15, 2026
Main gained 39 commits since 085672f, this branch's last merge:
#1615 (US and UK build simulations stop at the year they read), #1618
and #1624 (reference documents trimmed to the keys their kernels read),
#1096 (solve's opt-in softmax parametrization projects exactly onto the
capped simplex) and #1602 (Belgium's Child rules bindings and Axiom
input closure, still inactive).

Four files conflicted, all of them pin files. Each conflicted hunk takes
main's text, keeps this branch's comment sentences after main's, and
leaves the value to the tools.

- spec_engine/inventory_coverage.py, one hunk at seed_map and
  seed_protocol: main's three #1096 comment lines byte for byte, then
  this branch's three #1444 and #1453 lines byte for byte.
- tests/engine_free/shared/test_spec_engine_loader.py, one hunk: main's
  #1096 comment line, then this branch's two #1453 lines, then the
  golden value.
- tests/engine_workflow/us/test_us_multispine_pool_tool.py, one hunk:
  main's "attested bytes." line and its #1096 line, then this branch's
  #1453 sentence on two new lines (same words), then the spec_sha256.
- docs/evidence/spec-engine/us-f0-coverage.json, five hunks, digests
  only, each to main's side.

Git merged three other files that both sides changed:
tools/build_us_fiscal_refresh_release.py,
tests/engine_free/us/test_us_fiscal_refresh_builder.py and
tests/engine_free/us/test_us_post_export_scoring.py. In each, every
definition outside the pins was changed by one side, and the merged AST
equals that side's. In the tool, main changed seven helpers (among them
_dataset_from_frame and _materialize_base_simulation_columns) and this
branch changed _main, _with_local_jurisdiction_flags and
LOCAL_JURISDICTION_FLAG_SUPPORTS. The tool's imports hold main's
us_dataset_through and this branch's local-jurisdiction import. Main
touched no us_runtime module and no binding-identity list.

Pins on the merged tree, each written by its tool:

- tools/repin_us_spec_engine_contracts.py: seed_map 5230ab2f and
  seed_protocol 4ac422f9 in inventory_coverage.py; the golden 23b97b69
  in shared/test_spec_engine_loader.py; the US spec_sha256 97f2b938 in
  engine_workflow test_us_multispine_pool_tool.py. Its covered_item_count
  in engine_contract test_spec_engine_coverage_tool.py ends at main's 41.
- tools/spec_engine_coverage.py: us-f0-coverage.json (the seed map and
  protocol, the seed-stream implementation digest and spec_sha256, each
  twice); 42395/42395 configuration fields and 41/41 inventory checks.
- Unmoved by the merge, as the coverage tool observes them again:
  full_checkpoint 47d4474d and the stacked pool's code digest 3c5e14be,
  this branch's values on lines main did not touch.

tools/generate_us_bundle_from_constants.py --check reports the same US
spec_sha256, 97f2b938. tools/repin_us_pool_engine_contracts.py
--emit-json gives this branch's pinned manifest, 6e70bc74 over 1,059
rows. The release input coverage manifest built on the merged tree
equals the committed one. The calibrate parity fixture (direct.csv,
graph.json, inputs.csv, pins.json) has main's blob ids; this branch
changes nothing under microcosm.calibrate.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
MaxGhenis added a commit that referenced this pull request Nov 16, 2026
main's #1096 (exact softmax cap projection in solve) and this branch's
#1387 step both move the attested-source pins. The four conflicting pins
keep both comments and were recomputed with the five-step repin:
seed_map and seed_protocol, the loader golden vector, the pool tool's
US bundle spec_sha256 (now 21710776...) and us-f0-coverage.json.

Local verification on the merged tree: the three --check modes,
ci_test_plan.py verify, ruff check . and git diff --check pass; focused
ACS suites 828 passed, 1 skipped (-n 4); spec-engine pin suites 116
passed and national pin suites 481 passed (-n 2).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant