PolicyEngine / PolicyEngine/microcosm
Emit staging telemetry for US exact-K builds
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 0
- Forks
- 4
- Avg merge
- 1d 3h
- Merged PRs (30d)
- 94
Description
Problem
The official US exact-K build path cannot emit staging telemetry:
tools/build_us_exact_k_ladder_release.pyalways adds--no-stagingto the underlying fiscal-refresh build command.tools/build_us_fiscal_refresh_release.pyrejects every--exact-kinvocation that does not also pass--no-staging.
This couples two separate behaviors:
- Exact-K publication correctly uses
--no-latest --tag-only, which prevents the candidate from replacing the production dataset pointer. --no-stagingprevents the build from reporting progress and diagnostics under its own staging run ID.
Staging telemetry stores candidate runs side by side and does not update the production dataset pointer. An exact-K candidate can therefore remain tag-only in the production repository while still appearing on the staging dashboard during its build and review.
The exact-K implementation merged on 2026-08-03. As of 2026-09-15, the public policyengine/populace-us repository contains 26 release tags and no tag matching the required exact-K release identifier patterns (kN, k57240, or k20000). The two newest releases are source-enrichment releases that inherit a 57,240-household selection from Build P; they do not contain exact-K ladder evidence.
Required changes
- Remove the unconditional
--no-stagingargument from the US exact-K launcher. - Remove the parser rule that requires
--exact-kand--no-stagingtogether. - Use the shared versioned staging implementation introduced by #896 for exact-K builds.
- Default the staging run ID to the exact-K release ID so each count and seed has a distinct run.
- Report the complete build lifecycle, calibration diagnostics, requested and realized household counts, selection seed, and final success or failure state.
- Preserve
--no-latest --tag-onlypublication. Enabling staging must not updatelatest.jsonor any production dataset file. - Continue supporting an explicit
--no-stagingopt-out when the caller intentionally disables progress reporting. - Record staging delivery evidence in the build manifest and apply the same publication-time delivery validation used by other builds.
- Update documentation that currently states that exact-K builds always suppress staging.
Acceptance criteria
- The official exact-K launcher emits versioned staging telemetry by default.
- A numeric exact-K run and a
k=Nrun each appear under a distinct staging run ID. - Intermediate calibration updates and the final run state remain readable while and after the build executes.
- Exact-K publication remains immutable and tag-only and does not update
latest.json. -
--no-stagingremains an explicit opt-out rather than an exact-K requirement. - Tests demonstrate that staging and tag-only publication operate independently.
- Tests demonstrate that failed exact-K builds record a failed final state.
- Existing exact-K selection, refit, validation, naming, and evidence behavior remains unchanged.
Related work
- #578 defines the US exact-K dataset design.
- #637 covers immutable exact-K family publication and discovery.
- #898 covers extracting a shared country-neutral exact-K implementation and completing UK parity.
- #896 adds the shared versioned staging transport that this work should use.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with tools/build_us_exact_k_ladder_release.py and tools/build_us_fiscal_refresh_release.py, then read the shared versioned staging implementation from #896. Trace the exact-K entry points and publication path first. Done means default staging telemetry and manifest validation work for numeric and k=N runs, failed builds report failure, and --no-staging still preserves tag-only publication without changing production pointers.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, data-engineering, observability, release
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100