@vibemancer/core 1.0.9 → 1.0.11

package/src/engine/sandbox.ts

@@ -1,341 +1,347 @@
-/**
- * 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 {DEFAULT_FIGHT_BACKSTOP_MS} from './bot-compute-budget.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: 60000). */
-	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;
-		// Was a bare 60000, which the per-bot compute budget made wrong: a budgeted fight can
-		// legitimately let one runaway bot spend 45s before it stops being called, and 60s
-		// here would kill the whole fight first — putting the wall clock back in charge of
-		// outcomes. Shared constant so this cannot drift from the other copies again.
-		const timeoutMs = options?.timeoutMs ?? DEFAULT_FIGHT_BACKSTOP_MS;
-
-		// 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;
-		// Was a bare 60000, which the per-bot compute budget made wrong: a budgeted fight can
-		// legitimately let one runaway bot spend 45s before it stops being called, and 60s
-		// here would kill the whole fight first — putting the wall clock back in charge of
-		// outcomes. Shared constant so this cannot drift from the other copies again.
-		const timeoutMs = options?.timeoutMs ?? DEFAULT_FIGHT_BACKSTOP_MS;
-
-		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();
-	}
-}
+/**
+ * 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 DEFAULT_FIGHT_BACKSTOP_MS) 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 {DEFAULT_FIGHT_BACKSTOP_MS} from './bot-compute-budget.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. Defaults to DEFAULT_FIGHT_BACKSTOP_MS.
+	 *
+	 * Named rather than written out, because this file previously gave THREE different
+	 * numbers for one default — "30s" in the header, "60000" here, and the actual value used
+	 * below — and a reader had no way to tell which was true.
+	 */
+	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;
+		// Was a bare 60000, which the per-bot compute budget made wrong: a budgeted fight can
+		// legitimately let one runaway bot spend 45s before it stops being called, and 60s
+		// here would kill the whole fight first — putting the wall clock back in charge of
+		// outcomes. Shared constant so this cannot drift from the other copies again.
+		const timeoutMs = options?.timeoutMs ?? DEFAULT_FIGHT_BACKSTOP_MS;
+
+		// 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;
+		// Was a bare 60000, which the per-bot compute budget made wrong: a budgeted fight can
+		// legitimately let one runaway bot spend 45s before it stops being called, and 60s
+		// here would kill the whole fight first — putting the wall clock back in charge of
+		// outcomes. Shared constant so this cannot drift from the other copies again.
+		const timeoutMs = options?.timeoutMs ?? DEFAULT_FIGHT_BACKSTOP_MS;
+
+		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();
+	}
+}