quantum-forge 2.0.2

package/dist/lib/quantum.d.ts

@@ -0,0 +1,370 @@
+import { LoggerInterface } from './logging.js';
+
+declare class Predicate {
+    private cppInstance;
+    constructor(cppInstance: any);
+    value(): number;
+    is_equal(): boolean;
+    getCppInstance(): any;
+}
+declare class QuantumProperty {
+    private cppInstance;
+    constructor(dimension: number);
+    index(): number;
+    dimension(): number;
+    is(value: number): Predicate;
+    is_not(value: number): Predicate;
+    getCppInstance(): any;
+}
+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 x(prop: QuantumProperty, fraction?: number, predicates?: Predicate[]): void;
+declare function z(prop: QuantumProperty, fraction?: number, predicates?: Predicate[]): void;
+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 probabilities(props: QuantumProperty[]): Array<{
+    probability: number;
+    qudit_values: number[];
+}>;
+declare function reduced_density_matrix(props: QuantumProperty[]): Array<{
+    row_values: number[];
+    col_values: number[];
+    value: {
+        real: number;
+        imag: number;
+    };
+}>;
+declare class QuantumForge {
+    /**
+     * Initialize QuantumForge
+     * Automatically detects and loads the appropriate WASM module format
+     */
+    static initialize(): Promise<void>;
+    /**
+     * Check if QuantumForge is initialized
+     */
+    static isInitialized(): boolean;
+    static createQuantumProperty(dimension: number): QuantumProperty;
+    static getVersion(): string;
+    static getMaxDimension(): number;
+    static getMaxQudits(): number;
+    static isValidDimension(dimension: number): boolean;
+}
+
+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;
+declare const __quantum_forge_api_mjs_clock: typeof clock;
+declare const __quantum_forge_api_mjs_cycle: typeof cycle;
+declare const __quantum_forge_api_mjs_forced_measure_properties: typeof forced_measure_properties;
+declare const __quantum_forge_api_mjs_hadamard: typeof hadamard;
+declare const __quantum_forge_api_mjs_i_swap: typeof i_swap;
+declare const __quantum_forge_api_mjs_inverse_hadamard: typeof inverse_hadamard;
+declare const __quantum_forge_api_mjs_measure_predicate: typeof measure_predicate;
+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_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;
+declare const __quantum_forge_api_mjs_swap: typeof swap;
+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 { __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_clock as clock, __quantum_forge_api_mjs_cycle as cycle, __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_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 };
+}
+
+/**
+ * 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.
+ */
+declare function setWasmBasePath(path: string): void;
+/**
+ * Select a named WASM build variant (e.g. "d7n10").
+ * Sugar for `setWasmBasePath("/quantum-forge-{name}")`.
+ *
+ * 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;
+/**
+ * Start loading the WASM module in the background.
+ * Call this after the page has rendered (e.g., after DOMContentLoaded or initial paint).
+ */
+declare function startBackgroundLoad(loggerRef?: LoggerInterface): void;
+/**
+ * Ensure Quantum Forge is loaded and initialized.
+ * Returns a promise that resolves when the module is ready.
+ * Can be called multiple times - will return the same promise.
+ */
+declare function ensureLoaded(): Promise<void>;
+/**
+ * Check if Quantum Forge is ready to use (non-blocking).
+ */
+declare function isReady(): boolean;
+/**
+ * Get the loaded module. Throws if not loaded.
+ * For synchronous access after ensuring it's loaded.
+ */
+declare function getModule(): typeof __quantum_forge_api_mjs;
+/**
+ * Get the QuantumForge class from the loaded module.
+ */
+declare function getQuantumForge(): typeof QuantumForge;
+/**
+ * Convenience re-exports for common operations.
+ * These will throw if module not loaded.
+ */
+declare function getVersion(): string;
+declare function getMaxDimension(): number;
+declare function getMaxQudits(): number;
+/**
+ * Get the WASM memory bytes (for analytics).
+ */
+declare function getWasmMemoryBytes(): number | null;
+/**
+ * Get the required attribution text for display in your application.
+ * Include this in a user-visible location (credits screen, about page, etc.).
+ */
+declare function getAttribution(): string;
+/**
+ * Register the Quantum Forge service worker for offline WASM caching.
+ * Call once from your game controller after page load.
+ * The SW caches WASM artifacts on first fetch so subsequent loads work offline.
+ *
+ * @param swPath - Path to the service worker file. Default: "/quantum-forge-sw.js"
+ */
+declare function registerServiceWorker(swPath?: string): Promise<ServiceWorkerRegistration | null>;
+
+/**
+ * QuantumPropertyManager — manages quantum property lifecycles.
+ *
+ * Handles the common pattern of acquiring, pooling, and releasing WASM
+ * QuantumProperty handles. Games either extend this class or compose it
+ * to add game-specific quantum operations via getModule().
+ *
+ * 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().
+ */
+
+interface PredicateSpec$1 {
+    property: QuantumProperty;
+    value: number;
+    isEqual: boolean;
+}
+interface QuantumRecorderHook {
+    onAcquire?(prop: QuantumProperty): void;
+    onRelease?(prop: QuantumProperty, value: number): void;
+    onSetProperty?(id: string, prop: QuantumProperty): void;
+    onDeleteProperty?(id: string): void;
+}
+declare class QuantumPropertyManager {
+    readonly dimension: number;
+    private properties;
+    private pool;
+    protected logger?: LoggerInterface;
+    private _recorder?;
+    constructor(options?: {
+        dimension?: number;
+        logger?: LoggerInterface;
+    });
+    /** Attach an optional recorder for operation logging. */
+    setRecorder(recorder: QuantumRecorderHook | undefined): void;
+    /** Get the currently attached recorder, if any. */
+    getRecorder(): QuantumRecorderHook | undefined;
+    /**
+     * Get a property at |0⟩ — reuses a pooled one if available,
+     * otherwise creates a fresh standalone property.
+     */
+    acquireProperty(): QuantumProperty;
+    /**
+     * 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;
+    deleteProperty(id: string): void;
+    hasProperty(id: string): boolean;
+    /**
+     * Remove a property by ID: measure it, pool the handle, delete the mapping.
+     */
+    removeProperty(id: string): void;
+    /** Clear all properties, pool, and recorder. */
+    clear(): void;
+    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[];
+}
+
+/**
+ * QuantumOperationLog — serializable record of quantum state mutations.
+ *
+ * Each entry captures a single WASM-level operation. Property handles are
+ * mapped to sequential integer indices so the log is independent of runtime
+ * handle values. On replay, `forced_measure_properties` reproduces the
+ * exact measurement outcomes, yielding identical quantum state.
+ */
+interface SerializedPredicate {
+    propertyIndex: number;
+    value: number;
+    isEqual: boolean;
+}
+type QuantumOperation = {
+    op: "acquire";
+    index: number;
+} | {
+    op: "release";
+    index: number;
+    value: number;
+} | {
+    op: "assign";
+    index: number;
+    id: string;
+} | {
+    op: "unassign";
+    id: string;
+} | {
+    op: "cycle";
+    index: number;
+    fraction: number;
+    predicates?: SerializedPredicate[];
+} | {
+    op: "i_swap";
+    index1: number;
+    index2: number;
+    fraction: number;
+    predicates?: SerializedPredicate[];
+} | {
+    op: "clock";
+    index: number;
+    fraction: number;
+    predicates?: SerializedPredicate[];
+} | {
+    op: "hadamard";
+    index: number;
+    fraction: number;
+    predicates?: SerializedPredicate[];
+} | {
+    op: "measure";
+    indices: number[];
+    outcomes: number[];
+} | {
+    op: "shift";
+    index: number;
+    fraction: number;
+    predicates?: SerializedPredicate[];
+} | {
+    op: "y";
+    index: number;
+    fraction: number;
+    predicates?: SerializedPredicate[];
+} | {
+    op: "inverse_hadamard";
+    index: number;
+    predicates?: SerializedPredicate[];
+} | {
+    op: "swap";
+    index1: number;
+    index2: number;
+    predicates?: SerializedPredicate[];
+} | {
+    op: "phase_rotate";
+    predicates: SerializedPredicate[];
+    angle: number;
+} | {
+    op: "measure_predicate";
+    predicates: SerializedPredicate[];
+    outcome: number;
+} | {
+    op: "reset";
+    index: number;
+    value: number;
+};
+
+/**
+ * QuantumRecorder — opt-in recording and replay of quantum operations.
+ *
+ * Attach to a QuantumPropertyManager via `manager.setRecorder(recorder)`.
+ * When recording is active, lifecycle hooks log every state-mutating
+ * operation. The log can be replayed via replayLog() to recreate
+ * identical quantum state — measurements are forced to their recorded
+ * outcomes using forced_measure_properties.
+ *
+ * For gate recording, call wrapGate() around each WASM gate call.
+ */
+
+interface PredicateSpec {
+    property: QuantumProperty;
+    value: number;
+    isEqual: boolean;
+}
+declare class QuantumRecorder 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;
+    onDeleteProperty(id: string): void;
+    /**
+     * Build WASM predicate objects from PredicateSpec array.
+     */
+    buildWasmPredicates(specs: PredicateSpec[]): Predicate[];
+    /**
+     * Serialize predicates for the operation log.
+     */
+    serializePredicates(specs: PredicateSpec[]): SerializedPredicate[] | undefined;
+    /**
+     * Record a gate operation. Call this when recording is active
+     * and you want to log a gate call for replay.
+     */
+    recordOp(op: QuantumOperation): void;
+    /**
+     * Get the recorded index for a property handle.
+     */
+    getIndex(prop: QuantumProperty): number | undefined;
+    /** Begin recording quantum operations. Resets any existing log. */
+    startRecording(): void;
+    /** Stop recording and return the captured log. */
+    stopRecording(): QuantumOperation[];
+    /** Whether recording is currently active. */
+    isRecording(): boolean;
+    /** Get a copy of the current operation log (even while recording). */
+    getOperationLog(): QuantumOperation[];
+    /**
+     * Replay an operation log to recreate quantum state from scratch.
+     * Clears all existing state on the manager first. Measurements are
+     * forced to their recorded outcomes via forced_measure_properties.
+     */
+    replayLog(operations: QuantumOperation[]): void;
+    private _replayPredicates;
+}
+
+export { type PredicateSpec$1 as PredicateSpec, type QuantumOperation, QuantumPropertyManager, QuantumRecorder, type QuantumRecorderHook, type SerializedPredicate, ensureLoaded, getAttribution, getMaxDimension, getMaxQudits, getModule, getQuantumForge, getVersion, getWasmMemoryBytes, isReady, registerServiceWorker, setWasmBasePath, startBackgroundLoad, useQuantumForgeBuild };