Skip to content

Add canonical US runtime stage contracts, manifests, and docs #42

@anth-volk

Description

@anth-volk

Summary

Implement the canonical 9-stage US Microplex runtime taxonomy proposed in #20.

This issue tracks adding first-class stage contracts, saved-run manifests/overlays, resume-oriented stage artifacts, and docs for the canonical US build path.

Scope

  • Define the canonical 9 runtime stages in code.
  • Add stage contracts that describe each stage's inputs, outputs, artifacts, diagnostics, validation placeholders, and resume posture.
  • Write a saved-run stage_manifest.json alongside artifact bundles.
  • Add stage-local artifacts where the current pipeline already has stable boundaries, including source planning, PE entity materialization, calibration summary, dataset assembly, and validation evidence.
  • Update data-flow snapshots and benchmark evidence backfills to use the canonical stage IDs.
  • Add docs for the pipeline stages, stage contracts/manifests, and API reference using the repo's Sphinx/Jupyter Book docs path.

Out of scope for this first implementation

  • Automatic conditional execution or a scheduler.
  • A shared stage-validation execution engine.
  • Reworking the underlying modeling/calibration method.
  • Full source-frame snapshotting for every raw input source.

Acceptance criteria

  • Saved artifact bundles expose the 9 canonical stages.
  • Stage manifests are machine-readable and stable enough for saved-run overlays.
  • Existing artifact save and checkpoint evidence paths remain backward compatible.
  • Stage documentation is available in the repo docs.
  • Focused tests cover stage contract ordering, manifest shape, data-flow snapshot integration, and checkpoint evidence integration.

Related discussion: #20

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions