@kirkelliott/kdfts 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirk Elliott
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,102 @@
+# kdfts
+
+[![CI](https://github.com/dmvjs/kdfts/actions/workflows/ci.yml/badge.svg)](https://github.com/dmvjs/kdfts/actions/workflows/ci.yml)
+[![license](https://img.shields.io/github/license/dmvjs/kdfts)](LICENSE)
+
+If you're storing passwords or deriving secrets that must survive a server compromise, the salt is what attackers try to precompute. A stolen PRNG seed, a weak entropy source, or a future algorithm break can reconstruct every salt you've ever generated. `kdfts` removes that attack surface by sourcing salt from the [ANU Quantum Random Number Generator](https://quantumnumbers.anu.edu.au) — photon shot noise at a beam splitter. Those bytes were never produced by an algorithm. There is no state to steal.
+
+Falls back silently to `crypto.getRandomValues()` when the ANU API is unavailable.
+
+## Install
+
+```bash
+npm install @kirkelliott/kdfts
+```
+
+Get a free ANU API key at [quantumnumbers.anu.edu.au](https://quantumnumbers.anu.edu.au):
+
+```bash
+export ANU_API_KEY=your-key-here
+```
+
+## Usage
+
+**Derive and persist:**
+
+```ts
+import { derive, formatCert } from '@kirkelliott/kdfts'
+
+const { key, salt, certificate } = await derive('my-password', {
+  context: 'myapp:user42:session',  // domain separation — optional but recommended
+})
+
+// Persist these — both are needed to verify later
+const persistedSalt = salt.toString('hex')
+const persistedKey  = key.toString('hex')
+
+console.log(formatCert(certificate))
+// ════════════════════════════════════════════════════
+//   kdfts Key Certificate
+// ════════════════════════════════════════════════════
+//   Source:        ANU Quantum Vacuum (photon shot noise)
+//   Timestamp:     2026-03-07T04:00:00.000Z
+//   KDF:           scrypt
+//   N / r / p:     16384 / 8 / 1
+//   Key length:    32 bytes (256 bits)
+//   Salt bytes:    32 bytes (256 bits)
+//   Context:       myapp:user42:session
+//
+//   Salt hash:     7bcaf7d45ef1191f9d72556b5f7f6e17...
+//   Key hash:      f0d6b878bb864d5261d5ccd05353bfc1...
+// ════════════════════════════════════════════════════
+```
+
+**Verify later:**
+
+```ts
+import { verify } from '@kirkelliott/kdfts'
+
+const salt = Buffer.from(persistedSalt, 'hex')
+const key  = Buffer.from(persistedKey, 'hex')
+
+const valid = await verify('my-password', salt, key, {
+  context: 'myapp:user42:session',
+})
+```
+
+**Reuse a source across multiple derivations** (saves one ANU round-trip):
+
+```ts
+import { QuantumSource, derive } from '@kirkelliott/kdfts'
+
+const source = await QuantumSource.create()
+console.log(source.source)  // 'anu' | 'crypto'
+
+const [keyA, keyB] = await Promise.all([
+  derive(passwordA, { source }),
+  derive(passwordB, { source }),
+])
+```
+
+## Options
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `context` | `string` | — | Domain separation string. Mixed in as `password \|\| 0x00 \|\| context`. |
+| `saltBytes` | `number` | `32` | Bytes of quantum entropy to fetch. |
+| `keyLength` | `number` | `32` | Output key length in bytes. |
+| `cost` | `{ N, r, p }` | `{ N: 16384, r: 8, p: 1 }` | scrypt parameters. Increase `N` for higher-value keys. |
+| `source` | `QuantumSource` | — | Pre-created source for reuse or testing. |
+
+## Security notes
+
+- Salt is fetched fresh for every `derive` call — never reused
+- Context is domain-separated with a null byte: `password || 0x00 || context`
+- Verification uses `crypto.timingSafeEqual` — no timing oracle on key comparison
+- scrypt defaults (`N=16384, r=8, p=1`) follow [OWASP recommendations](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)
+- The certificate records only SHA-256 hashes of the salt and key, never the raw values
+- Every claim in this README is validated by the [test suite](https://github.com/dmvjs/kdfts/actions/workflows/ci.yml)
+
+## License
+
+MIT © Kirk Elliott

package/dist/bench/index.js

@@ -0,0 +1,232 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runBenchmarks = runBenchmarks;
+/**
+ * KwantumScrypt Boundary Tests
+ *
+ * These tests push the limits of the system and prove — with exact numbers —
+ * where and why things fail. Failures are not bugs; they are fundamental.
+ */
+const circuit_1 = require("../lang/circuit");
+const state_1 = require("../core/state");
+const line = '─'.repeat(60);
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const grn = (s) => `\x1b[32m${s}\x1b[0m`;
+const ylw = (s) => `\x1b[33m${s}\x1b[0m`;
+function fmt(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 ** 2)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 ** 3)
+        return `${(bytes / 1024 ** 2).toFixed(1)} MB`;
+    return `${(bytes / 1024 ** 3).toFixed(2)} GB`;
+}
+// ── Bell State Fidelity ────────────────────────────────────────────────────
+//
+// Prepares |Φ+⟩ = (|00⟩ + |11⟩)/√2, measures N shots.
+// Ideal: exactly 50% |00⟩, 50% |11⟩.
+// We show statistical deviation from ideal across shot counts.
+//
+async function testBellFidelity(ks) {
+    console.log(bold('\n[1] Bell State Fidelity — (|00⟩ + |11⟩)/√2'));
+    console.log('    Ideal: P(00) = P(11) = 0.5000');
+    console.log(line);
+    for (const shots of [10, 100, 1000, 10_000]) {
+        ks.reset().h(0).cx(0, 1);
+        const r = await ks.run(shots);
+        const p00 = (r.counts['00'] ?? 0) / shots;
+        const p11 = (r.counts['11'] ?? 0) / shots;
+        const deviation = Math.abs(p00 - 0.5);
+        const status = deviation < 0.05 ? grn('PASS') : ylw('DRIFT');
+        console.log(`    shots=${shots.toString().padStart(6)}  P(00)=${p00.toFixed(4)}  P(11)=${p11.toFixed(4)}  Δ=${deviation.toFixed(4)}  ${status}`);
+    }
+}
+// ── GHZ State Scaling ──────────────────────────────────────────────────────
+//
+// GHZ_n = (|000...0⟩ + |111...1⟩)/√2 across n qubits.
+// Tests entanglement fidelity as we scale up.
+// Ideal: 50% all-zeros, 50% all-ones. Everything else = decoherence.
+//
+async function testGHZScaling() {
+    console.log(bold('\n[2] GHZ State Scaling — (|0...0⟩ + |1...1⟩)/√2'));
+    console.log('    Ideal: P(0...0) = P(1...1) = 0.5, all others = 0');
+    console.log(line);
+    const shots = 1000;
+    for (const n of [2, 3, 4, 5, 6, 8, 10, 12, 16, 20]) {
+        const ks = await circuit_1.KwantumScrypt.create(n);
+        ks.h(0);
+        for (let i = 1; i < n; i++)
+            ks.cx(0, i);
+        const r = await ks.run(shots);
+        const allZeros = '0'.repeat(n);
+        const allOnes = '1'.repeat(n);
+        const p0 = (r.counts[allZeros] ?? 0) / shots;
+        const p1 = (r.counts[allOnes] ?? 0) / shots;
+        const leaked = 1 - p0 - p1; // probability in unwanted states
+        const mem = fmt(new state_1.StateVector(n).memoryBytes());
+        const status = leaked < 0.01 ? grn('IDEAL') : leaked < 0.1 ? ylw('DRIFT') : red('LEAKING');
+        console.log(`    n=${n.toString().padStart(2)}  P(0s)=${p0.toFixed(3)}  P(1s)=${p1.toFixed(3)}  leak=${leaked.toFixed(3)}  mem=${mem.padStart(8)}  ${status}`);
+    }
+}
+// ── Memory Wall ────────────────────────────────────────────────────────────
+//
+// State vector size = 2^n × 16 bytes (two float64s per complex number).
+// This is the fundamental reason classical quantum simulation is hard.
+// At ~26–28 qubits we hit RAM limits on most machines.
+//
+function testMemoryWall() {
+    console.log(bold('\n[3] Memory Wall — State Vector Size = 2^n × 16 bytes'));
+    console.log('    This is WHY quantum computers can\'t be classically simulated');
+    console.log(line);
+    for (const n of [1, 2, 4, 8, 10, 12, 16, 20, 24, 26, 28, 30, 32]) {
+        const bytes = (1 << Math.min(n, 30)) * 2 * 8;
+        const feasible = n <= 28;
+        const status = n <= 20 ? grn('feasible') : n <= 26 ? ylw('slow/heavy') : red('FAILS — OOM');
+        console.log(`    n=${n.toString().padStart(2)}  states=${(Math.pow(2, n)).toExponential(2).padStart(10)}  RAM=${fmt(bytes).padStart(10)}  ${status}`);
+    }
+    console.log();
+    console.log('    ' + red('BOUNDARY: Classical simulation breaks at ~26–30 qubits.'));
+    console.log('    ' + red('IonQ Aria (25q) and Forte (36q) operate beyond this wall.'));
+    console.log('    ' + red('This is why real quantum hardware has value.'));
+}
+// ── Circuit Depth & Decoherence Simulation ────────────────────────────────
+//
+// In a perfect simulator, fidelity never degrades.
+// But we can MODEL decoherence by applying small noise after each gate.
+// This demonstrates what happens on real hardware (IonQ, IBM, etc.).
+//
+async function testDepthDecoherence() {
+    console.log(bold('\n[4] Circuit Depth — Decoherence Simulation'));
+    console.log('    Applying small depolarizing noise ε per gate layer');
+    console.log('    Simulates T2 coherence loss on real hardware');
+    console.log(line);
+    const n = 3;
+    const shots = 500;
+    const noise = 0.01; // 1% depolarizing noise per layer
+    for (const depth of [1, 2, 4, 8, 16, 32, 64]) {
+        const ks = await circuit_1.KwantumScrypt.create(n);
+        // Build a circuit of `depth` layers of H + CX
+        ks.h(0);
+        for (let d = 0; d < depth; d++) {
+            for (let i = 0; i < n - 1; i++)
+                ks.cx(i, i + 1);
+            for (let i = 0; i < n; i++)
+                ks.h(i);
+        }
+        ks.measure();
+        const state = ks.inspect();
+        const probs = state.probabilities();
+        // Simulate decoherence: after `depth` layers, amplitudes decay
+        // Real metric: entropy of the probability distribution
+        // Higher entropy = more mixed = more decoherence
+        const entropy = -probs.reduce((s, p) => p > 0 ? s + p * Math.log2(p) : s, 0);
+        const maxEntropy = n; // fully mixed state has entropy = n bits
+        const decoherence = entropy / maxEntropy;
+        // Apply noise model: each layer depolarizes by (1-ε)^depth
+        const noiseDecay = Math.pow(1 - noise, depth);
+        const modelFidelity = 0.5 + 0.5 * noiseDecay; // fidelity vs ideal state
+        const status = decoherence < 0.6 ? grn('coherent') : decoherence < 0.9 ? ylw('degrading') : red('fully mixed');
+        console.log(`    depth=${depth.toString().padStart(3)}  entropy=${entropy.toFixed(3)}/${maxEntropy}  model_fidelity=${modelFidelity.toFixed(3)}  ${status}`);
+    }
+    console.log();
+    console.log(`    Noise model: ${noise * 100}% depolarizing per gate layer`);
+    console.log('    ' + red('On real IonQ hardware: T2 ≈ 1–10ms, ~100 gates before coherence loss'));
+}
+// ── KSIF Round-trip ───────────────────────────────────────────────────────
+//
+// Encode a circuit as binary bitstrings, decode it, verify it's identical.
+//
+async function testKSIFEncoding() {
+    console.log(bold('\n[5] KSIF Binary Encoding — Circuit ↔ Bitstring Round-trip'));
+    console.log('    Programs expressed as quantum bitstrings');
+    console.log(line);
+    const { decode } = await Promise.resolve().then(() => __importStar(require('../lang/encoder')));
+    const { CryptoQRNG } = await Promise.resolve().then(() => __importStar(require('../qrng/anu')));
+    const ks = circuit_1.KwantumScrypt.withQRNG(3, new CryptoQRNG(), 'crypto');
+    ks.h(0).cx(0, 1).cx(0, 2).rx(Math.PI / 4, 1).measure();
+    const ksif = ks.toKSIF();
+    console.log('\n    Circuit encoded as KSIF bitstrings:');
+    ksif.split('\n').forEach(line => console.log(`      ${line}`));
+    // Round-trip decode
+    const decoded = decode(ksif);
+    const reKs = circuit_1.KwantumScrypt.fromKSIF(ksif, 3, new CryptoQRNG(), 'crypto');
+    const r = await reKs.run(100);
+    console.log('\n    GHZ state superposition before measurement:');
+    Object.entries(r.superposition)
+        .sort((a, b) => b[1] - a[1])
+        .forEach(([bits, p]) => console.log(`      |${bits}⟩  ${(p * 100).toFixed(2)}%`));
+    console.log(`\n    Decoded ${decoded.length} ops. Sample result: |${r.bitstring}⟩  ${grn('✓')}`);
+}
+// ── Quantum Notation Test ─────────────────────────────────────────────────
+async function testQuantumNotation() {
+    console.log(bold('\n[6] Quantum Notation DSL — ks.bs("H|0⟩")'));
+    console.log(line);
+    const { CryptoQRNG } = await Promise.resolve().then(() => __importStar(require('../qrng/anu')));
+    const ks = circuit_1.KwantumScrypt.withQRNG(3, new CryptoQRNG(), 'crypto');
+    // Build Bell state using notation
+    ks.bs('H|0⟩')
+        .bs('CX|0→1⟩')
+        .bs('CX|0→2⟩')
+        .bs('M|*⟩');
+    const r = await ks.run(200);
+    console.log('\n    Circuit: H|0⟩ → CX|0→1⟩ → CX|0→2⟩ → M|*⟩');
+    console.log('    GHZ state |000⟩ + |111⟩:');
+    Object.entries(r.counts)
+        .sort((a, b) => b[1] - a[1])
+        .forEach(([bits, count]) => {
+        const bar = '█'.repeat(Math.round(count / 200 * 30));
+        console.log(`      |${bits}⟩  ${count.toString().padStart(4)} shots  ${bar}`);
+    });
+}
+// ── Main ──────────────────────────────────────────────────────────────────
+async function runBenchmarks() {
+    console.log(bold('\n╔══════════════════════════════════════════════════════════╗'));
+    console.log(bold('║         KwantumScrypt — Boundary Tests                   ║'));
+    console.log(bold('╚══════════════════════════════════════════════════════════╝'));
+    const ks2 = await circuit_1.KwantumScrypt.create(2);
+    const source = bold(ks2['qrngSource'] === 'anu' ? grn('ANU quantum vacuum') : ylw('crypto.getRandomValues'));
+    console.log(`\nRandom source: ${source}`);
+    await testBellFidelity(ks2);
+    await testGHZScaling();
+    testMemoryWall();
+    await testDepthDecoherence();
+    await testKSIFEncoding();
+    await testQuantumNotation();
+    console.log(bold('\n' + line));
+    console.log('Done.\n');
+}

package/dist/core/complex.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Complex = void 0;
+/** Immutable complex number */
+class Complex {
+    re;
+    im;
+    constructor(re, im = 0) {
+        this.re = re;
+        this.im = im;
+    }
+    add(b) { return new Complex(this.re + b.re, this.im + b.im); }
+    sub(b) { return new Complex(this.re - b.re, this.im - b.im); }
+    mul(b) {
+        return new Complex(this.re * b.re - this.im * b.im, this.re * b.im + this.im * b.re);
+    }
+    scale(s) { return new Complex(this.re * s, this.im * s); }
+    conj() { return new Complex(this.re, -this.im); }
+    abs2() { return this.re * this.re + this.im * this.im; }
+    abs() { return Math.sqrt(this.abs2()); }
+    toString() {
+        if (Math.abs(this.im) < 1e-10)
+            return this.re.toFixed(6);
+        if (Math.abs(this.re) < 1e-10)
+            return `${this.im.toFixed(6)}i`;
+        const sign = this.im >= 0 ? '+' : '';
+        return `${this.re.toFixed(6)}${sign}${this.im.toFixed(6)}i`;
+    }
+    static ZERO = new Complex(0, 0);
+    static ONE = new Complex(1, 0);
+    static I = new Complex(0, 1);
+    /** e^(iθ) */
+    static phase(theta) {
+        return new Complex(Math.cos(theta), Math.sin(theta));
+    }
+}
+exports.Complex = Complex;

package/dist/core/gates.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GATE_MATRICES = void 0;
+exports.rx = rx;
+exports.ry = ry;
+exports.rz = rz;
+exports.applySingleQubit = applySingleQubit;
+exports.applyCX = applyCX;
+exports.applySWAP = applySWAP;
+exports.applyXX = applyXX;
+exports.applyGPi = applyGPi;
+exports.applyGPi2 = applyGPi2;
+const complex_1 = require("./complex");
+const { ZERO: Z, ONE: O, I } = complex_1.Complex;
+/** Standard gate matrices */
+exports.GATE_MATRICES = {
+    H: [[O.scale(Math.SQRT1_2), O.scale(Math.SQRT1_2)],
+        [O.scale(Math.SQRT1_2), O.scale(-Math.SQRT1_2)]],
+    X: [[Z, O], [O, Z]],
+    Y: [[Z, I.scale(-1)], [I, Z]],
+    Z: [[O, Z], [Z, O.scale(-1)]],
+    S: [[O, Z], [Z, new complex_1.Complex(0, 1)]],
+    SI: [[O, Z], [Z, new complex_1.Complex(0, -1)]],
+    T: [[O, Z], [Z, complex_1.Complex.phase(Math.PI / 4)]],
+    TI: [[O, Z], [Z, complex_1.Complex.phase(-Math.PI / 4)]],
+};
+/** Rotation gate matrices */
+function rx(theta) {
+    const c = new complex_1.Complex(Math.cos(theta / 2));
+    const s = new complex_1.Complex(0, -Math.sin(theta / 2));
+    return [[c, s], [s, c]];
+}
+function ry(theta) {
+    const c = new complex_1.Complex(Math.cos(theta / 2));
+    const sp = new complex_1.Complex(Math.sin(theta / 2));
+    const sn = new complex_1.Complex(-Math.sin(theta / 2));
+    return [[c, sn], [sp, c]];
+}
+function rz(theta) {
+    return [
+        [complex_1.Complex.phase(-theta / 2), Z],
+        [Z, complex_1.Complex.phase(theta / 2)]
+    ];
+}
+/**
+ * Apply a single-qubit gate to `target` qubit.
+ * Modifies state in-place.
+ * Complexity: O(2^n)
+ */
+function applySingleQubit(state, target, mat) {
+    const size = state.size;
+    for (let i = 0; i < size; i++) {
+        // Only process pairs where bit `target` = 0
+        if ((i >> target) & 1)
+            continue;
+        const j = i | (1 << target);
+        const a = state.amp[i];
+        const b = state.amp[j];
+        state.amp[i] = mat[0][0].mul(a).add(mat[0][1].mul(b));
+        state.amp[j] = mat[1][0].mul(a).add(mat[1][1].mul(b));
+    }
+}
+/**
+ * Apply CNOT (CX) gate.
+ * Flips `target` when `control` = 1.
+ * Modifies state in-place.
+ */
+function applyCX(state, control, target) {
+    const size = state.size;
+    for (let i = 0; i < size; i++) {
+        if (!((i >> control) & 1))
+            continue; // control must be 1
+        if ((i >> target) & 1)
+            continue; // target must be 0
+        const j = i | (1 << target);
+        const tmp = state.amp[i];
+        state.amp[i] = state.amp[j];
+        state.amp[j] = tmp;
+    }
+}
+/**
+ * Apply SWAP gate.
+ * Modifies state in-place.
+ */
+function applySWAP(state, a, b) {
+    const size = state.size;
+    for (let i = 0; i < size; i++) {
+        const bitA = (i >> a) & 1;
+        const bitB = (i >> b) & 1;
+        if (bitA === bitB)
+            continue;
+        // Swap only when bits differ and bitA=0, bitB=1 (process each pair once)
+        if (bitA !== 0)
+            continue;
+        const j = (i ^ (1 << a)) | (1 << b);
+        const tmp = state.amp[i];
+        state.amp[i] = state.amp[j];
+        state.amp[j] = tmp;
+    }
+}
+/**
+ * Mølmer–Sørensen XX(θ) gate — IonQ's native 2-qubit gate.
+ * XX(θ) = exp(-i θ X⊗X / 2)
+ */
+function applyXX(state, a, b, theta) {
+    const c = Math.cos(theta / 2);
+    const s = Math.sin(theta / 2);
+    const size = state.size;
+    for (let i = 0; i < size; i++) {
+        const ba = (i >> a) & 1;
+        const bb = (i >> b) & 1;
+        if (ba !== 0 || bb !== 0)
+            continue; // process each group once
+        const i01 = i | (1 << b);
+        const i10 = i | (1 << a);
+        const i11 = i | (1 << a) | (1 << b);
+        const [v00, v01, v10, v11] = [state.amp[i], state.amp[i01], state.amp[i10], state.amp[i11]];
+        const ni = new complex_1.Complex(0, -s);
+        state.amp[i] = v00.scale(c).add(v11.mul(new complex_1.Complex(0, -s)));
+        state.amp[i01] = v01.scale(c).add(v10.mul(new complex_1.Complex(0, -s)));
+        state.amp[i10] = v10.scale(c).add(v01.mul(new complex_1.Complex(0, -s)));
+        state.amp[i11] = v11.scale(c).add(v00.mul(new complex_1.Complex(0, -s)));
+        void ni; // suppress lint
+    }
+}
+/**
+ * IonQ native GPi gate (single-qubit).
+ * GPi(φ) = [[0, e^(-iφ)], [e^(iφ), 0]]
+ */
+function applyGPi(state, target, phase) {
+    const mat = [
+        [complex_1.Complex.ZERO, complex_1.Complex.phase(-phase)],
+        [complex_1.Complex.phase(phase), complex_1.Complex.ZERO]
+    ];
+    applySingleQubit(state, target, mat);
+}
+/**
+ * IonQ native GPi2 gate (single-qubit).
+ * GPi2(φ) = 1/√2 * [[1, -i·e^(-iφ)], [-i·e^(iφ), 1]]
+ */
+function applyGPi2(state, target, phase) {
+    const s = Math.SQRT1_2;
+    const mat = [
+        [new complex_1.Complex(s, 0), complex_1.Complex.phase(-phase).mul(new complex_1.Complex(0, -s))],
+        [complex_1.Complex.phase(phase).mul(new complex_1.Complex(0, -s)), new complex_1.Complex(s, 0)]
+    ];
+    applySingleQubit(state, target, mat);
+}

package/dist/core/state.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StateVector = void 0;
+const complex_1 = require("./complex");
+/**
+ * Quantum state vector for n qubits.
+ * Size = 2^n complex amplitudes.
+ * Qubit 0 = least significant bit (matching IonQ convention).
+ */
+class StateVector {
+    numQubits;
+    size;
+    amp;
+    constructor(numQubits, amplitudes) {
+        this.numQubits = numQubits;
+        this.size = 1 << numQubits;
+        if (amplitudes) {
+            this.amp = amplitudes;
+        }
+        else {
+            // |00...0⟩
+            this.amp = new Array(this.size).fill(complex_1.Complex.ZERO);
+            this.amp[0] = complex_1.Complex.ONE;
+        }
+    }
+    /** Probability of basis state i (Born rule) */
+    prob(i) {
+        return this.amp[i].abs2();
+    }
+    /** All probabilities summed = 1 */
+    probabilities() {
+        return this.amp.map(a => a.abs2());
+    }
+    /** Nonzero terms as { bitstring → probability } */
+    toBitstrings() {
+        const result = {};
+        for (let i = 0; i < this.size; i++) {
+            const p = this.prob(i);
+            if (p > 1e-10) {
+                result[i.toString(2).padStart(this.numQubits, '0')] = p;
+            }
+        }
+        return result;
+    }
+    /** Collapse to index `outcome`, zero all other amplitudes */
+    collapse(outcome) {
+        for (let i = 0; i < this.size; i++) {
+            this.amp[i] = i === outcome ? complex_1.Complex.ONE : complex_1.Complex.ZERO;
+        }
+    }
+    /** Dirac notation */
+    toString() {
+        const terms = [];
+        for (let i = 0; i < this.size; i++) {
+            const a = this.amp[i];
+            if (a.abs2() > 1e-10) {
+                const bits = i.toString(2).padStart(this.numQubits, '0');
+                terms.push(`(${a})|${bits}⟩`);
+            }
+        }
+        return terms.join(' + ') || '|0⟩';
+    }
+    /**
+     * Memory footprint in bytes.
+     * Each complex number = 2 × 8 bytes (two float64s).
+     */
+    memoryBytes() {
+        return this.size * 2 * 8;
+    }
+    clone() {
+        return new StateVector(this.numQubits, [...this.amp]);
+    }
+}
+exports.StateVector = StateVector;