Migrating from 0.15 to 0.16

The concrete baseline is v0.15.4 (d0f2909) to v0.16.0 (0c2c0f4). Consumers on earlier 0.15 patches must also review their intervening changes. The 0.16 release replaced document shapes and reused some v1 identifiers. Changing only schema_version cannot migrate these documents. There is no automatic converter or implicit downgrade reader.

Consumer boundary

The integration audit on 2026-09-03 found two generations:

Consumer baseline

Contracts

Upgrade implication

robotics-acceptance-harness 0.18.0 (614864d)

>=0.16,<0.17; git source 6c6b72a, whose tree matches v0.16.0

Uses the new catalog and receipt/provider APIs

robotics-runtime-infra audited main (caa62ab)

0.15.4 (d0f2909), paired with harness 0.17.1 (2fbdaf7)

Upgrade producers, qualification tooling and both dependency pins together

These are dated observations, not a live compatibility certification. Infra’s foundation integration checks its pinned pair. Contracts’ local examples do not test that pair. Keep the 0.15.4/0.17.1 pair until the consumer migration passes its integration gate; an unbounded requirement such as “0.15.4 or newer” does not describe this compatibility boundary.

Document and API changes

0.15.4 form

0.16.0 form

Required migration work

acceptance-scenario.v4/v5

acceptance-scenario.v1

Supply provider_requirements, evaluator_requirements and metric_definitions from the actual execution design

runtime-manifest.v1/v2/v3

runtime-manifest.v1

Replace the old image/host/Gazebo layout with execution_subject, host_platform, execution_platform, provider_bindings and evaluator_bindings

acceptance-result.v4/v5

acceptance-result.v1

Record evaluation_mode, runtime_observation and evaluators, and use the new evidence links

acceptance-aggregate.v4

acceptance-aggregate.v1

Rebuild the aggregate from migrated domain results and validate its links

evidence-index.v2/v3

evidence-index.v1

Replace segments[] with artifacts[]; supply artifact identity, storage_state, recording summaries and receipt links where required

mcap-summary.v1

recording-summary.v1

Use the recording format and new summary shape; update referring evidence

zenoh-channel.v1, zenoh-channel-observation.v1

transport-channel.v1, transport-channel-observation.v1

Rebuild transport descriptions and observations against the catalog

transport-qualification-result.v1/v2

transport-qualification-result.v1

Supply scenario_sha256 and clock-relation evidence required by the new form

qualification-bundle.v2, qualification-policy.v2

qualification-bundle.v1, qualification-policy.v1

Update the statement, predicate type, policy and artifact kinds together

execution-permit.v1 with image_digest

Same name with subject_digest

Replace permit init --image-digest with --subject-digest and regenerate authorization from reviewed inputs

execution-verification.v1 with cosign_image_digest

Same name with cosign_subject_digest

Update the external verification producer and re-establish its digest links

PUBLISHED_SCHEMA_SHA256, SchemaCompatibilityError, allowed_companion_schemas, validate_companion_schema

Removed

Resolve roles through schema_for_role / validate_role; inspect packaged bytes with schema_digest

Names that survive the transition are not evidence of compatibility. This also applies to other retained names, such as acceptance-run.v1, campaign, model, dataset, causal-chain and clock-relation documents: validate each actual document and the complete linked set with the chosen package version.

validate-qualification no longer accepts mcap_summary or raw_mcap artifact kinds. It uses recording_summary and supports provider_conformance for conformance-result.v1 documents. Raw recording evidence belongs in the evidence index; do not relabel raw bytes as a summary. The qualification predicate changes from https://robotics-runtime-contracts.dev/attestations/qualification-bundle/v2 to the /v1 endpoint. Update signing and verification policy to match the exact predicateType in the packaged qualification-bundle schema.

Harness 0.18 also requires OTLP metrics as application/x-ndjson, replacing 0.17.1’s application/json convention. Its remote-evidence path needs artifact receipts and verification documents. A contracts version bump alone cannot provide missing observations, receipts or evidence producers.

Migration procedure

  1. Retain the original documents, signatures, digests and exact tool versions. Validate historical evidence using its original release. Do not rewrite it in place or claim that an old signature covers migrated bytes.

  2. Use the catalog and consumer examples to rebuild producer output. Obtain missing provider, evaluator and evidence data from the execution; do not fabricate values to satisfy a schema.

  3. Validate each new document against its intended role with validate_role, or select the schema explicitly with robotics-contracts validate --schema. An unchanged schema_version string is insufficient.

  4. Recompute every dependent SHA-256 from the new file bytes in dependency order, then regenerate qualification statements and obtain new external signatures and verification records as required. Validate the complete set with robotics-contracts validate-qualification.

  5. Run the consumer’s actual execution and qualification integration checks before updating its released dependency pins. The contracts test suite alone cannot qualify an infra/harness combination.

The historical identifier reuse is recorded here rather than repaired by changing released schemas. Future changes follow ADR 0007.