Compute
Versioning
Compute tracks six version lines separately. How to pin one, what counts as a breaking change, how overlap and retirement work, and why a contract version is not an endpoint version.
Six version lines, tracked separately
Six things carry a version, and they move independently. Treating them as one number is the most common upgrade mistake.
| Version line | What it versions | Where you read it |
|---|---|---|
| API | The operation surface and its paths | Developer settings, and the API description |
| Contract | The response envelope and payload shapes | The contract release on every response |
| Workflow | One workflow's behavior, parameters and output | workflow.version on your request |
| Profile | Your team's defaults for policy, quality, output and limits | The profile record, versioned and retired explicitly |
| Adapter | A compatibility level and its conformance matrix | The adapter's published matrix |
| Client | One released client library | That client's page |
How to pin a version
workflow.version accepts an exact version, such as eval.semantic_grade.v1. It also accepts current-compatible, which follows the current compatible release.
Pin exactly in production. Use current-compatible while you explore, and only where a changed output would not reach anyone.
Profiles are versioned by a deliberate act. You create a version, and you retire an old one; neither happens as a side effect of another change.
A contract version is not an endpoint version
The contract release on your response describes the payload shape. The API version describes the operation surface. They move on separate schedules.
A response can move to a new contract release with no path changing at all. A new path can appear with no contract release moving. So record both, and never infer one from the other in a compatibility check.
What counts as a breaking change
Unknown fields are rejected rather than dropped, so "additive" is not automatically safe for you.
Breaking:
- Removing a field you send or read.
- Narrowing the values a field accepts.
- Changing what a typed state means, or which states are terminal.
- Requiring a field you do not currently send.
Not breaking:
- Adding an optional field you may ignore.
- Adding an operation you do not call.
- Publishing a new workflow version alongside the one you pin.
The last one is the reason to pin exactly. A new workflow version cannot reach your pinned requests.
Overlap and retirement
A new version is published alongside the version it replaces, so both are callable during the overlap.
Retirement is an explicit, published act, not a silent stop. The dates of an overlap window are published on the descriptor for that version and repeated in the change record. Do not infer a window from a release date, and do not assume one is open-ended.
While an overlap is open, run the new version against a small input and compare results before you move production traffic.
Adapter compatibility levels
Four named levels exist: import_compatible, wire_subset_compatible, official_sdk_compatible and full_endpoint_compatible.
A level is a name plus a published conformance matrix. The matrix states the supported upstream version, and the field, lifecycle, error and limit coverage behind the claim.
A compatibility claim without that matrix is not a compatibility claim. Read the matrix for the exact upstream version you use, then see how a change is recorded before you upgrade.