@pella-labs/pinakes 0.1.0

package/dist/sandbox/executor.d.ts

@@ -0,0 +1,68 @@
+import { type ExecuteResult, type Executor, type ResolvedProvider } from './vendored-codemode.js';
+import { type PoolStats } from './pool.js';
+import { type BindingDeps } from './bindings/install.js';
+/**
+ * QuickJS-backed Executor.
+ *
+ * Phase 3 upgrade: warm pool N=2 + `executeWithBindings()` for the full
+ * `kg.project.*` binding surface. The legacy `execute()` path (flat
+ * providers) remains for backward compatibility with Phase 1/2 tests.
+ *
+ * **Pool path** (`executeWithBindings`):
+ *   1. Acquire a runtime from the warm pool (or cold-spawn on overflow)
+ *   2. Create a fresh context on the pooled runtime
+ *   3. Bootstrap disabled globals + install full bindings
+ *   4. Evaluate normalized code
+ *   5. Dispose context, release runtime back to pool
+ *
+ * **Legacy path** (`execute`):
+ *   Fresh runtime + context per call, flat provider injection.
+ *   Kept for Phase 1/2 spike tests that use `kg.search`/`kg.get` directly.
+ *
+ * Error handling is always in-payload (CLAUDE.md §API Rules #8).
+ */
+export interface QuickJSExecutorOptions {
+    /** Memory limit in bytes. Defaults to 64 MB per `KG_MAX_MEMORY_MB`. */
+    memoryLimitBytes?: number;
+    /**
+     * Execution deadline in ms. The interrupt handler fires after this much
+     * wall-clock time. Defaults to 2000; clamped to `maxTimeoutMs`.
+     */
+    timeoutMs?: number;
+    /**
+     * Hard ceiling on `timeoutMs` from tool-call params. Defaults to 10_000
+     * per `KG_MAX_TIMEOUT_MS`. Callers cannot set `timeoutMs` above this.
+     */
+    maxTimeoutMs?: number;
+    /** Warm pool size. Defaults to 2. */
+    poolSize?: number;
+}
+export declare class QuickJSExecutor implements Executor {
+    private wasmModule;
+    private pool;
+    private readonly memoryLimitBytes;
+    private readonly defaultTimeoutMs;
+    private readonly maxTimeoutMs;
+    private readonly poolSize;
+    constructor(options?: QuickJSExecutorOptions);
+    /**
+     * Warm the cached WASM module and initialize the pool. Safe to call
+     * multiple times.
+     */
+    warmup(): Promise<void>;
+    /**
+     * Phase 3 primary path: execute code with the full `kg.project.*`
+     * bindings, `budget.fit()`, and `logger.log()` installed via the pool.
+     */
+    executeWithBindings(code: string, deps: BindingDeps, timeoutMs?: number): Promise<ExecuteResult>;
+    /** Pool stats for instrumentation / tests. */
+    getPoolStats(): PoolStats | null;
+    /** Dispose the pool and release all runtimes. */
+    dispose(): void;
+    /**
+     * Execute LLM-generated JS with flat provider injection (Phase 1/2 path).
+     * Creates a fresh runtime + context per call. Kept for backward compat.
+     */
+    execute(code: string, providersOrFns: ResolvedProvider[] | Record<string, (...args: unknown[]) => Promise<unknown>>): Promise<ExecuteResult>;
+}
+//# sourceMappingURL=executor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/sandbox/executor.ts"],"names":[],"mappings":"AASA,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAWhC,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,WAAW,CAAC;AACxD,OAAO,EAAmB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,sBAAsB;IACrC,uEAAuE;IACvE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AASD,qBAAa,eAAgB,YAAW,QAAQ;IAC9C,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,IAAI,CAA4B;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;gBAEtB,OAAO,GAAE,sBAA2B;IAOhD;;;OAGG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAY7B;;;OAGG;IACG,mBAAmB,CACvB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,WAAW,EACjB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC;IAqFzB,8CAA8C;IAC9C,YAAY,IAAI,SAAS,GAAG,IAAI;IAIhC,iDAAiD;IACjD,OAAO,IAAI,IAAI;IASf;;;OAGG;IACG,OAAO,CACX,IAAI,EAAE,MAAM,EACZ,cAAc,EACV,gBAAgB,EAAE,GAClB,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,GAC3D,OAAO,CAAC,aAAa,CAAC;CA+E1B"}

