b894f1bbc5
The course's documents join the version contract. The course as kept and as served (wai.quantum.course/1) and each exercise (wai.quantum.exercise/1) move from course/schema/ to the crate's schemas/, named and versioned as the rest; a check, a lesson as served and a hint are wai.quantum.course-check/1, and a check now names its engine beside its schema; the command line's progress file is wai.quantum.learn-progress/1. The engine's test holds the course, every exercise, every lesson in each locale and a check and hint of some to them; the learn test holds the progress file; the contract workflow requires both, and the eval and lease tests, by name, and runs when the answer and eval sets its tests read change. The docs runner reads every page the branches added: the error-correction page, the version policy, the deprecations page, the service's self-hosting, scheduler and provenance pages, and the views' README. Each block the other branches wrote either runs or says why it cannot (a sweep fixture added), and the job service it starts keeps its store in its scratch. The crate's README names wai-quantum 0.7. The Chinese READMEs hold the English pages' code again: the sections for error correction, sets and sweeps, the service's dry runs, the scheduler, scoring a model, the answer layer, views and versions are translated, and the compile pages name the gate set basis. The command line's Chinese words cover task, qec, eval and version, and submit as it reads now. The documentation index links the policy, the deprecations, the error-correction page and the service's pages in both languages. The policy lists every schema file and says the answer layer is a draft outside its promise. The 0.7.0 heading names what the four branches bring. The views page bundles the Studio components that now read their words through the locale module; build-views.mjs gives it the English words alone, so no other language's words reach a host. The result parts the Studio and the views share read their words through it too, so the Studio's result pane stays translated, its English unchanged. Co-Authored-By: Claude Opus 5.5 <[email protected]>
16 KiB
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.7.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.3.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.7.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 standardserverInfo); - the job service in
GET /v1(versions) and in its toolquantum_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
--jsonmember 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
canonmember 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, compareswai-quantum,wai-quantum-cliandwai-quantum-qpuwith 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.