Transaction-Science/open-standards
Watch
1
0
Fork
You've already forked open-standards
 0
Code Issues Pull requests Projects Releases 17 Packages Wiki Activity Actions 278
open-standards/wai/wai-quantum/VERSIONING.md
Transaction Science b894f1bbc5 wai-quantum contract over the course and the docs: the course's schemas in schemas/, its checks named, every page run, the translations in step, and the views in English 
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]>
2026-10-28 08:43:06 -04:00

242 lines
16 KiB
Markdown
Raw Permalink Blame History

# 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.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](../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.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 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.
Reference in a new issue View git blame Copy permalink