package/dist/sandbox/executor.js

@@ -0,0 +1,280 @@
+import { getQuickJS, Scope, } from 'quickjs-emscripten';
+import { normalizeCode, } from './vendored-codemode.js';
+import { DISABLE_GLOBALS_BOOTSTRAP, drainPendingJobs, errorMessage, formatGuestError, isPromise, marshalJsValue, } from './helpers.js';
+import { SandboxPool } from './pool.js';
+import { installBindings } from './bindings/install.js';
+const DEFAULT_MEMORY_LIMIT = 64 * 1024 * 1024;
+const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_MAX_TIMEOUT_MS = 10_000;
+/** Error patterns that indicate the QuickJS runtime is compromised. */
+const CRASH_PATTERNS = ['out of memory', 'allocation failed', 'stack overflow'];
+export class QuickJSExecutor {
+    wasmModule = null;
+    pool = null;
+    memoryLimitBytes;
+    defaultTimeoutMs;
+    maxTimeoutMs;
+    poolSize;
+    constructor(options = {}) {
+        this.memoryLimitBytes = options.memoryLimitBytes ?? DEFAULT_MEMORY_LIMIT;
+        this.defaultTimeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.maxTimeoutMs = options.maxTimeoutMs ?? DEFAULT_MAX_TIMEOUT_MS;
+        this.poolSize = options.poolSize ?? 2;
+    }
+    /**
+     * Warm the cached WASM module and initialize the pool. Safe to call
+     * multiple times.
+     */
+    async warmup() {
+        if (!this.wasmModule) {
+            this.wasmModule = await getQuickJS();
+        }
+        if (!this.pool) {
+            this.pool = new SandboxPool(this.wasmModule, {
+                poolSize: this.poolSize,
+                memoryLimitBytes: this.memoryLimitBytes,
+            });
+        }
+    }
+    /**
+     * Phase 3 primary path: execute code with the full `kg.project.*`
+     * bindings, `budget.fit()`, and `logger.log()` installed via the pool.
+     */
+    async executeWithBindings(code, deps, timeoutMs) {
+        await this.warmup();
+        const pool = this.pool;
+        let wrapped;
+        try {
+            wrapped = normalizeCode(code);
+        }
+        catch (e) {
+            return { result: null, error: `normalizeCode failed: ${errorMessage(e)}` };
+        }
+        const effectiveTimeout = Math.min(timeoutMs ?? this.defaultTimeoutMs, this.maxTimeoutMs);
+        const pr = pool.acquire();
+        let context = null;
+        let crashed = false;
+        try {
+            const deadline = Date.now() + effectiveTimeout;
+            pr.runtime.setInterruptHandler(() => Date.now() > deadline);
+            context = pr.runtime.newContext();
+            // Bootstrap disabled globals
+            const disableResult = context.evalCode(DISABLE_GLOBALS_BOOTSTRAP);
+            if (disableResult.error) {
+                const err = context.dump(disableResult.error);
+                disableResult.error.dispose();
+                return { result: null, error: `bootstrap failed: ${JSON.stringify(err)}`, logs: deps.logs };
+            }
+            disableResult.value.dispose();
+            // Install all bindings (logger, kg.project.*, budget.fit)
+            installBindings(context, deps);
+            // Evaluate the wrapped code
+            const callSource = `(${wrapped})()`;
+            const evalResult = context.evalCode(callSource, 'kg_execute.js');
+            if (evalResult.error) {
+                const err = context.dump(evalResult.error);
+                evalResult.error.dispose();
+                return { result: null, error: formatGuestError(err), logs: deps.logs };
+            }
+            const promiseHandle = evalResult.value;
+            try {
+                drainPendingJobs(pr.runtime);
+                const state = context.getPromiseState(promiseHandle);
+                if (state.type === 'pending') {
+                    return {
+                        result: null,
+                        error: 'kg_execute Promise never settled — all host bindings are synchronous',
+                        logs: deps.logs,
+                    };
+                }
+                if (state.type === 'rejected') {
+                    try {
+                        const err = context.dump(state.error);
+                        return { result: null, error: formatGuestError(err), logs: deps.logs };
+                    }
+                    finally {
+                        state.error.dispose();
+                    }
+                }
+                try {
+                    const value = context.dump(state.value);
+                    return { result: value, logs: deps.logs };
+                }
+                finally {
+                    state.value.dispose();
+                }
+            }
+            finally {
+                promiseHandle.dispose();
+            }
+        }
+        catch (e) {
+            const msg = errorMessage(e);
+            crashed = isCrash(msg);
+            return { result: null, error: msg, logs: deps.logs };
+        }
+        finally {
+            context?.dispose();
+            pool.release(pr, crashed);
+        }
+    }
+    /** Pool stats for instrumentation / tests. */
+    getPoolStats() {
+        return this.pool?.getStats() ?? null;
+    }
+    /** Dispose the pool and release all runtimes. */
+    dispose() {
+        this.pool?.dispose();
+        this.pool = null;
+    }
+    // ==========================================================================
+    // Legacy path — backward compat for Phase 1/2 spike tests
+    // ==========================================================================
+    /**
+     * Execute LLM-generated JS with flat provider injection (Phase 1/2 path).
+     * Creates a fresh runtime + context per call. Kept for backward compat.
+     */
+    async execute(code, providersOrFns) {
+        await this.warmup();
+        const wasmModule = this.wasmModule;
+        let wrapped;
+        try {
+            wrapped = normalizeCode(code);
+        }
+        catch (e) {
+            return { result: null, error: `normalizeCode failed: ${errorMessage(e)}` };
+        }
+        const logs = [];
+        const timeoutMs = Math.min(this.defaultTimeoutMs, this.maxTimeoutMs);
+        let runtime = null;
+        let context = null;
+        try {
+            runtime = wasmModule.newRuntime();
+            runtime.setMemoryLimit(this.memoryLimitBytes);
+            const deadline = Date.now() + timeoutMs;
+            runtime.setInterruptHandler(() => Date.now() > deadline);
+            context = runtime.newContext();
+            const disableResult = context.evalCode(DISABLE_GLOBALS_BOOTSTRAP);
+            if (disableResult.error) {
+                const err = context.dump(disableResult.error);
+                disableResult.error.dispose();
+                return { result: null, error: `bootstrap failed: ${JSON.stringify(err)}`, logs };
+            }
+            disableResult.value.dispose();
+            installLegacyLogger(context, logs);
+            installProviders(context, providersOrFns);
+            const callSource = `(${wrapped})()`;
+            const evalResult = context.evalCode(callSource, 'kg_execute.js');
+            if (evalResult.error) {
+                const err = context.dump(evalResult.error);
+                evalResult.error.dispose();
+                return { result: null, error: formatGuestError(err), logs };
+            }
+            const promiseHandle = evalResult.value;
+            try {
+                drainPendingJobs(runtime);
+                const state = context.getPromiseState(promiseHandle);
+                if (state.type === 'pending') {
+                    return {
+                        result: null,
+                        error: 'kg_execute Promise never settled — async host bindings are not supported',
+                        logs,
+                    };
+                }
+                if (state.type === 'rejected') {
+                    try {
+                        const err = context.dump(state.error);
+                        return { result: null, error: formatGuestError(err), logs };
+                    }
+                    finally {
+                        state.error.dispose();
+                    }
+                }
+                try {
+                    const value = context.dump(state.value);
+                    return { result: value, logs };
+                }
+                finally {
+                    state.value.dispose();
+                }
+            }
+            finally {
+                promiseHandle.dispose();
+            }
+        }
+        catch (e) {
+            return { result: null, error: errorMessage(e), logs };
+        }
+        finally {
+            context?.dispose();
+            runtime?.dispose();
+        }
+    }
+}
+// ============================================================================
+// Crash detection
+// ============================================================================
+function isCrash(errorMsg) {
+    const lower = errorMsg.toLowerCase();
+    return CRASH_PATTERNS.some((p) => lower.includes(p));
+}
+// ============================================================================
+// Legacy logger (for execute() backward compat)
+// ============================================================================
+function installLegacyLogger(context, logs) {
+    Scope.withScope((scope) => {
+        const loggerObj = scope.manage(context.newObject());
+        const logFn = context.newFunction('log', (...argsHandles) => {
+            try {
+                const parts = [];
+                for (const h of argsHandles) {
+                    const dumped = context.dump(h);
+                    parts.push(typeof dumped === 'string' ? dumped : JSON.stringify(dumped));
+                }
+                logs.push(parts.join(' '));
+            }
+            catch (e) {
+                logs.push(`<logger.log serialization error: ${errorMessage(e)}>`);
+            }
+            return context.undefined;
+        });
+        context.setProp(loggerObj, 'log', logFn);
+        logFn.dispose();
+        context.setProp(context.global, 'logger', loggerObj);
+    });
+}
+// ============================================================================
+// Legacy provider injection (for execute() backward compat)
+// ============================================================================
+function installProviders(context, providersOrFns) {
+    const providers = Array.isArray(providersOrFns)
+        ? providersOrFns
+        : [{ name: 'codemode', fns: providersOrFns }];
+    for (const provider of providers) {
+        Scope.withScope((scope) => {
+            const nsObj = scope.manage(context.newObject());
+            for (const [fnName, hostFn] of Object.entries(provider.fns)) {
+                const wrapped = context.newFunction(fnName, (...argsHandles) => {
+                    try {
+                        const nativeArgs = argsHandles.map((h) => context.dump(h));
+                        const rawResult = provider.positionalArgs
+                            ? hostFn(...nativeArgs)
+                            : hostFn(nativeArgs[0]);
+                        if (isPromise(rawResult)) {
+                            throw new Error(`host function ${provider.name}.${fnName} returned a Promise; ` +
+                                'only synchronous host bindings are supported');
+                        }
+                        return marshalJsValue(context, rawResult);
+                    }
+                    catch (e) {
+                        return context.newError(errorMessage(e));
+                    }
+                });
+                context.setProp(nsObj, fnName, wrapped);
+                wrapped.dispose();
+            }
+            context.setProp(context.global, provider.name, nsObj);
+        });
+    }
+}
+//# sourceMappingURL=executor.js.map

