@wenathlan/saddle 1.8.18 → 2.0.2

package/dist/quantum.d.ts

@@ -0,0 +1,810 @@
+/**
+ * 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.
+ */
+/**
+ * frozen quantum layer anchors. every algorithm keeps its literature
+ * year so the registry can cite primary sources instead of folklore.
+ */
+export declare const quantumversions: {
+    readonly date: '2026-08-23';
+    readonly simulator: 'statevector';
+    readonly precision: 'float64 interleaved re/im';
+    readonly maxqubits: 20;
+    readonly amplitudelanes: 2097152;
+    readonly grover: '1996 stoc';
+    readonly deutschjozsa: '1992 proc r soc a';
+    readonly bb84: '1984 bangalore proceedings';
+    readonly e91: '1991 prl 67 661';
+    readonly teleportation: '1993 prl 70 1895';
+    readonly qram: '2008 prl 100 160501';
+};
+/**
+ * quantum layer failure envelope. every guard in this module throws it
+ * instead of a bare error so callers can branch on the code.
+ */
+export declare class quantumerror extends Error {
+    readonly code: string;
+    readonly detail?: string;
+    constructor(params: {
+        code: string;
+        message: string;
+        detail?: string;
+    });
+}
+/**
+ * a 2x2 complex unitary with rows and columns interleaved as
+ * [u00re, u00im, u01re, u01im, u10re, u10im, u11re, u11im].
+ * gate matrices are plain float tuples so the hot loop stays monomorphic.
+ */
+export type gate2x2 = readonly [number, number, number, number, number, number, number, number];
+/** hadamard matrix ((1/sqrt 2) [[1,1],[1,1]]). */
+export declare const hmatrix: gate2x2;
+/** pauli x matrix [[0,1],[1,0]]. */
+export declare const xmatrix: gate2x2;
+/** pauli y matrix [[0,-i],[i,0]]. */
+export declare const ymatrix: gate2x2;
+/** pauli z matrix diag(1,-1). */
+export declare const zmatrix: gate2x2;
+/** phase gate s = diag(1, i). */
+export declare const smatrix: gate2x2;
+/** inverse phase gate sdg = diag(1, -i). */
+export declare const sdgmatrix: gate2x2;
+/** t gate = diag(1, exp(i pi/4)). */
+export declare const tmatrix: gate2x2;
+/** inverse t gate = diag(1, exp(-i pi/4)). */
+export declare const tdgmatrix: gate2x2;
+/**
+ * builds the rotation-x matrix rx(theta) =
+ * [[cos(t/2), -i sin(t/2)], [-i sin(t/2), cos(t/2)]].
+ */
+export declare function rxmatrix(theta: number): gate2x2;
+/**
+ * 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 declare function rymatrix(theta: number): gate2x2;
+/**
+ * builds the rotation-z matrix rz(theta) = diag(e^{-i t/2}, e^{i t/2}).
+ */
+export declare function rzmatrix(theta: number): gate2x2;
+/**
+ * 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 declare class quantumsim implements Disposable {
+    #private;
+    constructor(nqubits: number);
+    /** number of qubits of the register. */
+    get nqubits(): number;
+    /** hilbert space dimension 2^n. */
+    get dim(): number;
+    /** true once Symbol.dispose released the state. */
+    get disposed(): boolean;
+    /** hadamard on qubit q. */
+    h(q: number): this;
+    /** pauli x (bit flip) on qubit q. */
+    x(q: number): this;
+    /** pauli y on qubit q. */
+    y(q: number): this;
+    /** pauli z (phase flip) on qubit q. */
+    z(q: number): this;
+    /** phase gate s = sqrt(z) on qubit q. */
+    s(q: number): this;
+    /** inverse phase gate on qubit q. */
+    sdg(q: number): this;
+    /** t = pi/8 gate on qubit q. */
+    t(q: number): this;
+    /** inverse t gate on qubit q. */
+    tdg(q: number): this;
+    /** rotation-x by theta radians on qubit q. */
+    rx(theta: number, q: number): this;
+    /** rotation-y by theta radians on qubit q. */
+    ry(theta: number, q: number): this;
+    /** rotation-z by theta radians on qubit q. */
+    rz(theta: number, q: number): this;
+    /**
+     * 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: number, target: number): this;
+    /**
+     * cz: flips the sign of every amplitude whose control and target
+     * bits are both 1.
+     */
+    cz(control: number, target: number): this;
+    /**
+     * toffoli (ccnot): swaps amplitude pairs only when both control bits
+     * are 1 and the target bit is 0.
+     */
+    toffoli(control1: number, control2: number, target: number): 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: number, b: number): this;
+    /**
+     * measures qubit q in the computational basis, collapsing the state.
+     * returns the observed classical bit.
+     */
+    measure(q: number): 0 | 1;
+    /**
+     * measures the full register in the computational basis and returns
+     * the observed basis index (qubit 0 in bit 0).
+     */
+    measureall(): number;
+    /**
+     * returns the [p0, p1] distribution of qubit q without collapsing;
+     * p1 = sum of |amplitude|^2 over indices with bit q set.
+     */
+    probs(q: number): [number, number];
+    /**
+     * returns the full |amplitude|^2 distribution over all 2^n basis
+     * states as a fresh Float64Array (index order: qubit 0 in bit 0).
+     */
+    probabilities(): Float64Array;
+    /** returns the complex amplitude of one basis index as [re, im]. */
+    amplitude(index: number): readonly [number, number];
+    /** returns a detached readonly snapshot copy of the state lanes. */
+    state(): Readonly<Float64Array>;
+    /** euclidean norm of the state vector (should stay within 1e-12 of 1). */
+    norm(): number;
+    /** renormalizes the state to unit norm (fixes float drift). */
+    normalize(): this;
+    /** resets the register to |0...0>. */
+    reset(): this;
+    /** releases the amplitude lanes; any further gate call throws. */
+    [Symbol.dispose](): void;
+}
+/**
+ * applies cnot(control, target) to sim; functional spelling of the
+ * quantumsim method for composition outside the class.
+ */
+export declare function cnot(sim: quantumsim, control: number, target: number): quantumsim;
+/**
+ * applies cz(control, target) to sim; the grover oracle for two qubits
+ * is exactly this gate on the |11> amplitude.
+ */
+export declare function cz(sim: quantumsim, control: number, target: number): quantumsim;
+/**
+ * applies toffoli(control1, control2, target) to sim, the universal
+ * reversible gate of toffoli 1980 as used in every compiled oracle.
+ */
+export declare function toffoli(sim: quantumsim, control1: number, control2: number, target: number): quantumsim;
+/**
+ * applies swap(a, b) to sim.
+ */
+export declare function swap(sim: quantumsim, a: number, b: number): quantumsim;
+/**
+ * ccz: three-qubit phase flip, composed as toffoli conjugated by
+ * hadamard on the target; used as the grover oracle and diffuser core.
+ */
+export declare function ccz(sim: quantumsim, control1: number, control2: number, target: number): quantumsim;
+/**
+ * proof bundle for a canonical circuit: the ready simulator plus the
+ * documented expected distribution so callers can assert outcomes.
+ */
+export type circuitproof = {
+    readonly sim: quantumsim;
+    readonly name: string;
+    readonly expectedprobs: readonly number[];
+    readonly reference: string;
+    readonly note: string;
+};
+/**
+ * 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 declare function bellstate(): circuitproof;
+/**
+ * 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 declare function ghzstate(n?: number): circuitproof;
+/**
+ * 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 declare function grover2(): circuitproof;
+/**
+ * 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 declare function grover3(): circuitproof;
+/**
+ * deutsch verdict of the single-bit oracle f: 'constant' when f(0) =
+ * f(1), 'balanced' when f(0) != f(1); one oracle call decides it.
+ */
+export type deutschverdict = 'constant' | 'balanced';
+/**
+ * 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 declare function deutsch(f: (x: 0 | 1) => 0 | 1): {
+    sim: quantumsim;
+    verdict: deutschverdict;
+    measured: 0 | 1;
+    expected: deutschverdict;
+    reference: string;
+};
+/**
+ * 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 declare function qteleport(input?: 'zero' | 'one' | 'plus'): {
+    sim: quantumsim;
+    outcome0: 0 | 1;
+    outcome1: 0 | 1;
+    fidelity: number;
+    input: 'zero' | 'one' | 'plus';
+    reference: string;
+};
+/**
+ * basis 0 is rectilinear (z, states |0>/|1>) and basis 1 is diagonal
+ * (x, states |+>/|->); the mapping matches the polarization bases of
+ * the 1984 protocol.
+ */
+export type bb84basis = 0 | 1;
+/**
+ * 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 declare class alice {
+    #private;
+    constructor(count: number);
+    /** alice's raw key bits. */
+    get bits(): readonly number[];
+    /** alice's basis string (0 rectilinear, 1 diagonal). */
+    get bases(): readonly number[];
+    /**
+     * 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(): quantumsim[];
+}
+/**
+ * bob station: measures each incoming photon in his own random bases
+ * (h before the z measurement when diagonal), collapsing the photon.
+ */
+export declare class bob {
+    #private;
+    constructor(count: number);
+    /** bob's basis string. */
+    get bases(): readonly number[];
+    /** bob's raw measurement outcomes. */
+    get outcomes(): readonly number[];
+    /**
+     * 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: readonly quantumsim[]): readonly number[];
+}
+/**
+ * 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 declare class eve {
+    #private;
+    /** bases eve used (for audits). */
+    get bases(): readonly number[];
+    /** bits eve extracted (for audits). */
+    get bits(): readonly number[];
+    /** taps the burst and returns the resent photons. */
+    intercept(photons: readonly quantumsim[]): quantumsim[];
+}
+/**
+ * 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 declare class bb84channel {
+    #private;
+    /** sends a photon burst onto the channel. */
+    send(photons: readonly quantumsim[]): void;
+    /**
+     * taps the channel: the operator receives the in-flight burst and its
+     * return value replaces it (intercept-resend); taps are counted.
+     */
+    tap(operator: (photons: readonly quantumsim[]) => quantumsim[]): quantumsim[];
+    /** drains the channel for the receiver. */
+    receive(): quantumsim[];
+    /** number of taps observed on the channel (informational). */
+    get tapped(): number;
+}
+/**
+ * runbb84 result: the sifted keys (sample bits removed), the
+ * full-channel qber, and the sampling-based eavesdropper verdict.
+ */
+export type bb84result = {
+    readonly keyalice: readonly number[];
+    readonly keybob: readonly number[];
+    readonly qber: number;
+    readonly detected: boolean;
+    readonly siftedlen: number;
+    readonly sampledlen: number;
+    readonly sampledqber: number;
+    readonly threshold: number;
+    readonly reference: string;
+};
+/**
+ * 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 declare function runbb84(options?: {
+    eve?: boolean;
+    bits?: number;
+}): bb84result;
+/**
+ * e91 run result: the chsh s value, the key bits extracted from
+ * matched analyzer settings and the eavesdropper verdict.
+ */
+export type e91result = {
+    readonly s: number;
+    readonly classicalbound: number;
+    readonly quantumbound: number;
+    readonly detected: boolean;
+    readonly keylen: number;
+    readonly qber: number;
+    readonly pairs: number;
+    readonly chshpairs: number;
+    readonly reference: string;
+};
+/**
+ * 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 declare function rune91(options?: {
+    eve?: boolean;
+    pairs?: number;
+}): e91result;
+/**
+ * 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 declare function quantuminspiredrandom(count: number, options?: {
+    min?: number;
+    max?: number;
+}): number[];
+/**
+ * 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 declare function anuqrng(count: number, options?: {
+    apikey?: string;
+    timeoutms?: number;
+    min?: number;
+    max?: number;
+}): Promise<{
+    values: number[];
+    source: 'anu' | 'csprng';
+    note: string;
+}>;
+/**
+ * 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 declare function quantuminspiredbytes(count: number): Uint8Array;
+/**
+ * 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 declare const dnavaultspec: {
+    readonly strandcount: 4;
+    readonly redundancy: 2;
+    readonly blockpayloadbytes: 32;
+    readonly blockframebytes: 35;
+    readonly nucleotidesperblock: 210;
+    readonly tritsperbyte: 6;
+    readonly maxinputbytes: 65536;
+    readonly homopolymerrunmax: 1;
+    readonly rule: 'next = (digit + 1 + previous) mod 4, digit in {0,1,2}';
+    readonly reference: 'goldman et al. 2013 nature 494 77-80 doi:10.1038/nature11875';
+};
+/**
+ * dnavaultencode result: the four strand oligo strings, the block
+ * count and the nucleotide accounting for the capacity planner.
+ */
+export type dnavaultencoderesult = {
+    readonly strands: readonly string[];
+    readonly blocks: number;
+    readonly oligos: number;
+    readonly nucleotides: number;
+    readonly redundancy: number;
+    readonly homopolymerrunmax: number;
+    readonly reference: string;
+};
+/**
+ * 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 declare function dnavaultencode(bytes: Uint8Array): dnavaultencoderesult;
+/**
+ * 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 declare function dnavaultdecode(strands: readonly string[]): Uint8Array;
+/**
+ * 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 declare const dnacapacityspec: {
+    readonly bytespergram: 215000000000000000;
+    readonly densityquote: '215 petabytes per gram of dna';
+    readonly densityreference: 'church, gao, kosuri 2012 science 337 1628 era estimates; nature news 2013';
+    readonly 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 declare function dnacapacity(sizebytes: number): {
+    grams: number;
+    oligos: number;
+    nucleotides: number;
+    overhead: number;
+    density: string;
+    reference: string;
+};
+/**
+ * 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 declare function planodefault(sizebytes: number): {
+    grams: number;
+    strands: number;
+    overhead: number;
+    storage: string;
+    reference: string;
+};
+/**
+ * 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 declare const opticalvaultspec: {
+    readonly bytesperdisc: 360000000000000;
+    readonly layersperdisc: 100;
+    readonly logicalbitsperdot: 4;
+    readonly redundancycopies: 3;
+    readonly stabilityc: 1000;
+    readonly lifetimeyearsroom: 13800000000;
+    readonly pulsedurationfs: 280;
+    readonly wavelengthnm: 1030;
+    readonly layerspacingum: 4.5;
+    readonly medium: 'fused quartz';
+    readonly dimensions: 'x, y, z + nanograting orientation + retardance';
+    readonly 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 declare function opticalplan(sizebytes: number): {
+    discs: number;
+    layers: number;
+    dots: number;
+    redundancy: number;
+    lifetimeyearsroom: number;
+    stabilityc: number;
+    writeplan: {
+        pulsedurationfs: number;
+        wavelengthnm: number;
+        layerspacingum: number;
+        dimensions: string;
+    };
+    reference: string;
+    note: string;
+};
+/**
+ * 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 declare const holographicnote: {
+    readonly vendor: 'microsoft research';
+    readonly program: 'hsd (holographic storage device), announced 2024';
+    readonly capacity: 'about 1.4 tb per 12-cm disc, multi-terabyte roadmap';
+    readonly medium: 'photosensitive holographic wafer cartridges';
+    readonly 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 declare function storagecompare(sizebytes: number): readonly {
+    tier: string;
+    units: string;
+    massorunits: string;
+    lifetime: string;
+    reference: string;
+}[];
+/**
+ * qramcell: one bucket-brigade memory slot addressed by its index.
+ */
+export interface qramcell {
+    readonly address: number;
+    readonly value: number;
+}
+/**
+ * qramreadresult: the value plus the routing trace that proves the
+ * o(log n) switch activity of the bucket-brigade tree.
+ */
+export interface qramreadresult {
+    readonly address: number;
+    readonly value: number;
+    readonly hops: number;
+    readonly path: readonly number[];
+    readonly switchesactive: number;
+    readonly classicalwritelines: number;
+}
+/**
+ * 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 declare class qrambucketbrigade {
+    #private;
+    constructor(cells: number);
+    /** number of addressable cells. */
+    get cellscount(): number;
+    /** address width in bits (the tree depth). */
+    get addressbits(): number;
+    /** switch count of the tree (inner nodes; n - 1 for n cells). */
+    get switchcount(): number;
+    /** classical write into one cell (energizes one word line). */
+    write(address: number, value: number): void;
+    /** lists the cells as an address/value table. */
+    cells(): readonly qramcell[];
+    /**
+     * 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: number): qramreadresult;
+}
+/**
+ * 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 declare function qramdemo(): {
+    reads: readonly qramreadresult[];
+    levels: number;
+    switches: number;
+    hops: number;
+    classicalwritelines: number;
+    reference: string;
+};
+/**
+ * shorcircuitplan: the honest factoring plan. the module ships the
+ * theoretical 7-qubit order-finding circuit for n = 15 (3 counting
+ * qubits + 4 work qubits, base a in {7, 11}, period 4,
+ * gcd(7^2 - 1, 15) = 3 and gcd(7^2 + 1, 15) = 5) and refuses to run it.
+ */
+export type shorcircuitplan = {
+    readonly n: number;
+    readonly executable: false;
+    readonly qubits: number;
+    readonly countingqubits: number;
+    readonly workqubits: number;
+    readonly bases: readonly number[];
+    readonly expectedperiod: number;
+    readonly factors: readonly number[];
+    readonly stages: readonly string[];
+    readonly gatesestimate: number;
+    readonly reason: string;
+    readonly references: readonly string[];
+};
+/**
+ * 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 declare function shorplan(n: number): shorcircuitplan;
+/**
+ * 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 declare const quantumregistry: Readonly<{
+    readonly simulator: "statevector";
+    readonly precision: "float64 interleaved re/im";
+    readonly maxqubits: 20;
+    readonly algorithms: readonly ["bellstate", "ghzstate", "grover2", "grover3", "deutsch", "qteleport", "shorplan (plan only)"];
+    readonly protocols: readonly ["bb84", "e91"];
+    readonly storage: readonly ["dna goldman 2013", "optical 5d quartz", "holographic note", "qram bucket brigade"];
+    readonly random: readonly ["csprng (node:crypto)", "anu qrng (optional, fallback)"];
+    readonly sources: readonly ["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"];
+}>;
+/** registry type alias for integrators that want the frozen shape. */
+export type quantumregistrytype = typeof quantumregistry;
+/**
+ * one machine-verified claim row: name, pass flag and a detail line
+ * with the measured numbers.
+ */
+export type quantumcheckrow = {
+    readonly name: string;
+    readonly pass: boolean;
+    readonly detail: string;
+};
+/**
+ * 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 declare function quantumselfcheck(): {
+    rows: readonly quantumcheckrow[];
+    passed: number;
+    failed: number;
+    reference: string;
+};
+//# sourceMappingURL=quantum.d.ts.map