quantum-forge 2.7.0 → 3.0.0

package/dist/lib/quantum.d.ts

@@ -7,20 +7,20 @@ interface InitializeOptions {
     /** Override Emscripten's default stdout handler (console.log). */
     print?: (text: string) => void;
 }
-declare class Predicate {
+declare class Predicate$1 {
     private cppInstance;
     constructor(cppInstance: any);
     value(): number;
     is_equal(): boolean;
     getCppInstance(): any;
 }
-declare class QuantumProperty {
+declare class QuantumProperty$1 {
     private cppInstance;
     constructor(dimension: number);
     index(): number;
     dimension(): number;
-    is(value: number): Predicate;
-    is_not(value: number): Predicate;
+    is(value: number): Predicate$1;
+    is_not(value: number): Predicate$1;
     /** Number of qudits in this property's shared quantum state. */
     num_active_qudits(): number;
     /** Current number of basis amplitudes in the state vector (sparse size). */
@@ -31,16 +31,16 @@ declare class QuantumProperty {
     is_valid(): boolean;
     getCppInstance(): any;
     /** @internal Create a QuantumProperty from an existing C++ instance. */
-    static _fromCpp(cppInstance: any): QuantumProperty;
+    static _fromCpp(cppInstance: any): QuantumProperty$1;
 }
 declare class QuantumSimulation {
     private cppInstance;
     constructor();
-    createProperty(dimension: number): QuantumProperty;
+    createProperty(dimension: number): QuantumProperty$1;
     /** Factorize a property out of this simulation's shared state and destroy it.
      *  Automatically factors out any remaining qudits that became separable.
      *  Frees memory incrementally — critical for search algorithms with many ancillas. */
-    destroyProperty(prop: QuantumProperty): void;
+    destroyProperty(prop: QuantumProperty$1): void;
     /** Factor out any separable qudits across all shared states in this simulation.
      *  Call after undo operations (e.g. i_swap reversal) that may have restored separability.
      *  Separable qudits are split into independent states, reducing entanglement overhead. */
@@ -48,40 +48,40 @@ declare class QuantumSimulation {
     destroy(): void;
     isDestroyed(): boolean;
 }
-declare function cycle(prop: QuantumProperty, fraction?: number, predicates?: Predicate[]): void;
-declare function shift(prop: QuantumProperty, fraction?: number, predicates?: Predicate[]): void;
-declare function clock(prop: QuantumProperty, fraction?: number, predicates?: Predicate[]): void;
-declare function hadamard(prop: QuantumProperty, fraction?: number, predicates?: Predicate[]): void;
-declare function inverse_hadamard(prop: QuantumProperty, predicates?: Predicate[]): void;
-declare function swap(prop1: QuantumProperty, prop2: QuantumProperty, predicates?: Predicate[]): void;
-declare function i_swap(prop1: QuantumProperty, prop2: QuantumProperty, fraction: number, predicates?: Predicate[]): void;
+declare function cycle(prop: QuantumProperty$1, fraction?: number, predicates?: Predicate$1[]): void;
+declare function shift(prop: QuantumProperty$1, fraction?: number, predicates?: Predicate$1[]): void;
+declare function clock(prop: QuantumProperty$1, fraction?: number, predicates?: Predicate$1[]): void;
+declare function hadamard(prop: QuantumProperty$1, fraction?: number, predicates?: Predicate$1[]): void;
+declare function inverse_hadamard(prop: QuantumProperty$1, predicates?: Predicate$1[]): void;
+declare function swap(prop1: QuantumProperty$1, prop2: QuantumProperty$1, predicates?: Predicate$1[]): void;
+declare function i_swap(prop1: QuantumProperty$1, prop2: QuantumProperty$1, fraction: number, predicates?: Predicate$1[]): void;
 /** Pauli X gate — alias for `shift` (C++ `qforge::x`, QuantumProperty.h).
  *  NOTE: X is `shift` (decrement mod d), NOT `cycle` (increment mod d). The two
  *  coincide only at dimension 2; for d > 2 they are inverses of each other. */
-declare function x(prop: QuantumProperty, fraction?: number, predicates?: Predicate[]): void;
+declare function x(prop: QuantumProperty$1, fraction?: number, predicates?: Predicate$1[]): void;
 /** Pauli Z gate — alias for `clock` (C++ `qforge::z`, QuantumProperty.h). */
-declare function z(prop: QuantumProperty, fraction?: number, predicates?: Predicate[]): void;
+declare function z(prop: QuantumProperty$1, fraction?: number, predicates?: Predicate$1[]): void;
 /** Pauli Y gate — qubit only. Composed as S · X · S† i.e.
  *  `clock(-0.5); shift(fraction?); clock(0.5)` (C++ `qforge::y`, QuantumProperty.h).
  *  @throws Error if the property dimension is not 2, mirroring the C++ guard. */
-declare function y(prop: QuantumProperty, fraction?: number, predicates?: Predicate[]): void;
-declare function reset(prop: QuantumProperty, currentValue: number): void;
-declare function phase_rotate(predicates: Predicate[], angle: number): void;
-declare function measure_properties(props: QuantumProperty[]): number[];
-declare function forced_measure_properties(props: QuantumProperty[], forcedValues: number[]): number[];
-declare function measure_predicate(predicates: Predicate[]): number;
+declare function y(prop: QuantumProperty$1, fraction?: number, predicates?: Predicate$1[]): void;
+declare function reset(prop: QuantumProperty$1, currentValue: number): void;
+declare function phase_rotate(predicates: Predicate$1[], angle: number): void;
+declare function measure_properties(props: QuantumProperty$1[]): number[];
+declare function forced_measure_properties(props: QuantumProperty$1[], forcedValues: number[]): number[];
+declare function measure_predicate(predicates: Predicate$1[]): number;
 /** Force a predicate measurement to a specific outcome.
  *  If the forced value is impossible (zero probability), falls back to
  *  stochastic measurement and returns the actual outcome instead of throwing. */
-declare function forced_measure_predicate(predicates: Predicate[], forcedValue: number): number;
+declare function forced_measure_predicate(predicates: Predicate$1[], forcedValue: number): number;
 /** Get the probability that all predicates are simultaneously satisfied.
  *  Read-only — does not collapse or modify quantum state. */
-declare function predicate_probability(predicates: Predicate[]): number;
-declare function probabilities(props: QuantumProperty[]): Array<{
+declare function predicate_probability(predicates: Predicate$1[]): number;
+declare function probabilities$1(props: QuantumProperty$1[]): Array<{
     probability: number;
     qudit_values: number[];
 }>;
-declare function reduced_density_matrix(props: QuantumProperty[]): Array<{
+declare function reduced_density_matrix(props: QuantumProperty$1[]): Array<{
     row_values: number[];
     col_values: number[];
     value: {
@@ -94,13 +94,13 @@ type OpCode = 'cycle' | 'shift' | 'clock' | 'x' | 'z' | 'y' | 'hadamard' | 'inve
 /** A single gate operation descriptor for batch execution. */
 interface BatchOp {
     op: OpCode;
-    target?: QuantumProperty;
-    target2?: QuantumProperty;
+    target?: QuantumProperty$1;
+    target2?: QuantumProperty$1;
     /** Gate fraction. Omit for non-fractional (discrete permutation) variant. */
     fraction?: number;
     /** Rotation angle (phase_rotate only). */
     angle?: number;
-    predicates?: Predicate[];
+    predicates?: Predicate$1[];
 }
 /** Result of a batch execution. */
 interface BatchResult {
@@ -175,7 +175,7 @@ type OpNum = typeof OP$1[keyof typeof OP$1];
  * @param tape Pre-encoded Float64Array of operations
  * @returns BatchResult
  */
-declare function executeBatchTape(properties: QuantumProperty[], tape: Float64Array): BatchResult;
+declare function executeBatchTape(properties: QuantumProperty$1[], tape: Float64Array): BatchResult;
 declare class QuantumForge {
     /**
      * Initialize QuantumForge
@@ -188,7 +188,7 @@ declare class QuantumForge {
      * Check if QuantumForge is initialized
      */
     static isInitialized(): boolean;
-    static createQuantumProperty(dimension: number): QuantumProperty;
+    static createQuantumProperty(dimension: number): QuantumProperty$1;
     static createSimulation(): QuantumSimulation;
     static getVersion(): string;
     static getMaxDimension(): number;
@@ -203,12 +203,8 @@ type __quantum_forge_api_mjs_BatchResult = BatchResult;
 type __quantum_forge_api_mjs_InitializeOptions = InitializeOptions;
 type __quantum_forge_api_mjs_OpCode = OpCode;
 type __quantum_forge_api_mjs_OpNum = OpNum;
-type __quantum_forge_api_mjs_Predicate = Predicate;
-declare const __quantum_forge_api_mjs_Predicate: typeof Predicate;
 type __quantum_forge_api_mjs_QuantumForge = QuantumForge;
 declare const __quantum_forge_api_mjs_QuantumForge: typeof QuantumForge;
-type __quantum_forge_api_mjs_QuantumProperty = QuantumProperty;
-declare const __quantum_forge_api_mjs_QuantumProperty: typeof QuantumProperty;
 type __quantum_forge_api_mjs_QuantumSimulation = QuantumSimulation;
 declare const __quantum_forge_api_mjs_QuantumSimulation: typeof QuantumSimulation;
 declare const __quantum_forge_api_mjs_clock: typeof clock;
@@ -224,7 +220,6 @@ declare const __quantum_forge_api_mjs_measure_predicate: typeof measure_predicat
 declare const __quantum_forge_api_mjs_measure_properties: typeof measure_properties;
 declare const __quantum_forge_api_mjs_phase_rotate: typeof phase_rotate;
 declare const __quantum_forge_api_mjs_predicate_probability: typeof predicate_probability;
-declare const __quantum_forge_api_mjs_probabilities: typeof probabilities;
 declare const __quantum_forge_api_mjs_reduced_density_matrix: typeof reduced_density_matrix;
 declare const __quantum_forge_api_mjs_reset: typeof reset;
 declare const __quantum_forge_api_mjs_shift: typeof shift;
@@ -233,23 +228,29 @@ declare const __quantum_forge_api_mjs_x: typeof x;
 declare const __quantum_forge_api_mjs_y: typeof y;
 declare const __quantum_forge_api_mjs_z: typeof z;
 declare namespace __quantum_forge_api_mjs {
-  export { type __quantum_forge_api_mjs_BatchOp as BatchOp, type __quantum_forge_api_mjs_BatchResult as BatchResult, type __quantum_forge_api_mjs_InitializeOptions as InitializeOptions, OP$1 as OP, type __quantum_forge_api_mjs_OpCode as OpCode, type __quantum_forge_api_mjs_OpNum as OpNum, __quantum_forge_api_mjs_Predicate as Predicate, __quantum_forge_api_mjs_QuantumForge as QuantumForge, __quantum_forge_api_mjs_QuantumProperty as QuantumProperty, __quantum_forge_api_mjs_QuantumSimulation as QuantumSimulation, __quantum_forge_api_mjs_clock as clock, __quantum_forge_api_mjs_cycle as cycle, __quantum_forge_api_mjs_executeBatch as executeBatch, __quantum_forge_api_mjs_executeBatchTape as executeBatchTape, __quantum_forge_api_mjs_forced_measure_predicate as forced_measure_predicate, __quantum_forge_api_mjs_forced_measure_properties as forced_measure_properties, __quantum_forge_api_mjs_hadamard as hadamard, __quantum_forge_api_mjs_i_swap as i_swap, __quantum_forge_api_mjs_inverse_hadamard as inverse_hadamard, __quantum_forge_api_mjs_measure_predicate as measure_predicate, __quantum_forge_api_mjs_measure_properties as measure_properties, __quantum_forge_api_mjs_phase_rotate as phase_rotate, __quantum_forge_api_mjs_predicate_probability as predicate_probability, __quantum_forge_api_mjs_probabilities as probabilities, __quantum_forge_api_mjs_reduced_density_matrix as reduced_density_matrix, __quantum_forge_api_mjs_reset as reset, __quantum_forge_api_mjs_shift as shift, __quantum_forge_api_mjs_swap as swap, __quantum_forge_api_mjs_x as x, __quantum_forge_api_mjs_y as y, __quantum_forge_api_mjs_z as z };
+  export { type __quantum_forge_api_mjs_BatchOp as BatchOp, type __quantum_forge_api_mjs_BatchResult as BatchResult, type __quantum_forge_api_mjs_InitializeOptions as InitializeOptions, OP$1 as OP, type __quantum_forge_api_mjs_OpCode as OpCode, type __quantum_forge_api_mjs_OpNum as OpNum, Predicate$1 as Predicate, __quantum_forge_api_mjs_QuantumForge as QuantumForge, QuantumProperty$1 as QuantumProperty, __quantum_forge_api_mjs_QuantumSimulation as QuantumSimulation, __quantum_forge_api_mjs_clock as clock, __quantum_forge_api_mjs_cycle as cycle, __quantum_forge_api_mjs_executeBatch as executeBatch, __quantum_forge_api_mjs_executeBatchTape as executeBatchTape, __quantum_forge_api_mjs_forced_measure_predicate as forced_measure_predicate, __quantum_forge_api_mjs_forced_measure_properties as forced_measure_properties, __quantum_forge_api_mjs_hadamard as hadamard, __quantum_forge_api_mjs_i_swap as i_swap, __quantum_forge_api_mjs_inverse_hadamard as inverse_hadamard, __quantum_forge_api_mjs_measure_predicate as measure_predicate, __quantum_forge_api_mjs_measure_properties as measure_properties, __quantum_forge_api_mjs_phase_rotate as phase_rotate, __quantum_forge_api_mjs_predicate_probability as predicate_probability, probabilities$1 as probabilities, __quantum_forge_api_mjs_reduced_density_matrix as reduced_density_matrix, __quantum_forge_api_mjs_reset as reset, __quantum_forge_api_mjs_shift as shift, __quantum_forge_api_mjs_swap as swap, __quantum_forge_api_mjs_x as x, __quantum_forge_api_mjs_y as y, __quantum_forge_api_mjs_z as z };
 }
 
 /**
  * Set the base URL path where Quantum Forge WASM files are served.
  * Default is "/quantum-forge" which matches the Vite plugin's serve path.
- * Consumers using the Vite plugin don't need to call this.
+ * Consumers using the Vite plugin don't need to call this. In Node the default
+ * is this package's own dist/ directory, so a file URL is only needed when the
+ * WASM lives somewhere else.
  */
 declare function setWasmBasePath(path: string): void;
 /**
- * Select a named WASM build variant (e.g. "d7n10").
- * Sugar for `setWasmBasePath("/quantum-forge-{name}")`.
+ * Select a named WASM build variant (e.g. "qubit").
+ * In a page this loads from "/quantum-forge-{name}"; in Node it loads from
+ * this package's dist/quantum-forge-{name}/. Replaces any earlier
+ * setWasmBasePath() call.
  *
  * Must be called before `ensureLoaded()`. If the module is already loaded,
  * a warning is logged and the call is ignored.
  */
 declare function useQuantumForgeBuild(name: string): void;
+/** The base path ensureLoaded() imports from, resolved at load time. */
+declare function getWasmBasePath(): string;
 /**
  * Start loading the WASM module in the background.
  * Call this after the page has rendered (e.g., after DOMContentLoaded or initial paint).
@@ -300,6 +301,444 @@ declare function getAttribution(): string;
  */
 declare function registerServiceWorker(swPath?: string): Promise<ServiceWorkerRegistration | null>;
 
+/**
+ * Quantum — one handle per quantum property.
+ *
+ * Declare a property by the values it can take, call gates on it as methods,
+ * and end its life with `dispose()` (or a `using` declaration). There is no
+ * manager and no `getModule()` in game code.
+ *
+ * ```typescript
+ * import { quantum, measure, ensureLoaded } from "quantum-forge/quantum";
+ *
+ * await ensureLoaded();
+ * const color = quantum(["red", "green", "blue"]);   // a qutrit, starts "red"
+ * color.superpose();                                 // alias for hadamard()
+ * color.probability("green");                        // 1/3, no collapse
+ * const c = color.measure();                         // "red" | "green" | "blue"
+ *
+ * const alive = quantum([false, true]);
+ * const twin = quantum([false, true]);
+ * alive.superpose();
+ * twin.flip({ when: [alive.is(true)] });             // CNOT: the pair is now entangled
+ * measure(alive, twin);                              // [false, false] or [true, true]
+ * ```
+ *
+ * `dispose()` always measures the property first. What happens to the WASM
+ * property next depends on whether it still shares a state with others:
+ *
+ * - Alone in its state: it is reset to |0⟩ and kept in a private
+ *   per-dimension cache, and the next `quantum()` at that dimension reuses it.
+ * - Still in a shared state with other qudits: it is destroyed, which factors
+ *   it out of that state, and it is not cached. Reusing it would hand the next
+ *   `quantum()` a qudit that still counts against the old state's size.
+ *
+ * Either way a disposed handle never grows anyone's tensor product.
+ */
+
+declare global {
+    interface SymbolConstructor {
+        readonly dispose: unique symbol;
+    }
+}
+/** A value a quantum property can be declared with: a game word, a number or a boolean. */
+type QuantumValue = string | number | boolean;
+/** Options accepted by every gate method. */
+interface GateOptions {
+    /**
+     * Predicates that condition the gate. The gate acts only on the part of the
+     * state where every predicate holds. A predicate on another property makes
+     * the gate an interaction, which entangles the two.
+     */
+    when?: QuantumPredicate[];
+}
+/**
+ * A condition on one property's value, built by `is()` or `isNot()`.
+ * Used in `{ when: [...] }` on gates and by the `*When` free functions.
+ */
+interface QuantumPredicate<V extends QuantumValue = QuantumValue> {
+    /** The property this predicate tests. */
+    readonly property: Quantum<V>;
+    /** The declared value being tested. */
+    readonly value: V;
+    /** The basis index of `value`. */
+    readonly index: number;
+    /** True for `is()`, false for `isNot()`. */
+    readonly isEqual: boolean;
+    /** @internal The WASM predicate. */
+    readonly raw: Predicate$1;
+}
+/** A predicate as it appears in observer events: handle id, basis index, polarity. */
+interface SerializedQuantumPredicate {
+    id: number;
+    index: number;
+    isEqual: boolean;
+}
+/**
+ * A gate that ran, as reported to observers.
+ *
+ * `op` is always the physics operation in the WASM `OpCode` spelling
+ * (`"hadamard"`, `"inverse_hadamard"`, `"i_swap"`, ...). Aliases report as the
+ * operation they alias: `superpose()` reports `"hadamard"`, `flip()` and
+ * `next()` report `"cycle"`, and so on. `fraction` is the value sent to WASM,
+ * and is `undefined` when the discrete gate ran.
+ */
+type QuantumGateEvent = {
+    op: "hadamard" | "cycle" | "shift" | "clock" | "x" | "y" | "z";
+    target: number;
+    fraction: number | undefined;
+    predicates: SerializedQuantumPredicate[];
+} | {
+    op: "inverse_hadamard";
+    target: number;
+    predicates: SerializedQuantumPredicate[];
+} | {
+    op: "swap";
+    targets: [number, number];
+    predicates: SerializedQuantumPredicate[];
+} | {
+    op: "i_swap";
+    targets: [number, number];
+    fraction: number;
+    predicates: SerializedQuantumPredicate[];
+} | {
+    op: "phase_rotate";
+    angle: number;
+    predicates: SerializedQuantumPredicate[];
+};
+/**
+ * A measurement that ran, as reported to observers. Outcomes are basis
+ * indices; predicate outcomes are 1 (all predicates held) or 0.
+ *
+ * - `"measure"`: `Quantum.measure()` and the free `measure()`.
+ * - `"forced_measure"`: `Quantum.forcedMeasure()` and the free `forcedMeasure()`.
+ * - `"measure_predicate"`: `measureWhen()`.
+ * - `"forced_measure_predicate"`: `forcedMeasureWhen()`.
+ *
+ * In both forced events the outcome always equals `forced`: forcing an
+ * outcome with zero probability throws and reports no event.
+ */
+type QuantumMeasureEvent = {
+    op: "measure";
+    targets: number[];
+    outcomes: number[];
+} | {
+    op: "forced_measure";
+    targets: number[];
+    forced: number[];
+    outcomes: number[];
+} | {
+    op: "measure_predicate";
+    predicates: SerializedQuantumPredicate[];
+    outcome: number;
+} | {
+    op: "forced_measure_predicate";
+    predicates: SerializedQuantumPredicate[];
+    forced: number;
+    outcome: number;
+};
+/**
+ * Receives every quantum operation after it succeeds in WASM. Attach with
+ * `observeQuantum()`. The measurement `dispose()` makes internally is not
+ * reported through `onMeasure`; `onDispose` carries its outcome instead.
+ *
+ * Delivery rules:
+ * - An observer that throws does not stop the others from seeing the event,
+ *   and the error never reaches the code that ran the operation. It is
+ *   reported with `reportError()` where the runtime has it, else `console.error`.
+ * - Events arrive in execution order. An operation run from inside an
+ *   observer callback is queued, and its event is delivered once the current
+ *   event has reached every observer.
+ * - Each event goes to the observers attached when the operation ran. An
+ *   observer attached or detached from inside a callback changes who sees
+ *   later operations, not operations already queued.
+ * - Gate and measurement events are deeply frozen, and every observer gets
+ *   the same object. Copy before changing one. `onCreate` and `onDispose`
+ *   receive the live handle, which is not frozen.
+ */
+interface QuantumObserver {
+    /** A handle was created by `quantum()`. */
+    onCreate?(prop: Quantum<any>): void;
+    /** A gate ran. */
+    onGate?(event: QuantumGateEvent): void;
+    /** A measurement ran. */
+    onMeasure?(event: QuantumMeasureEvent): void;
+    /** A handle was disposed; `value` is the declared value it measured to. */
+    onDispose?(prop: Quantum<any>, value: QuantumValue): void;
+}
+/**
+ * Marker present on every `Quantum` instance as an own, non-enumerable,
+ * read-only data property with value `true`. The engine uses it to find
+ * handles on an entity without walking objects it does not understand. It is
+ * a registry symbol so two copies of core still recognize each other's
+ * handles, and non-enumerable so a spread copy `{ ...handle }` is not a handle.
+ */
+declare const QUANTUM_HANDLE: unique symbol;
+/**
+ * One quantum property, declared by its values. Create with `quantum()`; the
+ * constructor is private and throws a TypeError when called directly.
+ *
+ * Every gate returns `this` so calls chain. A gate on one property is
+ * evolution; a gate that takes a second property, or whose `when` predicate
+ * reads another property, is an interaction and leaves the two entangled.
+ *
+ * Gates that take a fraction take it as an optional leading number: omit it,
+ * or pass exactly 1, for the discrete gate. Options may follow the fraction or
+ * stand in its place: `b.flip({ when: [a.is(true)] })` and
+ * `b.flip(0.5, { when: [a.is(true)] })` both work.
+ *
+ * Wherever a value is accepted, pass either a declared value or its basis
+ * index. A declared value wins when a number could be both.
+ *
+ * A bare `Quantum` means `Quantum<QuantumValue>`, so a field typed `Quantum`
+ * holds any handle, named or numeric.
+ */
+declare class Quantum<V extends QuantumValue = QuantumValue> {
+    #private;
+    /**
+     * Marker for `isQuantum()`. Always `true`. Defined in the constructor as a
+     * non-enumerable data property, so it survives neither a spread nor
+     * `Object.assign({}, handle)`.
+     */
+    readonly [QUANTUM_HANDLE]: true;
+    /** Unique per `quantum()` call, increasing, never reused. */
+    readonly id: number;
+    /** Declared values in basis order. Index 0 is the starting value. */
+    readonly values: readonly V[];
+    /** Number of declared values. */
+    readonly dimension: number;
+    private readonly _raw;
+    /**
+     * 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(): QuantumProperty$1;
+    private constructor();
+    /** True once `dispose()` has run. Every other call then throws. */
+    get disposed(): boolean;
+    /**
+     * 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?: number | GateOptions, opts?: GateOptions): this;
+    /** Inverse Hadamard gate. Undoes `hadamard()`. */
+    inverseHadamard(opts?: GateOptions): 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?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * 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?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * 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?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * 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?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * 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?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * 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?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * Alias for `hadamard()`.
+     * Spread the property evenly across every value.
+     */
+    superpose(fraction?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * Alias for `cycle()`.
+     * Move to the next value, wrapping. `next(0.5)` is half a step.
+     */
+    next(fraction?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * Alias for `shift()`.
+     * Move to the previous value, wrapping.
+     */
+    previous(fraction?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * Alias for `clock()`.
+     * Turn the phase dial.
+     */
+    phase(fraction?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * 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?: number | GateOptions, opts?: GateOptions): this;
+    /**
+     * Swap the states of this property and `other`.
+     * @throws Error when `other` is this property, or has a different number of values.
+     */
+    swap(other: Quantum<any>, opts?: GateOptions): 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: Quantum<any>, fraction: number, opts?: GateOptions): this;
+    /**
+     * 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: V | number): QuantumPredicate<V>;
+    /**
+     * 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: V | number): QuantumPredicate<V>;
+    /** Measure this property, collapsing it and every entangled partner. Returns the declared value. */
+    measure(): V;
+    /**
+     * 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: V | number): V;
+    /**
+     * Probability that a measurement would give `value`. Does not collapse the state.
+     * @param value A declared value or its basis index.
+     */
+    probability(value: V | number): number;
+    /** Probability of every declared value, in basis order. Does not collapse the state. */
+    probabilities(): Array<{
+        value: V;
+        probability: number;
+    }>;
+    /**
+     * 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(): void;
+    /** Same as `dispose()`, so a `using` declaration disposes the handle at scope exit. */
+    [Symbol.dispose](): void;
+    /** Number of qudits in the shared state this property belongs to. */
+    numActiveQudits(): number;
+    /** Number of basis amplitudes in the shared state vector. */
+    stateVectorSize(): number;
+    private _predicate;
+    /** Checks shared by swap() and iSwap(). Returns the WASM predicates. */
+    private _pair;
+    private _gate;
+}
+/**
+ * Create a quantum property declared by its values. The dimension is the
+ * number of values, and the property starts at the first one.
+ *
+ * @example
+ * const color = quantum(["red", "green", "blue"]);
+ * const alive = quantum([false, true]);
+ * @throws RangeError when `values` has fewer than 2 entries or a non-finite number.
+ * @throws Error when `values` has duplicates, or more entries than the loaded build's maximum dimension.
+ */
+declare function quantum<V extends QuantumValue>(values: readonly V[]): Quantum<V>;
+/**
+ * Create a quantum property with `dimension` values `0..dimension-1`, starting at 0.
+ * @throws RangeError when `dimension` is not an integer, or is less than 2.
+ * @throws Error when `dimension` exceeds the loaded build's maximum dimension.
+ */
+declare function quantum(dimension: number): Quantum<number>;
+/**
+ * True when `x` is a `Quantum` handle: it has an own `QUANTUM_HANDLE` data
+ * property whose value is `true`. The marker is read through its descriptor,
+ * so a getter under that key is never invoked, and a spread copy of a handle
+ * (which drops the non-enumerable marker) is not a handle.
+ */
+declare function isQuantum(x: unknown): x is Quantum<any>;
+/**
+ * Destroy every cached WASM property and empty the cache. Live handles are not
+ * affected. Meant for tests and for freeing memory between scenes.
+ */
+declare function clearQuantumCache(): void;
+/**
+ * Attach an observer that sees every quantum operation after it succeeds.
+ * @returns A function that detaches the observer.
+ */
+declare function observeQuantum(observer: QuantumObserver): () => void;
+/**
+ * Measure several properties together. Returns each one's declared value, in argument order.
+ * @example const [a, b] = measure(alive, twin);
+ */
+declare function measure(...props: Quantum<any>[]): QuantumValue[];
+/**
+ * Measure several properties together with each outcome forced. For replays and tests.
+ * @param values One declared value or basis index per property.
+ * @throws Error when the combination of values has zero probability in the
+ * current state. The state is left unchanged.
+ */
+declare function forcedMeasure(props: Quantum<any>[], values: QuantumValue[]): QuantumValue[];
+/**
+ * Joint probabilities over several properties. Each entry lists one declared
+ * value per property, in argument order. Does not collapse the state.
+ */
+declare function probabilities(...props: Quantum<any>[]): Array<{
+    values: QuantumValue[];
+    probability: number;
+}>;
+/**
+ * Reduced density matrix over several properties. Rows and columns are
+ * labelled with one declared value per property. Does not collapse the state.
+ */
+declare function densityMatrix(...props: Quantum<any>[]): Array<{
+    row: QuantumValue[];
+    col: QuantumValue[];
+    real: number;
+    imag: number;
+}>;
+/** Measure whether every predicate holds, collapsing the state to agree. */
+declare function measureWhen(preds: QuantumPredicate[]): boolean;
+/**
+ * Measure whether every predicate holds, with the outcome forced. For replays
+ * and tests. Returns `outcome`.
+ * @throws Error when the forced outcome has zero probability in the current
+ * state. The state is left unchanged.
+ */
+declare function forcedMeasureWhen(preds: QuantumPredicate[], outcome: boolean): boolean;
+/** Probability that every predicate holds at once. Does not collapse the state. */
+declare function probabilityWhen(preds: QuantumPredicate[]): number;
+/**
+ * Rotate the phase of the part of the state where every predicate holds by `angle` radians.
+ * @example phaseRotate(Math.PI, { when: [a.is(1), b.is(1)] });
+ */
+declare function phaseRotate(angle: number, opts: {
+    when: QuantumPredicate[];
+}): void;
+
 /**
  * QuantumPropertyManager — manages quantum property lifecycles.
  *
@@ -310,20 +749,26 @@ declare function registerServiceWorker(swPath?: string): Promise<ServiceWorkerRe
  * Property pooling is critical: measured/removed properties are recycled
  * to avoid growing the tensor product and hitting qudit limits.
  *
- * For opt-in operation recording, attach a QuantumRecorder via setRecorder().
+ * For opt-in operation recording, attach a LegacyQuantumRecorder via setRecorder().
  */
 
 interface PredicateSpec$1 {
-    property: QuantumProperty;
+    property: QuantumProperty$1;
     value: number;
     isEqual: boolean;
 }
 interface QuantumRecorderHook {
-    onAcquire?(prop: QuantumProperty): void;
-    onRelease?(prop: QuantumProperty, value: number): void;
-    onSetProperty?(id: string, prop: QuantumProperty): void;
+    onAcquire?(prop: QuantumProperty$1): void;
+    onRelease?(prop: QuantumProperty$1, value: number): void;
+    onSetProperty?(id: string, prop: QuantumProperty$1): void;
     onDeleteProperty?(id: string): void;
 }
+/**
+ * Pools raw WASM properties behind string ids.
+ *
+ * @deprecated Use `quantum()` handles from the same entry point; see
+ * docs/QUANTUM_INTEGRATION.md. Removed in 4.0.
+ */
 declare class QuantumPropertyManager {
     readonly dimension: number;
     private properties;
@@ -342,15 +787,15 @@ declare class QuantumPropertyManager {
      * Get a property at |0⟩ — reuses a pooled one if available,
      * otherwise creates a fresh standalone property.
      */
-    acquireProperty(): QuantumProperty;
+    acquireProperty(): QuantumProperty$1;
     /**
      * Return a property to the pool after resetting it to |0⟩.
      * Uses the `reset` primitive which applies non-fractional cycles —
      * correct for all dimensions (no superposition created).
      */
-    releaseProperty(prop: QuantumProperty, measuredValue: number): void;
-    setProperty(id: string, prop: QuantumProperty): void;
-    getProperty(id: string): QuantumProperty | undefined;
+    releaseProperty(prop: QuantumProperty$1, measuredValue: number): void;
+    setProperty(id: string, prop: QuantumProperty$1): void;
+    getProperty(id: string): QuantumProperty$1 | undefined;
     deleteProperty(id: string): void;
     hasProperty(id: string): boolean;
     /**
@@ -362,12 +807,173 @@ declare class QuantumPropertyManager {
     get size(): number;
     get poolSize(): number;
     getModule(): ReturnType<typeof getModule>;
-    /** @internal — used by QuantumRecorder.replayLog() to restore pool state. */
-    _setPool(pool: QuantumProperty[]): void;
-    /** @internal — used by QuantumRecorder to enumerate live handles. */
-    _getProperties(): Map<string, QuantumProperty>;
-    /** @internal — used by QuantumRecorder to enumerate pool handles. */
-    _getPool(): QuantumProperty[];
+    /** @internal — used by LegacyQuantumRecorder.replayLog() to restore pool state. */
+    _setPool(pool: QuantumProperty$1[]): void;
+    /** @internal — used by LegacyQuantumRecorder to enumerate live handles. */
+    _getProperties(): Map<string, QuantumProperty$1>;
+    /** @internal — used by LegacyQuantumRecorder to enumerate pool handles. */
+    _getPool(): QuantumProperty$1[];
+}
+
+/**
+ * QuantumRecorder — opt-in recording and replay of `quantum()` handles.
+ *
+ * The recorder attaches through `observeQuantum()`, so every gate, measurement,
+ * creation and disposal is logged without the game calling anything extra.
+ * Entries name handles by their `id` and values by basis index, and the log is
+ * plain JSON: `{ "version": 1, "entries": [...] }`.
+ *
+ * ```typescript
+ * const recorder = new QuantumRecorder();
+ * recorder.startRecording();
+ * const a = quantum([false, true]);
+ * const b = quantum([false, true]);
+ * a.superpose();
+ * b.flip({ when: [a.is(true)] });
+ * measure(a, b);
+ * const text = QuantumRecorder.serialize(recorder.stopRecording());
+ *
+ * const handles = QuantumRecorder.replay(QuantumRecorder.deserialize(text));
+ * handles.get(a.id); // the replayed `a`, collapsed to the recorded outcome
+ * ```
+ */
+
+type FractionalGateOp = "hadamard" | "cycle" | "shift" | "clock" | "x" | "y" | "z";
+/**
+ * One recorded operation. Handles are named by `id`, values by basis index.
+ *
+ * Gate and measurement entries mirror `QuantumGateEvent` and
+ * `QuantumMeasureEvent` one to one, with op names in the WASM spelling
+ * (`"hadamard"`, `"cycle"`, `"i_swap"`, ...). A gate's `fraction` is omitted
+ * when the discrete gate ran.
+ */
+type QuantumLogEntry = {
+    op: "create";
+    id: number;
+    values: QuantumValue[];
+} | {
+    op: "dispose";
+    id: number;
+    outcome: number;
+} | {
+    op: FractionalGateOp;
+    target: number;
+    fraction?: number;
+    predicates: SerializedQuantumPredicate[];
+} | {
+    op: "inverse_hadamard";
+    target: number;
+    predicates: SerializedQuantumPredicate[];
+} | {
+    op: "swap";
+    targets: [number, number];
+    predicates: SerializedQuantumPredicate[];
+} | {
+    op: "i_swap";
+    targets: [number, number];
+    fraction: number;
+    predicates: SerializedQuantumPredicate[];
+} | {
+    op: "phase_rotate";
+    angle: number;
+    predicates: SerializedQuantumPredicate[];
+} | {
+    op: "measure";
+    targets: number[];
+    outcomes: number[];
+} | {
+    op: "forced_measure";
+    targets: number[];
+    forced: number[];
+    outcomes: number[];
+} | {
+    op: "measure_predicate";
+    predicates: SerializedQuantumPredicate[];
+    outcome: number;
+} | {
+    op: "forced_measure_predicate";
+    predicates: SerializedQuantumPredicate[];
+    forced: number;
+    outcome: number;
+};
+/** The log format version `serialize()` writes and `deserialize()` accepts. */
+declare const LOG_VERSION = 1;
+/**
+ * A recorded session: `{ version: 1, entries: [...] }`. `getLog()`,
+ * `stopRecording()` and `deserialize()` return this shape, and `serialize()`
+ * and `replay()` take it.
+ *
+ * `untrackedIds` is present only when the recording touched handles created
+ * before `startRecording()`. Such a log cannot be replayed: `replay()` throws.
+ */
+interface QuantumLog {
+    version: typeof LOG_VERSION;
+    entries: QuantumLogEntry[];
+    /** Ids of handles the log references but never creates, in ascending order. */
+    untrackedIds?: number[];
+}
+/**
+ * Records every operation on `quantum()` handles into a JSON-safe log, and
+ * replays a log into fresh handles with the same state.
+ *
+ * Start recording before creating the handles you want replayed. When a
+ * recorded operation touches a handle created before `startRecording()`, the
+ * recorder warns once per handle through `console.warn`, keeps recording, and
+ * lists the handle's id in the log's `untrackedIds`. `replay()` refuses such a
+ * log.
+ *
+ * Replay runs every measurement as its forced variant with the recorded
+ * outcomes, so the replayed state matches the recorded one. A recorder that is
+ * running during a replay records what the replay did: the fresh handles'
+ * `create` entries and the forced measurements. So "load a save, keep
+ * recording" yields a log that replays on its own.
+ */
+declare class QuantumRecorder {
+    private _entries;
+    private _seen;
+    private _untracked;
+    private _detach;
+    /**
+     * @throws TypeError when given any argument. The 2.x recorder took a
+     * `QuantumPropertyManager`; that one is now `LegacyQuantumRecorder`.
+     */
+    constructor(...args: []);
+    /** Begin recording. Clears the log. Calling it while recording restarts with an empty log. */
+    startRecording(): void;
+    /** Note created ids, and warn the first time an entry touches a handle this recording never saw created. */
+    private _track;
+    /**
+     * Stop recording and return the log, `{ version: 1, entries }`. The log
+     * carries `untrackedIds` when it touched handles created before recording.
+     */
+    stopRecording(): QuantumLog;
+    /** True between `startRecording()` and `stopRecording()`. */
+    isRecording(): boolean;
+    /** A copy of the log so far, `{ version: 1, entries }`. Works while recording. */
+    getLog(): QuantumLog;
+    /**
+     * 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: QuantumLog): Map<number, Quantum<any>>;
+    /** Serialize a log to JSON: `{ "version": 1, "entries": [...] }`. */
+    static serialize(log: QuantumLog): string;
+    /**
+     * 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: string): QuantumLog;
 }
 
 /**
@@ -378,11 +984,13 @@ declare class QuantumPropertyManager {
  * handle values. On replay, `forced_measure_properties` reproduces the
  * exact measurement outcomes, yielding identical quantum state.
  */
+/** @deprecated Use QuantumRecorder with quantum() handles. Removed in 4.0. */
 interface SerializedPredicate {
     propertyIndex: number;
     value: number;
     isEqual: boolean;
 }
+/** @deprecated Use QuantumRecorder with quantum() handles. Removed in 4.0. */
 type QuantumOperation = {
     op: "acquire";
     index: number;
@@ -456,7 +1064,9 @@ type QuantumOperation = {
 };
 
 /**
- * QuantumRecorder — opt-in recording and replay of quantum operations.
+ * LegacyQuantumRecorder — opt-in recording and replay of quantum operations
+ * for QuantumPropertyManager. Superseded by QuantumRecorder, which records
+ * `quantum()` handles.
  *
  * Attach to a QuantumPropertyManager via `manager.setRecorder(recorder)`.
  * When recording is active, lifecycle hooks log every state-mutating
@@ -468,25 +1078,30 @@ type QuantumOperation = {
  */
 
 interface PredicateSpec {
-    property: QuantumProperty;
+    property: QuantumProperty$1;
     value: number;
     isEqual: boolean;
 }
-declare class QuantumRecorder implements QuantumRecorderHook {
+/**
+ * Records and replays operations on a QuantumPropertyManager's pooled properties.
+ *
+ * @deprecated Use QuantumRecorder with quantum() handles. Removed in 4.0.
+ */
+declare class LegacyQuantumRecorder implements QuantumRecorderHook {
     private _recording;
     private _log;
     private _handleToIndex;
     private _nextIndex;
     private readonly _manager;
     constructor(manager: QuantumPropertyManager);
-    onAcquire(prop: QuantumProperty): void;
-    onRelease(prop: QuantumProperty, value: number): void;
-    onSetProperty(id: string, prop: QuantumProperty): void;
+    onAcquire(prop: QuantumProperty$1): void;
+    onRelease(prop: QuantumProperty$1, value: number): void;
+    onSetProperty(id: string, prop: QuantumProperty$1): void;
     onDeleteProperty(id: string): void;
     /**
      * Build WASM predicate objects from PredicateSpec array.
      */
-    buildWasmPredicates(specs: PredicateSpec[]): Predicate[];
+    buildWasmPredicates(specs: PredicateSpec[]): Predicate$1[];
     /**
      * Serialize predicates for the operation log.
      */
@@ -499,7 +1114,7 @@ declare class QuantumRecorder implements QuantumRecorderHook {
     /**
      * Get the recorded index for a property handle.
      */
-    getIndex(prop: QuantumProperty): number | undefined;
+    getIndex(prop: QuantumProperty$1): number | undefined;
     /** Begin recording quantum operations. Resets any existing log. */
     startRecording(): void;
     /** Stop recording and return the captured log. */
@@ -517,6 +1132,10 @@ declare class QuantumRecorder implements QuantumRecorderHook {
     private _replayPredicates;
 }
 
+/** The WASM property `Quantum.raw` returns, for the batch API (`executeBatch`, `executeBatchTape`). */
+type QuantumProperty = QuantumProperty$1;
+/** The WASM predicate behind `QuantumPredicate.raw`. */
+type Predicate = Predicate$1;
 /** Numeric opcode constants for tape encoding. Matches C++ OpCode enum. */
 declare const OP: {
     readonly CYCLE: 0;
@@ -533,4 +1152,4 @@ declare const OP: {
     readonly ROTATE_BASIS_PAIR: 11;
 };
 
-export { type BatchOp, type BatchResult, OP, type OpCode, type OpNum, type PredicateSpec$1 as PredicateSpec, type QuantumOperation, QuantumPropertyManager, QuantumRecorder, type QuantumRecorderHook, type SerializedPredicate, ensureLoaded, getAttribution, getMaxDimension, getMaxQudits, getMaxStateSize, getModule, getQuantumForge, getVersion, getWasmMemoryBytes, isReady, registerServiceWorker, setWasmBasePath, startBackgroundLoad, useQuantumForgeBuild };
+export { type BatchOp, type BatchResult, type GateOptions, LegacyQuantumRecorder, OP, type OpCode, type OpNum, type Predicate, type PredicateSpec$1 as PredicateSpec, QUANTUM_HANDLE, Quantum, type QuantumGateEvent, type QuantumLog, type QuantumLogEntry, type QuantumMeasureEvent, type QuantumObserver, type QuantumOperation, type QuantumPredicate, type QuantumProperty, QuantumPropertyManager, QuantumRecorder, type QuantumRecorderHook, type QuantumValue, type SerializedPredicate, type SerializedQuantumPredicate, clearQuantumCache, densityMatrix, ensureLoaded, forcedMeasure, forcedMeasureWhen, getAttribution, getMaxDimension, getMaxQudits, getMaxStateSize, getModule, getQuantumForge, getVersion, getWasmBasePath, getWasmMemoryBytes, isQuantum, isReady, measure, measureWhen, observeQuantum, phaseRotate, probabilities, probabilityWhen, quantum, registerServiceWorker, setWasmBasePath, startBackgroundLoad, useQuantumForgeBuild };