quantum-forge 2.7.0 → 3.0.0

package/dist/lib/quantum.js

@@ -1,7 +1,8 @@
 // src/quantum/QuantumForgeLoader.ts
-var wasmBasePath = "/quantum-forge";
+var explicitBasePath = null;
+var variant = null;
 function setWasmBasePath(path) {
-  wasmBasePath = path.endsWith("/") ? path.slice(0, -1) : path;
+  explicitBasePath = path.endsWith("/") ? path.slice(0, -1) : path;
 }
 function useQuantumForgeBuild(name) {
   if (isInitialized) {
@@ -11,7 +12,20 @@ function useQuantumForgeBuild(name) {
     );
     return;
   }
-  setWasmBasePath(`/quantum-forge-${name}`);
+  variant = name;
+  explicitBasePath = null;
+}
+function runningFromDisk() {
+  return typeof process !== "undefined" && typeof process.versions?.node === "string" && import.meta.url.startsWith("file:");
+}
+function getWasmBasePath() {
+  if (explicitBasePath !== null) return explicitBasePath;
+  if (runningFromDisk()) {
+    const dist = import.meta.url.endsWith(".ts") ? "../../dist/" : "../";
+    const dir = variant ? `${dist}quantum-forge-${variant}/` : dist;
+    return new URL(dir, import.meta.url).href.replace(/\/$/, "");
+  }
+  return variant ? `/quantum-forge-${variant}` : "/quantum-forge";
 }
 var quantumForgeModule = null;
 var initPromise = null;