package/dist/sandbox/executor.js.map

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

package/dist/sandbox/helpers.d.ts

@@ -0,0 +1,26 @@
+import type { QuickJSContext, QuickJSHandle, QuickJSRuntime } from 'quickjs-emscripten';
+/**
+ * Shared helpers for the QuickJS sandbox. Extracted from executor.ts in
+ * Phase 3 so both the legacy flat-binding path and the new nested-binding
+ * path can reuse them.
+ */
+export declare const DISABLE_GLOBALS_BOOTSTRAP = "\n(() => {\n  const ban = (name) => {\n    try { delete globalThis[name]; } catch (_) {}\n    try {\n      Object.defineProperty(globalThis, name, {\n        get() { throw new Error(name + ' is not available in the kg sandbox'); },\n        configurable: false,\n      });\n    } catch (_) {}\n  };\n  ban('eval');\n  ban('Function');\n  ban('fetch');\n  ban('require');\n  ban('process');\n  ban('WebAssembly');\n  try {\n    Object.defineProperty(globalThis, 'constructor', {\n      get() { throw new Error('constructor is not available in the kg sandbox'); },\n      configurable: false,\n    });\n  } catch (_) {}\n})();\n";
+/**
+ * Pump the pending-jobs queue until it's drained or the runtime rejects
+ * further work. Our async IIFE's microtasks all live in this queue, so a
+ * single pass is usually enough — but nested `Promise.then` chains can
+ * require multiple passes. Bounded at 32 iterations to avoid spinning
+ * forever on runaway code (the interrupt handler is the real safety net).
+ */
+export declare function drainPendingJobs(runtime: QuickJSRuntime): void;
+/**
+ * Convert a plain JS value into a QuickJSHandle that the guest can see.
+ * Handles primitives, arrays, and plain objects recursively. The caller is
+ * NOT responsible for disposing the returned handle — QuickJS's function
+ * return mechanism transfers ownership into the guest VM.
+ */
+export declare function marshalJsValue(context: QuickJSContext, value: unknown): QuickJSHandle;
+export declare function errorMessage(e: unknown): string;
+export declare function formatGuestError(dumped: unknown): string;
+export declare function isPromise(value: unknown): value is Promise<unknown>;
+//# sourceMappingURL=helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"helpers.d.ts","sourceRoot":"","sources":["../../src/sandbox/helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,cAAc,EACf,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AAMH,eAAO,MAAM,yBAAyB,unBAwBrC,CAAC;AAMF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAS9D;AAMD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,OAAO,GAAG,aAAa,CA2BrF;AAMD,wBAAgB,YAAY,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,CAQ/C;AAED,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CASxD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,CAMnE"}

