Repository navigation
Migrate US staging run files to the version 2 contract #1135
Copy link
Copy link
Open
Description
Problem
The US fiscal-refresh build still writes schema version 1 staging run files, while UK builds use the stricter, country-neutral version 2 format introduced by #895. Both implementations write the same conceptual run bundle, but Microcosm maintains separate writer classes, fixtures, lifecycle behavior, and dashboard parsing paths.
PR #1099 separates hosted event delivery through LocalTelemetryEmitter from staging run-file persistence. It intentionally leaves the existing US file format unchanged. The next step should migrate US builds to version 2 and remove the version 1 writer.
Version 2 should be the single current staging run-file contract because it provides:
- named and validated document schemas;
- country, operation, pipeline, candidate, release, and run-kind identity;
- explicit lifecycle and delivery state;
- ordered events and consistent bundle validation;
- reviewed aggregate-only artifacts with digests and size limits;
- safeguards against uploading row-level data, credentials, archives, or dataset files;
- optional authenticated remote read-back.
Required changes
- Use the version 2 writer for every US fiscal-refresh build, including exact-count builds covered by Emit staging telemetry for US exact-K builds #933.
- Replace the two writer classes with one country-neutral
StagingRunBundleWriterimplementation based on the current version 2 code. - Stop producing schema version 1 staging files.
- Remove the version 1 writer, producer fixtures, and producer-only tests after the US path migrates.
- Keep
LocalTelemetryEmitterfunctionally independent. Disabling staging run files with--no-stagingmust not disable hosted event delivery. - Populate the version 2 country, operation, pipeline, candidate, release, run-kind, sampling, and delivery fields for US builds.
- Convert US lifecycle statuses and events to the version 2 contract.
- Audit every US diagnostic currently attached to the staging run. Version 1 accepts arbitrary JSON files; version 2 permits only reviewed aggregate data and rejects record arrays, sensitive keys, dataset files, and oversized files. Summarize or omit artifacts that do not satisfy the version 2 content policy.
- Verify that Calibration Diagnostics reads new US version 2 runs before deploying the producer change. Retaining read-only support for historical version 1 runs is a separate compatibility decision and does not require retaining a version 1 writer.
Acceptance criteria
- US fiscal-refresh and exact-count builds instantiate the single shared staging run-bundle writer.
- No production Microcosm path emits schema version 1 staging files.
- Every US staging document and attached artifact passes version 2 schema and content validation.
- US run identity and delivery fields are complete and consistent across the manifest, progress document, event stream, calibration progress, and run index.
- A staging file write, validation, or upload failure cannot suppress hosted events from
LocalTelemetryEmitter. -
--no-stagingsuppresses only staging run files and their uploads. - Calibration Diagnostics tests cover a US version 2 run before the Microcosm producer change is deployed.
- Tests cover successful, failed, local-only, remote-delivery-failure, and exact-count US runs.
- The obsolete version 1 writer and its producer fixtures are removed.
Context
- Add versioned UK staging telemetry and non-release smoke verification #895 introduced the version 2 staging run-file contract for UK builds while explicitly retaining version 1 for US builds.
- Emit staging telemetry for US exact-K builds #933 covers enabling staging output for US exact-count builds.
- Add always-on build telemetry delivery #1099 separates the always-on hosted event emitter from staging run-file persistence.
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
No labels
Activity