# 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](../../consumer-examples/README.md)
   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](../decisions/0007-preserve-published-schema-compatibility.md).
