### wai-quantum: the variational and algorithm library

- **Parameters in a job** (`engine::catalog::bind_params`): a job's `"params"` gives each of its program's parameters
  (`input float theta;`, `input angle phi;`) its value, written into the program as a `const` at exactly that double
  before it is read, every line keeping its number. A parameter left without a value, a name the program does not
  declare, or a value that is no number is refused with `J050` (and `Q114`, the reader's code for an input given no
  value). A sweep may fix some parameters in `"params"` while it sweeps the others. A job without `"params"` runs to
  the bytes it gave.
- **The reader carries each gate's derivative** (`qasm::tangents`): every gate's parameters with their derivatives by
  each of the program's parameters, forward, through sums, products, quotients, constant powers, the built-in
  functions, loops, broadcast and gate definitions. What it cannot follow (a parameter under a modifier, in a
  classical variable, a condition, an index, a size, a loop's range or a subroutine, or a type that rounds it) is
  refused on its line with the new reader code `Q129`.
- **Exact gradients** (`engine::variational::gradient`): a Hamiltonian's expectation (a sum of Pauli terms in the form
  of a job's observables) and its gradient by each parameter, on the double-precision state vector, by adjoint
  differentiation or the parameter-shift rule (two terms for a generator with two eigenvalues, four for a controlled
  rotation's three). Every answer states its method, that it is f64 and approximate, and an a priori bound on the
  rounding of the value and of each component. Each method is held to gradients worked out by hand for every gate
  with a parameter within that bound, to central finite differences, and to the other.
- **Deterministic optimisers** (`engine::variational::optimize`): gradient descent with a fixed step, Adam, and SPSA
  from a seeded stream, using only `+ − × ÷`, `√` and the crate's own `exp` and `ln`. Every step's parameters and
  value are listed, each a link of a BLAKE3 chain from the request (`wai.quantum.trace/1`), and the receipt seals the
  program, every step, the method and the seed; `engine::variational::verify` checks the chain and runs the answer
  again to the same bytes. The answers' digests are pinned and hold on x86_64 Linux, arm64 macOS and in wasm32.
- **The variational eigensolver and QAOA** (`engine::variational::vqe`, `qaoa`): an ansatz (a program, or the
  hardware-efficient ansatz the variational machine-learning module trains, written as a program and held to that
  module's distribution and gradient) optimised on a Hamiltonian, its energy set beside the exact ground energy by
  diagonalisation up to 8 qubits; Max-Cut built from a graph, its program and cost Hamiltonian, optimised and read
  against the maximum cut by brute force. Held to closed-form spectra, to the p = 1 expected cut on an edge and a ring,
  and to brute force.
- **Algorithm builders** (`engine::algorithms::build`): phase estimation, amplitude estimation by phase estimation of
  the Grover operator built from `A`, the ripple-carry adder in place, and quantum signal processing of a signal or
  of a real symmetric matrix through its block encoding. Each answer carries the equivalence ladder's verdict
  against a reference built from the definition, not the program's gates: the ladder gains a rung against a
  reference matrix (`engine::equiv::against_matrix`) and one against a truth table (`against_permutation`). Held to
  the Fejér distribution, a truth table written apart and run bit-exact, and the Chebyshev polynomials.
- **Every surface:** the command line's `gradient`, `optimize`, `vqe`, `qaoa` and `build`, `--param` on `run`, `plan`
  and `submit`, and `verify` running these answers again; both MCP servers' `gradient_qasm`, `optimize_qasm`,
  `vqe_ground_state`, `qaoa_maxcut` and `build_algorithm`, and `params` on `run_quantum_circuit`; the job service's
  `POST /v1/gradient`, `/v1/optimize`, `/v1/vqe`, `/v1/qaoa` and `/v1/build`, within its own bounds (`J031` past
  them, naming the local command); the page engine's `QuantumEngine.variational`. Every answer follows the new schema
  `wai.quantum.algorithms/1`. The job codes `J050` to `J053` join the table. The reference page is
  `wai-quantum/docs/variational.md`.
- **CI:** `wai-quantum-variational.yml` runs every new test by name on x86_64 and arm64 and builds each feature set
  the hosts build without warnings; the contract requires the new schema test; `wai-web-wasm.yml`'s pins rise to 27
  (native) and 19 (wasm32). The job service's smoke checks now use every submission a client's window holds (30).
- **Breaking:** `api:rust:wai_quantum::engine::schema::FILES`: the committed schemas grow from 23 to 24 with
  `algorithms.v1.json`, the variational and algorithm library's answers. Code that names the array's length iterates
  over `FILES` instead.

