Exact-k ladder launcher + release plumbing: pool → k ∈ {N, 57,240, 20,000} datasets (#578 inc 3)

README.md

@@ -104,9 +104,9 @@ normal `uv run pytest` suite; the real-H5 mode above is a local/runbook step.
 
 ## Releasing & alerts
 
-Publishing uploads the locally built `releases/<id>/` artifacts to the Hugging
-Face dataset, tags the release, and updates `latest.json`. It runs on the build
-machine (it needs the freshly built H5), so it isn't a CI step:
+Standard publication uploads the locally built `releases/<id>/` artifacts to
+the Hugging Face dataset, tags the release, and updates `latest.json`. It runs
+on the build machine (it needs the freshly built H5), so it isn't a CI step:
 
 ```bash
 tools/publish_release.sh releases/<id> --repo-id policyengine/populace-us
@@ -117,6 +117,17 @@ tools/publish_release.sh releases/<id> --repo-id policyengine/populace-us
 publish CLI posts a release alert to Slack — `#populace-us` or `#populace-uk`,
 chosen from the repo id.
 
+US exact-k ladder candidates use a tag-only lane. Run
+`tools/build_us_exact_k_ladder_release.py`, then execute the `publish_command`
+recorded in `package_result.json`. That command includes `--create-tag`,
+`--no-latest`, and `--tag-only`: it uploads the immutable release and creates its
+tag without committing candidate artifacts or release copies to the production
+main branch. The launcher also forces `--no-staging`, so the build writes neither
+a production nor a staging pointer. The candidate is therefore available only
+by its explicit release id or tag until a separate promotion updates
+`latest.json`. Because Slack alerts are coupled to that production pointer
+update, tag-only publication sends no release alert.
+
 The alert is a **no-op unless the channel's incoming-webhook URL is set**, so
 configure it once on the build machine:
 

changelog.d/578-exact-k-ladder-release.added.md

@@ -0,0 +1,21 @@
+Added the US exact-k ladder release launcher for the full multispine pool,
+57,240 households, and 20,000 households. It authenticates the ready pool and
+frozen target register, requires strict improvement over the incumbent on the
+shared weighted loss, preserves the full-pool identity arm, uses seeded
+Sampford selection plus an original-weight HT-with-q refit for smaller points,
+records the selection and calibration receipts, and emits exact-count release
+IDs with immutable `--create-tag --no-latest --tag-only` publication plumbing
+without moving a pointer or mutating canonical artifacts on the dataset main
+branch. Canonical artifact filenames remain loadable after a later manual
+promotion, and an optional hash-pinned SSI retry basis preserves the certified
+hard-gate path.
+
+The release lane now authenticates the pool's own release id and scores the
+incumbent from the same verified bytes whose SHA-256 enters the manifest. It
+binds the frozen-register comparison to the incumbent's weighting version,
+family multipliers, loss cap, and name-aligned loss-vector digest, and refuses
+basis drift. The house builder independently enforces the `N`, `57240`, and
+`20000` ladder, an explicit seed, requested-versus-realized row-count equality,
+and disabled staging. Package receipts record that neither the production nor
+staging pointer changes. Legacy no-pool builds retain their previous receipt,
+console-output, and CLI contracts.