open-standards/wai/wai-quantum/VERSIONING.md

# WAI Quantum: versions, stability and deprecations

This page says what anyone building on WAI Quantum can rely on: which parts are
public, what a version number promises about each, how long a version is
supported, and how a change is announced before it happens. It covers every
WAI Quantum package. Each package's README links here.

The deprecated items, each with the version that deprecated it and its
replacement, are listed in [DEPRECATIONS.md](DEPRECATIONS.md).

## The packages

| Package | Where | Version today |
|---|---|---|
| `wai-quantum`, the engine (Rust crate) | `wai/wai-quantum`, published on crates.io | 0.8.x |
| `wai-quantum-cli`, the command line `wai-quantum` and its MCP server (Rust crate) | `wai/wai-quantum-cli`, published on crates.io | 0.2.x |
| `wai-quantum-qpu`, quantum processors and the person's own providers (Rust crate) | `wai/wai-quantum-qpu`, published on crates.io | 0.4.x |
| The job service, its HTTP API and its MCP server | `wai/wai-quantum-service`, at `https://wai.transaction.science/quantum-jobs` | 0.2.x |
| `wai-quantum`, the Python package | `wai/wai-quantum-py` | 0.1.x |
| The editor extension | `wai/tools/wai-quantum-editor` | 0.1.x |
| `tree-sitter-openqasm`, the grammar | `wai/tools/tree-sitter-openqasm` | 0.1.x |

Each package has its own version number, read from the package itself, never
from a page: `wai-quantum version --json` gives the command line's, the
engine's and the schemas'. Quantum Studio and the desktop app are
applications: what they promise is the engine's, through the documents below.

## What is public

These are the public surface. Everything else may change in any release.

| Surface | What is public | What holds it in CI |
|---|---|---|
| The engine's Rust API | Every item `wai-quantum` documents on docs.rs, with all features (the crate is documented with all features on). Items marked `#[doc(hidden)]` and the internal `_signing` feature are not. | `cargo-semver-checks` against the last version published |
| The command line | Its verbs and subcommands, their flags and arguments, their exit statuses, and everything a verb prints with `--json`. The text a verb prints without `--json` is for people and may change in any release. | the help of every verb, committed in `wai-quantum-cli/docs/llms-full.txt`; the `--json` output by its schemas |
| The job JSON | A job's request, its result, the job as a host returns it, a plan, and a compile: the schemas `wai.quantum.job-request/1`, `wai.quantum.job-result/1`, `wai.quantum.job/1`, `wai.quantum.plan/1` and `wai.quantum.compile-result/1` | the schema tests: every method's result, held to them |
| The reader's diagnostics | Each diagnostic code (`Q…`), its outcome and its meaning: a code never changes meaning once released, and a retired code keeps its row | the reader's table, served by `qasm_diagnostics`, and its schema |
| The MCP servers | Both servers' tool names, each tool's `inputSchema` and `outputSchema`, their resources' URIs and their prompts' names and arguments | the committed tool lists (`wai-quantum-cli/docs/local-mcp.json`, `wai-quantum-cli/docs/service-mcp.json`), and every tool's answer held to its `outputSchema` |
| The receipt | A result's receipt, `wai.quantum.receipt/2` (its first form still verifies), what it seals and how, and the receipts of the engine's other families (circuits, sparse Pauli dynamics, resource estimates and the rest) | receipts sealed before each change, kept as fixtures and pinned (`src/engine/testdata/`, `src/receipt_pins.rs`, the conformance corpora) |
| The job service | Its HTTP API (`/v1`, described by `/v1/openapi.json`) and its MCP server | the service's tests and its smoke checks |
| The Python package | The names `wai_quantum.__all__` lists and the widgets, with their parameters and what they return | the package's tests |
| The provider protocol | `wai.quantum.provider/1`: its messages, their fields and its error codes ([the extension](../extensions/quantum-providers.md), section 10) | the protocol's schema, `wai.quantum.provider/1`, held to every message the client sends and every answer the reference provider gives |
| The editor extension | Its settings (`waiQuantum.*`) and its commands | the extension's tests |
| The grammar | The names of its nodes and fields, which queries name | its corpus tests and the committed parser |

