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;
    /** 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). */
    state_vector_size(): number;
    /** Factorize this qudit out of any shared state and release the property. */
    destroy(): void;
    /** Check whether this property still holds a valid quantum state. */
    is_valid(): boolean;
    getCppInstance(): any;
    /** @internal Create a QuantumProperty from an existing C++ instance. */
    static _fromCpp(cppInstance: any): QuantumProperty;
}
declare class QuantumSimulation {
    private cppInstance;
    constructor();
    createProperty(dimension: number): QuantumProperty;
    /** 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;
    /** 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. */
    factorizeAllSeparable(): void;
    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 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;
/** 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;
/** 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<{
    probability: number;
    qudit_values: number[];
}>;
declare function reduced_density_matrix(props: QuantumProperty[]): Array<{
    row_values: number[];
    col_values: number[];
    value: {
        real: number;
        imag: number;
    };
}>;
/** Gate opcode for batch execution. */
type OpCode = 'cycle' | 'shift' | 'clock' | 'x' | 'z' | 'y' | 'hadamard' | 'inverse_hadamard' | 'swap' | 'i_swap' | 'phase_rotate';
/** A single gate operation descriptor for batch execution. */
interface BatchOp {
    op: OpCode;
    target?: QuantumProperty;
    target2?: QuantumProperty;
    /** Gate fraction. Omit for non-fractional (discrete permutation) variant. */
    fraction?: number;
    /** Rotation angle (phase_rotate only). */
    angle?: number;
    predicates?: Predicate[];
}
/** Result of a batch execution. */
interface BatchResult {
    opsExecuted: number;
    success: boolean;
    errorMessage: string;
}
/**
 * Execute a sequence of gate operations in a single WASM call.
 *
 * Operations execute sequentially. On the first error, execution stops.
 * Already-executed operations are not rolled back.
 */
declare function executeBatch(ops: BatchOp[]): BatchResult;
/** Numeric opcode values matching the C++ OpCode enum for tape encoding. */
declare const OP$1: {
    readonly CYCLE: 0;
    readonly SHIFT: 1;
    readonly CLOCK: 2;
    readonly X: 3;
    readonly Z: 4;
    readonly Y: 5;
    readonly HADAMARD: 6;
    readonly INVERSE_HADAMARD: 7;
    readonly SWAP: 8;
    readonly I_SWAP: 9;
    readonly PHASE_ROTATE: 10;
    /** Fused rotation between two basis states. Tape format:
     *  [11, nq, -1, NaN, angle, 0, a[0]..a[nq-1], b[0]..b[nq-1]] */
    readonly ROTATE_BASIS_PAIR: 11;
};
type OpNum = typeof OP$1[keyof typeof OP$1];
/**
 * Fast-path batch execution using a pre-encoded Float64Array tape.
 *
 * Bypasses embind per-op marshaling entirely. The tape is bulk-copied to WASM
 * in one memcpy (~0.1ms for 3000+ ops) instead of parsing thousands of JS
 * objects through embind val accessors (~300ms).
 *
 * **Tape format per operation (variable length):**
 * ```
 * [opcode, target_idx, target2_idx, fraction, angle, pred_count,
 *  (pred_prop_idx, pred_value, pred_is_equal) × pred_count]
 * ```
 * - Minimum 6 doubles per op (no predicates)
 * - `target_idx` / `target2_idx`: index into `properties` array, or -1 for none
 * - `fraction`: NaN for non-fractional gate variant
 * - `pred_prop_idx`: index into `properties` array
 * - `pred_is_equal`: 1.0 for is(), 0.0 for is_not()
 *
 * Use the `OP` enum for opcodes. Build the tape directly for maximum throughput —
 * avoid creating intermediate JS objects.
 *
 * @example
 * ```typescript
 * import { executeBatchTape, OP } from "quantum-forge/quantum";
 *
 * // Register properties by index
 * const properties = [prop1, prop2, prop3];
 *
 * // Build tape: 3 non-fractional shifts on prop[0]
 * const tape = new Float64Array([
 *   OP.SHIFT, 0, -1, NaN, 0, 0,  // shift(prop1)
 *   OP.SHIFT, 0, -1, NaN, 0, 0,  // shift(prop1)
 *   OP.SHIFT, 0, -1, NaN, 0, 0,  // shift(prop1)
 * ]);
 *
 * const result = executeBatchTape(properties, tape);
 * ```
 *
 * @param properties Array of properties referenced by index in the tape
 * @param tape Pre-encoded Float64Array of operations
 * @returns BatchResult
 */
declare function executeBatchTape(properties: QuantumProperty[], tape: Float64Array): BatchResult;
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 createSimulation(): QuantumSimulation;
    static getVersion(): string;
    static getMaxDimension(): number;
    static getMaxQudits(): number;
    static isValidDimension(dimension: number): boolean;
    /** Returns the compile-time maximum number of basis amplitudes allowed. */
    static getMaxStateSize(): number;
}

type __quantum_forge_api_mjs_BatchOp = BatchOp;
type __quantum_forge_api_mjs_BatchResult = BatchResult;
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;
declare const __quantum_forge_api_mjs_cycle: typeof cycle;
declare const __quantum_forge_api_mjs_executeBatch: typeof executeBatch;
declare const __quantum_forge_api_mjs_executeBatchTape: typeof executeBatchTape;
declare const __quantum_forge_api_mjs_forced_measure_predicate: typeof forced_measure_predicate;
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_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;
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 { type __quantum_forge_api_mjs_BatchOp as BatchOp, type __quantum_forge_api_mjs_BatchResult as BatchResult, 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 };
}

/**
 * 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;
declare function getMaxStateSize(): 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;
}

/** Numeric opcode constants for tape encoding. Matches C++ OpCode enum. */
declare const OP: {
    readonly CYCLE: 0;
    readonly SHIFT: 1;
    readonly CLOCK: 2;
    readonly X: 3;
    readonly Z: 4;
    readonly Y: 5;
    readonly HADAMARD: 6;
    readonly INVERSE_HADAMARD: 7;
    readonly SWAP: 8;
    readonly I_SWAP: 9;
    readonly PHASE_ROTATE: 10;
    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 };