@@ -48,7 +62,7 @@ async function ensureLoaded() {
   initPromise = (async () => {
     const startTime = performance.now();
     logger?.info?.("Loading Quantum Forge WASM module...", "QuantumForgeLoader");
-    const modulePath = `${wasmBasePath}/quantum-forge-web-api.mjs`;
+    const modulePath = `${getWasmBasePath()}/quantum-forge-web-api.mjs`;
     const mod = await import(
       /* @vite-ignore */
       modulePath
@@ -128,6 +142,683 @@ async function registerServiceWorker(swPath = "/quantum-forge-sw.js") {
   }
 }
 
+// src/quantum/Quantum.ts
+Symbol.dispose ??= /* @__PURE__ */ Symbol.for("Symbol.dispose");
+var QUANTUM_HANDLE = /* @__PURE__ */ Symbol.for("quantum-forge.quantum-handle");
+var nextId = 1;
+var cache = /* @__PURE__ */ new Map();
+var observers = /* @__PURE__ */ new Set();
+var pending = [];
+var delivering = false;
+function reportObserverError(err) {
+  try {
+    const report = globalThis.reportError;
+    if (typeof report === "function") report(err);
+    else console.error("A quantum observer threw:", err);
+  } catch {
+  }
+}
+function notify(deliver) {
+  if (observers.size === 0) return;
+  pending.push({ deliver, to: [...observers] });
+  if (delivering) return;
+  delivering = true;
+  try {
+    for (let next = pending.shift(); next; next = pending.shift()) {
+      for (const o of next.to) {
+        try {
+          next.deliver(o);
+        } catch (err) {
+          reportObserverError(err);
+        }
+      }
+    }
+  } finally {
+    delivering = false;
+  }
+}
+function deepFreeze(value) {
+  if (typeof value === "object" && value !== null && !Object.isFrozen(value)) {
+    Object.freeze(value);
+    for (const child of Object.values(value)) deepFreeze(child);
+  }
+  return value;
+}
+function notifyGate(event) {
+  if (observers.size === 0) return;
+  deepFreeze(event);
+  notify((o) => o.onGate?.(event));
+}
+function notifyMeasure(event) {
+  if (observers.size === 0) return;
+  deepFreeze(event);
+  notify((o) => o.onMeasure?.(event));
+}
+var IMPOSSIBLE = 1e-10;
+function wasm(method, call) {
+  try {
+    return call();
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    const limit = /num_qudits (\d+) exceeds compile-time MAX_NUM_QUDITS \((\d+)\)/.exec(message);
+    if (limit) {
+      throw new Error(
+        `${method}(): this would put ${limit[1]} qudits in one entangled state, and the loaded build holds at most ${limit[2]}. Dispose handles you no longer need to free qudits.`,
+        { cause: err }
+      );
+    }
+    throw err;
+  }
+}
+function describeValue(v) {
+  return typeof v === "string" ? JSON.stringify(v) : String(v);
+}
+function describeValues(values) {
+  return `[${values.map(describeValue).join(", ")}]`;
+}
+function assertLive(prop) {
+  if (prop.disposed) {
+    throw new Error(`Quantum property #${prop.id} was disposed and can no longer be used.`);
+  }
+}
+function checkPredicates(preds, gate) {
+  if (!preds) return [];
+  return preds.map((p) => {
+    if (p.property.disposed) {
+      throw new Error(
+        `Predicate on quantum property #${p.property.id} cannot be used: the property was disposed.`
+      );
+    }
+    if (gate?.targets.includes(p.property)) {
+      throw new Error(
+        `${gate.method}(): a gate on quantum property #${p.property.id} cannot be conditioned on that same property. A when predicate must read a different property.`
+      );
+    }
+    return p.raw;
+  });
+}
+function assertPossible(method, terms, holds, what) {
+  const m = getModule();
+  const probability = (preds) => wasm(method, () => m.predicate_probability(preds));
+  const impossible = () => new Error(
+    `${method}(): ${what} has zero probability in the current state, so it cannot be forced. Force only an outcome a measurement could give.`
+  );
+  const own = terms.map((t) => probability([t.raw]));
+  if (holds && own.some((p) => p <= IMPOSSIBLE)) throw impossible();
+  if (!holds && own.some((p) => 1 - p > IMPOSSIBLE)) return;
+  const uses = /* @__PURE__ */ new Map();
+  for (const t of terms) uses.set(t.prop, (uses.get(t.prop) ?? 0) + 1);
+  let all = 1;
+  const correlated = [];
+  terms.forEach((t, i) => {
+    if (uses.get(t.prop) === 1 && t.prop.raw.num_active_qudits() === 1) all *= own[i];
+    else correlated.push(i);
+  });
+  if (correlated.length === 1) all *= own[correlated[0]];
+  else if (correlated.length > 1) all *= probability(correlated.map((i) => terms[i].raw));
+  if ((holds ? all : 1 - all) <= IMPOSSIBLE) throw impossible();
+}
+function serialize(preds) {
+  return (preds ?? []).map((p) => ({ id: p.property.id, index: p.index, isEqual: p.isEqual }));
+}
+function indexIn(prop, value) {
+  const declared = prop.values.indexOf(value);
+  if (declared !== -1) return declared;
+  if (typeof value === "number" && Number.isInteger(value) && value >= 0 && value < prop.dimension) {
+    return value;
+  }
+  throw new RangeError(
+    `${describeValue(value)} is not a value of quantum property #${prop.id}; its values are ${describeValues(prop.values)} (or an index 0..${prop.dimension - 1}).`
+  );
+}
+function finite(n, what) {
+  if (typeof n !== "number" || !Number.isFinite(n)) {
+    throw new RangeError(`${what} must be a finite number, got ${String(n)}.`);
+  }
+  return n;
+}
+var CONSTRUCT = /* @__PURE__ */ Symbol("Quantum.construct");
+var construct;
+var Quantum = class _Quantum {
+  static {
+    construct = (raw, values) => new _Quantum(CONSTRUCT, raw, values);
+  }
+  /** Unique per `quantum()` call, increasing, never reused. */
+  id;
+  /** Declared values in basis order. Index 0 is the starting value. */
+  values;
+  /** Number of declared values. */
+  dimension;
+  _raw;
+  // An ES private field, not a property: `Object.freeze()` on the handle
+  // (deep-freeze helpers on game state do this) cannot stop dispose() from
+  // setting it.
+  #disposed = false;
+  /**
+   * The WASM property behind this handle, for the batch API (`executeBatch`,
+   * `executeBatchTape`), which has no handle-level form yet.
+   *
+   * Caveats:
+   * - Operations run through `.raw` are invisible to observers, so a
+   *   `QuantumRecorder` log will not contain them and a replay will diverge.
+   * - Never call `destroy()` on it. The handle still owns it, and its
+   *   `dispose()` would then fail.
+   * - It is valid only while the handle is live. After `dispose()` it may back
+   *   a different handle, so this getter throws.
+   * @throws Error once the handle is disposed.
+   */
+  get raw() {
+    assertLive(this);
+    return this._raw;
+  }
+  constructor(token, raw, values) {
+    if (token !== CONSTRUCT) {
+      throw new TypeError("Quantum handles are created with quantum(); the constructor is private.");
+    }
+    Object.defineProperty(this, QUANTUM_HANDLE, { value: true });
+    this.id = nextId++;
+    this._raw = raw;
+    this.values = Object.freeze([...values]);
+    this.dimension = values.length;
+  }
+  /** True once `dispose()` has run. Every other call then throws. */
+  get disposed() {
+    return this.#disposed;
+  }
+  // -- Evolution --
+  /**
+   * Hadamard gate: spread the property evenly across every value.
+   * @param fraction Omit (or pass exactly 1) for the discrete gate; any other number runs the fractional gate.
+   */
+  hadamard(fraction, opts) {
+    return this._gate("hadamard", "hadamard", fraction, opts);
+  }
+  /** Inverse Hadamard gate. Undoes `hadamard()`. */
+  inverseHadamard(opts) {
+    assertLive(this);
+    const preds = checkPredicates(opts?.when, { method: "inverseHadamard", targets: [this] });
+    const m = getModule();
+    wasm("inverseHadamard", () => {
+      if (preds.length) m.inverse_hadamard(this.raw, preds);
+      else m.inverse_hadamard(this.raw);
+    });
+    const event = {
+      op: "inverse_hadamard",
+      target: this.id,
+      predicates: serialize(opts?.when)
+    };
+    notifyGate(event);
+    return this;
+  }
+  /**
+   * Cycle gate: move to the next value, wrapping (index + 1 mod dimension).
+   * @param fraction Omit (or pass exactly 1) for the discrete gate; any other number runs the fractional gate.
+   */
+  cycle(fraction, opts) {
+    return this._gate("cycle", "cycle", fraction, opts);
+  }
+  /**
+   * Shift gate: move to the previous value, wrapping (index - 1 mod dimension).
+   * @param fraction Omit (or pass exactly 1) for the discrete gate; any other number runs the fractional gate.
+   */
+  shift(fraction, opts) {
+    return this._gate("shift", "shift", fraction, opts);
+  }
+  /**
+   * Clock gate: rotate the phase of each value by its index.
+   * @param fraction Omit (or pass exactly 1) for the discrete gate; any other number runs the fractional gate.
+   */
+  clock(fraction, opts) {
+    return this._gate("clock", "clock", fraction, opts);
+  }
+  /**
+   * Pauli X gate. Same as `shift()`; at dimension 2 also the same as `cycle()`.
+   * @param fraction Omit (or pass exactly 1) for the discrete gate; any other number runs the fractional gate.
+   */
+  x(fraction, opts) {
+    return this._gate("x", "x", fraction, opts);
+  }
+  /**
+   * Pauli Y gate. Dimension 2 only; throws on any other dimension.
+   * @param fraction Omit (or pass exactly 1) for the discrete gate; any other number runs the fractional gate.
+   */
+  y(fraction, opts) {
+    return this._gate("y", "y", fraction, opts);
+  }
+  /**
+   * Pauli Z gate. Same as `clock()`.
+   * @param fraction Omit (or pass exactly 1) for the discrete gate; any other number runs the fractional gate.
+   */
+  z(fraction, opts) {
+    return this._gate("z", "z", fraction, opts);
+  }
+  // -- Game-word aliases --
+  /**
+   * Alias for `hadamard()`.
+   * Spread the property evenly across every value.
+   */
+  superpose(fraction, opts) {
+    return this._gate("hadamard", "superpose", fraction, opts);
+  }
+  /**
+   * Alias for `cycle()`.
+   * Move to the next value, wrapping. `next(0.5)` is half a step.
+   */
+  next(fraction, opts) {
+    return this._gate("cycle", "next", fraction, opts);
+  }
+  /**
+   * Alias for `shift()`.
+   * Move to the previous value, wrapping.
+   */
+  previous(fraction, opts) {
+    return this._gate("shift", "previous", fraction, opts);
+  }
+  /**
+   * Alias for `clock()`.
+   * Turn the phase dial.
+   */
+  phase(fraction, opts) {
+    return this._gate("clock", "phase", fraction, opts);
+  }
+  /**
+   * Alias for `cycle()`, restricted to dimension 2.
+   * Swap the two values. `flip(0.5)` is the square root of NOT. Throws on any
+   * other dimension.
+   */
+  flip(fraction, opts) {
+    assertLive(this);
+    if (this.dimension !== 2) {
+      throw new Error(
+        `flip() needs a property with 2 values; quantum property #${this.id} has ${this.dimension}. Use next() or cycle() instead.`
+      );
+    }
+    return this._gate("cycle", "flip", fraction, opts);
+  }
+  // -- Interaction --
+  /**
+   * Swap the states of this property and `other`.
+   * @throws Error when `other` is this property, or has a different number of values.
+   */
+  swap(other, opts) {
+    const preds = this._pair("swap", other, opts);
+    const m = getModule();
+    wasm("swap", () => {
+      if (preds.length) m.swap(this.raw, other.raw, preds);
+      else m.swap(this.raw, other.raw);
+    });
+    const event = {
+      op: "swap",
+      targets: [this.id, other.id],
+      predicates: serialize(opts?.when)
+    };
+    notifyGate(event);
+    return this;
+  }
+  /**
+   * iSwap gate between this property and `other`. `iSwap(other, 0.5)` on
+   * a pair where one is set leaves them entangled.
+   * @param fraction Required; 1 is a full iSwap.
+   * @throws Error when `other` is this property, or has a different number of values.
+   */
+  iSwap(other, fraction, opts) {
+    const preds = this._pair("iSwap", other, opts);
+    finite(fraction, "iSwap fraction");
+    const m = getModule();
+    wasm("iSwap", () => {
+      if (preds.length) m.i_swap(this.raw, other.raw, fraction, preds);
+      else m.i_swap(this.raw, other.raw, fraction);
+    });
+    const event = {
+      op: "i_swap",
+      targets: [this.id, other.id],
+      fraction,
+      predicates: serialize(opts?.when)
+    };
+    notifyGate(event);
+    return this;
+  }
+  // -- Predicates --
+  /**
+   * A predicate that holds when this property equals `value`.
+   * @param value A declared value or its basis index.
+   * @throws RangeError when `value` is neither.
+   */
+  is(value) {
+    return this._predicate(value, true);
+  }
+  /**
+   * A predicate that holds when this property does not equal `value`.
+   * @param value A declared value or its basis index.
+   * @throws RangeError when `value` is neither.
+   */
+  isNot(value) {
+    return this._predicate(value, false);
+  }
+  // -- Measurement and inspection --
+  /** Measure this property, collapsing it and every entangled partner. Returns the declared value. */
+  measure() {
+    assertLive(this);
+    const [outcome] = wasm("measure", () => getModule().measure_properties([this.raw]));
+    const event = { op: "measure", targets: [this.id], outcomes: [outcome] };
+    notifyMeasure(event);
+    return this.values[outcome];
+  }
+  /**
+   * Measure this property with the outcome forced to `value`. For replays and tests.
+   * @param value A declared value or its basis index.
+   * @throws Error when `value` has zero probability in the current state. The
+   * state is left unchanged.
+   */
+  forcedMeasure(value) {
+    assertLive(this);
+    const index = indexIn(this, value);
+    assertPossible(
+      "forcedMeasure",
+      [{ prop: this, raw: this.raw.is(index) }],
+      true,
+      `value ${describeValue(this.values[index])} of quantum property #${this.id}`
+    );
+    const [outcome] = wasm(
+      "forcedMeasure",
+      () => getModule().forced_measure_properties([this.raw], [index])
+    );
+    const event = {
+      op: "forced_measure",
+      targets: [this.id],
+      forced: [index],
+      outcomes: [outcome]
+    };
+    notifyMeasure(event);
+    return this.values[outcome];
+  }
+  /**
+   * Probability that a measurement would give `value`. Does not collapse the state.
+   * @param value A declared value or its basis index.
+   */
+  probability(value) {
+    assertLive(this);
+    const index = indexIn(this, value);
+    return wasm("probability", () => getModule().predicate_probability([this.raw.is(index)]));
+  }
+  /** Probability of every declared value, in basis order. Does not collapse the state. */
+  probabilities() {
+    assertLive(this);
+    const probs = new Array(this.dimension).fill(0);
+    for (const entry of wasm("probabilities", () => getModule().probabilities([this.raw]))) {
+      probs[entry.qudit_values[0]] += entry.probability;
+    }
+    return this.values.map((value, i) => ({ value, probability: probs[i] }));
+  }
+  // -- Lifecycle --
+  /**
+   * End this property's life. Measures it first, which collapses any
+   * entangled partners. Then:
+   *
+   * - If it is alone in its state, it is reset to its first value and its
+   *   WASM property goes to a private cache for the next `quantum()` at this
+   *   dimension.
+   * - If it still shares a state with other qudits, its WASM property is
+   *   destroyed, which factors it out of that state, and it is not cached.
+   *   A partner left on its own shrinks back to one qudit.
+   *
+   * Calling it again does nothing. Works on a frozen handle.
+   */
+  dispose() {
+    if (this.#disposed) return;
+    const m = getModule();
+    const raw = this._raw;
+    const [outcome] = wasm("dispose", () => m.measure_properties([raw]));
+    this.#disposed = true;
+    if (raw.num_active_qudits() === 1) {
+      m.reset(raw, outcome);
+      let bucket = cache.get(this.dimension);
+      if (!bucket) {
+        bucket = [];
+        cache.set(this.dimension, bucket);
+      }
+      bucket.push(raw);
+    } else {
+      raw.destroy();
+    }
+    const value = this.values[outcome];
+    notify((o) => o.onDispose?.(this, value));
+  }
+  /** Same as `dispose()`, so a `using` declaration disposes the handle at scope exit. */
+  [Symbol.dispose]() {
+    this.dispose();
+  }
+  // -- Diagnostics --
+  /** Number of qudits in the shared state this property belongs to. */
+  numActiveQudits() {
+    assertLive(this);
+    return this.raw.num_active_qudits();
+  }
+  /** Number of basis amplitudes in the shared state vector. */
+  stateVectorSize() {
+    assertLive(this);
+    return this.raw.state_vector_size();
+  }
+  // -- Internals --
+  _predicate(value, isEqual) {
+    assertLive(this);
+    const index = indexIn(this, value);
+    const raw = isEqual ? this.raw.is(index) : this.raw.is_not(index);
+    return Object.freeze({ property: this, value: this.values[index], index, isEqual, raw });
+  }
+  /** Checks shared by swap() and iSwap(). Returns the WASM predicates. */
+  _pair(method, other, opts) {
+    assertLive(this);
+    assertLive(other);
+    if (other === this) {
+      throw new Error(`${method}(): quantum property #${this.id} cannot ${method} with itself.`);
+    }
+    if (other.dimension !== this.dimension) {
+      throw new Error(
+        `${method}(): quantum property #${this.id} has ${this.dimension} values and #${other.id} has ${other.dimension}. Both need the same number of values.`
+      );
+    }
+    return checkPredicates(opts?.when, { method, targets: [this, other] });
+  }
+  _gate(op, method, fractionOrOpts, maybeOpts) {
+    assertLive(this);
+    const [fraction, opts] = typeof fractionOrOpts === "object" ? [void 0, fractionOrOpts] : [fractionOrOpts, maybeOpts];
+    const preds = checkPredicates(opts?.when, { method, targets: [this] });
+    const sent = fraction === void 0 || fraction === 1 ? void 0 : finite(fraction, `${method} fraction`);
+    const fn = getModule()[op];
+    wasm(method, () => {
+      if (preds.length) fn(this.raw, sent, preds);
+      else if (sent !== void 0) fn(this.raw, sent);
+      else fn(this.raw);
+    });
+    const event = {
+      op,
+      target: this.id,
+      fraction: sent,
+      predicates: serialize(opts?.when)
+    };
+    notifyGate(event);
+    return this;
+  }
+};
+function declaredValuesProblem(values) {
+  if (values.length < 2) {
+    return { reason: "a quantum property needs at least 2 values", ErrorType: RangeError };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const v of values) {
+    if (typeof v !== "string" && typeof v !== "number" && typeof v !== "boolean") {
+      return {
+        reason: `${String(v)} is not a string, number or boolean`,
+        ErrorType: TypeError
+      };
+    }
+    if (typeof v === "number" && !Number.isFinite(v)) {
+      return { reason: `${describeValue(v)} is not a finite number`, ErrorType: RangeError };
+    }
+    if (seen.has(v)) {
+      return { reason: `value ${describeValue(v)} is declared twice`, ErrorType: Error };
+    }
+    seen.add(v);
+  }
+  return void 0;
+}
+function quantum(arg) {
+  let values;
+  if (typeof arg === "number") {
+    if (!Number.isInteger(arg)) {
+      throw new RangeError(`quantum(${arg}): dimension must be an integer.`);
+    }
+    if (arg < 2) {
+      throw new RangeError(`quantum(${arg}): a quantum property needs at least 2 values.`);
+    }
+    values = Array.from({ length: arg }, (_, i) => i);
+  } else {
+    const problem = declaredValuesProblem(arg);
+    if (problem) {
+      throw new problem.ErrorType(`quantum(${describeValues(arg)}): ${problem.reason}.`);
+    }
+    values = arg;
+  }
+  const dimension = values.length;
+  const max = getMaxDimension();
+  if (dimension > max) {
+    throw new Error(
+      `quantum(): a property with ${dimension} values exceeds the loaded build's maximum of ${max} values per property.`
+    );
+  }
+  const raw = cache.get(dimension)?.pop() ?? getModule().QuantumForge.createQuantumProperty(dimension);
+  const prop = construct(raw, values);
+  notify((o) => o.onCreate?.(prop));
+  return prop;
+}
+function isQuantum(x) {
+  if (typeof x !== "object" || x === null) return false;
+  const marker = Object.getOwnPropertyDescriptor(x, QUANTUM_HANDLE);
+  return marker !== void 0 && "value" in marker && marker.value === true;
+}
+function clearQuantumCache() {
+  for (const bucket of cache.values()) {
+    for (const raw of bucket) raw.destroy();
+  }
+  cache.clear();
+}
+function observeQuantum(observer) {
+  observers.add(observer);
+  return () => {
+    observers.delete(observer);
+  };
+}
+function requireProps(fn, props) {
+  if (props.length === 0) throw new Error(`${fn}() needs at least one quantum property.`);
+  props.forEach(assertLive);
+}
+function measure(...props) {
+  requireProps("measure", props);
+  const outcomes = wasm("measure", () => getModule().measure_properties(props.map((p) => p.raw)));
+  const event = {
+    op: "measure",
+    targets: props.map((p) => p.id),
+    outcomes: [...outcomes]
+  };
+  notifyMeasure(event);
+  return outcomes.map((index, i) => props[i].values[index]);
+}
+function forcedMeasure(props, values) {
+  requireProps("forcedMeasure", props);
+  if (values.length !== props.length) {
+    throw new Error(
+      `forcedMeasure(): got ${props.length} properties but ${values.length} values.`
+    );
+  }
+  const forced = props.map((p, i) => indexIn(p, values[i]));
+  assertPossible(
+    "forcedMeasure",
+    props.map((p, i) => ({ prop: p, raw: p.raw.is(forced[i]) })),
+    true,
+    `the outcome ${describeValues(props.map((p, i) => p.values[forced[i]]))} for quantum properties ${props.map((p) => `#${p.id}`).join(", ")}`
+  );
+  const outcomes = wasm(
+    "forcedMeasure",
+    () => getModule().forced_measure_properties(
+      props.map((p) => p.raw),
+      forced
+    )
+  );
+  const event = {
+    op: "forced_measure",
+    targets: props.map((p) => p.id),
+    forced,
+    outcomes: [...outcomes]
+  };
+  notifyMeasure(event);
+  return outcomes.map((index, i) => props[i].values[index]);
+}
+function probabilities(...props) {
+  requireProps("probabilities", props);
+  return wasm("probabilities", () => getModule().probabilities(props.map((p) => p.raw))).map((entry) => ({
+    values: entry.qudit_values.map((index, i) => props[i].values[index]),
+    probability: entry.probability
+  }));
+}
+function densityMatrix(...props) {
+  requireProps("densityMatrix", props);
+  return wasm(
+    "densityMatrix",
+    () => getModule().reduced_density_matrix(props.map((p) => p.raw))
+  ).map((entry) => ({
+    row: entry.row_values.map((index, i) => props[i].values[index]),
+    col: entry.col_values.map((index, i) => props[i].values[index]),
+    real: entry.value.real,
+    imag: entry.value.imag
+  }));
+}
+function measureWhen(preds) {
+  const raw = checkPredicates(preds);
+  const outcome = wasm("measureWhen", () => getModule().measure_predicate(raw));
+  const event = {
+    op: "measure_predicate",
+    predicates: serialize(preds),
+    outcome
+  };
+  notifyMeasure(event);
+  return outcome !== 0;
+}
+function forcedMeasureWhen(preds, outcome) {
+  const raw = checkPredicates(preds);
+  const forced = outcome ? 1 : 0;
+  const what = `${outcome ? "every" : "not every"} predicate holding`;
+  assertPossible(
+    "forcedMeasureWhen",
+    preds.map((p, i) => ({ prop: p.property, raw: raw[i] })),
+    outcome,
+    what
+  );
+  const actual = wasm("forcedMeasureWhen", () => getModule().forced_measure_predicate(raw, forced));
+  const event = {
+    op: "forced_measure_predicate",
+    predicates: serialize(preds),
+    forced,
+    outcome: actual
+  };
+  notifyMeasure(event);
+  if (actual !== forced) {
+    throw new Error(`forcedMeasureWhen(): ${what} has zero probability in the current state, so it cannot be forced.`);
+  }
+  return actual !== 0;
+}
+function probabilityWhen(preds) {
+  const raw = checkPredicates(preds);
+  return wasm("probabilityWhen", () => getModule().predicate_probability(raw));
+}
+function phaseRotate(angle, opts) {
+  finite(angle, "phaseRotate angle");
+  const raw = checkPredicates(opts.when);
+  wasm("phaseRotate", () => getModule().phase_rotate(raw, angle));
+  const event = { op: "phase_rotate", angle, predicates: serialize(opts.when) };
+  notifyGate(event);
+}
+
 // src/quantum/QuantumPropertyManager.ts
 var QuantumPropertyManager = class {
   dimension;
@@ -215,23 +906,381 @@ var QuantumPropertyManager = class {
   getModule() {
     return getModule();
   }
-  // -- Internal access for QuantumRecorder replay --
-  /** @internal — used by QuantumRecorder.replayLog() to restore pool state. */
+  // -- Internal access for LegacyQuantumRecorder replay --
+  /** @internal — used by LegacyQuantumRecorder.replayLog() to restore pool state. */
   _setPool(pool) {
     this.pool = pool;
   }
-  /** @internal — used by QuantumRecorder to enumerate live handles. */
+  /** @internal — used by LegacyQuantumRecorder to enumerate live handles. */
   _getProperties() {
     return this.properties;
   }
-  /** @internal — used by QuantumRecorder to enumerate pool handles. */
+  /** @internal — used by LegacyQuantumRecorder to enumerate pool handles. */
   _getPool() {
     return this.pool;
   }
 };
 
 // src/quantum/QuantumRecorder.ts
+var LOG_VERSION = 1;
+function copyPredicates(preds) {
+  return preds.map((p) => ({ id: p.id, index: p.index, isEqual: p.isEqual }));
+}
+function gateEntry(e) {
+  const predicates = copyPredicates(e.predicates);
+  switch (e.op) {
+    case "inverse_hadamard":
+      return { op: e.op, target: e.target, predicates };
+    case "swap":
+      return { op: e.op, targets: [e.targets[0], e.targets[1]], predicates };
+    case "i_swap":
+      return { op: e.op, targets: [e.targets[0], e.targets[1]], fraction: e.fraction, predicates };
+    case "phase_rotate":
+      return { op: e.op, angle: e.angle, predicates };
+    default:
+      return e.fraction === void 0 ? { op: e.op, target: e.target, predicates } : { op: e.op, target: e.target, fraction: e.fraction, predicates };
+  }
+}
+function measureEntry(e) {
+  switch (e.op) {
+    case "measure":
+      return { op: e.op, targets: [...e.targets], outcomes: [...e.outcomes] };
+    case "forced_measure":
+      return {
+        op: e.op,
+        targets: [...e.targets],
+        forced: [...e.forced],
+        outcomes: [...e.outcomes]
+      };
+    case "measure_predicate":
+      return { op: e.op, predicates: copyPredicates(e.predicates), outcome: e.outcome };
+    case "forced_measure_predicate":
+      return {
+        op: e.op,
+        predicates: copyPredicates(e.predicates),
+        forced: e.forced,
+        outcome: e.outcome
+      };
+  }
+}
+function referencedIds(e) {
+  if (e.op === "create") return [];
+  const ids = [];
+  if ("id" in e) ids.push(e.id);
+  if ("target" in e) ids.push(e.target);
+  if ("targets" in e) ids.push(...e.targets);
+  if ("predicates" in e) ids.push(...e.predicates.map((p) => p.id));
+  return ids;
+}
+var isObj = (x) => typeof x === "object" && x !== null && !Array.isArray(x);
+var isInt = (x) => typeof x === "number" && Number.isInteger(x);
+var isNum = (x) => typeof x === "number" && Number.isFinite(x);
+var isIntArray = (x) => Array.isArray(x) && x.every(isInt);
+var isPair = (x) => isIntArray(x) && x.length === 2;
+var isBit = (x) => x === 0 || x === 1;
+var isPredicates = (x) => Array.isArray(x) && x.every((p) => isObj(p) && isInt(p.id) && isInt(p.index) && typeof p.isEqual === "boolean");
+function indexReason(dims, id, index, what) {
+  if (index < 0) return `${what} ${index} is negative`;
+  const dim = dims.get(id);
+  if (dim !== void 0 && index >= dim) {
+    return `${what} ${index} is out of range for quantum property #${id}, which has ${dim} values`;
+  }
+  return void 0;
+}
+function predicatesReason(dims, preds) {
+  if (!isPredicates(preds)) return "predicates are malformed";
+  for (const p of preds) {
+    const reason = indexReason(dims, p.id, p.index, "predicate index");
+    if (reason) return reason;
+  }
+  return void 0;
+}
+function indicesReason(dims, targets, indices, what) {
+  for (let i = 0; i < targets.length; i++) {
+    const reason = indexReason(dims, targets[i], indices[i], what);
+    if (reason) return reason;
+  }
+  return void 0;
+}
+function invalidReason(e, dims) {
+  switch (e.op) {
+    case "create":
+      if (!isInt(e.id)) return "id must be an integer";
+      if (!Array.isArray(e.values)) return "values must be an array";
+      return declaredValuesProblem(e.values)?.reason;
+    case "dispose":
+      if (!isInt(e.id) || !isInt(e.outcome)) return "id and outcome must be integers";
+      return indexReason(dims, e.id, e.outcome, "outcome");
+    case "hadamard":
+    case "cycle":
+    case "shift":
+    case "clock":
+    case "x":
+    case "y":
+    case "z":
+      if (!isInt(e.target)) return "target must be an integer";
+      if (e.fraction !== void 0 && !isNum(e.fraction)) return "fraction must be a number";
+      return predicatesReason(dims, e.predicates);
+    case "inverse_hadamard":
+      if (!isInt(e.target)) return "target must be an integer";
+      return predicatesReason(dims, e.predicates);
+    case "swap":
+      if (!isPair(e.targets)) return "targets must be two integers";
+      return predicatesReason(dims, e.predicates);
+    case "i_swap":
+      if (!isPair(e.targets)) return "targets must be two integers";
+      if (!isNum(e.fraction)) return "fraction must be a number";
+      return predicatesReason(dims, e.predicates);
+    case "phase_rotate":
+      if (!isNum(e.angle)) return "angle must be a number";
+      return predicatesReason(dims, e.predicates);
+    case "measure":
+      if (!isIntArray(e.targets) || !isIntArray(e.outcomes)) {
+        return "targets and outcomes must be integer arrays";
+      }
+      if (e.targets.length !== e.outcomes.length) return "targets and outcomes differ in length";
+      return indicesReason(dims, e.targets, e.outcomes, "outcome");
+    case "forced_measure":
+      if (!isIntArray(e.targets) || !isIntArray(e.forced) || !isIntArray(e.outcomes)) {
+        return "targets, forced and outcomes must be integer arrays";
+      }
+      if (e.targets.length !== e.outcomes.length) return "targets and outcomes differ in length";
+      if (e.targets.length !== e.forced.length) return "targets and forced differ in length";
+      return indicesReason(dims, e.targets, e.forced, "forced outcome") ?? indicesReason(dims, e.targets, e.outcomes, "outcome");
+    case "measure_predicate":
+      if (!isBit(e.outcome)) return "outcome must be 0 or 1";
+      return predicatesReason(dims, e.predicates);
+    case "forced_measure_predicate":
+      if (!isBit(e.outcome) || !isBit(e.forced)) return "forced and outcome must be 0 or 1";
+      return predicatesReason(dims, e.predicates);
+    default:
+      return typeof e.op === "string" ? `unknown op ${JSON.stringify(e.op)}` : "missing op";
+  }
+}
+function validateLog(input, where) {
+  if (!isObj(input)) {
+    throw new Error(
+      `${where}: expected a log object { "version": ${LOG_VERSION}, "entries": [...] }.`
+    );
+  }
+  if (input.version !== LOG_VERSION) {
+    const got = input.version === void 0 ? "no version" : `version ${JSON.stringify(input.version)}`;
+    throw new Error(
+      `${where}: unsupported log format (${got}). This build reads version ${LOG_VERSION}.`
+    );
+  }
+  if (!Array.isArray(input.entries)) {
+    throw new Error(`${where}: the log's "entries" must be an array.`);
+  }
+  if (input.untrackedIds !== void 0 && !isIntArray(input.untrackedIds)) {
+    throw new Error(`${where}: the log's "untrackedIds" must be an array of integers.`);
+  }
+  const dims = /* @__PURE__ */ new Map();
+  input.entries.forEach((entry, position) => {
+    const reason = isObj(entry) ? invalidReason(entry, dims) : "not an object";
+    if (reason) {
+      throw new Error(`${where}: entry ${position} is invalid: ${reason}.`);
+    }
+    const valid = entry;
+    if (valid.op === "create") dims.set(valid.id, valid.values.length);
+  });
+  const entries = [...input.entries];
+  const log = { version: LOG_VERSION, entries };
+  if (input.untrackedIds !== void 0) log.untrackedIds = [...input.untrackedIds];
+  return log;
+}
 var QuantumRecorder = class {
+  _entries = [];
+  _seen = /* @__PURE__ */ new Set();
+  _untracked = /* @__PURE__ */ new Set();
+  _detach;
+  /**
+   * @throws TypeError when given any argument. The 2.x recorder took a
+   * `QuantumPropertyManager`; that one is now `LegacyQuantumRecorder`.
+   */
+  constructor(...args) {
+    if (args.length > 0) {
+      throw new TypeError(
+        "new QuantumRecorder() takes no arguments: it records quantum() handles through observeQuantum(). To record a QuantumPropertyManager, use new LegacyQuantumRecorder(manager)."
+      );
+    }
+  }
+  /** Begin recording. Clears the log. Calling it while recording restarts with an empty log. */
+  startRecording() {
+    this._detach?.();
+    this._entries = [];
+    this._seen = /* @__PURE__ */ new Set();
+    this._untracked = /* @__PURE__ */ new Set();
+    const push = (entry) => {
+      this._track(entry);
+      this._entries.push(entry);
+    };
+    this._detach = observeQuantum({
+      onCreate: (prop) => push({ op: "create", id: prop.id, values: [...prop.values] }),
+      onGate: (event) => push(gateEntry(event)),
+      onMeasure: (event) => push(measureEntry(event)),
+      onDispose: (prop, value) => push({ op: "dispose", id: prop.id, outcome: prop.values.indexOf(value) })
+    });
+  }
+  /** Note created ids, and warn the first time an entry touches a handle this recording never saw created. */
+  _track(entry) {
+    if (entry.op === "create") {
+      this._seen.add(entry.id);
+      return;
+    }
+    for (const id of referencedIds(entry)) {
+      if (this._seen.has(id) || this._untracked.has(id)) continue;
+      this._untracked.add(id);
+      console.warn(
+        `QuantumRecorder: ${entry.op} touched quantum property #${id}, which was created before startRecording(). The log cannot be replayed. Start recording before creating the handles you want replayed.`
+      );
+    }
+  }
+  /**
+   * Stop recording and return the log, `{ version: 1, entries }`. The log
+   * carries `untrackedIds` when it touched handles created before recording.
+   */
+  stopRecording() {
+    this._detach?.();
+    this._detach = void 0;
+    return this.getLog();
+  }
+  /** True between `startRecording()` and `stopRecording()`. */
+  isRecording() {
+    return this._detach !== void 0;
+  }
+  /** A copy of the log so far, `{ version: 1, entries }`. Works while recording. */
+  getLog() {
+    const log = { version: LOG_VERSION, entries: structuredClone(this._entries) };
+    if (this._untracked.size > 0) log.untrackedIds = [...this._untracked].sort((a, b) => a - b);
+    return log;
+  }
+  /**
+   * Replay a log into new handles. Each `create` makes a fresh handle with a
+   * new id; the returned map is keyed by the id in the log. Handles the log
+   * disposes are removed from the map, so it holds the handles still live at
+   * the end of the log.
+   *
+   * The log is validated first, as `deserialize()` does. A recorder running
+   * during the replay records it (see the class docs); the log passed in is
+   * never modified.
+   *
+   * @throws Error when the log is malformed, lists `untrackedIds`, or an entry
+   * references an id with no earlier `create` entry. No handle survives a throw.
+   */
+  static replay(log) {
+    const { entries, untrackedIds } = validateLog(log, "QuantumRecorder.replay");
+    if (untrackedIds && untrackedIds.length > 0) {
+      throw new Error(
+        `QuantumRecorder.replay: the log touches ${untrackedIds.map((id) => `#${id}`).join(", ")}, created before recording started, so it has no state to rebuild them from. Start recording before creating the handles you want replayed.`
+      );
+    }
+    const handles = /* @__PURE__ */ new Map();
+    const created = [];
+    try {
+      entries.forEach((entry, position) => replayEntry(entry, position, handles, created));
+    } catch (error) {
+      for (const h of created) {
+        try {
+          h.dispose();
+        } catch {
+        }
+      }
+      throw error;
+    }
+    return handles;
+  }
+  /** Serialize a log to JSON: `{ "version": 1, "entries": [...] }`. */
+  static serialize(log) {
+    return JSON.stringify(log);
+  }
+  /**
+   * Parse a log serialized by `serialize()`.
+   * @throws Error when the text is not JSON, the version is missing or
+   * unsupported, or any entry is malformed or names a basis index outside its
+   * handle's declared values.
+   */
+  static deserialize(text) {
+    return validateLog(JSON.parse(text), "QuantumRecorder.deserialize");
+  }
+};
+function replayEntry(entry, position, handles, created) {
+  const get = (id) => {
+    const h = handles.get(id);
+    if (!h) {
+      throw new Error(
+        `QuantumRecorder.replay: entry ${position} (${entry.op}) references quantum property #${id}, which no earlier create entry in the log made. Start recording before creating the handles you want replayed.`
+      );
+    }
+    return h;
+  };
+  const preds = (list) => list.map((p) => {
+    const h = get(p.id);
+    const value = h.values[p.index];
+    return p.isEqual ? h.is(value) : h.isNot(value);
+  });
+  const force = (ids, outcomes) => {
+    const props = ids.map(get);
+    forcedMeasure(
+      props,
+      props.map((h, i) => h.values[outcomes[i]])
+    );
+  };
+  switch (entry.op) {
+    case "create": {
+      if (handles.has(entry.id)) {
+        throw new Error(
+          `QuantumRecorder.replay: entry ${position} creates quantum property #${entry.id}, which an earlier create entry already made and the log has not disposed.`
+        );
+      }
+      const h = quantum(entry.values);
+      handles.set(entry.id, h);
+      created.push(h);
+      return;
+    }
+    case "dispose": {
+      const h = get(entry.id);
+      force([entry.id], [entry.outcome]);
+      h.dispose();
+      handles.delete(entry.id);
+      return;
+    }
+    case "hadamard":
+    case "cycle":
+    case "shift":
+    case "clock":
+    case "x":
+    case "y":
+    case "z":
+      get(entry.target)[entry.op](entry.fraction, { when: preds(entry.predicates) });
+      return;
+    case "inverse_hadamard":
+      get(entry.target).inverseHadamard({ when: preds(entry.predicates) });
+      return;
+    case "swap":
+      get(entry.targets[0]).swap(get(entry.targets[1]), { when: preds(entry.predicates) });
+      return;
+    case "i_swap":
+      get(entry.targets[0]).iSwap(get(entry.targets[1]), entry.fraction, {
+        when: preds(entry.predicates)
+      });
+      return;
+    case "phase_rotate":
+      phaseRotate(entry.angle, { when: preds(entry.predicates) });
+      return;
+    case "measure":
+    case "forced_measure":
+      force(entry.targets, entry.outcomes);
+      return;
+    case "measure_predicate":
+    case "forced_measure_predicate":
+      forcedMeasureWhen(preds(entry.predicates), entry.outcome !== 0);
+      return;
+  }
+}
+
+// src/quantum/LegacyQuantumRecorder.ts
+var LegacyQuantumRecorder = class {
   _recording = false;
   _log = [];
   _handleToIndex = /* @__PURE__ */ new Map();
@@ -537,10 +1586,17 @@ var OP = {
   ROTATE_BASIS_PAIR: 11
 };
 export {
+  LegacyQuantumRecorder,
   OP,
+  QUANTUM_HANDLE,
+  Quantum,
   QuantumPropertyManager,
   QuantumRecorder,
+  clearQuantumCache,
+  densityMatrix,
   ensureLoaded,
+  forcedMeasure,
+  forcedMeasureWhen,
   getAttribution,
   getMaxDimension,
   getMaxQudits,
@@ -548,8 +1604,17 @@ export {
   getModule,
   getQuantumForge,
   getVersion,
+  getWasmBasePath,
   getWasmMemoryBytes,
+  isQuantum,
   isReady,
+  measure,
+  measureWhen,
+  observeQuantum,
+  phaseRotate,
+  probabilities,
+  probabilityWhen,
+  quantum,
   registerServiceWorker,
   setWasmBasePath,
   startBackgroundLoad,