Skip to content

feat(manifest): add exact schema version routing - #88

Open
stacknil wants to merge 3 commits into
mainfrom
stacknil/run-manifest-version-router
Open

feat(manifest): add exact schema version routing#88
stacknil wants to merge 3 commits into
mainfrom
stacknil/run-manifest-version-router

Conversation

@stacknil

Copy link
Copy Markdown
Owner

Summary

  • add one immutable registry for exact run-manifest/v1 and run-manifest/v2 schema selection
  • fail closed on missing, malformed, blank, case-changed, whitespace-changed, or unknown version markers
  • add a reviewer CLI, representative v1/v2 fixtures, compatibility tests, and contract documentation

Why

The repository documents both strict v1 and current v2 run-manifest contracts, but readers previously had no executable selection policy. A consumer could therefore hard-code one schema or invent a newest-version fallback. This PR makes the embedded marker authoritative before shape validation.

This is intentionally a reader-side contract change. Artifact-diff workflow work remains out of scope.

How to validate

python scripts/check_release_contract.py
python scripts/validate_run_manifest.py tests/fixtures/run_manifests/v1.json
python scripts/validate_run_manifest.py tests/fixtures/run_manifests/v2.json
python scripts/validate_run_manifest.py data/processed/run_manifest.json

Local result before push: 216 tests passed; 29 committed artifacts matched regenerated output; all three validation commands selected the expected schema.

Design and risk

  • Design decision: telemetry_lab.run_manifest_contract.RUN_MANIFEST_SCHEMA_REGISTRY is the single authoritative marker-to-schema mapping. select_run_manifest_schema() performs exact lookup before JSON Schema validation; the CLI is a thin adapter.
  • Main risk: a future schema version will be rejected until it is deliberately added to the registry and compatibility tests. This explicit failure is preferable to silently validating against the wrong contract.
  • Compatibility impact: current writers still emit only run-manifest/v2; strict v1 and v2 schema files, generated artifacts, aggregate digests, and runtime dependencies are unchanged. Historical v1 inputs gain an explicit supported reader path. The CLI uses the existing dev-only jsonschema dependency.
  • Rollback path: revert the three commits in this PR. No migration, backfill, dual-write state, or generated artifact rollback is required.

Screenshots / GIF

Not applicable; there is no UI change.

@stacknil

Copy link
Copy Markdown
Owner Author

Post-CI diff review completed at eebba4a.

  • Checks: CI and Repo Sentinel passed for both push and PR runs.
  • Design decision: exact embedded-marker lookup through one immutable registry before schema-shape validation.
  • Main risk: future versions fail closed until deliberately registered and covered by compatibility fixtures.
  • Compatibility impact: reader-only addition; writers remain v2-only, v1/v2 schemas and committed artifacts are unchanged, and no runtime dependency was added.
  • Rollback path: revert the three semantic commits; no migration, backfill, artifact regeneration, or dual-write rollback is needed.
  • Final diff review: no unexpected files, private identifiers, local paths, secrets, generated artifact changes, or scope overlap with the separate artifact-diff work.

The report/schema behavior change remains open for the required spaced review; it is intentionally not being merged immediately.

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant