@vibemancer/core 0.1.0

package/src/engine/sandbox.ts

@@ -0,0 +1,332 @@
+/**
+ * VIBEMANCER — SANDBOX
+ *
+ * Provides isolated-vm sandboxing for bot code execution. Both bots + the
+ * entire simulation engine run inside a single V8 isolate, so there is ZERO
+ * per-tick boundary crossing overhead. The only data crossing the boundary
+ * is fight/simulate options going in and results coming out.
+ *
+ * Architecture:
+ * - Host: creates isolate, loads compiled bundle, calls __fight/__simulate
+ * - Isolate: contains both bots + full simulation engine, runs fight/simulate
+ *
+ * Safety:
+ * - Memory limit (default 512 MB) catches memory bombs
+ * - Timeout (default 30s) catches infinite loops
+ * - Prototype freeze prevents cross-bot sabotage
+ * - platform: 'neutral' strips Node.js APIs (no fs/net/process)
+ */
+
+import ivm from 'isolated-vm';
+import type {FightResult, SimulateResult} from './simulation.js';
+import {BotBundle, compileMatchBundle} from './sandbox-compile.js';
+import type {CompileOptions} from './sandbox-compile.js';
+
+// Re-export BotBundle so existing imports from sandbox.ts keep working
+export {BotBundle} from './sandbox-compile.js';
+export {compileMatchBundle, compileManualMatchBundle} from './sandbox-compile.js';
+export type {CompileOptions} from './sandbox-compile.js';
+
+/**
+ * Options for sandbox creation.
+ */
+export interface SandboxOptions
+{
+	/** Memory limit in MB for the isolate (default: 512). */
+	memoryLimitMB?: number;
+	/** Timeout in ms for fight/simulate calls (default: 30000). */
+	timeoutMs?: number;
+	/** Options passed to esbuild compilation (aliases, externals). */
+	compileOptions?: CompileOptions;
+}
+
+/**
+ * A sandboxed match runner. Both bots + the entire simulation engine run
+ * inside a single isolated-vm isolate.
+ *
+ * Usage:
+ * ```ts
+ * const sandbox = await MatchSandbox.create(botA, botB);
+ * const result = sandbox.fight({ seed: 42 });
+ * sandbox.dispose();
+ * ```
+ */
+export class MatchSandbox
+{
+	private isolate: ivm.Isolate;
+	private context: ivm.Context;
+	private fightFn: ivm.Reference;
+	private simulateFn: ivm.Reference;
+	private timeout: number;
+	private disposed = false;
+
+	private constructor(
+		isolate: ivm.Isolate,
+		context: ivm.Context,
+		fightFn: ivm.Reference,
+		simulateFn: ivm.Reference,
+		timeout: number,
+	)
+	{
+		this.isolate = isolate;
+		this.context = context;
+		this.fightFn = fightFn;
+		this.simulateFn = simulateFn;
+		this.timeout = timeout;
+	}
+
+	/**
+	 * Create a sandbox with both bots loaded. Compiles the match bundle
+	 * automatically using esbuild.
+	 */
+	static async create(
+		bot1: BotBundle,
+		bot2: BotBundle,
+		options?: SandboxOptions,
+	): Promise<MatchSandbox>
+	{
+		const memoryLimitMB = options?.memoryLimitMB ?? 512;
+		const timeoutMs = options?.timeoutMs ?? 30000;
+
+		// 1. Compile the match bundle
+		const bundle = await compileMatchBundle(bot1, bot2, options?.compileOptions);
+
+		// 2. Create isolate with memory limit
+		const isolate = new ivm.Isolate({memoryLimit: memoryLimitMB});
+
+		try
+		{
+			// 3. Create context and load the bundle
+			const context = await isolate.createContext();
+			const script = await isolate.compileScript(bundle, {filename: 'match-bundle.js'});
+			await script.run(context, {timeout: timeoutMs});
+
+			// 4. Get references to the exposed functions
+			const global = context.global;
+			const fightFn = await global.get('__fight', {reference: true});
+			const simulateFn = await global.get('__simulate', {reference: true});
+
+			return new MatchSandbox(isolate, context, fightFn, simulateFn, timeoutMs);
+		}
+		catch(error)
+		{
+			// OOM or timeout can auto-dispose the isolate, so guard the cleanup dispose.
+			try
+			{
+				isolate.dispose();
+			}
+			catch
+			{
+				// already disposed
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Create a sandbox from a pre-compiled bundle string.
+	 * Useful for caching compiled bundles across multiple MatchSandbox instances.
+	 */
+	static async fromBundle(
+		bundle: string,
+		options?: SandboxOptions,
+	): Promise<MatchSandbox>
+	{
+		const memoryLimitMB = options?.memoryLimitMB ?? 512;
+		const timeoutMs = options?.timeoutMs ?? 30000;
+
+		const isolate = new ivm.Isolate({memoryLimit: memoryLimitMB});
+
+		try
+		{
+			const context = await isolate.createContext();
+			const script = await isolate.compileScript(bundle, {filename: 'match-bundle.js'});
+			await script.run(context, {timeout: timeoutMs});
+
+			const global = context.global;
+			const fightFn = await global.get('__fight', {reference: true});
+			const simulateFn = await global.get('__simulate', {reference: true});
+
+			return new MatchSandbox(isolate, context, fightFn, simulateFn, timeoutMs);
+		}
+		catch(error)
+		{
+			try
+			{
+				isolate.dispose();
+			}
+			catch
+			{
+				// already disposed
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * Compile a match bundle without creating an isolate.
+	 * Returns the compiled JS string for caching/reuse.
+	 */
+	static async compile(bot1: BotBundle, bot2: BotBundle, compileOptions?: CompileOptions): Promise<string>
+	{
+		return compileMatchBundle(bot1, bot2, compileOptions);
+	}
+
+	/**
+	 * Run a full fight (10 matches: 5 spawn distances x 2 sides).
+	 * Synchronous after isolate creation — runs entirely inside the isolate.
+	 */
+	fight(options?: {seed?: number; maxTicks?: number}): FightResult
+	{
+		this.ensureNotDisposed();
+
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- isolated-vm returns unknown
+		return this.fightFn.applySync(undefined, [options ?? {}], {
+			arguments: {copy: true},
+			result: {copy: true},
+			timeout: this.timeout,
+		}) as FightResult;
+	}
+
+	/**
+	 * Run a single simulation.
+	 * Synchronous after isolate creation.
+	 *
+	 * @param options.params1 - useParam overrides for bot 1 (wizard-1)
+	 * @param options.params2 - useParam overrides for bot 2 (wizard-2)
+	 */
+	simulate(options?: {
+		seed?: number;
+		maxTicks?: number;
+		spawnDistance?: number;
+		skipHistory?: boolean;
+		params1?: Record<string, number>;
+		params2?: Record<string, number>;
+	}): SimulateResult
+	{
+		this.ensureNotDisposed();
+
+		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- isolated-vm returns unknown
+		return this.simulateFn.applySync(undefined, [options ?? {}], {
+			arguments: {copy: true},
+			result: {copy: true},
+			timeout: this.timeout,
+		}) as SimulateResult;
+	}
+
+	/**
+	 * Dispose the isolate and free all memory.
+	 * The sandbox cannot be used after disposal.
+	 */
+	dispose(): void
+	{
+		if (!this.disposed)
+		{
+			this.disposed = true;
+			// OOM can auto-dispose the isolate, so guard all cleanup
+			try
+			{
+				this.fightFn.release();
+			}
+			catch
+			{
+				// isolate already disposed
+			}
+			try
+			{
+				this.simulateFn.release();
+			}
+			catch
+			{
+				// isolate already disposed
+			}
+			try
+			{
+				this.context.release();
+			}
+			catch
+			{
+				// isolate already disposed
+			}
+			try
+			{
+				this.isolate.dispose();
+			}
+			catch
+			{
+				// isolate already disposed
+			}
+		}
+	}
+
+	/**
+	 * Whether this sandbox has been disposed.
+	 */
+	get isDisposed(): boolean
+	{
+		return this.disposed;
+	}
+
+	private ensureNotDisposed(): void
+	{
+		if (this.disposed)
+		{
+			throw new Error('MatchSandbox has been disposed');
+		}
+	}
+}
+
+/**
+ * One-shot sandboxed fight. Creates isolate, runs fight, disposes.
+ * Convenience wrapper for single-use scenarios.
+ */
+export async function sandboxFight(
+	bot1: BotBundle,
+	bot2: BotBundle,
+	options?: {seed?: number; maxTicks?: number} & SandboxOptions,
+): Promise<FightResult>
+{
+	const sandbox = await MatchSandbox.create(bot1, bot2, options);
+	try
+	{
+		return sandbox.fight({seed: options?.seed, maxTicks: options?.maxTicks});
+	}
+	finally
+	{
+		sandbox.dispose();
+	}
+}
+
+/**
+ * One-shot sandboxed simulate. Creates isolate, runs simulate, disposes.
+ */
+export async function sandboxSimulate(
+	bot1: BotBundle,
+	bot2: BotBundle,
+	options?: {
+		seed?: number;
+		maxTicks?: number;
+		spawnDistance?: number;
+		skipHistory?: boolean;
+		params1?: Record<string, number>;
+		params2?: Record<string, number>;
+	} & SandboxOptions,
+): Promise<SimulateResult>
+{
+	const sandbox = await MatchSandbox.create(bot1, bot2, options);
+	try
+	{
+		return sandbox.simulate({
+			seed: options?.seed,
+			maxTicks: options?.maxTicks,
+			spawnDistance: options?.spawnDistance,
+			skipHistory: options?.skipHistory,
+			params1: options?.params1,
+			params2: options?.params2,
+		});
+	}
+	finally
+	{
+		sandbox.dispose();
+	}
+}