package/dist/sandbox/helpers.js

@@ -0,0 +1,131 @@
+/**
+ * Shared helpers for the QuickJS sandbox. Extracted from executor.ts in
+ * Phase 3 so both the legacy flat-binding path and the new nested-binding
+ * path can reuse them.
+ */
+// ============================================================================
+// Bootstrap: disabled globals
+// ============================================================================
+export const DISABLE_GLOBALS_BOOTSTRAP = `
+(() => {
+  const ban = (name) => {
+    try { delete globalThis[name]; } catch (_) {}
+    try {
+      Object.defineProperty(globalThis, name, {
+        get() { throw new Error(name + ' is not available in the kg sandbox'); },
+        configurable: false,
+      });
+    } catch (_) {}
+  };
+  ban('eval');
+  ban('Function');
+  ban('fetch');
+  ban('require');
+  ban('process');
+  ban('WebAssembly');
+  try {
+    Object.defineProperty(globalThis, 'constructor', {
+      get() { throw new Error('constructor is not available in the kg sandbox'); },
+      configurable: false,
+    });
+  } catch (_) {}
+})();
+`;
+// ============================================================================
+// Pending-jobs drain
+// ============================================================================
+/**
+ * Pump the pending-jobs queue until it's drained or the runtime rejects
+ * further work. Our async IIFE's microtasks all live in this queue, so a
+ * single pass is usually enough — but nested `Promise.then` chains can
+ * require multiple passes. Bounded at 32 iterations to avoid spinning
+ * forever on runaway code (the interrupt handler is the real safety net).
+ */
+export function drainPendingJobs(runtime) {
+    for (let i = 0; i < 32; i++) {
+        const result = runtime.executePendingJobs();
+        if (result.error) {
+            result.error.dispose();
+            return;
+        }
+        if (result.value <= 0)
+            return;
+    }
+}
+// ============================================================================
+// Host-value marshaling
+// ============================================================================
+/**
+ * Convert a plain JS value into a QuickJSHandle that the guest can see.
+ * Handles primitives, arrays, and plain objects recursively. The caller is
+ * NOT responsible for disposing the returned handle — QuickJS's function
+ * return mechanism transfers ownership into the guest VM.
+ */
+export function marshalJsValue(context, value) {
+    if (value === undefined)
+        return context.undefined;
+    if (value === null)
+        return context.null;
+    if (typeof value === 'string')
+        return context.newString(value);
+    if (typeof value === 'number')
+        return context.newNumber(value);
+    if (typeof value === 'boolean')
+        return value ? context.true : context.false;
+    if (typeof value === 'bigint')
+        return context.newNumber(Number(value));
+    if (Array.isArray(value)) {
+        const arr = context.newArray();
+        for (let i = 0; i < value.length; i++) {
+            const elem = marshalJsValue(context, value[i]);
+            context.setProp(arr, i, elem);
+            elem.dispose();
+        }
+        return arr;
+    }
+    if (typeof value === 'object') {
+        const obj = context.newObject();
+        for (const [k, v] of Object.entries(value)) {
+            const elem = marshalJsValue(context, v);
+            context.setProp(obj, k, elem);
+            elem.dispose();
+        }
+        return obj;
+    }
+    // Fallback: stringify unknowns. Covers symbols, functions, etc.
+    return context.newString(String(value));
+}
+// ============================================================================
+// Error helpers
+// ============================================================================
+export function errorMessage(e) {
+    if (e instanceof Error)
+        return e.message;
+    if (typeof e === 'string')
+        return e;
+    try {
+        return JSON.stringify(e);
+    }
+    catch {
+        return String(e);
+    }
+}
+export function formatGuestError(dumped) {
+    if (dumped && typeof dumped === 'object') {
+        const obj = dumped;
+        const parts = [];
+        if (obj.name)
+            parts.push(String(obj.name));
+        if (obj.message)
+            parts.push(String(obj.message));
+        if (parts.length > 0)
+            return parts.join(': ');
+    }
+    return typeof dumped === 'string' ? dumped : JSON.stringify(dumped);
+}
+export function isPromise(value) {
+    return (value !== null &&
+        (typeof value === 'object' || typeof value === 'function') &&
+        typeof value.then === 'function');
+}
+//# sourceMappingURL=helpers.js.map

