@quantumplayed/quantum-game-engine 1.0.0

package/README.md

@@ -0,0 +1,314 @@
+# Quantum Game Engine
+
+A generalized, sparse-matrix quantum simulation library designed specifically for game developers. 
+
+Unlike traditional quantum SDKs (like Qiskit or Cirq) that focus on low-level circuit design and dense matrices, this engine abstracts Away the complex math. It uses "Second Quantization" and sparse amplitude dictionaries to allow you to easily attach quantum mechanics (superposition, entanglement, interference) directly to high-dimensional objects in your game (like an $(x,y)$ coordinate grid, a character's inventory, or a branching dialogue tree).
+
+## Core Concepts
+
+*   **`QuantumEntity`**: Represents any quantum object in your game (a player, a coin, a chess piece). It manages its own state, but if it becomes entangled, it defers mathematically to a joint system behind the scenes.
+*   **`Operations`**: A suite of generalized quantum gates (Shift, Phase, Hadamard) that work on *qudits* of any dimension, not just qubits.
+*   **`EntanglementEngine`**: A powerful manager that tracks interactions between different `QuantumEntity` objects. When entities interact conditionally (e.g., "IF player is on square 5, open the door"), their states become mathematically linked.
+
+---
+
+## 1. Creating and Modifying Entities
+
+A `QuantumEntity` requires a `dimension` (how many possible classical states it can have) and an initial state index.
+
+```typescript
+import { QuantumEntity, Operations } from 'quantum-game-engine';
+
+// A coin has dimension 2 (Heads=0, Tails=1)
+const coin = new QuantumEntity({ dimension: 2, initialState: 0 });
+
+// A character moving on a 10x10 grid has dimension 100
+const player = new QuantumEntity({ dimension: 100, initialState: 45 });
+```
+
+### Applying Operations
+
+You can mutate the state of an entity using `apply()`.
+
+**1. Shift (Generalized Pauli-X / Clock)**
+Shifts the classical state by a certain amount modulo the dimension.
+```typescript
+player.apply(Operations.Shift(1)); // Moves player from 45 to 46
+```
+
+**2. Phase (Generalized Pauli-Z)**
+Applies a phase rotation to the state. Crucial for interference effects.
+```typescript
+coin.apply(Operations.Phase(Math.PI));
+```
+
+**3. Hadamard (Quantum Fourier Transform)**
+Puts the entity into a uniform superposition of all its possible states.
+```typescript
+coin.apply(Operations.Hadamard()); 
+// Coin is now 50% Heads, 50% Tails
+```
+
+**4. SparseTransition**
+For complex game logic (like a "Quantum Split" move in Checkers), you can define a custom transition matrix. You only need to provide the non-zero mappings.
+```typescript
+const splitMove = Operations.SparseTransition(dimension, {
+    45: [
+        { state: 54, amplitude: { re: 0.707, im: 0 } }, // 50% chance to move left
+        { state: 56, amplitude: { re: 0.707, im: 0 } }  // 50% chance to move right
+    ]
+});
+player.apply(splitMove);
+```
+
+---
+
+## 2. Entanglement and Interactions
+
+The true power of the engine is the `EntanglementEngine`. In games, things interact. If a quantum player steps on a quantum button, they become entangled. Measuring one affects the other.
+
+Use `conditionalInteract` to apply operations to a `target` *only if* the `control` entity is in a specific state.
+
+```typescript
+import { EntanglementEngine } from 'quantum-game-engine';
+
+const player = new QuantumEntity({ dimension: 10, initialState: 5 });
+const door = new QuantumEntity({ dimension: 2, initialState: 0 }); // 0=Closed, 1=Open
+
+// Player steps left and right at the same time
+player.apply(Operations.Hadamard()); 
+
+// If the player is on square 6, they open the door.
+EntanglementEngine.conditionalInteract({
+    controlEntities: [{ entity: player, state: 6 }],
+    targets: [{ entity: door, operation: Operations.Shift(1) }]
+});
+
+// The Player and the Door are now ENTANGLED. 
+// - In a universe where player is at 6, the door is Open (1).
+// - In a universe where player is at 5, the door is Closed (0).
+```
+
+---
+
+## 3. Observation and Rendering
+
+### Extracting Probabilities (For UI)
+
+To render the game to the screen, you need to know the likelihood of an entity being in a certain state. Use `getProbabilities()` to get a classical probability distribution (0.0 to 1.0).
+
+```typescript
+const probs = player.getProbabilities();
+// Returns: { '5': 0.5, '6': 0.5 }
+
+// If entangled, getProbabilities() automatically calculates the 
+// marginal probabilities of just this entity from the joint system!
+```
+
+**Advanced Physics: Reduced Density Matrices**
+If your game logic requires knowing whether an entity has "decohered" due to entanglement (losing its quantum interference capability), you can calculate its One-Body Reduced Density Matrix:
+```typescript
+const rho = player.getReducedDensityMatrix();
+// Returns a 2D map of Complex numbers. 
+// rho[x][x] = Probability of state x
+// rho[x][y] = Coherence between state x and y
+```
+
+### Measuring (Collapsing the Wavefunction)
+
+When gameplay requires an entity to commit to a single reality (e.g., an enemy attacks the player, forcing them to be in one specific location), use `measure()`.
+
+```typescript
+const finalPosition = player.measure(); 
+// Returns exactly 5 or exactly 6.
+```
+
+**The Magic of Entanglement:**
+If `player` and `door` are entangled (as in the example above), measuring the `player` will **instantly collapse the `door` as well**.
+If `player.measure()` returns `6`, any subsequent call to `door.measure()` is mathematically guaranteed to return `1` (Open).
+
+### Forced Measurements (Deterministic Replay)
+
+Pass an optional `forcedOutcome` to `measure()` to force a specific collapse state. This bypasses `Math.random()` entirely.
+
+```typescript
+const outcome = player.measure(0); // Always collapses to state 0
+```
+
+This works with entangled systems too — the forced outcome propagates through the joint system, collapsing entangled partners accordingly. Use this for:
+- **Game history replay** — reproduce recorded measurement outcomes exactly
+- **Undo/redo** — re-apply the same measurement results
+- **Testing** — verify specific branches without randomness
+
+---
+
+## 4. Circuit Logging
+
+The engine includes a toggleable `CircuitLogger` that records every state-mutating operation as an append-only log. Recording is **off by default** — zero overhead during normal gameplay.
+
+```typescript
+import { CircuitLogger } from 'quantum-game-engine';
+
+CircuitLogger.startRecording();
+
+// ... game operations (apply, interactMany, conditionalInteract, measure) ...
+
+const log = CircuitLogger.stopRecording(); // CircuitEntry[]
+```
+
+Each entry is either a `GateEntry` (for `apply`, `interactMany`, `conditionalInteract`) or a `MeasurementEntry` (for `measure`), tagged with entity IDs, dimensions, and an auto-incrementing timestamp.
+
+| Method | Description |
+|---|---|
+| `startRecording()` | Begin recording (resets log) |
+| `stopRecording()` | Stop and return `CircuitEntry[]` |
+| `isRecording()` | Fast guard for hot path |
+| `getLog()` | Get log copy while recording |
+| `getLogForEntities(ids)` | Filter by entity IDs |
+| `reset()` | Clear log and counter |
+
+Every `QuantumEntity` has a unique readonly `id: number` (auto-incrementing), used to identify entities in log entries.
+
+## Engine Boundaries and Limitations
+
+*   **Joint Dimension Limit:** When entities entangle, their state spaces multiply (a dimension-10 player interacting with a dimension-10 enemy creates a dimension-100 joint system). The `EntanglementEngine` currently enforces a hard limit of `4096` total joint dimensions to prevent out-of-memory crashes on the browser's main thread. Design your game's entanglement mechanics to collapse frequently!
+
+
+---
+
+## 5. Full API Usage Examples
+
+### Example 1: A Quantum Platformer (Schrödinger's Jump)
+
+**The Scenario:** You have a platformer game. The player (`playerX`) reaches a gap. They can press a "Quantum Jump" button to simultaneously jump *and* not jump, putting their position in a superposition. Later, they encounter a "Quantum Door" that only opens if the player is standing on a specific button.
+
+```javascript
+import { QuantumEntity, Operations, EntanglementEngine } from 'quantum-game-engine';
+
+// 1. Initialize the player's X position as a qudit (e.g., 100 possible tiles)
+// We start purely classical: 100% chance of being at tile 5.
+const playerX = new QuantumEntity({ dimension: 100, initialState: 5 });
+
+// --- THE QUANTUM JUMP ---
+// The player hits the "Quantum Jump" button!
+// We want an equal 50/50 superposition of staying at 5 or jumping to 10.
+// We apply a custom sparse unitary operation (a basic split/Hadamard variant).
+const jumpOp = Operations.SparseTransition(100, {
+    5: [
+        { state: 5, amplitude: { re: 0.707, im: 0 } },  // Branch A: didn't jump
+        { state: 10, amplitude: { re: 0.707, im: 0 } } // Branch B: did jump
+    ]
+});
+
+playerX.apply(jumpOp);
+
+// playerX.amplitudes is now roughly:
+// { 5: {re: 0.707, im: 0}, 10: {re: 0.707, im: 0} }
+
+
+// --- ENTANGLEMENT ---
+// A Quantum Door (qudit: 0=Closed, 1=Open)
+const door = new QuantumEntity({ dimension: 2, initialState: 0 });
+
+// If the player landed on the button at tile 10, the door opens.
+EntanglementEngine.conditionalInteract({
+    controlEntities: [{ entity: playerX, state: 10 }],
+    targets: [{ entity: door, operation: Operations.Shift(1) }]
+});
+
+// Since playerX was in superposition, the Door is now entangled!
+// The joint amplitudes (PlayerX ⊗ Door):
+// { 
+//   "5,0": {re: 0.707, im: 0},  // Player at 5, Door is Closed
+//   "10,1": {re: 0.707, im: 0}  // Player at 10, Door is Open
+// }
+
+
+// --- MEASUREMENT / COLLAPSE ---
+// The player walks into a "Camera / Observation Zone"
+// We force a collapse of the player's position.
+const result = playerX.measure(); 
+
+// Let's say the engine rolled the 50% chance and returned '10'.
+// Because of the Entanglement Engine, the Door's state automatically 
+// collapses to '1' (Open)! The universe branch where the player didn't 
+// jump is pruned (amplitudes deleted).
+```
+
+---
+
+### Example 2: Quantum Checkers (Squares as Qubits)
+
+**The Scenario:** A player wants to move a piece from square 12. Instead of a normal move, they do a `SplitMove` to squares 16 and 17. Later, an opponent tries to take the piece on square 16.
+
+*Note: In Cheqqers, instead of tracking a "Piece" as a 32-dimension entity (First Quantization), it is much more natural to track each "Square" as a 2-dimension Qubit (Second Quantization), where `0 = Empty` and `1 = Occupied`.*
+
+```javascript
+import { QuantumEntity, Operations, EntanglementEngine } from 'quantum-game-engine';
+
+// We represent squares as individual Qubits.
+// Initial state: Square 12 is Occupied (1), Squares 16 and 17 are Empty (0).
+const sq12 = new QuantumEntity({ dimension: 2, initialState: 1 });
+const sq16 = new QuantumEntity({ dimension: 2, initialState: 0 });
+const sq17 = new QuantumEntity({ dimension: 2, initialState: 0 });
+
+// --- THE SPLIT MOVE ---
+// The "Quantum Chess Split" matrix is an 8x8 matrix that acts on 3 qubits 
+// (From, To1, To2). Our engine provides a helper to apply this sparse sub-matrix.
+// Because it involves 3 entities, the EntanglementEngine automatically merges them 
+// into an 8-dimension joint Hilbert space (2x2x2).
+EntanglementEngine.interactMany([sq12, sq16, sq17], Operations.SparseTransition(8, {
+    // Binary 100 (state 4) -> 010 (state 2) + 001 (state 1)
+    4: [
+        { state: 2, amplitude: { re: 0.707, im: 0 } },
+        { state: 1, amplitude: { re: 0.707, im: 0 } }
+    ]
+}));
+
+// After the split:
+// sq12 is now definitely Empty (|0>).
+// The system of (sq16 ⊗ sq17) is in a superposition:
+// 50% chance of |1, 0> (Piece is on 16)
+// 50% chance of |0, 1> (Piece is on 17)
+
+
+// --- THE PASSAGE OF TIME (PHASE) ---
+// In Cheqqers, time/turns applies a phase shift to superpositions.
+EntanglementEngine.conditionalInteract({
+    controlEntities: [{ entity: sq16, state: 1 }],
+    targets: [{ entity: sq16, operation: Operations.Phase(Math.PI / 4) }]
+});
+EntanglementEngine.conditionalInteract({
+    controlEntities: [{ entity: sq17, state: 1 }],
+    targets: [{ entity: sq17, operation: Operations.Phase(Math.PI / 4) }]
+});
+
+
+// --- CONDITIONAL CAPTURE (ENTANGLEMENT) ---
+// Opponent moves a black piece from square 20 to square 12, capturing 16.
+const sq20 = new QuantumEntity({ dimension: 2, initialState: 1 }); // Black piece
+
+// The capture logic:
+// IF Black is on 20 (it is) AND White is on 16 (it's in superposition):
+//   1. Black moves to 12 (sq20 -> 0, sq12 -> 1)
+//   2. White is captured  (sq16 -> 0)
+// This translates to a Toffoli (CCX) and CNOT (CX) sequence in quantum circuits.
+
+EntanglementEngine.conditionalInteract({
+    controlEntities: [{ entity: sq20, state: 1 }, { entity: sq16, state: 1 }],
+    targets: [
+        { entity: sq20, operation: Operations.Shift(1) }, // 1 -> 0 (wrapping)
+        { entity: sq12, operation: Operations.Shift(1) }, // 0 -> 1
+        { entity: sq16, operation: Operations.Shift(1) }  // 1 -> 0 (captured)
+    ]
+});
+
+// The Joint Hilbert space now tracks the entangled state of shapes.
+// Branch A: (White was on 17). 
+//           sq16 resolves to 0. The capture condition fails! Black stays on 20.
+// Branch B: (White was on 16). 
+//           sq16 resolves to 1. Capture fires! Black moves to 12, sq16 flips to 0.
+
+// Because everything is sparse, branches where mathematically invalid things happen
+// (like trying to capture an empty square) don't consume memory.
+```

package/dist/CircuitLog.d.ts

@@ -0,0 +1,54 @@
+/**
+ * CircuitLog — toggleable, append-only log of quantum operations.
+ *
+ * When recording is active, every state-mutating call (gate or measurement)
+ * appends an entry. The log is designed for future incremental OpenQASM export:
+ * each new entry maps to one circuit instruction, so the export never rebuilds.
+ */
+export interface GateEntry {
+    type: 'gate';
+    name: string;
+    entityIds: number[];
+    dimensions: number[];
+    controls?: {
+        entityId: number;
+        state: number;
+    }[];
+    params?: Record<string, any>;
+    timestamp: number;
+}
+export interface MeasurementEntry {
+    type: 'measurement';
+    entityId: number;
+    dimension: number;
+    outcome: number;
+    timestamp: number;
+}
+export type CircuitEntry = GateEntry | MeasurementEntry;
+declare class CircuitLoggerImpl {
+    private _recording;
+    private _log;
+    private _counter;
+    /** Begin recording. Resets the existing log. */
+    startRecording(): void;
+    /** Stop recording and return the captured log. */
+    stopRecording(): CircuitEntry[];
+    /** Fast guard — check before constructing entry objects on the hot path. */
+    isRecording(): boolean;
+    /** Append an entry (auto-assigns timestamp). */
+    addGate(name: string, entityIds: number[], dimensions: number[], params?: Record<string, any>, controls?: {
+        entityId: number;
+        state: number;
+    }[]): void;
+    /** Append a measurement entry. */
+    addMeasurement(entityId: number, dimension: number, outcome: number): void;
+    /** Get a copy of the current log. */
+    getLog(): CircuitEntry[];
+    /** Filter log to entries involving any of the given entity IDs. */
+    getLogForEntities(entityIds: number[]): CircuitEntry[];
+    /** Clear the log and reset the counter. */
+    reset(): void;
+}
+/** Global singleton circuit logger. */
+export declare const CircuitLogger: CircuitLoggerImpl;
+export {};

package/dist/CircuitLog.js

@@ -0,0 +1,80 @@
+/**
+ * CircuitLog — toggleable, append-only log of quantum operations.
+ *
+ * When recording is active, every state-mutating call (gate or measurement)
+ * appends an entry. The log is designed for future incremental OpenQASM export:
+ * each new entry maps to one circuit instruction, so the export never rebuilds.
+ */
+// ── Logger ───────────────────────────────────────────────────────────
+class CircuitLoggerImpl {
+    _recording = false;
+    _log = [];
+    _counter = 0;
+    /** Begin recording. Resets the existing log. */
+    startRecording() {
+        this._recording = true;
+        this._log = [];
+        this._counter = 0;
+    }
+    /** Stop recording and return the captured log. */
+    stopRecording() {
+        this._recording = false;
+        return [...this._log];
+    }
+    /** Fast guard — check before constructing entry objects on the hot path. */
+    isRecording() {
+        return this._recording;
+    }
+    /** Append an entry (auto-assigns timestamp). */
+    addGate(name, entityIds, dimensions, params, controls) {
+        const entry = {
+            type: 'gate',
+            name,
+            entityIds,
+            dimensions,
+            timestamp: this._counter++,
+        };
+        if (params)
+            entry.params = params;
+        if (controls)
+            entry.controls = controls;
+        this._log.push(entry);
+    }
+    /** Append a measurement entry. */
+    addMeasurement(entityId, dimension, outcome) {
+        this._log.push({
+            type: 'measurement',
+            entityId,
+            dimension,
+            outcome,
+            timestamp: this._counter++,
+        });
+    }
+    /** Get a copy of the current log. */
+    getLog() {
+        return [...this._log];
+    }
+    /** Filter log to entries involving any of the given entity IDs. */
+    getLogForEntities(entityIds) {
+        const idSet = new Set(entityIds);
+        return this._log.filter(entry => {
+            if (entry.type === 'measurement') {
+                return idSet.has(entry.entityId);
+            }
+            // Gate — check targets and controls
+            if (entry.entityIds.some(id => idSet.has(id)))
+                return true;
+            if (entry.controls?.some(c => idSet.has(c.entityId)))
+                return true;
+            return false;
+        });
+    }
+    /** Clear the log and reset the counter. */
+    reset() {
+        this._log = [];
+        this._counter = 0;
+    }
+}
+/** Global singleton circuit logger. */
+export const CircuitLogger = new CircuitLoggerImpl();
+//# sourceMappingURL=CircuitLog.js.map

package/dist/CircuitLog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CircuitLog.js","sourceRoot":"","sources":["../src/CircuitLog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAwBH,wEAAwE;AAExE,MAAM,iBAAiB;IACX,UAAU,GAAG,KAAK,CAAC;IACnB,IAAI,GAAmB,EAAE,CAAC;IAC1B,QAAQ,GAAG,CAAC,CAAC;IAErB,gDAAgD;IAChD,cAAc;QACV,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QACf,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IACtB,CAAC;IAED,kDAAkD;IAClD,aAAa;QACT,IAAI,CAAC,UAAU,GAAG,KAAK,CAAC;QACxB,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,4EAA4E;IAC5E,WAAW;QACP,OAAO,IAAI,CAAC,UAAU,CAAC;IAC3B,CAAC;IAED,gDAAgD;IAChD,OAAO,CACH,IAAY,EACZ,SAAmB,EACnB,UAAoB,EACpB,MAA4B,EAC5B,QAAgD;QAEhD,MAAM,KAAK,GAAc;YACrB,IAAI,EAAE,MAAM;YACZ,IAAI;YACJ,SAAS;YACT,UAAU;YACV,SAAS,EAAE,IAAI,CAAC,QAAQ,EAAE;SAC7B,CAAC;QACF,IAAI,MAAM;YAAE,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC;QAClC,IAAI,QAAQ;YAAE,KAAK,CAAC,QAAQ,GAAG,QAAQ,CAAC;QACxC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC1B,CAAC;IAED,kCAAkC;IAClC,cAAc,CAAC,QAAgB,EAAE,SAAiB,EAAE,OAAe;QAC/D,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,aAAa;YACnB,QAAQ;YACR,SAAS;YACT,OAAO;YACP,SAAS,EAAE,IAAI,CAAC,QAAQ,EAAE;SAC7B,CAAC,CAAC;IACP,CAAC;IAED,qCAAqC;IACrC,MAAM;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,mEAAmE;IACnE,iBAAiB,CAAC,SAAmB;QACjC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,SAAS,CAAC,CAAC;QACjC,OAAO,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;YAC5B,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;gBAC/B,OAAO,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;YACrC,CAAC;YACD,oCAAoC;YACpC,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YAC3D,IAAI,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;gBAAE,OAAO,IAAI,CAAC;YAClE,OAAO,KAAK,CAAC;QACjB,CAAC,CAAC,CAAC;IACP,CAAC;IAED,2CAA2C;IAC3C,KAAK;QACD,IAAI,CAAC,IAAI,GAAG,EAAE,CAAC;QACf,IAAI,CAAC,QAAQ,GAAG,CAAC,CAAC;IACtB,CAAC;CACJ;AAED,uCAAuC;AACvC,MAAM,CAAC,MAAM,aAAa,GAAG,IAAI,iBAAiB,EAAE,CAAC"}

package/dist/Complex.d.ts

@@ -0,0 +1,13 @@
+export interface Complex {
+    re: number;
+    im: number;
+}
+export declare const ComplexMath: {
+    add(a: Complex, b: Complex): Complex;
+    subtract(a: Complex, b: Complex): Complex;
+    multiply(a: Complex, b: Complex): Complex;
+    conjugate(a: Complex): Complex;
+    scale(a: Complex, scalar: number): Complex;
+    magnitudeSquared(a: Complex): number;
+    phase(angle: number): Complex;
+};

package/dist/Complex.js

@@ -0,0 +1,49 @@
+export const ComplexMath = {
+    // Add two complex numbers
+    add(a, b) {
+        return {
+            re: a.re + b.re,
+            im: a.im + b.im
+        };
+    },
+    // Subtract b from a
+    subtract(a, b) {
+        return {
+            re: a.re - b.re,
+            im: a.im - b.im
+        };
+    },
+    // Multiply two complex numbers
+    multiply(a, b) {
+        return {
+            re: a.re * b.re - a.im * b.im,
+            im: a.im * b.re + a.re * b.im
+        };
+    },
+    // Complex conjugate
+    conjugate(a) {
+        return {
+            re: a.re,
+            im: -a.im
+        };
+    },
+    // Multiply a complex number by a scalar
+    scale(a, scalar) {
+        return {
+            re: a.re * scalar,
+            im: a.im * scalar
+        };
+    },
+    // Calculate magnitude squared (probability)
+    magnitudeSquared(a) {
+        return a.re * a.re + a.im * a.im;
+    },
+    // Calculate the complex phase e^(i * angle)
+    phase(angle) {
+        return {
+            re: Math.cos(angle),
+            im: Math.sin(angle)
+        };
+    }
+};
+//# sourceMappingURL=Complex.js.map

package/dist/Complex.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Complex.js","sourceRoot":"","sources":["../src/Complex.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,MAAM,WAAW,GAAG;IACvB,0BAA0B;IAC1B,GAAG,CAAC,CAAU,EAAE,CAAU;QACtB,OAAO;YACH,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE;YACf,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE;SAClB,CAAC;IACN,CAAC;IAED,oBAAoB;IACpB,QAAQ,CAAC,CAAU,EAAE,CAAU;QAC3B,OAAO;YACH,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE;YACf,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE;SAClB,CAAC;IACN,CAAC;IAED,+BAA+B;IAC/B,QAAQ,CAAC,CAAU,EAAE,CAAU;QAC3B,OAAO;YACH,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE;YAC7B,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE;SAChC,CAAC;IACN,CAAC;IAED,oBAAoB;IACpB,SAAS,CAAC,CAAU;QAChB,OAAO;YACH,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE;SACZ,CAAC;IACN,CAAC;IAED,wCAAwC;IACxC,KAAK,CAAC,CAAU,EAAE,MAAc;QAC5B,OAAO;YACH,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM;YACjB,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,MAAM;SACpB,CAAC;IACN,CAAC;IAED,4CAA4C;IAC5C,gBAAgB,CAAC,CAAU;QACvB,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC;IACrC,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,KAAa;QACf,OAAO;YACH,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YACnB,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;SACtB,CAAC;IACN,CAAC;CACJ,CAAC"}

package/dist/EntanglementEngine.d.ts

@@ -0,0 +1,48 @@
+import { QuantumEntity, type Predicate } from './QuantumEntity';
+import { type QuantumOperation, type SparseAmplitudes } from './Operations';
+import { type Complex } from './Complex';
+export declare class JointQuantumSystem {
+    entities: QuantumEntity[];
+    dimensions: number[];
+    totalDimension: number;
+    jointAmplitudes: SparseAmplitudes;
+    private constructor();
+    static create(entities: QuantumEntity[]): JointQuantumSystem;
+    static merge(involvedEntities: QuantumEntity[]): JointQuantumSystem;
+    private _calculateTensorProduct;
+    decomposeState(jointState: number): number[];
+    composeState(states: number[]): number;
+    applyLocal(entityIndex: number, operation: QuantumOperation): void;
+    applyToSubspace(targetEntities: QuantumEntity[], operation: QuantumOperation): void;
+    getTargetProbabilities(targetEntity: QuantumEntity): Record<number, number>;
+    getTargetAmplitudes(targetEntity: QuantumEntity): Record<number, Complex>;
+    measureTarget(targetEntity: QuantumEntity, forcedOutcome?: number): number;
+    getProjectedAmplitudes(conditions: {
+        entity: QuantumEntity;
+        state: number;
+    }[]): SparseAmplitudes;
+    getJointProbability(conditions: {
+        entity: QuantumEntity;
+        state: number;
+    }[]): number;
+    areMutuallyExclusive(conditions: {
+        entity: QuantumEntity;
+        state: number;
+    }[]): boolean;
+    getReducedDensityMatrix(targetEntity: QuantumEntity): Record<number, Record<number, Complex>>;
+    /**
+     * Create a joint system from existing amplitudes and entities (Bit-Perfect Restoration/Cloning).
+     */
+    static inject(entities: QuantumEntity[], jointAmplitudes: SparseAmplitudes): JointQuantumSystem;
+}
+export interface TargetOperation {
+    entity: QuantumEntity;
+    operation: QuantumOperation;
+}
+export declare const EntanglementEngine: {
+    interactMany(entities: QuantumEntity[], operation: QuantumOperation): void;
+    conditionalInteract(args: {
+        controls: Predicate[];
+        targets: TargetOperation[];
+    }): void;
+};