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.

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, 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) 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):

"engine": { "name": "wai-quantum", "version": "0.8.1" },
"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: 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; 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 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, under wai-quantum headings. Each deprecation is also a row of 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.