package/dist/sandbox/helpers.js.map

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

package/dist/sandbox/pool.d.ts

@@ -0,0 +1,63 @@
+import type { QuickJSRuntime, QuickJSWASMModule } from 'quickjs-emscripten';
+/**
+ * Warm sandbox pool (presearch D12, CLAUDE.md §Architecture #1).
+ *
+ * Manages a pool of N pre-created QuickJS runtimes with synchronous
+ * acquire/release semantics. Each runtime has its memory limit pre-set;
+ * callers create fresh contexts on the acquired runtime, run code, dispose
+ * the context, then release the runtime back.
+ *
+ * **Overflow**: when all N runtimes are checked out, `acquire()` spawns a
+ * cold runtime on the spot — it never blocks. Cold overflow runtimes are
+ * disposed on release (the pool never grows beyond `maxSize`).
+ *
+ * **Crash recovery**: if the caller signals `crashed=true` on release, the
+ * runtime is disposed and a fresh replacement is created so the pool stays
+ * at its target size. This handles QuickJS OOM or WASM-level failures that
+ * leave the runtime in an inconsistent state.
+ *
+ * **Instrumentation**: `getStats()` reports warm hits, cold hits, and crash
+ * counts for the Phase 3 test suite.
+ */
+export interface PoolStats {
+    warmHits: number;
+    coldHits: number;
+    crashes: number;
+    currentSize: number;
+}
+export interface PooledRuntime {
+    runtime: QuickJSRuntime;
+    /** Monotonic id for instrumentation / test assertions. */
+    id: number;
+    /** True if this runtime came from the warm pool, false if overflow-spawned. */
+    isWarm: boolean;
+}
+export declare class SandboxPool {
+    private readonly wasmModule;
+    private readonly available;
+    private readonly maxSize;
+    private readonly memoryLimitBytes;
+    private readonly stats;
+    private nextId;
+    private disposed;
+    constructor(wasmModule: QuickJSWASMModule, opts?: {
+        poolSize?: number;
+        memoryLimitBytes?: number;
+    });
+    /**
+     * Acquire a runtime from the pool. If the pool has warm runtimes available,
+     * returns one immediately. Otherwise spawns a cold overflow runtime.
+     * Never blocks.
+     */
+    acquire(): PooledRuntime;
+    /**
+     * Release a runtime back to the pool. If `crashed` is true, the runtime
+     * is disposed and replaced with a fresh one. Overflow runtimes (not from
+     * the warm pool) are always disposed on release.
+     */
+    release(pr: PooledRuntime, crashed: boolean): void;
+    getStats(): Readonly<PoolStats>;
+    dispose(): void;
+    private spawnRuntime;
+}
+//# sourceMappingURL=pool.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../../src/sandbox/pool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,cAAc,CAAC;IACxB,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAC;IACX,+EAA+E;IAC/E,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,WAAW;IAcpB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAb7B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAKpB;IACF,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,QAAQ,CAAS;gBAGN,UAAU,EAAE,iBAAiB,EAC9C,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;KAAE;IAYzD;;;;OAIG;IACH,OAAO,IAAI,aAAa;IAcxB;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,aAAa,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI;IAyBlD,QAAQ,IAAI,QAAQ,CAAC,SAAS,CAAC;IAI/B,OAAO,IAAI,IAAI;IAUf,OAAO,CAAC,YAAY;CAKrB"}