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 |
|---|---|---|
|
|
Uses the new catalog and receipt/provider APIs |
|
0.15.4 ( |
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 |
|---|---|---|
|
|
Supply |
|
|
Replace the old image/host/Gazebo layout with |
|
|
Record |
|
|
Rebuild the aggregate from migrated domain results and validate its links |
|
|
Replace |
|
|
Use the recording format and new summary shape; update referring evidence |
|
|
Rebuild transport descriptions and observations against the catalog |
|
|
Supply |
|
|
Update the statement, predicate type, policy and artifact kinds together |
|
Same name with |
Replace |
|
Same name with |
Update the external verification producer and re-establish its digest links |
|
Removed |
Resolve roles through |
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¶
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.
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.
Validate each new document against its intended role with
validate_role, or select the schema explicitly withrobotics-contracts validate --schema. An unchangedschema_versionstring is insufficient.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.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.