## The schemas

Every document the engine and its hosts write has a JSON Schema (2020-12),
committed as data:

| Schema | File |
|---|---|
| `wai.quantum.job-request/1` | `wai/wai-quantum/schemas/job-request.v1.json` |
| `wai.quantum.job-result/1` | `wai/wai-quantum/schemas/job-result.v1.json` |
| `wai.quantum.job/1` | `wai/wai-quantum/schemas/job.v1.json` |
| `wai.quantum.receipt/2` | `wai/wai-quantum/schemas/receipt.v2.json` |
| `wai.quantum.plan/1` | `wai/wai-quantum/schemas/plan.v1.json` |
| `wai.quantum.compile-result/1`: a compile, its certificate (`wai.quantum.compile/1`) and its receipt | `wai/wai-quantum/schemas/compile-result.v1.json` |
| `wai.quantum.tools/1`: the engine's tools' answers (lint, the reader's diagnostic codes, critique, the equivalence check, improve, the classical shortcuts, the methods, the rewrites, novelty, the workbench, convergence, the study) | `wai/wai-quantum/schemas/tools.v1.json` |
| `wai.quantum.versions/1`: what a host reports of its versions | `wai/wai-quantum/schemas/versions.v1.json` |
| `wai.quantum.verdict/1`: how far the engine checked an answer | `wai/wai-quantum/schemas/verdict.v1.json` |
| `wai.quantum.target/1`: a device target | `wai/wai-quantum/schemas/target.v1.json` |
| `wai.quantum.estimate/1`: a resource estimate and its check | `wai/wai-quantum/schemas/estimate.v1.json` |
| `wai.quantum.set/1`: a set's or a sweep's result and its check | `wai/wai-quantum/schemas/set.v1.json` |
| `wai.quantum.provenance/1`: what a result came from | `wai/wai-quantum/schemas/provenance.v1.json` |
| `wai.quantum.qec/1`: an error-correction answer (a code, a decode, a threshold) | `wai/wai-quantum/schemas/qec.v1.json` |
| `wai.quantum.distance/1`: a code's distance certificate | `wai/wai-quantum/schemas/distance.v1.json` |
| `wai.quantum.mitigation/1`: a job's mitigation | `wai/wai-quantum/schemas/mitigation.v1.json` |
| `wai.quantum.answer/1`: the answer view layer, a draft (below) | `wai/wai-quantum/schemas/answer.v1.json` |
| `wai.quantum.telemetry/1`: a correctness record and its corpus | `wai/wai-quantum/schemas/telemetry.v1.json` |
| `wai.quantum.views-bundle/1`: the manifest of the views' page | `wai/wai-quantum/schemas/views-bundle.v1.json` |
| `wai.quantum.course/1`, `wai.quantum.exercise/1`: the circuits course as kept and as served, and each lesson's exercise | `wai/wai-quantum/schemas/course.v1.json`, `exercise.v1.json` |
| `wai.quantum.course-check/1`: a program checked against an exercise, a lesson as served and a hint | `wai/wai-quantum/schemas/course-check.v1.json` |
| `wai.quantum.local-tools/1`: the local MCP server's own tools' answers | `wai/wai-quantum-cli/schemas/local-tools.v1.json` |
| `wai.quantum.lease/1`, `wai.quantum.eval-report/1`, `wai.quantum.eval-answers/1`, `wai.quantum.token-cost/1`, `wai.quantum.learn-progress/1`: the command line's scheduler lease, the harness's report, corpus and token counts, and the course's progress file | `wai/wai-quantum-cli/schemas/` |
| `wai.quantum.service-tools/1`: the job service's MCP tools' answers | `wai/wai-quantum-service/schemas/service-tools.v1.json` |
| `wai.quantum.receipt-keys/1`: every key the job service has signed with, and its signed rotations | `wai/wai-quantum-service/schemas/receipt-keys.v1.json` |
| `wai.quantum.provider/1`: the provider protocol's messages | `wai/wai-quantum-qpu/schemas/provider.v1.json` |

A draft is outside this promise until it settles: the answer view layer
(`wai.quantum.answer/1`, [its extension](../extensions/quantum-answers.md))
may change its form in any release, and DEPRECATIONS.md lists no change to
it. Its schema says what the engine writes today, and the tests hold the
engine to it all the same.

A schema's name is `wai.quantum.<document>/<major>`, its file
`<document>.v<major>.json`, and its `$id` the file's address on the forge.
Each MCP tool's `outputSchema` is its answer's schema, every reference in it
resolved so that it stands alone.

Within one major version a schema only grows: a new optional member, a new
value of a member that lists its values, a new `$def`. A member keeps its name,
its type and its meaning. A reader written against one text of a schema
therefore reads every later document of the same major version, as long as it
ignores members it does not know, and a reader that validates should take the
newest text of that major version. A change that a reader could not read
(a member removed, renamed, retyped, or given another meaning; a member made
required) is a new major version: a new name and a new file, beside the old
one, in a new major version of the package that writes it.

The tests hold the code to its schemas more strictly than a reader does: a
document that carries a member its schema does not name fails them. So a
change to what the code writes cannot ship without its schema changing in the
same commit, where review sees it.

### Versions in what is written

Every result names the engine that made it and the schema it follows (a
compile's result names `wai.quantum.compile-result/1`):

```json fragment
"engine": { "name": "wai-quantum", "version": "0.8.0" },
"schema": "wai.quantum.job-result/1"
```

Both are inside what the receipt seals, so neither can be changed or removed
without the receipt failing. The receipt's own form did not change: it is an
Ed25519 signature over BLAKE3(`wai:quantum-service-receipt\x02` ‖ the request
‖ the result), each in its RFC 8785 canonical text, the result without its
`receipt` member. What changed is the canonical text of a new result, which
now holds two more members in their sorted places,
`"engine":{"name":"wai-quantum","version":"…"}` and
`"schema":"wai.quantum.job-result/1"`. A receipt issued before them seals a
result without them, and the verifier recomputes the digest of whatever result
it is shown, so every receipt already issued verifies as it did. Two job
bodies sealed by the engine as it was before (a run here, and a run on a
provider) are kept in `wai/wai-quantum/src/engine/testdata/` with their
digests pinned; the tests verify them, and also verify that adding the new
members to them breaks their receipts, as adding anything would.

A host reports its versions, as `wai.quantum.versions/1`:

- `wai-quantum version --json`: the command line's version and the engine's,
  every schema it writes, the MCP protocol version its server speaks, and the
  provider protocol;
- both MCP servers, in `initialize`, under
  `_meta["science.transaction.wai/versions"]` (beside the standard
  `serverInfo`);
- the job service in `GET /v1` (`versions`) and in its tool
  `quantum_service_info`.

## What a version number promises

Each package follows [Semantic Versioning 2.0](https://semver.org): MAJOR.MINOR.PATCH.

- **A major release** may make a breaking change: an API item removed or its
  signature changed; a verb, flag or `--json` member removed or renamed; a job
  JSON member removed, retyped or given another meaning; an MCP tool or one of
  its parameters removed or renamed, or a parameter made required; anything a
  reader could no longer read. Every breaking change is in the changelog with
  what to do instead.
- **A minor release** adds: API items, verbs, flags, optional members of a
  document, MCP tools, resources and prompts, methods, accuracy classes,
  values of a member that lists its values. It may deprecate (below). It
  breaks nothing a public surface promised.
- **A patch release** fixes, and adds nothing to a public surface. A fix that
  makes a wrong number right is a fix: a result that was wrong was never a
  promise. Such a fix is in the changelog, with the requests it changes.

Some things hold in every release, whatever its number:

- **Every receipt ever issued verifies.** The verifier keeps every form a
  receipt has had (the first, which signed serde_json's text, and the
  canonical one). A receipt's signed bytes are never changed; a new form of
  receipt is a new form, named by its `canon` member or its domain, beside
  the old ones. The pinned fixtures and conformance corpora are never re-pinned
  to make a test pass.
- **A result says how exact it is.** Each method's accuracy class keeps its
  meaning. A method may become more exact; it is never made less exact under
  the same class.
- **The engine is deterministic.** The same request gives the same answer
  (its counts, expectation values, amplitudes and hashes; not the time it took
  or the energy it spent) on every platform the release supports. A release
  that changes what a request gives says so in the changelog.

### Before 1.0

Every WAI Quantum package is 0.x today. Semantic Versioning promises nothing
before 1.0; these packages promise this:

- **The first non-zero component is the major.** For a 0.y.z version, a
  breaking change bumps y (0.6.16 to 0.7.0); additions and fixes bump z. This
  is how Cargo reads 0.x versions, and what the API check below enforces.
- **What holds already:** the public surface above; breaking changes only in
  a 0.y bump, with the changelog saying what to do instead; deprecation at
  least one release before removal, listed in [DEPRECATIONS.md](DEPRECATIONS.md);
  the schemas' rules; and every receipt ever issued verifying.
- **What does not hold yet:** the support windows below. Before 1.0, a 0.y
  release may follow the last sooner than a year after it, and the previous
  0.y series is fixed only where the changelog says so. Each package's
  windows begin with its 1.0.

## Support windows

Decided by the owner on 2026-10-27, for each package from its 1.0:

- **At least one year between major versions.** A major version is never
  replaced by the next sooner than a year after it shipped.
- **Six months of support for the previous major version.** When a new major
  version ships, the previous one gets fixes, security fixes among them, for at
  least six months after.
- **Deprecation before removal.** An item is deprecated at least one minor
  release before it is removed, removal comes only in a major release, and the
  deprecation is listed in [DEPRECATIONS.md](DEPRECATIONS.md) with its
  replacement from the release that makes it.

## How a change is announced

Before an item changes or goes, the tools that use it say so:

| Surface | How a deprecated item says so |
|---|---|
| The engine's Rust API | `#[deprecated(since = "…", note = "use … instead")]`: the compiler warns every build that uses it |
| The command line | a deprecated verb or flag still works, and prints `wai-quantum: deprecated: …, use … instead` on standard error |
| The job JSON and the schemas | the member is marked `"deprecated": true` in its schema, with its replacement in its description; it is still written until its removal |
| The MCP servers | the tool's description begins `Deprecated: use … instead.`, and the tool still answers until its removal |
| The Python package | a `DeprecationWarning` naming the replacement |
| The provider protocol | a later protocol version is a new `protocol` string; a provider of only this one answers `unsupported_version` to another |
| The editor extension | the setting's `deprecationMessage`, which the editor shows |

Every release's additions, fixes, deprecations and breaking changes are in
[the changelog](../CHANGELOG.md), under `wai-quantum` headings. Each
deprecation is also a row of [DEPRECATIONS.md](DEPRECATIONS.md) from the
release that makes it until the release that removes the item.

## What CI checks

The workflow `.github/workflows/wai-quantum-contract.yml`, on Linux:

- **API compatibility:** `cargo-semver-checks`, at a pinned version, compares
  `wai-quantum`, `wai-quantum-cli` and `wai-quantum-qpu` with the last version
  of each published on crates.io (today 0.6.16, 0.1.4 and 0.2.0). It reports every change it finds, and
  fails only on a breaking change made without the version bump the rule
  above asks for (a 0.y bump before 1.0, a major bump after).
- **The schemas:** every schema file reads, names itself and refers only to
  what is there; every method's job, every engine tool's answer, both MCP
  servers' answers to every tool, the job service's job in each status, and
  every provider protocol message and answer, are held to their schemas with
  no member they do not name; and receipts issued before results named their
  engine and schema still verify, their digests pinned.
- **The committed tool lists** of both MCP servers equal their live lists, so
  a change to any tool's name or schema shows in review.