@wenathlan/saddle 1.8.18 → 2.0.2

package/dist/quantum.js

@@ -0,0 +1,2073 @@
+/**
+ * quantum.ts — classical quantum-simulation layer for saddle v18.
+ *
+ * the module is a 100 percent classical software statevector simulator:
+ * no hardware, no photons, no qpu. the engine "supports" quantum the same
+ * way it virtualizes cores, memory and gpus — as one more virtualization
+ * layer: every "qubit" is a pair of float64 lanes inside a 2^n amplitude
+ * vector (interleaved re/im), every "gate" is an in-place index-pair
+ * transformation and every "measurement" is a crypto-seeded collapse of
+ * that vector.
+ *
+ * contexts (22):
+ *  01 version anchors (algorithm dates, simulator envelope)
+ *  02 error catcher (quantumerror envelope)
+ *  03 complex math kernel (2x2 unitary type + gate matrices)
+ *  04 quantumsim statevector core (1-20 qubits, Disposable)
+ *  05 multi-qubit gate kernels (cnot, cz, toffoli, swap, ccz)
+ *  06 canonical circuits (bellstate, ghzstate)
+ *  07 grover search (grover2 provable, grover3 statistical)
+ *  08 deutsch oracle discrimination (deutsch)
+ *  09 quantum teleportation sketch (qteleport)
+ *  10 bb84 stations (alice, bob, eve over a simulated channel)
+ *  11 bb84 protocol runner (runbb84: sifting, qber, intercept detection)
+ *  12 e91 entangled pairs + chsh (rune91)
+ *  13 qrng (quantuminspiredrandom, honest anu fallback)
+ *  14 dnavault codec (goldman 2013 ternary rotation, framing, strands)
+ *  15 dnavault decode (checksum verification, redundancy, roundtrip)
+ *  16 dnavault capacity planner (215 pb/g, planodefault)
+ *  17 optical 5d quartz planner (360 tb/disc, femtosecond write plan)
+ *  18 holographic note (microsoft hsd) and storage compare
+ *  19 qram bucket brigade (giovannetti 2008, o(log n) routing, n=8)
+ *  20 shor plan (honest: theoretical 7-qubit circuit, never executed)
+ *  21 registry (quantumregistry capability catalog)
+ *  22 self check (quantumselfcheck: every claim, machine-verified)
+ *
+ * rules: lowercase identifiers, english jsdoc third person, no emoji,
+ * try/catch catcher on every fallible path, node:* built-ins only
+ * (node:crypto for all randomness), zero runtime dependencies, no
+ * filesystem, network or process coupling beyond the optional,
+ * always-fallback anu qrng fetch. ascii only.
+ */
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { randomBytes, randomInt } from 'node:crypto';
+/* ------------------------------------------------------------------ */
+/* context: version anchors (quantum simulation envelope)               */
+/* ------------------------------------------------------------------ */
+/**
+ * frozen quantum layer anchors. every algorithm keeps its literature
+ * year so the registry can cite primary sources instead of folklore.
+ */
+export const quantumversions = {
+    date: '2026-08-23',
+    simulator: 'statevector',
+    precision: 'float64 interleaved re/im',
+    maxqubits: 20,
+    amplitudelanes: 2097152,
+    grover: '1996 stoc',
+    deutschjozsa: '1992 proc r soc a',
+    bb84: '1984 bangalore proceedings',
+    e91: '1991 prl 67 661',
+    teleportation: '1993 prl 70 1895',
+    qram: '2008 prl 100 160501',
+};
+/* ------------------------------------------------------------------ */
+/* context: error catcher                                               */
+/* ------------------------------------------------------------------ */
+/**
+ * quantum layer failure envelope. every guard in this module throws it
+ * instead of a bare error so callers can branch on the code.
+ */
+export class quantumerror extends Error {
+    code;
+    detail;
+    constructor(params) {
+        super(params.message);
+        this.name = 'quantumerror';
+        this.code = params.code;
+        this.detail = params.detail;
+    }
+}
+const invsqrt2 = Math.SQRT1_2;
+/** hadamard matrix ((1/sqrt 2) [[1,1],[1,1]]). */
+export const hmatrix = [invsqrt2, 0, invsqrt2, 0, invsqrt2, 0, invsqrt2, 0];
+/** pauli x matrix [[0,1],[1,0]]. */
+export const xmatrix = [0, 0, 1, 0, 1, 0, 0, 0];
+/** pauli y matrix [[0,-i],[i,0]]. */
+export const ymatrix = [0, 0, 0, -1, 0, 1, 0, 0];
+/** pauli z matrix diag(1,-1). */
+export const zmatrix = [1, 0, 0, 0, 0, 0, -1, 0];
+/** phase gate s = diag(1, i). */
+export const smatrix = [1, 0, 0, 0, 0, 0, 0, 1];
+/** inverse phase gate sdg = diag(1, -i). */
+export const sdgmatrix = [1, 0, 0, 0, 0, 0, 0, -1];
+/** t gate = diag(1, exp(i pi/4)). */
+export const tmatrix = [1, 0, 0, 0, 0, 0, invsqrt2, invsqrt2];
+/** inverse t gate = diag(1, exp(-i pi/4)). */
+export const tdgmatrix = [1, 0, 0, 0, 0, 0, invsqrt2, -invsqrt2];
+/**
+ * builds the rotation-x matrix rx(theta) =
+ * [[cos(t/2), -i sin(t/2)], [-i sin(t/2), cos(t/2)]].
+ */
+export function rxmatrix(theta) {
+    const c = Math.cos(theta / 2);
+    const s = Math.sin(theta / 2);
+    return [c, 0, 0, -s, 0, -s, c, 0];
+}
+/**
+ * builds the rotation-y matrix ry(theta) =
+ * [[cos(t/2), -sin(t/2)], [sin(t/2), cos(t/2)]]; ry(2a)|0> equals the
+ * polarization state cos(a)|0> + sin(a)|1>, which the e91 context uses
+ * to prepare and measure at arbitrary analyzer angles.
+ */
+export function rymatrix(theta) {
+    const c = Math.cos(theta / 2);
+    const s = Math.sin(theta / 2);
+    return [c, 0, -s, 0, s, 0, c, 0];
+}
+/**
+ * builds the rotation-z matrix rz(theta) = diag(e^{-i t/2}, e^{i t/2}).
+ */
+export function rzmatrix(theta) {
+    const c = Math.cos(theta / 2);
+    const s = Math.sin(theta / 2);
+    return [c, -s, 0, 0, 0, 0, c, s];
+}
+/* ------------------------------------------------------------------ */
+/* context: quantumsim statevector core (1-20 qubits, Disposable)       */
+/* ------------------------------------------------------------------ */
+/**
+ * pure-software statevector simulator. the state is one Float64Array of
+ * 2 * 2^n lanes holding interleaved real and imaginary parts; qubit q is
+ * bit q of the basis index (qubit 0 is the least significant bit), so
+ * for a single-qubit gate on qubit q the kernel iterates every index i
+ * with bit q = 0, takes j = i | 2^q and replaces the pair by
+ * u @ [amp(i), amp(j)] exactly as specified. the class is Disposable and
+ * meant to be used with `using` so amplitude memory is logically freed
+ * even though the gc owns it.
+ */
+export class quantumsim {
+    #amp;
+    #n;
+    #disposed = false;
+    constructor(nqubits) {
+        if (!Number.isInteger(nqubits) || nqubits < 1 || nqubits > 20) {
+            throw new quantumerror({
+                code: 'qubitrange',
+                message: `quantumsim supports 1 to 20 qubits, got ${nqubits}`,
+                detail: '2^n amplitudes with n > 20 exceed the float64 lane budget',
+            });
+        }
+        this.#n = nqubits;
+        this.#amp = new Float64Array(2 << nqubits);
+        this.#amp[0] = 1;
+    }
+    /** number of qubits of the register. */
+    get nqubits() {
+        return this.#n;
+    }
+    /** hilbert space dimension 2^n. */
+    get dim() {
+        return 1 << this.#n;
+    }
+    /** true once Symbol.dispose released the state. */
+    get disposed() {
+        return this.#disposed;
+    }
+    #guardlive() {
+        if (this.#disposed) {
+            throw new quantumerror({
+                code: 'disposed',
+                message: 'quantumsim state was disposed; create a new register',
+            });
+        }
+    }
+    #guardqubit(q, gate) {
+        if (!Number.isInteger(q) || q < 0 || q >= this.#n) {
+            throw new quantumerror({
+                code: 'qubitrange',
+                message: `gate ${gate} needs a qubit in [0, ${this.#n - 1}], got ${q}`,
+            });
+        }
+    }
+    /**
+     * applies a 2x2 unitary to qubit q by visiting each amplitude pair
+     * (i, i|2^q) once; this is the mathematical core every named
+     * single-qubit gate forwards to.
+     */
+    #apply1(q, m, gate) {
+        this.#guardlive();
+        this.#guardqubit(q, gate);
+        const amp = this.#amp;
+        const mask = 1 << q;
+        const [u00re, u00im, u01re, u01im, u10re, u10im, u11re, u11im] = m;
+        for (let i = 0; i < this.dim; i++) {
+            if ((i & mask) !== 0)
+                continue;
+            const j = i | mask;
+            const i2 = i << 1;
+            const j2 = j << 1;
+            const are = amp[i2];
+            const aim = amp[i2 + 1];
+            const bre = amp[j2];
+            const bim = amp[j2 + 1];
+            amp[i2] = u00re * are - u00im * aim + u01re * bre - u01im * bim;
+            amp[i2 + 1] = u00re * aim + u00im * are + u01re * bim + u01im * bre;
+            amp[j2] = u10re * are - u10im * aim + u11re * bre - u11im * bim;
+            amp[j2 + 1] = u10re * aim + u10im * are + u11re * bim + u11im * bre;
+        }
+        return this;
+    }
+    /** hadamard on qubit q. */
+    h(q) {
+        return this.#apply1(q, hmatrix, 'h');
+    }
+    /** pauli x (bit flip) on qubit q. */
+    x(q) {
+        return this.#apply1(q, xmatrix, 'x');
+    }
+    /** pauli y on qubit q. */
+    y(q) {
+        return this.#apply1(q, ymatrix, 'y');
+    }
+    /** pauli z (phase flip) on qubit q. */
+    z(q) {
+        return this.#apply1(q, zmatrix, 'z');
+    }
+    /** phase gate s = sqrt(z) on qubit q. */
+    s(q) {
+        return this.#apply1(q, smatrix, 's');
+    }
+    /** inverse phase gate on qubit q. */
+    sdg(q) {
+        return this.#apply1(q, sdgmatrix, 'sdg');
+    }
+    /** t = pi/8 gate on qubit q. */
+    t(q) {
+        return this.#apply1(q, tmatrix, 't');
+    }
+    /** inverse t gate on qubit q. */
+    tdg(q) {
+        return this.#apply1(q, tdgmatrix, 'tdg');
+    }
+    /** rotation-x by theta radians on qubit q. */
+    rx(theta, q) {
+        return this.#apply1(q, rxmatrix(theta), `rx(${theta})`);
+    }
+    /** rotation-y by theta radians on qubit q. */
+    ry(theta, q) {
+        return this.#apply1(q, rymatrix(theta), `ry(${theta})`);
+    }
+    /** rotation-z by theta radians on qubit q. */
+    rz(theta, q) {
+        return this.#apply1(q, rzmatrix(theta), `rz(${theta})`);
+    }
+    /**
+     * cnot: for every index i with control bit 1 and target bit 0,
+     * swaps amplitudes i and i|2^target; each pair is visited once.
+     */
+    cnot(control, target) {
+        this.#guardlive();
+        this.#guardqubit(control, 'cnot');
+        this.#guardqubit(target, 'cnot');
+        if (control === target) {
+            throw new quantumerror({
+                code: 'qubitcollision',
+                message: `cnot control and target are both qubit ${control}`,
+            });
+        }
+        const amp = this.#amp;
+        const maskc = 1 << control;
+        const maskt = 1 << target;
+        for (let i = 0; i < this.dim; i++) {
+            if ((i & maskc) === 0 || (i & maskt) !== 0)
+                continue;
+            this.#swappair(amp, i, i | maskt);
+        }
+        return this;
+    }
+    /**
+     * cz: flips the sign of every amplitude whose control and target
+     * bits are both 1.
+     */
+    cz(control, target) {
+        this.#guardlive();
+        this.#guardqubit(control, 'cz');
+        this.#guardqubit(target, 'cz');
+        if (control === target) {
+            throw new quantumerror({
+                code: 'qubitcollision',
+                message: `cz control and target are both qubit ${control}`,
+            });
+        }
+        const amp = this.#amp;
+        const mask = (1 << control) | (1 << target);
+        for (let i = 0; i < this.dim; i++) {
+            if ((i & mask) !== mask)
+                continue;
+            const i2 = i << 1;
+            amp[i2] = -amp[i2];
+            amp[i2 + 1] = -amp[i2 + 1];
+        }
+        return this;
+    }
+    /**
+     * toffoli (ccnot): swaps amplitude pairs only when both control bits
+     * are 1 and the target bit is 0.
+     */
+    toffoli(control1, control2, target) {
+        this.#guardlive();
+        this.#guardqubit(control1, 'toffoli');
+        this.#guardqubit(control2, 'toffoli');
+        this.#guardqubit(target, 'toffoli');
+        if (control1 === target || control2 === target || control1 === control2) {
+            throw new quantumerror({
+                code: 'qubitcollision',
+                message: `toffoli needs three distinct qubits, got ${control1}, ${control2}, ${target}`,
+            });
+        }
+        const amp = this.#amp;
+        const mask1 = 1 << control1;
+        const mask2 = 1 << control2;
+        const maskt = 1 << target;
+        for (let i = 0; i < this.dim; i++) {
+            if ((i & mask1) === 0 || (i & mask2) === 0 || (i & maskt) !== 0)
+                continue;
+            this.#swappair(amp, i, i | maskt);
+        }
+        return this;
+    }
+    /**
+     * swap: exchanges qubits a and b by visiting each index pair once
+     * (bit a = 0 with bit b = 1 maps to its complement bit a = 1, bit
+     * b = 0), so no pair is touched twice.
+     */
+    swap(a, b) {
+        this.#guardlive();
+        this.#guardqubit(a, 'swap');
+        this.#guardqubit(b, 'swap');
+        if (a === b) {
+            throw new quantumerror({
+                code: 'qubitcollision',
+                message: `swap needs two distinct qubits, got ${a} twice`,
+            });
+        }
+        const amp = this.#amp;
+        const maska = 1 << a;
+        const maskb = 1 << b;
+        for (let i = 0; i < this.dim; i++) {
+            if ((i & maska) !== 0 || (i & maskb) === 0)
+                continue;
+            this.#swappair(amp, i, (i | maska) & ~maskb);
+        }
+        return this;
+    }
+    /** swaps the two interleaved complex amplitudes at basis indexes. */
+    #swappair(amp, i, j) {
+        const i2 = i << 1;
+        const j2 = j << 1;
+        const re = amp[i2];
+        const im = amp[i2 + 1];
+        amp[i2] = amp[j2];
+        amp[i2 + 1] = amp[j2 + 1];
+        amp[j2] = re;
+        amp[j2 + 1] = im;
+    }
+    /**
+     * measurement outcome sampler: draws one uniform from node:crypto
+     * (randomInt over 2^30 buckets, finer than any probability gap this
+     * module produces), compares it with the |1> branch probability and
+     * returns the observed branch.
+     */
+    #sample(pone) {
+        const roll = randomInt(0, 0x40000000) / 0x40000000;
+        return roll < pone ? 1 : 0;
+    }
+    /**
+     * measures qubit q in the computational basis, collapsing the state.
+     * returns the observed classical bit.
+     */
+    measure(q) {
+        this.#guardlive();
+        this.#guardqubit(q, 'measure');
+        const amp = this.#amp;
+        const mask = 1 << q;
+        let pone = 0;
+        for (let i = 0; i < this.dim; i++) {
+            if ((i & mask) === 0)
+                continue;
+            const i2 = i << 1;
+            pone += amp[i2] * amp[i2] + amp[i2 + 1] * amp[i2 + 1];
+        }
+        const outcome = this.#sample(pone);
+        const keep = outcome === 1 ? mask : 0;
+        let mass = 0;
+        for (let i = 0; i < this.dim; i++) {
+            const i2 = i << 1;
+            if ((i & mask) !== keep) {
+                amp[i2] = 0;
+                amp[i2 + 1] = 0;
+            }
+            else {
+                mass += amp[i2] * amp[i2] + amp[i2 + 1] * amp[i2 + 1];
+            }
+        }
+        if (mass <= 0) {
+            throw new quantumerror({
+                code: 'zerovector',
+                message: `collapse of qubit ${q} hit a zero-mass branch`,
+            });
+        }
+        const scale = 1 / Math.sqrt(mass);
+        for (let i = 0; i < this.#amp.length; i++) {
+            this.#amp[i] *= scale;
+        }
+        return outcome;
+    }
+    /**
+     * measures the full register in the computational basis and returns
+     * the observed basis index (qubit 0 in bit 0).
+     */
+    measureall() {
+        this.#guardlive();
+        const amp = this.#amp;
+        const roll = randomInt(0, 0x40000000) / 0x40000000;
+        let acc = 0;
+        let pick = this.dim - 1;
+        for (let i = 0; i < this.dim; i++) {
+            const i2 = i << 1;
+            acc += amp[i2] * amp[i2] + amp[i2 + 1] * amp[i2 + 1];
+            if (roll < acc) {
+                pick = i;
+                break;
+            }
+        }
+        amp.fill(0);
+        amp[pick << 1] = 1;
+        return pick;
+    }
+    /**
+     * returns the [p0, p1] distribution of qubit q without collapsing;
+     * p1 = sum of |amplitude|^2 over indices with bit q set.
+     */
+    probs(q) {
+        this.#guardlive();
+        this.#guardqubit(q, 'probs');
+        const amp = this.#amp;
+        const mask = 1 << q;
+        let pone = 0;
+        for (let i = 0; i < this.dim; i++) {
+            if ((i & mask) === 0)
+                continue;
+            const i2 = i << 1;
+            pone += amp[i2] * amp[i2] + amp[i2 + 1] * amp[i2 + 1];
+        }
+        return [1 - pone, pone];
+    }
+    /**
+     * returns the full |amplitude|^2 distribution over all 2^n basis
+     * states as a fresh Float64Array (index order: qubit 0 in bit 0).
+     */
+    probabilities() {
+        this.#guardlive();
+        const amp = this.#amp;
+        const out = new Float64Array(this.dim);
+        for (let i = 0; i < this.dim; i++) {
+            const i2 = i << 1;
+            out[i] = amp[i2] * amp[i2] + amp[i2 + 1] * amp[i2 + 1];
+        }
+        return out;
+    }
+    /** returns the complex amplitude of one basis index as [re, im]. */
+    amplitude(index) {
+        this.#guardlive();
+        if (!Number.isInteger(index) || index < 0 || index >= this.dim) {
+            throw new quantumerror({
+                code: 'indexrange',
+                message: `amplitude index must be in [0, ${this.dim - 1}], got ${index}`,
+            });
+        }
+        const i2 = index << 1;
+        return [this.#amp[i2], this.#amp[i2 + 1]];
+    }
+    /** returns a detached readonly snapshot copy of the state lanes. */
+    state() {
+        this.#guardlive();
+        return this.#amp.slice();
+    }
+    /** euclidean norm of the state vector (should stay within 1e-12 of 1). */
+    norm() {
+        this.#guardlive();
+        let sum = 0;
+        for (let i = 0; i < this.#amp.length; i++) {
+            sum += this.#amp[i] * this.#amp[i];
+        }
+        return Math.sqrt(sum);
+    }
+    /** renormalizes the state to unit norm (fixes float drift). */
+    normalize() {
+        this.#guardlive();
+        const n = this.norm();
+        if (n <= 0) {
+            throw new quantumerror({
+                code: 'zerovector',
+                message: 'cannot normalize a zero vector',
+            });
+        }
+        for (let i = 0; i < this.#amp.length; i++) {
+            this.#amp[i] /= n;
+        }
+        return this;
+    }
+    /** resets the register to |0...0>. */
+    reset() {
+        this.#guardlive();
+        this.#amp.fill(0);
+        this.#amp[0] = 1;
+        return this;
+    }
+    /** releases the amplitude lanes; any further gate call throws. */
+    [Symbol.dispose]() {
+        this.#amp = new Float64Array(0);
+        this.#disposed = true;
+    }
+}
+/* ------------------------------------------------------------------ */
+/* context: multi-qubit gate kernels (module-level forms)               */
+/* ------------------------------------------------------------------ */
+/**
+ * applies cnot(control, target) to sim; functional spelling of the
+ * quantumsim method for composition outside the class.
+ */
+export function cnot(sim, control, target) {
+    return sim.cnot(control, target);
+}
+/**
+ * applies cz(control, target) to sim; the grover oracle for two qubits
+ * is exactly this gate on the |11> amplitude.
+ */
+export function cz(sim, control, target) {
+    return sim.cz(control, target);
+}
+/**
+ * applies toffoli(control1, control2, target) to sim, the universal
+ * reversible gate of toffoli 1980 as used in every compiled oracle.
+ */
+export function toffoli(sim, control1, control2, target) {
+    return sim.toffoli(control1, control2, target);
+}
+/**
+ * applies swap(a, b) to sim.
+ */
+export function swap(sim, a, b) {
+    return sim.swap(a, b);
+}
+/**
+ * ccz: three-qubit phase flip, composed as toffoli conjugated by
+ * hadamard on the target; used as the grover oracle and diffuser core.
+ */
+export function ccz(sim, control1, control2, target) {
+    sim.h(target);
+    sim.toffoli(control1, control2, target);
+    sim.h(target);
+    return sim;
+}
+/**
+ * builds the bell state (|00> + |11>)/sqrt(2) with h(0) then cnot(0,1);
+ * measurement of either qubit is a perfect coin and both always agree.
+ * expected distribution: [0.5, 0, 0.5, 0].
+ * reference: einstein-podolsky-rosen 1935; bell 1964; chapter 1 of
+ * nielsen and chuang, quantum computation and quantum information
+ * (2000).
+ */
+export function bellstate() {
+    const sim = new quantumsim(2);
+    sim.h(0).cnot(0, 1);
+    return {
+        sim,
+        name: 'bell',
+        expectedprobs: [0.5, 0, 0.5, 0],
+        reference: 'bell 1964; nielsen and chuang 2000 ch. 1',
+        note: 'maximally entangled pair; probs(0) = probs(1) = [0.5, 0.5]',
+    };
+}
+/**
+ * builds an n-qubit ghz state (|0...0> + |1...1>)/sqrt(2) by h(0) plus
+ * a cnot fanout; expected distribution carries mass 0.5 on index 0 and
+ * index 2^n - 1 only. reference: greenberger-horne-zeilinger 1989.
+ */
+export function ghzstate(n = 3) {
+    if (!Number.isInteger(n) || n < 2 || n > 12) {
+        throw new quantumerror({
+            code: 'qubitrange',
+            message: `ghzstate supports 2 to 12 qubits, got ${n}`,
+            detail: 'cap exists so expectedprobs stays readable',
+        });
+    }
+    const sim = new quantumsim(n);
+    sim.h(0);
+    for (let q = 1; q < n; q++) {
+        sim.cnot(0, q);
+    }
+    const expected = new Array(1 << n).fill(0);
+    expected[0] = 0.5;
+    expected[(1 << n) - 1] = 0.5;
+    return {
+        sim,
+        name: `ghz${n}`,
+        expectedprobs: expected,
+        reference: 'greenberger, horne, zeilinger 1989',
+        note: 'n-party entanglement witness; only |0...0> and |1...1> survive',
+    };
+}
+/* ------------------------------------------------------------------ */
+/* context: grover search (grover2 provable, grover3 statistical)       */
+/* ------------------------------------------------------------------ */
+/**
+ * grover2: exhaustive-search winner |11> on 2 qubits with exactly one
+ * oracle call. the circuit is the task-pinned sequence
+ * h,h -> cz -> h,h -> x,x -> cz -> h,h whose unique fixed point is
+ * amplitude -1 on |11>, so prob(11) = 1 up to 1e-12 float noise.
+ * expected distribution: [0, 0, 0, 1].
+ * reference: grover, a fast quantum mechanical algorithm for database
+ * search, stoc 1996 (arxiv:quant-ph/9605043).
+ */
+export function grover2() {
+    const sim = new quantumsim(2);
+    sim.h(0).h(1);
+    sim.cz(0, 1);
+    sim.h(0).h(1);
+    sim.x(0).x(1);
+    sim.cz(0, 1);
+    sim.h(0).h(1);
+    return {
+        sim,
+        name: 'grover2',
+        expectedprobs: [0, 0, 0, 1],
+        reference: 'grover 1996 stoc (arxiv:quant-ph/9605043)',
+        note: 'one oracle call finds |11> with certainty (4 states, 1 marked)',
+    };
+}
+/**
+ * grover3: search over 8 items for winner |111> with two iterations of
+ * oracle ccz + diffuser (h x3, x x3, ccz, x x3, h x3). theory gives
+ * success sin^2(5 * asin(1/sqrt 8)) = 0.9461, comfortably above 0.9.
+ * reference: grover 1996; boyer, brassard, hoefer, tapp 1998 iteration
+ * counting for m = 1 marked item of n = 8.
+ */
+export function grover3() {
+    const sim = new quantumsim(3);
+    sim.h(0).h(1).h(2);
+    for (let iteration = 0; iteration < 2; iteration++) {
+        ccz(sim, 0, 1, 2);
+        sim.h(0).h(1).h(2);
+        sim.x(0).x(1).x(2);
+        ccz(sim, 0, 1, 2);
+        sim.x(0).x(1).x(2);
+        sim.h(0).h(1).h(2);
+    }
+    const dim = sim.dim;
+    const expected = new Array(dim).fill(0.0077);
+    expected[dim - 1] = 0.9461;
+    return {
+        sim,
+        name: 'grover3',
+        expectedprobs: expected,
+        reference: 'grover 1996; boyer-brassard-hoefer-tapp 1998',
+        note: 'prob(111) = 0.9461 theoretical; measured within float noise',
+    };
+}
+/**
+ * deutsch algorithm on 2 qubits (input qubit 0, ancilla qubit 1 in
+ * |->). the oracle is built from the truth table of f exactly as the
+ * four possible (x, y) -> (x, y xor f(x)) unitaries: identity, x on
+ * the ancilla, cnot(0,1) for f(x) = x, and x + cnot for f(x) = not x.
+ * phase kickback leaves qubit 0 in |0> for constant f and |1> for
+ * balanced f, so a single measurement decides the promise problem.
+ * reference: deutsch 1985; deutsch and jozsa, rapid solution of
+ * problems by quantum computation, proc r soc lond a 439, 553 (1992).
+ */
+export function deutsch(f) {
+    const f0 = f(0);
+    const f1 = f(1);
+    const sim = new quantumsim(2);
+    sim.x(1);
+    sim.h(0).h(1);
+    if (f0 === 0 && f1 === 0) {
+        // constant zero: identity oracle, no gates.
+    }
+    else if (f0 === 1 && f1 === 1) {
+        sim.x(1);
+    }
+    else if (f0 === 0 && f1 === 1) {
+        sim.cnot(0, 1);
+    }
+    else {
+        sim.x(1);
+        sim.cnot(0, 1);
+    }
+    sim.h(0);
+    const measured = sim.measure(0);
+    return {
+        sim,
+        verdict: measured === 0 ? 'constant' : 'balanced',
+        measured,
+        expected: f0 === f1 ? 'constant' : 'balanced',
+        reference: 'deutsch 1985; deutsch-jozsa 1992 proc r soc a 439 553',
+    };
+}
+/* ------------------------------------------------------------------ */
+/* context: quantum teleportation sketch                                */
+/* ------------------------------------------------------------------ */
+/**
+ * qteleport: teleports the state of qubit 0 to qubit 2 through a bell
+ * pair on qubits 1 and 2 (h(1), cnot(1,2)), the bell-basis measurement
+ * cnot(0,1) + h(0), then the classical corrections x/z on qubit 2
+ * conditioned on the two outcomes. the simulator runs the whole loop so
+ * the fidelity is exactly 1 for any of the three prepared inputs; the
+ * fidelity is read off the two amplitudes that survive the bell
+ * measurement (index m1*2 + m0 and its +4 partner on qubit 2).
+ * reference: bennett, brassard, crepeau, jozsa, peres, wootters,
+ * teleporting an unknown quantum state via dual classical and
+ * einstein-podolsky-rosen channels, prl 70, 1895 (1993).
+ */
+export function qteleport(input = 'one') {
+    const sim = new quantumsim(3);
+    if (input === 'one') {
+        sim.x(0);
+    }
+    else if (input === 'plus') {
+        sim.h(0);
+    }
+    sim.h(1);
+    sim.cnot(1, 2);
+    sim.cnot(0, 1);
+    sim.h(0);
+    const outcome1 = sim.measure(1);
+    const outcome0 = sim.measure(0);
+    if (outcome1 === 1) {
+        sim.x(2);
+    }
+    if (outcome0 === 1) {
+        sim.z(2);
+    }
+    const lowindex = (outcome1 << 1) | outcome0;
+    const alow = sim.amplitude(lowindex);
+    const ahigh = sim.amplitude(lowindex + 4);
+    const fidelity = input === 'plus'
+        ? ((alow[0] + ahigh[0]) / Math.SQRT2) ** 2 + ((alow[1] + ahigh[1]) / Math.SQRT2) ** 2
+        : input === 'one'
+            ? ahigh[0] * ahigh[0] + ahigh[1] * ahigh[1]
+            : alow[0] * alow[0] + alow[1] * alow[1];
+    return {
+        sim,
+        outcome0,
+        outcome1,
+        fidelity,
+        input,
+        reference: 'bennett, brassard, crepeau, jozsa, peres, wootters 1993 prl 70 1895',
+    };
+}
+/**
+ * alice station: draws random key bits and random bases from
+ * node:crypto and prepares one 1-qubit quantumsim photon per bit
+ * (x for bit 1, extra h when the basis is diagonal).
+ */
+export class alice {
+    #bits = [];
+    #bases = [];
+    constructor(count) {
+        try {
+            for (let i = 0; i < count; i++) {
+                this.#bits.push(randomInt(0, 2));
+                this.#bases.push(randomInt(0, 2));
+            }
+        }
+        catch (cause) {
+            throw new quantumerror({
+                code: 'randomness',
+                message: 'alice could not draw randomness from node:crypto',
+                detail: String(cause),
+            });
+        }
+    }
+    /** alice's raw key bits. */
+    get bits() {
+        return this.#bits;
+    }
+    /** alice's basis string (0 rectilinear, 1 diagonal). */
+    get bases() {
+        return this.#bases;
+    }
+    /**
+     * prepares the photon burst; each photon is a real 1-qubit state so
+     * the channel, eve and bob all act on amplitudes, not on labels.
+     */
+    prepare() {
+        return this.#bits.map((bit, i) => {
+            const photon = new quantumsim(1);
+            if (bit === 1) {
+                photon.x(0);
+            }
+            if (this.#bases[i] === 1) {
+                photon.h(0);
+            }
+            return photon;
+        });
+    }
+}
+/**
+ * bob station: measures each incoming photon in his own random bases
+ * (h before the z measurement when diagonal), collapsing the photon.
+ */
+export class bob {
+    #bases = [];
+    #outcomes = [];
+    constructor(count) {
+        try {
+            for (let i = 0; i < count; i++) {
+                this.#bases.push(randomInt(0, 2));
+            }
+        }
+        catch (cause) {
+            throw new quantumerror({
+                code: 'randomness',
+                message: 'bob could not draw randomness from node:crypto',
+                detail: String(cause),
+            });
+        }
+    }
+    /** bob's basis string. */
+    get bases() {
+        return this.#bases;
+    }
+    /** bob's raw measurement outcomes. */
+    get outcomes() {
+        return this.#outcomes;
+    }
+    /**
+     * measures the whole burst and stores the classical outcomes;
+     * measuring a diagonal-basis photon in the rectilinear basis
+     * genuinely yields a coin flip, which is where intercept-resend
+     * damage shows up.
+     */
+    measure(photons) {
+        this.#outcomes.length = 0;
+        for (let i = 0; i < photons.length; i++) {
+            const photon = photons[i];
+            if (this.#bases[i] === 1) {
+                photon.h(0);
+            }
+            this.#outcomes.push(photon.measure(0));
+        }
+        return this.#outcomes;
+    }
+}
+/**
+ * eve station: intercept-resend attacker. she measures every photon in
+ * her own random basis (collapsing it) and resends a fresh photon
+ * prepared in that basis with the bit she saw. on sifted bits where
+ * alice and bob used the same basis, eve chose the wrong basis half
+ * the time and bob then errs half of those, so the qber lands at 25
+ * percent against 0 percent on a clean channel.
+ * reference: the intercept-resend attack is exercise material of every
+ * bb84 treatment since bennett-brassard 1984.
+ */
+export class eve {
+    #bases = [];
+    #bits = [];
+    /** bases eve used (for audits). */
+    get bases() {
+        return this.#bases;
+    }
+    /** bits eve extracted (for audits). */
+    get bits() {
+        return this.#bits;
+    }
+    /** taps the burst and returns the resent photons. */
+    intercept(photons) {
+        this.#bases.length = 0;
+        this.#bits.length = 0;
+        return photons.map((photon) => {
+            const basis = randomInt(0, 2);
+            if (basis === 1) {
+                photon.h(0);
+            }
+            const bit = photon.measure(0);
+            const resend = new quantumsim(1);
+            if (bit === 1) {
+                resend.x(0);
+            }
+            if (basis === 1) {
+                resend.h(0);
+            }
+            this.#bases.push(basis);
+            this.#bits.push(bit);
+            return resend;
+        });
+    }
+}
+/**
+ * bb84 quantum channel: a photon pipeline that alice fills, an optional
+ * eve taps (counted), and bob drains. no network, no localhost — the
+ * channel is an in-memory queue standing in for fiber.
+ */
+export class bb84channel {
+    #inflight = [];
+    #taps = 0;
+    /** sends a photon burst onto the channel. */
+    send(photons) {
+        this.#inflight = [...photons];
+    }
+    /**
+     * taps the channel: the operator receives the in-flight burst and its
+     * return value replaces it (intercept-resend); taps are counted.
+     */
+    tap(operator) {
+        this.#taps += 1;
+        this.#inflight = operator(this.#inflight);
+        return this.#inflight;
+    }
+    /** drains the channel for the receiver. */
+    receive() {
+        const out = this.#inflight;
+        this.#inflight = [];
+        return out;
+    }
+    /** number of taps observed on the channel (informational). */
+    get tapped() {
+        return this.#taps;
+    }
+}
+/**
+ * runs the complete bb84 flow over the simulated channel: alice
+ * prepares, the optional eve taps, bob measures, both sides sift on
+ * equal bases, the qber is computed over the full sifted key and the
+ * detection verdict comes from comparing a public sample of up to 128
+ * sifted bits (abort threshold 11 percent, the one-way bb84
+ * reconciliation bound of the shor-preskill lineage).
+ * reference: bennett and brassard, quantum cryptography: public key
+ * distribution and coin tossing, proc ieee int conf on computers,
+ * systems and signal processing, bangalore 1984, pp. 175-179.
+ */
+export function runbb84(options = {}) {
+    const bits = options.bits ?? 1024;
+    if (!Number.isInteger(bits) || bits < 64 || bits > 8192) {
+        throw new quantumerror({
+            code: 'bitcount',
+            message: `bb84 burst size must be in [64, 8192], got ${bits}`,
+            detail: '1024 keeps the qber estimate comfortably outside noise bands',
+        });
+    }
+    const a = new alice(bits);
+    const b = new bob(bits);
+    const channel = new bb84channel();
+    channel.send(a.prepare());
+    if (options.eve === true) {
+        const attacker = new eve();
+        channel.tap((photons) => attacker.intercept(photons));
+    }
+    b.measure(channel.receive());
+    const sifted = [];
+    for (let i = 0; i < bits; i++) {
+        if (a.bases[i] === b.bases[i]) {
+            sifted.push(i);
+        }
+    }
+    if (sifted.length < 16) {
+        throw new quantumerror({
+            code: 'siftempty',
+            message: 'sifting kept fewer than 16 bits; raise the burst size',
+        });
+    }
+    let mismatches = 0;
+    for (const i of sifted) {
+        if (a.bits[i] !== b.outcomes[i]) {
+            mismatches += 1;
+        }
+    }
+    const qber = mismatches / sifted.length;
+    const order = [...sifted.keys()];
+    for (let i = order.length - 1; i > 0; i--) {
+        const j = randomInt(0, i + 1);
+        const tmp = order[i];
+        order[i] = order[j];
+        order[j] = tmp;
+    }
+    const samplecount = Math.min(128, Math.max(8, Math.floor(sifted.length / 2)));
+    const sample = new Set(order.slice(0, samplecount));
+    let samplemismatch = 0;
+    for (const i of sample) {
+        if (a.bits[i] !== b.outcomes[i]) {
+            samplemismatch += 1;
+        }
+    }
+    const sampledqber = samplemismatch / sample.size;
+    const keyalice = [];
+    const keybob = [];
+    for (const i of sifted) {
+        if (sample.has(i))
+            continue;
+        keyalice.push(a.bits[i]);
+        keybob.push(b.outcomes[i]);
+    }
+    return {
+        keyalice,
+        keybob,
+        qber,
+        detected: sampledqber > 0.11,
+        siftedlen: sifted.length,
+        sampledlen: sample.size,
+        sampledqber,
+        threshold: 0.11,
+        reference: 'bb84, bangalore 1984; abort threshold from shor-preskill 2000 lineage',
+    };
+}
+const deg2rad = Math.PI / 180;
+/**
+ * measures qubit q of sim at analyzer angle a (degrees): applies
+ * ry(-2a) so outcome 0 projects onto cos(a)|0> + sin(a)|1> and outcome
+ * 1 onto its orthogonal partner, then collapses via measure.
+ */
+function measureatangle(sim, q, angledeg) {
+    sim.ry(-2 * angledeg * deg2rad, q);
+    return sim.measure(q);
+}
+/**
+ * prepares a fresh |+a> = cos(a)|0> + sin(a)|1> photon on qubit q;
+ * used by eve to resend exactly what she measured.
+ */
+function prepareangle(sim, q, angledeg, bit) {
+    if (bit === 1) {
+        sim.x(q);
+    }
+    if (angledeg !== 0) {
+        sim.ry(2 * angledeg * deg2rad, q);
+    }
+}
+/**
+ * rune91: ekert-1991 entanglement-based key distribution on |phi+>
+ * pairs. each round is half the time a key round (both parties pick
+ * 0 or 45 degrees; equal angles give perfectly correlated bits on a
+ * clean source) and half the time a chsh round (alice 0 or 45 degrees,
+ * bob 22.5 or 67.5 degrees). the chsh statistic
+ * s = e(0,22.5) - e(0,67.5) + e(45,22.5) + e(45,67.5) converges to
+ * 2 sqrt(2) = 2.8284 for the entangled source and cannot exceed the
+ * classical bound 2 once eve collapses the pairs, which is exactly the
+ * e91 security test (bell-inequality violation as the eavesdropper
+ * detector). an intercept-resend eve also pushes the matched-angle key
+ * qber to 25 percent.
+ * reference: ekert, quantum cryptography based on bell's theorem,
+ * prl 67, 661 (1991); clauser-horne-shimony-holt 1969 prl 23 880;
+ * bell 1964; aspect, dalibard, roger 1982.
+ */
+export function rune91(options = {}) {
+    const pairs = options.pairs ?? 2400;
+    if (!Number.isInteger(pairs) || pairs < 200 || pairs > 200000) {
+        throw new quantumerror({
+            code: 'paircount',
+            message: `e91 needs 200 to 200000 pairs, got ${pairs}`,
+            detail: '2400 pairs put the chsh noise band about three sigma from the verdict line',
+        });
+    }
+    const keytotals = { matched: 0, mismatch: 0 };
+    const buckets = new Map();
+    for (let round = 0; round < pairs; round++) {
+        let pair = new quantumsim(2);
+        pair.h(0).cnot(0, 1);
+        if (options.eve === true) {
+            const b0 = randomInt(0, 2) === 1 ? 45 : 0;
+            const b1 = randomInt(0, 2) === 1 ? 45 : 0;
+            const m0 = measureatangle(pair, 0, b0);
+            const m1 = measureatangle(pair, 1, b1);
+            const resend = new quantumsim(2);
+            prepareangle(resend, 0, b0, m0);
+            prepareangle(resend, 1, b1, m1);
+            pair = resend;
+        }
+        const mode = randomInt(0, 2);
+        if (mode === 0) {
+            const adeg = randomInt(0, 2) === 1 ? 45 : 0;
+            const bdeg = randomInt(0, 2) === 1 ? 45 : 0;
+            const ma = measureatangle(pair, 0, adeg);
+            const mb = measureatangle(pair, 1, bdeg);
+            if (adeg === bdeg) {
+                keytotals.matched += 1;
+                if (ma !== mb) {
+                    keytotals.mismatch += 1;
+                }
+            }
+        }
+        else {
+            const adeg = randomInt(0, 2) === 1 ? 45 : 0;
+            const bdeg = randomInt(0, 2) === 1 ? 67.5 : 22.5;
+            const ea = measureatangle(pair, 0, adeg);
+            const eb = measureatangle(pair, 1, bdeg);
+            const keyname = `${adeg}:${bdeg}`;
+            const bucket = buckets.get(keyname) ?? { n: 0, agree: 0 };
+            bucket.n += 1;
+            if (ea === eb) {
+                bucket.agree += 1;
+            }
+            buckets.set(keyname, bucket);
+        }
+    }
+    const correlation = (a, b) => {
+        const bucket = buckets.get(`${a}:${b}`);
+        if (!bucket || bucket.n === 0) {
+            return Number.NaN;
+        }
+        return (2 * bucket.agree) / bucket.n - 1;
+    };
+    const s = correlation(0, 22.5) - correlation(0, 67.5) + correlation(45, 22.5) + correlation(45, 67.5);
+    if (!Number.isFinite(s)) {
+        throw new quantumerror({
+            code: 'chshsample',
+            message: 'a chsh angle pair received zero samples; raise the pair count',
+        });
+    }
+    const keylen = keytotals.matched;
+    const qber = keylen === 0 ? Number.NaN : keytotals.mismatch / keylen;
+    let chshpairs = 0;
+    for (const bucket of buckets.values()) {
+        chshpairs += bucket.n;
+    }
+    const detected = s <= 2.4 || (Number.isFinite(qber) && qber > 0.05);
+    return {
+        s,
+        classicalbound: 2,
+        quantumbound: 2 * Math.SQRT2,
+        detected,
+        keylen,
+        qber,
+        pairs,
+        chshpairs,
+        reference: 'ekert 1991 prl 67 661; chsh 1969; bell 1964; aspect 1982',
+    };
+}
+/* ------------------------------------------------------------------ */
+/* context: qrng (quantum-inspired random, honest anu fallback)         */
+/* ------------------------------------------------------------------ */
+/**
+ * quantuminspiredrandom: draws count integers in [min, max) from the
+ * node crypto CSPRNG via randomInt (node rejection-samples internally,
+ * so the stream is unbiased). this is a classical CSPRNG standing in
+ * for a QRNG photon source; the API shape matches hardware QRNG
+ * services (count + integer range in, uniform integers out) so the
+ * integration seam is already quantum-ready. no physics is claimed.
+ */
+export function quantuminspiredrandom(count, options = {}) {
+    if (!Number.isInteger(count) || count < 1 || count > 1048576) {
+        throw new quantumerror({
+            code: 'countrange',
+            message: `qrng count must be in [1, 1048576], got ${count}`,
+        });
+    }
+    const min = options.min ?? 0;
+    const max = options.max ?? 256;
+    if (!Number.isInteger(min) || !Number.isInteger(max) || min >= max || max - min > 2 ** 36) {
+        throw new quantumerror({
+            code: 'range',
+            message: `qrng range needs integers min < max with span <= 2^36, got [${min}, ${max})`,
+        });
+    }
+    try {
+        const values = [];
+        for (let i = 0; i < count; i++) {
+            values.push(randomInt(min, max));
+        }
+        return values;
+    }
+    catch (cause) {
+        throw new quantumerror({
+            code: 'randomness',
+            message: 'crypto.randomInt failed while filling the qrng batch',
+            detail: String(cause),
+        });
+    }
+}
+/**
+ * anuqrng: optional asynchronous fetch of the australian national
+ * university quantum random numbers service (api.quantumnumbers.io,
+ * successor of qrng.anu.edu.au), which digitizes vacuum fluctuations.
+ * the planner is honest: without network egress or an api key the call
+ * fails fast (abort timeout 2500 ms default) and the function falls
+ * back to the same CSPRNG as quantuminspiredrandom, reporting
+ * source: 'csprng'. anu values are 64-bit unsigned integers folded
+ * into the requested range with one modulo (bias below 2^-32 for any
+ * practical span, documented here rather than hidden).
+ */
+export async function anuqrng(count, options = {}) {
+    const min = options.min ?? 0;
+    const max = options.max ?? 256;
+    const span = max - min;
+    if (!Number.isInteger(count) ||
+        count < 1 ||
+        count > 1024 ||
+        !Number.isInteger(min) ||
+        min >= max) {
+        throw new quantumerror({
+            code: 'range',
+            message: `anuqrng needs count in [1, 1024] and integer min < max, got count=${count}`,
+        });
+    }
+    const timeoutms = options.timeoutms ?? 2500;
+    const apikey = options.apikey ?? '';
+    try {
+        const url = `https://api.quantumnumbers.io/qranum/v1/generate?apikey=${apikey}` +
+            `&number=${count}&size=8`;
+        const response = await fetch(url, { signal: AbortSignal.timeout(timeoutms) });
+        if (!response.ok) {
+            throw new Error(`anu http status ${response.status}`);
+        }
+        const payload = (await response.json());
+        if (!Array.isArray(payload.data) || payload.data.length < count) {
+            throw new Error('anu payload did not carry enough values');
+        }
+        const values = payload.data.slice(0, count).map((value) => min + (Number(value) % span));
+        if (values.some((value) => !Number.isInteger(value) || value < min || value >= max)) {
+            throw new Error('anu payload contained non-integer entries');
+        }
+        return {
+            values,
+            source: 'anu',
+            note: 'vacuum-fluctuation source, api.quantumnumbers.io',
+        };
+    }
+    catch (cause) {
+        return {
+            values: quantuminspiredrandom(count, { min, max }),
+            source: 'csprng',
+            note: `anu fetch unavailable (${String(cause)}); honest CSPRNG fallback`,
+        };
+    }
+}
+/**
+ * convenience bytes draw used by the self check and available to
+ * integrators: crypto.randomBytes surfaced under the qrng banner with
+ * the same honesty note as quantuminspiredrandom.
+ */
+export function quantuminspiredbytes(count) {
+    if (!Number.isInteger(count) || count < 1 || count > 1048576) {
+        throw new quantumerror({
+            code: 'countrange',
+            message: `qrng byte count must be in [1, 1048576], got ${count}`,
+        });
+    }
+    try {
+        return randomBytes(count);
+    }
+    catch (cause) {
+        throw new quantumerror({
+            code: 'randomness',
+            message: 'crypto.randomBytes failed',
+            detail: String(cause),
+        });
+    }
+}
+/* ------------------------------------------------------------------ */
+/* context: dnavault codec (goldman 2013 ternary rotation)              */
+/* ------------------------------------------------------------------ */
+/**
+ * dnavault codec constants: 4 strands addressed by blockindex mod 4,
+ * each block synthesized twice (on its home strand and the next one)
+ * so decoding survives the loss of any single strand; every byte maps
+ * to 6 ternary digits (3^6 = 729 > 256) and every digit to one
+ * nucleotide through the goldman rotation next = (digit + 1 + previous)
+ * mod 4, which makes consecutive repeats impossible (homopolymer run
+ * length 1, stricter than the standard run-length <= 3 synthesis
+ * constraint). reference: goldman et al., towards practical,
+ * high-capacity, low-maintenance information storage in synthesized
+ * dna, nature 494, 77-80 (2013), doi:10.1038/nature11875.
+ */
+export const dnavaultspec = {
+    strandcount: 4,
+    redundancy: 2,
+    blockpayloadbytes: 32,
+    blockframebytes: 35,
+    nucleotidesperblock: 210,
+    tritsperbyte: 6,
+    maxinputbytes: 65536,
+    homopolymerrunmax: 1,
+    rule: 'next = (digit + 1 + previous) mod 4, digit in {0,1,2}',
+    reference: 'goldman et al. 2013 nature 494 77-80 doi:10.1038/nature11875',
+};
+const nucleotides = ['A', 'C', 'G', 'T'];
+const nucleotideindex = { A: 0, C: 1, G: 2, T: 3 };
+const powersof3 = [1, 3, 9, 27, 81, 243];
+/**
+ * encodes bytes into four dna strands with real goldman-2013 rules:
+ * a 4-byte big-endian length prefix, 32-byte payload blocks framed as
+ * [index u16 be][payload 32][checksum u8 of index + payload], ternary
+ * rotation encoding per byte, dual-strand placement (blockindex mod 4
+ * and (blockindex + 1) mod 4). the archive planner guard caps input at
+ * 64 kib; real synthesis runs are planned, not executed, here.
+ */
+export function dnavaultencode(bytes) {
+    if (bytes.length > dnavaultspec.maxinputbytes) {
+        throw new quantumerror({
+            code: 'archiveguard',
+            message: `dnavaultencode is an archive planner: input capped at ${dnavaultspec.maxinputbytes} bytes, got ${bytes.length}`,
+            detail: 'use the capacity planner (planodefault) for larger archives',
+        });
+    }
+    const stream = [
+        (bytes.length >>> 24) & 0xff,
+        (bytes.length >>> 16) & 0xff,
+        (bytes.length >>> 8) & 0xff,
+        bytes.length & 0xff,
+        ...bytes,
+    ];
+    const blocks = Math.ceil(stream.length / dnavaultspec.blockpayloadbytes);
+    const strands = [[], [], [], []];
+    for (let b = 0; b < blocks; b++) {
+        const payload = [];
+        for (let k = 0; k < dnavaultspec.blockpayloadbytes; k++) {
+            payload.push(stream[b * dnavaultspec.blockpayloadbytes + k] ?? 0);
+        }
+        const hi = (b >>> 8) & 0xff;
+        const lo = b & 0xff;
+        let sum = hi + lo;
+        for (const byte of payload) {
+            sum += byte;
+        }
+        const frame = [hi, lo, ...payload, sum & 0xff];
+        let oligo = '';
+        let previous = 0;
+        for (const byte of frame) {
+            let value = byte;
+            for (let k = 0; k < dnavaultspec.tritsperbyte; k++) {
+                const digit = value % 3;
+                value = (value - digit) / 3;
+                const base = (digit + previous + 1) % 4;
+                oligo += nucleotides[base];
+                previous = base;
+            }
+        }
+        strands[b % 4].push(oligo);
+        strands[(b + 1) % 4].push(oligo);
+    }
+    const oligos = blocks * dnavaultspec.redundancy;
+    return {
+        strands: strands.map((strand) => strand.join('')),
+        blocks,
+        oligos,
+        nucleotides: oligos * dnavaultspec.nucleotidesperblock,
+        redundancy: dnavaultspec.redundancy,
+        homopolymerrunmax: dnavaultspec.homopolymerrunmax,
+        reference: dnavaultspec.reference,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* context: dnavault decode (checksums, redundancy, roundtrip)          */
+/* ------------------------------------------------------------------ */
+/**
+ * decodes strands back to bytes: every 210-nucleotide oligo is
+ * de-rotated to a 35-byte frame, checksum-verified, deduplicated by
+ * block index and reassembled in order. oligos failing checksum or
+ * carrying invalid letters are dropped silently because every block
+ * exists on two strands; a genuinely missing index throws.
+ */
+export function dnavaultdecode(strands) {
+    const byindex = new Map();
+    for (const strand of strands) {
+        const clean = strand.replace(/\s+/g, '').toUpperCase();
+        for (let start = 0; start + dnavaultspec.nucleotidesperblock <= clean.length; start += dnavaultspec.nucleotidesperblock) {
+            const oligo = clean.slice(start, start + dnavaultspec.nucleotidesperblock);
+            try {
+                const frame = [];
+                let previous = 0;
+                let value = 0;
+                let power = 0;
+                for (const letter of oligo) {
+                    const base = nucleotideindex[letter];
+                    if (base === undefined) {
+                        throw new Error(`non-nucleotide letter ${letter}`);
+                    }
+                    const digit = (((base - previous - 1) % 4) + 4) % 4;
+                    if (digit > 2) {
+                        throw new Error('rotation arithmetic produced an impossible digit');
+                    }
+                    value += digit * powersof3[power];
+                    power += 1;
+                    if (power === dnavaultspec.tritsperbyte) {
+                        frame.push(value);
+                        value = 0;
+                        power = 0;
+                    }
+                    previous = base;
+                }
+                const index = (frame[0] << 8) | frame[1];
+                let sum = frame[0] + frame[1];
+                for (let k = 2; k < frame.length - 1; k++) {
+                    sum += frame[k];
+                }
+                if ((sum & 0xff) !== frame[frame.length - 1]) {
+                    throw new Error(`checksum mismatch on block ${index}`);
+                }
+                if (!byindex.has(index)) {
+                    byindex.set(index, frame);
+                }
+            }
+            catch {
+                // corrupted oligo: redundancy owns recovery, skip it.
+            }
+        }
+    }
+    const count = byindex.size;
+    if (count === 0) {
+        throw new quantumerror({
+            code: 'unrecoverable',
+            message: 'no valid dnavault block survived decoding',
+        });
+    }
+    for (let b = 0; b < count; b++) {
+        if (!byindex.has(b)) {
+            throw new quantumerror({
+                code: 'blockmissing',
+                message: `dnavault block ${b} is missing across all strands`,
+            });
+        }
+    }
+    const stream = [];
+    for (let b = 0; b < count; b++) {
+        const frame = byindex.get(b);
+        if (!frame) {
+            throw new quantumerror({
+                code: 'blockmissing',
+                message: `dnavault block ${b} vanished between the has check and the read`,
+            });
+        }
+        for (let k = 2; k < frame.length - 1; k++) {
+            stream.push(frame[k]);
+        }
+    }
+    const length = ((stream[0] << 24) | (stream[1] << 16) | (stream[2] << 8) | stream[3]) >>> 0;
+    if (length > stream.length - 4) {
+        throw new quantumerror({
+            code: 'lengthcorrupt',
+            message: `declared length ${length} exceeds decoded payload ${stream.length - 4}`,
+        });
+    }
+    return Uint8Array.from(stream.slice(4, 4 + length));
+}
+/* ------------------------------------------------------------------ */
+/* context: dnavault capacity planner (215 pb/g)                        */
+/* ------------------------------------------------------------------ */
+/**
+ * dnavault capacity anchors: the widely quoted 215 petabytes per gram
+ * of dna figure (church 2012 science era synthesis estimates, echoed
+ * by the nature 2013 news coverage around goldman et al.) anchors the
+ * physical planner; the codec rates above are what this module
+ * actually charges.
+ */
+export const dnacapacityspec = {
+    bytespergram: 2.15e17,
+    densityquote: '215 petabytes per gram of dna',
+    densityreference: 'church, gao, kosuri 2012 science 337 1628 era estimates; nature news 2013',
+    synthesispitch: 'archive planner only; no oligo is ordered or synthesized',
+};
+/**
+ * dnavault capacity estimate for an archive of sizebytes: dna grams at
+ * the 215 pb/g density, oligo and nucleotide counts at this codec's
+ * real rates, and the storage overhead ratio.
+ */
+export function dnacapacity(sizebytes) {
+    if (!Number.isFinite(sizebytes) || sizebytes <= 0 || sizebytes > 2 ** 40) {
+        throw new quantumerror({
+            code: 'sizerange',
+            message: `capacity planner accepts archives up to 1 tebibyte, got ${sizebytes}`,
+        });
+    }
+    const payload = sizebytes + 4;
+    const blocks = Math.ceil(payload / dnavaultspec.blockpayloadbytes);
+    const oligos = blocks * dnavaultspec.redundancy;
+    const nucleotides = oligos * dnavaultspec.nucleotidesperblock;
+    return {
+        grams: sizebytes / dnacapacityspec.bytespergram,
+        oligos,
+        nucleotides,
+        overhead: (blocks * dnavaultspec.blockframebytes + 4) / sizebytes - 1,
+        density: dnacapacityspec.densityquote,
+        reference: dnacapacityspec.densityreference,
+    };
+}
+/**
+ * planodefault: the default dna archive plan for a payload of
+ * sizebytes — dna mass in grams (215 pb/g density), number of oligo
+ * strands to synthesize, and the codec overhead fraction. this is the
+ * planner entry point for the storage tier; nothing is written.
+ */
+export function planodefault(sizebytes) {
+    const estimate = dnacapacity(sizebytes);
+    return {
+        grams: estimate.grams,
+        strands: estimate.oligos,
+        overhead: estimate.overhead,
+        storage: 'dna (goldman 2013 ternary rotation, 4 strands, dual placement)',
+        reference: `${dnavaultspec.reference}; ${estimate.reference}`,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* context: optical 5d quartz planner (360 tb/disc)                     */
+/* ------------------------------------------------------------------ */
+/**
+ * opticalvault anchors: 5d femtosecond-laser nanostructuring of fused
+ * quartz as demonstrated by the university of southampton
+ * optoelectronics research centre (zhang, kazansky et al., 2013-2016):
+ * 360 tb per disc headline capacity, survival to 1000 c and the quoted
+ * 13.8-billion-year room-temperature stability. the five dimensions
+ * are three spatial coordinates plus nanograting orientation and
+ * retardance. the write parameters below are planning defaults for the
+ * femtosecond pass, not device constants.
+ */
+export const opticalvaultspec = {
+    bytesperdisc: 3.6e14,
+    layersperdisc: 100,
+    logicalbitsperdot: 4,
+    redundancycopies: 3,
+    stabilityc: 1000,
+    lifetimeyearsroom: 1.38e10,
+    pulsedurationfs: 280,
+    wavelengthnm: 1030,
+    layerspacingum: 4.5,
+    medium: 'fused quartz',
+    dimensions: 'x, y, z + nanograting orientation + retardance',
+    reference: 'zhang, gecavicius, beresna, kazansky 2013 cleo; southampton orc 2013-2016 (360 tb/disc, 13.8 billion years at room temperature)',
+};
+/**
+ * opticalplan: recording plan for a 5d quartz archive of sizebytes:
+ * disc count at 360 tb per disc with three-copy redundancy, layer and
+ * nanograting dot counts at 4 logical bits per dot, and the
+ * femtosecond write pass description. pure planner output.
+ */
+export function opticalplan(sizebytes) {
+    if (!Number.isFinite(sizebytes) || sizebytes <= 0 || sizebytes > 2 ** 50) {
+        throw new quantumerror({
+            code: 'sizerange',
+            message: `optical planner accepts archives up to 1 pebibyte, got ${sizebytes}`,
+        });
+    }
+    const stored = sizebytes * opticalvaultspec.redundancycopies;
+    const discs = Math.max(1, Math.ceil(stored / opticalvaultspec.bytesperdisc));
+    const dots = Math.ceil((stored * 8) / opticalvaultspec.logicalbitsperdot);
+    return {
+        discs,
+        layers: discs * opticalvaultspec.layersperdisc,
+        dots,
+        redundancy: opticalvaultspec.redundancycopies,
+        lifetimeyearsroom: opticalvaultspec.lifetimeyearsroom,
+        stabilityc: opticalvaultspec.stabilityc,
+        writeplan: {
+            pulsedurationfs: opticalvaultspec.pulsedurationfs,
+            wavelengthnm: opticalvaultspec.wavelengthnm,
+            layerspacingum: opticalvaultspec.layerspacingum,
+            dimensions: opticalvaultspec.dimensions,
+        },
+        reference: opticalvaultspec.reference,
+        note: 'planning defaults, not device constants; lifetime figure is the quoted upper bound',
+    };
+}
+/* ------------------------------------------------------------------ */
+/* context: holographic note (microsoft hsd) and storage compare        */
+/* ------------------------------------------------------------------ */
+/**
+ * holographic storage note for the storage tier compare: microsoft
+ * research announced the holographic storage device (hsd) program in
+ * 2024 — page-oriented holograms in a photosensitive wafer cartridge,
+ * about 1.4 tb per 12-centimeter disc form factor with a multi-terabyte
+ * roadmap. this module keeps it as a comparison note only; the
+ * concrete planners shipped here are dna and 5d quartz.
+ */
+export const holographicnote = {
+    vendor: 'microsoft research',
+    program: 'hsd (holographic storage device), announced 2024',
+    capacity: 'about 1.4 tb per 12-cm disc, multi-terabyte roadmap',
+    medium: 'photosensitive holographic wafer cartridges',
+    position: 'comparison note; no planner shipped for this tier',
+};
+/**
+ * storagecompare: one-line planner comparison across the three
+ * quantum-adjacent storage tiers this module knows about.
+ */
+export function storagecompare(sizebytes) {
+    const dna = planodefault(sizebytes);
+    const optical = opticalplan(sizebytes);
+    return [
+        {
+            tier: 'dna',
+            units: `${dna.strands} oligo strands`,
+            massorunits: `${dna.grams.toExponential(3)} g of dna`,
+            lifetime: 'centuries dry and dark (synthesis-dependent)',
+            reference: 'goldman 2013 nature 494 77-80',
+        },
+        {
+            tier: 'optical5d',
+            units: `${optical.discs} quartz disc${optical.discs === 1 ? '' : 's'}`,
+            massorunits: `${optical.layers} layers, ${optical.dots.toExponential(3)} dots`,
+            lifetime: `quoted ${optical.lifetimeyearsroom.toExponential(2)} years at room temperature, ${optical.stabilityc} c survival`,
+            reference: 'southampton orc 2013-2016',
+        },
+        {
+            tier: 'holographic',
+            units: `${Math.max(1, Math.ceil((sizebytes * 3) / 1.4e12))} hsd discs (planner sketch)`,
+            massorunits: 'wafer cartridges',
+            lifetime: 'decades, drive-dependent',
+            reference: 'microsoft hsd 2024 announcement',
+        },
+    ];
+}
+/**
+ * qrambucketbrigade: classical simulation of the giovannetti-lloyd-
+ * maccone bucket-brigade qram. a classical ram read energizes n word
+ * lines; the bucket brigade routes one bus down a binary switch tree so
+ * only log2(n) switches per read must flip (and, in the quantum
+ * version, only o(log n) qubits must be active, which is what makes
+ * quantum-addressed lookup of a superposition affordable). the switch
+ * tree is simulated hop by hop and the read result carries the trace.
+ * reference: giovannetti, lloyd, maccone, quantum random access memory,
+ * prl 100, 160501 (2008); giovannetti, lloyd, maccone, architectures
+ * for a quantum random access memory, pra 78, 052310 (2008).
+ */
+export class qrambucketbrigade {
+    #cells;
+    #addressbits;
+    constructor(cells) {
+        if (!Number.isInteger(cells) || cells < 2 || cells > 256 || (cells & (cells - 1)) !== 0) {
+            throw new quantumerror({
+                code: 'cellcount',
+                message: `qram needs a power-of-two cell count in [2, 256], got ${cells}`,
+            });
+        }
+        this.#cells = new Array(cells).fill(0);
+        this.#addressbits = Math.round(Math.log2(cells));
+    }
+    /** number of addressable cells. */
+    get cellscount() {
+        return this.#cells.length;
+    }
+    /** address width in bits (the tree depth). */
+    get addressbits() {
+        return this.#addressbits;
+    }
+    /** switch count of the tree (inner nodes; n - 1 for n cells). */
+    get switchcount() {
+        return this.#cells.length - 1;
+    }
+    /** classical write into one cell (energizes one word line). */
+    write(address, value) {
+        this.#guardaddress(address);
+        this.#cells[address] = value;
+    }
+    /** lists the cells as an address/value table. */
+    cells() {
+        return this.#cells.map((value, address) => ({ address, value }));
+    }
+    /**
+     * routes one read down the bucket-brigade tree: at level l the switch
+     * forwards along address bit (addressbits - 1 - l); the bus ends at
+     * the leaf and the trace records every switch node id visited
+     * (root id 1, children 2i and 2i + 1).
+     */
+    read(address) {
+        this.#guardaddress(address);
+        const path = [1];
+        let node = 1;
+        for (let level = 0; level < this.#addressbits; level++) {
+            const bit = (address >> (this.#addressbits - 1 - level)) & 1;
+            node = node * 2 + bit;
+            path.push(node);
+        }
+        return {
+            address,
+            value: this.#cells[address],
+            hops: this.#addressbits,
+            path,
+            switchesactive: this.#addressbits,
+            classicalwritelines: this.#cells.length,
+        };
+    }
+    #guardaddress(address) {
+        if (!Number.isInteger(address) || address < 0 || address >= this.#cells.length) {
+            throw new quantumerror({
+                code: 'addressrange',
+                message: `qram address must be in [0, ${this.#cells.length - 1}], got ${address}`,
+            });
+        }
+    }
+}
+/**
+ * qramdemo: the n=8 showcase — 3 switch levels, 7 switches, every read
+ * routes 3 hops against 8 classical word lines, plus a note of what
+ * the quantum version would query in one shot (a superposed address
+ * returning a superposed memory word).
+ */
+export function qramdemo() {
+    const qram = new qrambucketbrigade(8);
+    for (let address = 0; address < 8; address++) {
+        qram.write(address, address * 100 + 7);
+    }
+    const reads = [qram.read(0), qram.read(3), qram.read(7)];
+    return {
+        reads,
+        levels: qram.addressbits,
+        switches: qram.switchcount,
+        hops: qram.addressbits,
+        classicalwritelines: qram.cellscount,
+        reference: 'giovannetti, lloyd, maccone 2008 prl 100 160501',
+    };
+}
+/**
+ * shorplan(n): returns the theoretical shor circuit for the
+ * factorization and never runs it. honesty clause: compiled
+ * controlled-modular-exponentiation networks for any semiprime beyond
+ * toy size grow past the 20-qubit statevector budget of this
+ * simulator (numbers above 15 need more than 20 clean qubits plus
+ * ancillas before scheduling even starts in js), and the 2013
+ * "oversimplifying quantum factoring" literature shows compressed
+ * order-finding circuits for 15 can factor without any genuine quantum
+ * advantage — so the module plans, cites and stops.
+ * references: shor 1994 focs / siam j comput 26 1484 (1997);
+ * vedal, barenco, ekert 1996 pra 54 147; vandersypen et al. 2001
+ * nature 414 883 (the 7-qubit nmr run of 15); smolin, gambetta,
+ * smith 2013 pra 87 030302 "oversimplifying quantum factoring".
+ */
+export function shorplan(n) {
+    if (!Number.isInteger(n) || n < 4) {
+        throw new quantumerror({
+            code: 'compositerange',
+            message: `shorplan needs an integer >= 4, got ${n}`,
+        });
+    }
+    const isfifteen = n === 15;
+    const workqubits = isfifteen ? 4 : Math.max(4, Math.ceil(Math.log2(n)));
+    const countingqubits = isfifteen ? 3 : Math.max(3, 2 * workqubits - 5);
+    const stages = [
+        'init work register to |1> (x on the low work qubit)',
+        `hadamard over the ${countingqubits} counting qubits (uniform superposition of exponents x)`,
+        'controlled a^x mod n per exponent bit (order-4 swap pattern for a in {7, 11} when n = 15)',
+        `inverse qft over the ${countingqubits} counting qubits`,
+        'measure counting register: phases concentrate on k/4 with r = 4',
+        'continued fractions on the measured phase -> candidate order r',
+        'gcd(a^(r/2) - 1, n), gcd(a^(r/2) + 1, n) -> classical factors',
+    ];
+    return {
+        n,
+        executable: false,
+        qubits: countingqubits + workqubits,
+        countingqubits,
+        workqubits,
+        bases: isfifteen ? [7, 11] : [2],
+        expectedperiod: isfifteen ? 4 : 0,
+        factors: isfifteen ? [3, 5] : [],
+        stages,
+        gatesestimate: isfifteen ? 400 : countingqubits * workqubits * workqubits * 12,
+        reason: 'theoretical plan only: controlled modular exponentiation for semiprimes beyond 15 exceeds the 20-qubit statevector envelope of this simulator, and compressed 15-circuits are known to factor without quantum advantage (smolin-gambetta-smith 2013)',
+        references: [
+            'shor 1994 focs; siam j comput 26 1484 (1997)',
+            'vedal-barenco-ekert 1996 pra 54 147',
+            'vandersypen et al. 2001 nature 414 883',
+            'smolin-gambetta-smith 2013 pra 87 030302',
+        ],
+    };
+}
+/* ------------------------------------------------------------------ */
+/* context: registry (capability catalog)                               */
+/* ------------------------------------------------------------------ */
+/**
+ * freeze helper with a const type parameter so the registry literal
+ * keeps its exact readonly member types after freezing.
+ */
+function freeze(spec) {
+    return Object.freeze(spec);
+}
+/**
+ * quantumregistry: the capability catalog of this module for the engine
+ * integrator: simulator envelope, provable algorithms, key-exchange
+ * protocols, storage tiers, randomness sources and primary citations.
+ */
+export const quantumregistry = freeze({
+    simulator: 'statevector',
+    precision: 'float64 interleaved re/im',
+    maxqubits: 20,
+    algorithms: [
+        'bellstate',
+        'ghzstate',
+        'grover2',
+        'grover3',
+        'deutsch',
+        'qteleport',
+        'shorplan (plan only)',
+    ],
+    protocols: ['bb84', 'e91'],
+    storage: ['dna goldman 2013', 'optical 5d quartz', 'holographic note', 'qram bucket brigade'],
+    random: ['csprng (node:crypto)', 'anu qrng (optional, fallback)'],
+    sources: [
+        'goldman et al. 2013 nature 494 77-80 doi:10.1038/nature11875',
+        'church, gao, kosuri 2012 science 337 1628 (215 pb/g era)',
+        'grover 1996 stoc arxiv:quant-ph/9605043',
+        'deutsch-jozsa 1992 proc r soc lond a 439 553',
+        'bennett-brassard 1984 bangalore proceedings 175-179',
+        'ekert 1991 prl 67 661; chsh 1969 prl 23 880; bell 1964',
+        'bennett et al. 1993 prl 70 1895 (teleportation)',
+        'giovannetti-lloyd-maccone 2008 prl 100 160501 (qram)',
+        'shor 1994/1997; vandersypen 2001 nature 414 883; smolin-gambetta-smith 2013',
+        'zhang-kazansky et al. 2013-2016 southampton orc (5d quartz)',
+        'microsoft research hsd 2024 announcement',
+        'anu quantum numbers, api.quantumnumbers.io',
+    ],
+});
+/**
+ * quantumselfcheck: runs every documented claim of this module against
+ * the real simulator — bell/grover/deutsch/teleport statistics, bb84
+ * with and without an eavesdropper, the e91 chsh violation, the dna
+ * roundtrip including strand loss, the qrng range, the qram routing
+ * depth, the shor honesty clause, the 20-qubit envelope guard and the
+ * using/disposal guard. returns the row table plus pass counts so the
+ * integrator can gate ci on it. randomness is live node:crypto, so the
+ * protocol rows carry the statistical margins described in their
+ * circuit references.
+ */
+export function quantumselfcheck() {
+    const rows = [];
+    const push = (name, pass, detail) => {
+        rows.push({ name, pass, detail });
+    };
+    // 1. envelope guard: 21 qubits must be refused.
+    let refused = false;
+    try {
+        new quantumsim(21);
+    }
+    catch (cause) {
+        refused = cause instanceof quantumerror && cause.code === 'qubitrange';
+    }
+    push('maxqubits guard', refused, `quantumsim(21) refused: ${refused}`);
+    // 2. norm stability under a 12-qubit hadamard ladder.
+    {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const ladder = __addDisposableResource(env_1, new quantumsim(12), false);
+            for (let q = 0; q < 12; q++) {
+                ladder.h(q);
+            }
+            const drift = Math.abs(ladder.norm() - 1);
+            push('statevector norm', drift < 1e-12, `12 hadamards leave norm 1 within ${drift.toExponential(2)}`);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            __disposeResources(env_1);
+        }
+    }
+    // 3. bell state distribution.
+    {
+        const env_2 = { stack: [], error: void 0, hasError: false };
+        try {
+            const bell = __addDisposableResource(env_2, bellstate().sim, false);
+            const p = bell.probabilities();
+            const ok = Math.abs(p[0] - 0.5) < 1e-12 && Math.abs(p[3] - 0.5) < 1e-12 && p[1] < 1e-12 && p[2] < 1e-12;
+            push('bellstate', ok, `probs [${p[0].toFixed(6)}, ${p[1].toFixed(6)}, ${p[2].toFixed(6)}, ${p[3].toFixed(6)}] ~ [0.5, 0, 0.5, 0]`);
+        }
+        catch (e_2) {
+            env_2.error = e_2;
+            env_2.hasError = true;
+        }
+        finally {
+            __disposeResources(env_2);
+        }
+    }
+    // 4. ghz corners.
+    {
+        const env_3 = { stack: [], error: void 0, hasError: false };
+        try {
+            const ghz = __addDisposableResource(env_3, ghzstate(4).sim, false);
+            const p = ghz.probabilities();
+            const ok = Math.abs(p[0] - 0.5) < 1e-12 && Math.abs(p[15] - 0.5) < 1e-12;
+            push('ghzstate(4)', ok, `p[0000]=${p[0].toFixed(6)}, p[1111]=${p[15].toFixed(6)}`);
+        }
+        catch (e_3) {
+            env_3.error = e_3;
+            env_3.hasError = true;
+        }
+        finally {
+            __disposeResources(env_3);
+        }
+    }
+    // 5. grover2 certainty.
+    {
+        const env_4 = { stack: [], error: void 0, hasError: false };
+        try {
+            const g2 = __addDisposableResource(env_4, grover2().sim, false);
+            const p11 = g2.probabilities()[3];
+            push('grover2', p11 >= 0.99, `prob(11) = ${p11.toFixed(9)} (>= 0.99)`);
+        }
+        catch (e_4) {
+            env_4.error = e_4;
+            env_4.hasError = true;
+        }
+        finally {
+            __disposeResources(env_4);
+        }
+    }
+    // 6. grover3 statistics.
+    {
+        const env_5 = { stack: [], error: void 0, hasError: false };
+        try {
+            const g3 = __addDisposableResource(env_5, grover3().sim, false);
+            const p111 = g3.probabilities()[7];
+            push('grover3', p111 >= 0.9, `prob(111) = ${p111.toFixed(6)} (theory 0.9461, >= 0.9)`);
+        }
+        catch (e_5) {
+            env_5.error = e_5;
+            env_5.hasError = true;
+        }
+        finally {
+            __disposeResources(env_5);
+        }
+    }
+    // 7-8. deutsch both promises.
+    {
+        const constant = deutsch(() => 0);
+        const balanced = deutsch((x) => x);
+        push('deutsch constant', constant.verdict === 'constant' && constant.verdict === constant.expected, `f=0 -> ${constant.verdict} (measured ${constant.measured})`);
+        push('deutsch balanced', balanced.verdict === 'balanced' && balanced.verdict === balanced.expected, `f=x -> ${balanced.verdict} (measured ${balanced.measured})`);
+    }
+    // 9-10. teleportation fidelity for both nontrivial inputs.
+    {
+        const one = qteleport('one');
+        const plus = qteleport('plus');
+        push('qteleport |1>', Math.abs(one.fidelity - 1) < 1e-12, `fidelity ${one.fidelity.toFixed(12)} (corrections m0=${one.outcome0}, m1=${one.outcome1})`);
+        push('qteleport |+>', Math.abs(plus.fidelity - 1) < 1e-12, `fidelity ${plus.fidelity.toFixed(12)} (basis restored after z correction)`);
+    }
+    // 11-12. bb84 clean channel and intercept-resend.
+    {
+        const clean = runbb84({ eve: false, bits: 1024 });
+        push('bb84 clean', clean.qber < 0.05 && !clean.detected, `qber ${clean.qber.toFixed(4)} < 0.05, detected ${clean.detected}, sifted ${clean.siftedlen}, key ${clean.keyalice.length} bits`);
+        const attacked = runbb84({ eve: true, bits: 1024 });
+        push('bb84 intercept-resend', attacked.detected && attacked.qber > 0.2, `qber ${attacked.qber.toFixed(4)} > 0.2, sampled ${attacked.sampledqber.toFixed(4)} > ${attacked.threshold}, detected ${attacked.detected}`);
+    }
+    // 13-14. e91 chsh violation and collapse under eve.
+    {
+        const clean = rune91({ eve: false, pairs: 2400 });
+        push('e91 clean chsh', clean.s > 2.4 && !clean.detected, `s = ${clean.s.toFixed(4)} > 2.4 (tsirelson 2.8284), detected ${clean.detected}, keylen ${clean.keylen}`);
+        const attacked = rune91({ eve: true, pairs: 2400 });
+        push('e91 intercept-resend', attacked.detected, `s = ${attacked.s.toFixed(4)} (classical bound 2), qber ${Number.isFinite(attacked.qber) ? attacked.qber.toFixed(4) : 'n/a'}, detected ${attacked.detected}`);
+    }
+    // 15. dna roundtrip with a strand lost.
+    {
+        const payload = randomBytes(1000);
+        const encoded = dnavaultencode(payload);
+        const direct = dnavaultdecode(encoded.strands);
+        const degraded = dnavaultdecode([encoded.strands[0], encoded.strands[2], encoded.strands[3]]);
+        let equal = direct.length === payload.length && degraded.length === payload.length;
+        for (let i = 0; equal && i < payload.length; i++) {
+            equal = direct[i] === payload[i] && degraded[i] === payload[i];
+        }
+        let runmax = 1;
+        for (const strand of encoded.strands) {
+            let current = 1;
+            for (let i = 1; i < strand.length; i++) {
+                current = strand[i] === strand[i - 1] ? current + 1 : 1;
+                if (current > runmax) {
+                    runmax = current;
+                }
+            }
+        }
+        push('dnavault roundtrip', equal && runmax <= 3, `1000 bytes roundtrip byte-perfect with strand 1 lost; longest homopolymer run ${runmax} (<= 3)`);
+    }
+    // 16. qrng range.
+    {
+        const values = quantuminspiredrandom(4096, { min: -7, max: 19 });
+        const distinct = new Set(values).size;
+        const inrange = values.every((value) => Number.isInteger(value) && value >= -7 && value < 19);
+        push('qrng range', inrange && distinct > 16, `4096 draws in [-7, 19): all in range ${inrange}, ${distinct} distinct values`);
+    }
+    // 17. qram routing depth.
+    {
+        const demo = qramdemo();
+        push('qram bucket brigade', demo.hops === 3 && demo.switches === 7 && demo.reads.every((read) => read.hops === 3), `n=8: ${demo.switches} switches, every read routes ${demo.hops} hops vs ${demo.classicalwritelines} word lines`);
+    }
+    // 18. shor plan honesty.
+    {
+        const plan = shorplan(15);
+        push('shorplan honest', plan.executable === false && plan.qubits === 7 && plan.expectedperiod === 4, `n=15 plan: ${plan.qubits} qubits, period ${plan.expectedperiod}, factors [${plan.factors.join(', ')}], execution refused`);
+    }
+    // 19. using/disposal guard.
+    {
+        let survivor;
+        {
+            const env_6 = { stack: [], error: void 0, hasError: false };
+            try {
+                const disposable = __addDisposableResource(env_6, new quantumsim(2), false);
+                disposable.h(0);
+                survivor = disposable;
+            }
+            catch (e_6) {
+                env_6.error = e_6;
+                env_6.hasError = true;
+            }
+            finally {
+                __disposeResources(env_6);
+            }
+        }
+        let disposed = false;
+        try {
+            survivor.x(0);
+        }
+        catch (cause) {
+            disposed = cause instanceof quantumerror && cause.code === 'disposed';
+        }
+        push('using disposal', disposed, 'post-using gate call threw quantumerror(disposed)');
+    }
+    const passed = rows.filter((row) => row.pass).length;
+    return {
+        rows,
+        passed,
+        failed: rows.length - passed,
+        reference: 'task v18-quantum validation matrix; live node:crypto randomness',
+    };
+}
+//# sourceMappingURL=quantum.js.map