Skip to content

Migrate US staging run files to the version 2 contract #1135

Open

Description

@anth-volk

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 StagingRunBundleWriter implementation 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 LocalTelemetryEmitter functionally independent. Disabling staging run files with --no-staging must 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-staging suppresses 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

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions