@vurb/core 3.2.0

package/dist/sandbox/SandboxEngine.d.ts

@@ -0,0 +1,225 @@
+/**
+ * SandboxEngine — Zero-Trust V8 Isolate for Computation Delegation
+ *
+ * Allows LLMs to send JavaScript functions as strings to be executed
+ * in a sealed V8 isolate. The data stays on the client's machine,
+ * only the result travels back to the LLM.
+ *
+ * Architecture (V8 Engineering Rules):
+ *   1. ONE Isolate per SandboxEngine (boot ~5-10ms), reused across requests
+ *   2. NEW Context per execute() call (~0.1ms), pristine and empty
+ *   3. ExternalCopy + Script + Context are ALWAYS released in `finally`
+ *   4. Execution is ALWAYS async (script.run, never runSync)
+ *   5. Context is empty — no process, require, fs, globalThis injected
+ *   6. AbortSignal kills isolate.dispose() instantly (Connection Watchdog)
+ *
+ * The `isolated-vm` package is a peerDependency (optional).
+ * If not installed, the engine throws a clear error at construction time.
+ *
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  SandboxEngine (owns 1 Isolate)                         │
+ *   │                                                         │
+ *   │  execute(code, data, { signal? })                       │
+ *   │    ┌──────────┐                                         │
+ *   │    │ Abort?   │ pre-flight signal check                  │
+ *   │    ├──────────┤                                         │
+ *   │    │ Guard    │ fail-fast syntax check                   │
+ *   │    ├──────────┤                                         │
+ *   │    │ Context  │ new per request (empty!)                 │
+ *   │    ├──────────┤                                         │
+ *   │    │ Copy In  │ ExternalCopy (deep, no refs)             │
+ *   │    ├──────────┤                                         │
+ *   │    │ Compile  │ isolate.compileScript                    │
+ *   │    ├──────────┤                                         │
+ *   │    │ Run      │ script.run (ASYNC, with timeout + abort) │
+ *   │    ├──────────┤                                         │
+ *   │    │ Copy Out │ JSON.parse result                        │
+ *   │    └──────────┘                                         │
+ *   │                                                         │
+ *   │  finally: signal.removeEventListener()                  │
+ *   │           inputCopy.release()                           │
+ *   │           script.release()                              │
+ *   │           context.release()                             │
+ *   └─────────────────────────────────────────────────────────┘
+ *
+ * @module
+ */
+import { type TelemetrySink } from '../observability/TelemetryEvent.js';
+/**
+ * Configuration for a SandboxEngine instance.
+ *
+ * All fields are optional — sensible defaults are applied.
+ *
+ * @example
+ * ```typescript
+ * const engine = new SandboxEngine({
+ *     timeout: 3000,       // Kill after 3s
+ *     memoryLimit: 64,     // 64MB per isolate
+ *     maxOutputBytes: 512_000, // 500KB max result
+ * });
+ * ```
+ */
+export interface SandboxConfig {
+    /**
+     * Maximum execution time in milliseconds.
+     * If the script exceeds this, the V8 isolate kills it.
+     * @default 5000
+     */
+    timeout?: number;
+    /**
+     * Maximum memory for the V8 isolate in megabytes.
+     * If exceeded, the isolate dies and is recreated on next call.
+     * @default 128
+     */
+    memoryLimit?: number;
+    /**
+     * Maximum size of the serialized output in bytes.
+     * Prevents a malicious script from returning gigabytes of data.
+     * @default 1_048_576 (1MB)
+     */
+    maxOutputBytes?: number;
+}
+/**
+ * Error codes for sandbox execution failures.
+ *
+ * - `TIMEOUT`: Script exceeded the time limit
+ * - `MEMORY`: Isolate ran out of memory (auto-recovered)
+ * - `SYNTAX`: JavaScript syntax error in the provided code
+ * - `RUNTIME`: Script threw an error during execution
+ * - `OUTPUT_TOO_LARGE`: Result exceeds `maxOutputBytes`
+ * - `INVALID_CODE`: Failed the SandboxGuard fail-fast check
+ * - `INVALID_DATA`: Input data contains non-serializable values
+ * - `UNAVAILABLE`: `isolated-vm` is not installed
+ * - `ABORTED`: Execution was cancelled via AbortSignal (client disconnect)
+ */
+export type SandboxErrorCode = 'TIMEOUT' | 'MEMORY' | 'SYNTAX' | 'RUNTIME' | 'OUTPUT_TOO_LARGE' | 'INVALID_CODE' | 'INVALID_DATA' | 'UNAVAILABLE' | 'ABORTED';
+/**
+ * Result of a sandbox execution.
+ *
+ * @example
+ * ```typescript
+ * const result = await engine.execute('(data) => data.length', [1, 2, 3]);
+ * if (result.ok) {
+ *     console.log(result.value);       // 3
+ *     console.log(result.executionMs); // 0.42
+ * } else {
+ *     console.log(result.code);  // 'TIMEOUT'
+ *     console.log(result.error); // 'Script execution timed out (5000ms)'
+ * }
+ * ```
+ */
+export type SandboxResult<T = unknown> = {
+    readonly ok: true;
+    readonly value: T;
+    readonly executionMs: number;
+} | {
+    readonly ok: false;
+    readonly error: string;
+    readonly code: SandboxErrorCode;
+};
+/**
+ * Reset the cached isolated-vm module reference.
+ * Exported exclusively for testing — allows mock/unmock cycles
+ * without process restart (Bug #137).
+ * @internal
+ */
+export declare function resetIvmCache(): void;
+/**
+ * Zero-trust V8 sandbox for executing LLM-provided JavaScript.
+ *
+ * Creates a single V8 `Isolate` at construction time and reuses it
+ * across all `execute()` calls. Each call gets a fresh, empty `Context`
+ * with no dangerous globals (no `process`, `require`, `fs`, etc.).
+ *
+ * If the isolate dies (e.g., OOM), it is automatically recreated
+ * on the next `execute()` call.
+ *
+ * @example
+ * ```typescript
+ * const sandbox = new SandboxEngine({ timeout: 3000, memoryLimit: 64 });
+ *
+ * const result = await sandbox.execute(
+ *     '(data) => data.filter(d => d.risk > 90)',
+ *     [{ name: 'A', risk: 95 }, { name: 'B', risk: 30 }],
+ * );
+ *
+ * if (result.ok) {
+ *     console.log(result.value); // [{ name: 'A', risk: 95 }]
+ * }
+ *
+ * // IMPORTANT: dispose when no longer needed
+ * sandbox.dispose();
+ * ```
+ */
+export declare class SandboxEngine {
+    private readonly _timeout;
+    private readonly _memoryLimit;
+    private readonly _maxOutputBytes;
+    private _isolate;
+    private _disposed;
+    private _telemetry?;
+    /** Number of in-flight execute() calls sharing the isolate. */
+    private _activeExecutions;
+    constructor(config?: SandboxConfig);
+    /**
+     * Set the telemetry sink for `sandbox.exec` event emission.
+     * When set, every `execute()` call emits a telemetry event
+     * visible in the Inspector TUI.
+     */
+    telemetry(sink: TelemetrySink): this;
+    /**
+     * Execute a JavaScript function string against the provided data.
+     *
+     * The function is compiled and run in a sealed V8 isolate with:
+     * - No `process`, `require`, `fs`, or network access
+     * - Strict timeout enforcement (async, non-blocking)
+     * - Memory limit enforcement
+     * - Automatic C++ pointer cleanup (ExternalCopy, Script, Context)
+     * - Cooperative cancellation via AbortSignal (Connection Watchdog)
+     *
+     * @param code - A JavaScript function expression as a string.
+     *   Must be an arrow function or function expression.
+     *   Example: `(data) => data.filter(d => d.value > 10)`
+     *
+     * @param data - The data to pass into the function.
+     *   Deeply copied into the isolate (no references leak).
+     *
+     * @param options - Optional execution options.
+     * @param options.signal - AbortSignal for cooperative cancellation.
+     *   When the signal fires (e.g., MCP client disconnects), the engine
+     *   calls `isolate.dispose()` to kill the V8 C++ threads instantly.
+     *   The isolate is auto-recovered on the next `.execute()` call.
+     *
+     * @returns A `SandboxResult` with the computed value or an error.
+     */
+    execute<T = unknown>(code: string, data: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<SandboxResult<T>>;
+    /**
+     * Release all resources held by this engine.
+     *
+     * After calling `dispose()`, any subsequent `execute()` calls
+     * will return `{ ok: false, code: 'UNAVAILABLE' }`.
+     */
+    dispose(): void;
+    /**
+     * Check if the engine has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Emit a `sandbox.exec` telemetry event if a sink is configured.
+     * @internal
+     */
+    private _emitTelemetry;
+    /**
+     * Ensure the isolate is alive. If it died (OOM), create a new one.
+     * @internal
+     */
+    private _ensureIsolate;
+    /**
+     * Classify an error from V8 execution into a typed SandboxResult.
+     * @internal
+     */
+    private _classifyError;
+}
+//# sourceMappingURL=SandboxEngine.d.ts.map

package/dist/sandbox/SandboxEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxEngine.d.ts","sourceRoot":"","sources":["../../src/sandbox/SandboxEngine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,EAAyB,KAAK,aAAa,EAAE,MAAM,oCAAoC,CAAC;AAI/F;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,aAAa;IAC1B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,gBAAgB,GACtB,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,kBAAkB,GAClB,cAAc,GACd,cAAc,GACd,aAAa,GACb,SAAS,CAAC;AAEhB;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,aAAa,CAAC,CAAC,GAAG,OAAO,IAC/B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAkCtF;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,IAAI,CAEpC;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,aAAa;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEzC,OAAO,CAAC,QAAQ,CAAM;IACtB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,UAAU,CAAC,CAAgB;IACnC,+DAA+D;IAC/D,OAAO,CAAC,iBAAiB,CAAK;gBAElB,MAAM,CAAC,EAAE,aAAa;IAgBlC;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,aAAa,GAAG,IAAI;IAKpC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EACrB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACnC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC;IAqK5B;;;;;OAKG;IACH,OAAO,IAAI,IAAI;IAUf;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;;OAGG;IACH,OAAO,CAAC,cAAc;IActB;;;OAGG;IACH,OAAO,CAAC,cAAc;IAatB;;;OAGG;IACH,OAAO,CAAC,cAAc;CA6CzB"}

package/dist/sandbox/SandboxEngine.js

@@ -0,0 +1,437 @@
+/**
+ * SandboxEngine — Zero-Trust V8 Isolate for Computation Delegation
+ *
+ * Allows LLMs to send JavaScript functions as strings to be executed
+ * in a sealed V8 isolate. The data stays on the client's machine,
+ * only the result travels back to the LLM.
+ *
+ * Architecture (V8 Engineering Rules):
+ *   1. ONE Isolate per SandboxEngine (boot ~5-10ms), reused across requests
+ *   2. NEW Context per execute() call (~0.1ms), pristine and empty
+ *   3. ExternalCopy + Script + Context are ALWAYS released in `finally`
+ *   4. Execution is ALWAYS async (script.run, never runSync)
+ *   5. Context is empty — no process, require, fs, globalThis injected
+ *   6. AbortSignal kills isolate.dispose() instantly (Connection Watchdog)
+ *
+ * The `isolated-vm` package is a peerDependency (optional).
+ * If not installed, the engine throws a clear error at construction time.
+ *
+ *   ┌─────────────────────────────────────────────────────────┐
+ *   │  SandboxEngine (owns 1 Isolate)                         │
+ *   │                                                         │
+ *   │  execute(code, data, { signal? })                       │
+ *   │    ┌──────────┐                                         │
+ *   │    │ Abort?   │ pre-flight signal check                  │
+ *   │    ├──────────┤                                         │
+ *   │    │ Guard    │ fail-fast syntax check                   │
+ *   │    ├──────────┤                                         │
+ *   │    │ Context  │ new per request (empty!)                 │
+ *   │    ├──────────┤                                         │
+ *   │    │ Copy In  │ ExternalCopy (deep, no refs)             │
+ *   │    ├──────────┤                                         │
+ *   │    │ Compile  │ isolate.compileScript                    │
+ *   │    ├──────────┤                                         │
+ *   │    │ Run      │ script.run (ASYNC, with timeout + abort) │
+ *   │    ├──────────┤                                         │
+ *   │    │ Copy Out │ JSON.parse result                        │
+ *   │    └──────────┘                                         │
+ *   │                                                         │
+ *   │  finally: signal.removeEventListener()                  │
+ *   │           inputCopy.release()                           │
+ *   │           script.release()                              │
+ *   │           context.release()                             │
+ *   └─────────────────────────────────────────────────────────┘
+ *
+ * @module
+ */
+import { validateSandboxCode } from './SandboxGuard.js';
+import {} from '../observability/TelemetryEvent.js';
+// ── Constants ────────────────────────────────────────────
+const DEFAULT_TIMEOUT_MS = 5_000;
+const DEFAULT_MEMORY_LIMIT_MB = 128;
+const DEFAULT_MAX_OUTPUT_BYTES = 1_048_576; // 1MB
+const MAX_CODE_LENGTH = 65_536; // 64KB — generous for any legitimate sandbox function
+const TEXT_ENCODER = new TextEncoder(); // Bug #138: reuse stateless encoder
+// ── Lazy Require ─────────────────────────────────────────
+/**
+ * Lazy-load isolated-vm to avoid hard dependency.
+ * Returns `null` if the package is not installed.
+ * @internal
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _ivm = undefined;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function getIvm() {
+    if (_ivm !== undefined)
+        return _ivm;
+    try {
+        // Dynamic import would be cleaner but isolated-vm uses
+        // native bindings that require synchronous resolution.
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        _ivm = require('isolated-vm');
+    }
+    catch {
+        _ivm = null;
+    }
+    return _ivm;
+}
+/**
+ * Reset the cached isolated-vm module reference.
+ * Exported exclusively for testing — allows mock/unmock cycles
+ * without process restart (Bug #137).
+ * @internal
+ */
+export function resetIvmCache() {
+    _ivm = undefined;
+}
+// ── Engine Implementation ────────────────────────────────
+/**
+ * Zero-trust V8 sandbox for executing LLM-provided JavaScript.
+ *
+ * Creates a single V8 `Isolate` at construction time and reuses it
+ * across all `execute()` calls. Each call gets a fresh, empty `Context`
+ * with no dangerous globals (no `process`, `require`, `fs`, etc.).
+ *
+ * If the isolate dies (e.g., OOM), it is automatically recreated
+ * on the next `execute()` call.
+ *
+ * @example
+ * ```typescript
+ * const sandbox = new SandboxEngine({ timeout: 3000, memoryLimit: 64 });
+ *
+ * const result = await sandbox.execute(
+ *     '(data) => data.filter(d => d.risk > 90)',
+ *     [{ name: 'A', risk: 95 }, { name: 'B', risk: 30 }],
+ * );
+ *
+ * if (result.ok) {
+ *     console.log(result.value); // [{ name: 'A', risk: 95 }]
+ * }
+ *
+ * // IMPORTANT: dispose when no longer needed
+ * sandbox.dispose();
+ * ```
+ */
+export class SandboxEngine {
+    _timeout;
+    _memoryLimit;
+    _maxOutputBytes;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    _isolate; // ivm.Isolate
+    _disposed = false;
+    _telemetry;
+    /** Number of in-flight execute() calls sharing the isolate. */
+    _activeExecutions = 0;
+    constructor(config) {
+        this._timeout = config?.timeout ?? DEFAULT_TIMEOUT_MS;
+        this._memoryLimit = config?.memoryLimit ?? DEFAULT_MEMORY_LIMIT_MB;
+        this._maxOutputBytes = config?.maxOutputBytes ?? DEFAULT_MAX_OUTPUT_BYTES;
+        const ivm = getIvm();
+        if (!ivm) {
+            throw new Error('SandboxEngine requires the "isolated-vm" package. ' +
+                'Install it with: npm install isolated-vm');
+        }
+        this._isolate = new ivm.Isolate({ memoryLimit: this._memoryLimit });
+    }
+    /**
+     * Set the telemetry sink for `sandbox.exec` event emission.
+     * When set, every `execute()` call emits a telemetry event
+     * visible in the Inspector TUI.
+     */
+    telemetry(sink) {
+        this._telemetry = sink;
+        return this;
+    }
+    /**
+     * Execute a JavaScript function string against the provided data.
+     *
+     * The function is compiled and run in a sealed V8 isolate with:
+     * - No `process`, `require`, `fs`, or network access
+     * - Strict timeout enforcement (async, non-blocking)
+     * - Memory limit enforcement
+     * - Automatic C++ pointer cleanup (ExternalCopy, Script, Context)
+     * - Cooperative cancellation via AbortSignal (Connection Watchdog)
+     *
+     * @param code - A JavaScript function expression as a string.
+     *   Must be an arrow function or function expression.
+     *   Example: `(data) => data.filter(d => d.value > 10)`
+     *
+     * @param data - The data to pass into the function.
+     *   Deeply copied into the isolate (no references leak).
+     *
+     * @param options - Optional execution options.
+     * @param options.signal - AbortSignal for cooperative cancellation.
+     *   When the signal fires (e.g., MCP client disconnects), the engine
+     *   calls `isolate.dispose()` to kill the V8 C++ threads instantly.
+     *   The isolate is auto-recovered on the next `.execute()` call.
+     *
+     * @returns A `SandboxResult` with the computed value or an error.
+     */
+    async execute(code, data, options) {
+        if (this._disposed) {
+            return { ok: false, error: 'SandboxEngine has been disposed.', code: 'UNAVAILABLE' };
+        }
+        const signal = options?.signal;
+        // ── Step 0: Pre-flight abort check ───────────────
+        // If the signal is already aborted (client disconnected before
+        // we even started), skip all V8 allocation entirely.
+        if (signal?.aborted) {
+            return {
+                ok: false,
+                error: 'Execution aborted: client disconnected before sandbox started.',
+                code: 'ABORTED',
+            };
+        }
+        // ── Step 0b: Code length guard ──────────────────
+        // Prevent host-side OOM before V8 is even involved.
+        // The V8 memoryLimit only bounds the isolate heap, not the host.
+        if (code.length > MAX_CODE_LENGTH) {
+            return {
+                ok: false,
+                error: `Code length (${code.length} chars) exceeds maximum (${MAX_CODE_LENGTH} chars). ` +
+                    'Sandbox functions should be small, pure transformations.',
+                code: 'INVALID_CODE',
+            };
+        }
+        // ── Step 1: Fail-fast guard ─────────────────────
+        const guard = validateSandboxCode(code);
+        if (!guard.ok) {
+            return { ok: false, error: guard.violation, code: 'INVALID_CODE' };
+        }
+        // ── Step 2: Ensure isolate is alive ─────────────
+        this._ensureIsolate();
+        const ivm = getIvm();
+        const isolate = this._isolate;
+        this._activeExecutions++;
+        // ── Step 3: Wire abort kill-switch ──────────────
+        // When the signal fires and this is the ONLY execution in
+        // progress, we call isolate.dispose() to kill V8 instantly.
+        //
+        // Bug #142: When other executions share the same isolate
+        // (activeExecutions > 1), we cannot dispose the isolate
+        // without killing all concurrent work (Bug #63 fix). Instead
+        // we set the `aborted` flag AND release the per-request
+        // context (if already created) to interrupt the running
+        // script without collateral damage. If context is not yet
+        // created, the script will terminate at its timeout boundary.
+        let aborted = false;
+        const onAbort = signal ? () => {
+            aborted = true;
+            if (this._activeExecutions <= 1) {
+                try {
+                    isolate.dispose();
+                }
+                catch { /* may already be dead */ }
+            }
+            else {
+                // Release this request's context to interrupt execution
+                // without killing the shared isolate (Bug #142).
+                try {
+                    context?.release();
+                }
+                catch { /* may already be released */ }
+            }
+        } : undefined;
+        if (signal && onAbort) {
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+        // ── Step 4: Execute in sealed context ───────────
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let inputCopy; // ivm.ExternalCopy
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let context; // ivm.Context
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        let script; // ivm.Script
+        const startMs = performance.now();
+        try {
+            // Create pristine context (NO globals injected — this IS the security)
+            context = await isolate.createContext();
+            // Deep-copy data into isolated heap (no references!)
+            // Bug #135: catch serialization errors from ExternalCopy separately
+            try {
+                inputCopy = new ivm.ExternalCopy(data);
+            }
+            catch (copyErr) {
+                const copyMsg = copyErr instanceof Error ? copyErr.message : String(copyErr);
+                const result = {
+                    ok: false,
+                    error: `Data serialization error: ${copyMsg}. The input data contains non-serializable values (functions, Symbols, WeakRefs, etc.).`,
+                    code: 'INVALID_DATA',
+                };
+                this._emitTelemetry(result);
+                return result;
+            }
+            await context.global.set('__input__', inputCopy.copyInto());
+            // Compile with wrapper: call the function and serialize result
+            const wrappedCode = `const __fn__ = ${code};\nJSON.stringify(__fn__(__input__));`;
+            script = await isolate.compileScript(wrappedCode);
+            // ASYNC execution — never blocks the Node.js event loop
+            const rawResult = await script.run(context, { timeout: this._timeout });
+            const executionMs = performance.now() - startMs;
+            // ── Step 5: Output size guard ───────────────
+            if (typeof rawResult === 'string') {
+                const outputByteLength = TEXT_ENCODER.encode(rawResult).byteLength;
+                if (outputByteLength > this._maxOutputBytes) {
+                    const oversized = {
+                        ok: false,
+                        error: `Output size (${outputByteLength} bytes) exceeds limit (${this._maxOutputBytes} bytes). ` +
+                            'Use more selective filters to reduce the result set.',
+                        code: 'OUTPUT_TOO_LARGE',
+                    };
+                    this._emitTelemetry(oversized);
+                    return oversized;
+                }
+            }
+            // ── Step 6: Parse result ────────────────────
+            const parsed = typeof rawResult === 'string' ? JSON.parse(rawResult) : rawResult;
+            const result = { ok: true, value: parsed, executionMs };
+            this._emitTelemetry(result);
+            return result;
+        }
+        catch (err) {
+            // If the abort listener disposed the isolate, classify as ABORTED
+            // (not MEMORY — the user disconnected, not an OOM condition)
+            if (aborted) {
+                const result = {
+                    ok: false,
+                    error: 'Execution aborted: client disconnected during sandbox execution.',
+                    code: 'ABORTED',
+                };
+                this._emitTelemetry(result);
+                return result;
+            }
+            const result = this._classifyError(err);
+            this._emitTelemetry(result);
+            return result;
+        }
+        finally {
+            // ── MANDATORY ABORT LISTENER CLEANUP ─────────
+            // Remove the listener to prevent memory leaks when
+            // execution completes before the signal fires.
+            if (signal && onAbort) {
+                signal.removeEventListener('abort', onAbort);
+            }
+            // ── MANDATORY C++ POINTER RELEASE ────────────
+            // Order matters: release inner resources first.
+            // After abort-triggered dispose, these will throw
+            // but the catch blocks handle dead-isolate gracefully.
+            try {
+                inputCopy?.release();
+            }
+            catch { /* already released or isolate dead */ }
+            try {
+                script?.release();
+            }
+            catch { /* already released or isolate dead */ }
+            try {
+                context?.release();
+            }
+            catch { /* already released or isolate dead */ }
+            this._activeExecutions--;
+        }
+    }
+    /**
+     * Release all resources held by this engine.
+     *
+     * After calling `dispose()`, any subsequent `execute()` calls
+     * will return `{ ok: false, code: 'UNAVAILABLE' }`.
+     */
+    dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        try {
+            this._isolate?.dispose();
+        }
+        catch {
+            // Isolate may already be dead (OOM)
+        }
+    }
+    /**
+     * Check if the engine has been disposed.
+     */
+    get isDisposed() {
+        return this._disposed;
+    }
+    /**
+     * Emit a `sandbox.exec` telemetry event if a sink is configured.
+     * @internal
+     */
+    _emitTelemetry(result) {
+        if (!this._telemetry)
+            return;
+        const event = {
+            type: 'sandbox.exec',
+            ok: result.ok,
+            executionMs: result.ok ? result.executionMs : 0,
+            ...(!result.ok ? { errorCode: result.code } : {}),
+            timestamp: Date.now(),
+        };
+        this._telemetry(event);
+    }
+    // ── Private ──────────────────────────────────────────
+    /**
+     * Ensure the isolate is alive. If it died (OOM), create a new one.
+     * @internal
+     */
+    _ensureIsolate() {
+        const ivm = getIvm();
+        // Check if isolate is still usable
+        try {
+            if (this._isolate?.isDisposed) {
+                this._isolate = new ivm.Isolate({ memoryLimit: this._memoryLimit });
+            }
+        }
+        catch {
+            // isDisposed threw → isolate is dead, recreate
+            this._isolate = new ivm.Isolate({ memoryLimit: this._memoryLimit });
+        }
+    }
+    /**
+     * Classify an error from V8 execution into a typed SandboxResult.
+     * @internal
+     */
+    _classifyError(err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // Timeout: isolated-vm throws a specific error
+        if (message.includes('Script execution timed out')) {
+            return {
+                ok: false,
+                error: `Script execution timed out (${this._timeout}ms). ` +
+                    'Simplify the computation or increase the timeout limit.',
+                code: 'TIMEOUT',
+            };
+        }
+        // Memory: V8 kills the isolate
+        if (message.includes('Isolate was disposed') ||
+            message.includes('out of memory') ||
+            message.includes('allocation failed')) {
+            // Mark isolate for recreation on next call
+            try {
+                this._isolate?.dispose();
+            }
+            catch { /* ignore */ }
+            return {
+                ok: false,
+                error: `Isolate ran out of memory (${this._memoryLimit}MB limit). ` +
+                    'Reduce the data size or simplify the computation.',
+                code: 'MEMORY',
+            };
+        }
+        // Syntax: V8 compilation error
+        if (message.includes('SyntaxError')) {
+            return {
+                ok: false,
+                error: `JavaScript syntax error: ${message}`,
+                code: 'SYNTAX',
+            };
+        }
+        // Runtime: any other V8 error (ReferenceError, TypeError, etc.)
+        return {
+            ok: false,
+            error: `Runtime error: ${message}`,
+            code: 'RUNTIME',
+        };
+    }
+}
+//# sourceMappingURL=SandboxEngine.js.map

package/dist/sandbox/SandboxEngine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SandboxEngine.js","sourceRoot":"","sources":["../../src/sandbox/SandboxEngine.ts"],"names":[],"mappings":"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"}