@vibemancer/core 1.0.2 → 1.0.4

package/src/engine/bot-compute-budget.ts

@@ -0,0 +1,173 @@
+/**
+ * VIBEMANCER — BOT COMPUTE BUDGET
+ *
+ * The real-time guard, moved off the whole fight and onto each bot.
+ *
+ * Decision 0002: fight LENGTH is simulation time (`maxTicks`) and always was; "stop a bot
+ * looping forever" genuinely needs real time. Conflating both into one wall-clock timeout
+ * around the entire match meant a slow SERVER was indistinguishable from a broken bot — and
+ * matchmaking blamed the player for it, up to auto-deactivating their bot.
+ *
+ * The constraint that shapes this module: the tick loop runs INSIDE the isolate, where the
+ * only clock is `Date.now()`. There is no way to measure a bot in machine-independent units
+ * from in there. So this guard is wall-clock, and wall clock on a shared server is exactly
+ * the thing that caused the original bug.
+ *
+ * The resolution is therefore in what going over budget COSTS:
+ *
+ *   - A bot has ONE budget: total thinking time across a whole fight.
+ *   - Spend it and the bot is not called again for the rest of the fight. It stands still.
+ *   - That is never recorded as an error, so it cannot increment `consecutiveCrashes` and
+ *     cannot auto-deactivate a bot.
+ *
+ * A bot too slow to answer loses the fight it was too slow for, which is the same thing that
+ * happens to a lagging player in any real-time game. A busy server can cost someone a match;
+ * it must never cost them their bot.
+ *
+ * ## Why there is no per-tick limit
+ *
+ * There was one, briefly: overrun 50ms in a single tick and that tick's action was
+ * discarded. It had to go, and the reason is the important part of this file.
+ *
+ * This engine is DETERMINISTIC by design. Spectate re-simulates a recorded match and gates
+ * on ENGINE_VERSION precisely so that the same version and seed reproduce the same fight. A
+ * per-tick threshold breaks that: under load a single call can cross 50ms through a GC pause
+ * or a scheduler hiccup, its action is discarded, and the fight diverges. Outcomes then
+ * depend on how busy the machine was — which is the original bug, reintroduced at finer
+ * granularity by the thing meant to fix it. It was caught by a test that passed alone and
+ * failed inside a loaded run.
+ *
+ * A single cumulative budget does not have that problem in practice. Measurement still
+ * varies with load, but it only changes BEHAVIOUR at one point — exhaustion — and an honest
+ * bot never approaches it: the worst real bot measured spends 5.6s of a 45s allowance. So
+ * every legitimate fight is bit-identical to an unbudgeted one, and determinism holds.
+ *
+ * A bot that stalls inside one tick is left to the outer wall-clock backstop, which is the
+ * only thing that could ever catch it anyway: a `while(true)` cannot be interrupted from
+ * inside a single-threaded isolate, no matter what the tick loop measures.
+ *
+ * Everything here is pure arithmetic so it can be tested exhaustively. The only impure part
+ * — reading the clock — stays in the tick loop.
+ *
+ * A note on precision, because it looks broken and is not. `Date.now()` resolves to 1ms here
+ * (measured), while a typical bot call is microseconds — so nearly every individual call
+ * measures 0ms and contributes nothing. That is fine, and deliberately not "fixed": a call
+ * lasting d milliseconds (d < 1) straddles a millisecond boundary with probability d, so it
+ * reads 1 exactly that often and 0 otherwise. The expected measurement equals the true
+ * duration, which over the thousands of calls in a fight is what a cumulative budget needs.
+ * Swapping in a higher-resolution clock is not an option anyway: inside the isolate there is
+ * no other clock, and a per-call `performance.now()` would cost more than it measures.
+ */
+
+/** Limits applied to a single bot for one fight. */
+export interface BudgetLimits
+{
+	/** Milliseconds a bot may spend thinking, in total, before it stops being called. */
+	totalMs: number;
+}
+
+/** A single bot's running spend for one fight. */
+export interface BotBudgetState
+{
+	spentMs: number;
+	exhausted: boolean;
+}
+
+/**
+ * Default, sized from measurement (2026-08-30) — and resized once, after the first
+ * measurement turned out to be worthless.
+ *
+ * The first pass measured TargetDummy, a bot whose entire body is `return idle()`. Against
+ * that, a full-length 30,000-tick match costs ~196ms and any budget looks generous. Real
+ * built-in bots are nothing like it. One `fight()` — ten matches — between two of them:
+ *
+ *     Bonemancer vs Turtle       18392ms
+ *     Bonemancer vs Spellseeker  11251ms
+ *     Turtle vs Hogger           10185ms
+ *
+ * and instrumenting the calls shows bot code is 70-78% of that, one honest bot spending
+ * 5611ms in a single fight. A 20s budget, which had looked like 200x headroom, was really
+ * about 2-4x — it would have fired on innocent play the first time the server was busy,
+ * which is the exact bug it exists to prevent.
+ *
+ * Hence 45s per bot per fight: roughly 8x the honest worst case measured here. That margin
+ * is also what keeps fights deterministic, since behaviour only changes if it is reached.
+ *
+ * This exists to catch runaway code, not to make anyone optimise.
+ */
+export const DEFAULT_BUDGET: BudgetLimits = {
+	totalMs: 45_000,
+};
+
+/**
+ * Last-resort wall-clock backstop for a whole fight (ms).
+ *
+ * Lives here, next to the budget, because the two numbers only make sense together: the
+ * budget is what bounds bot compute, and this is only for the case no in-isolate guard can
+ * reach — a bot in `while(true)`, which cannot be interrupted from inside a single-threaded
+ * isolate no matter what the tick loop measures.
+ *
+ * One runaway bot (45s of budget) plus an honest opponent has to fit inside it, or the
+ * backstop fires first and the budget never gets to attribute anything. It is capped at 110s
+ * rather than raised further because the mcp Cloud Function's own `timeoutSeconds` is 120 —
+ * above that the platform kills the request first and nothing useful is reported.
+ *
+ * It is a single exported constant precisely because it was previously four separate
+ * literals (bundle-fight, sandbox twice, functions/fight-runner) that drifted apart.
+ */
+export const DEFAULT_FIGHT_BACKSTOP_MS = 110_000;
+
+/**
+ * Both bots' budgets for ONE FIGHT.
+ *
+ * The scope matters more than it looks. `fight()` is not one simulation, it is ten (five
+ * spawn distances, each played from both sides). A budget scoped to a single `simulate`
+ * would hand a runaway bot its whole total ten times over — 450 seconds of bot compute
+ * inside a 110-second backstop — and would look like it was bounding something while
+ * bounding nothing. So the budget belongs to the fight, and is carried across its matches.
+ *
+ * This is the one mutable thing in this module: `simulate` updates `states` in place as it
+ * runs so the spend survives from one match to the next.
+ */
+export interface FightBudget
+{
+	states: [BotBudgetState, BotBudgetState];
+	limits: BudgetLimits;
+}
+
+/** A fresh budget for one bot at the start of a fight. */
+export function createBudgetState(): BotBudgetState
+{
+	return {spentMs: 0, exhausted: false};
+}
+
+/** A fresh budget covering both bots for one whole fight (all of its matches). */
+export function createFightBudget(limits: BudgetLimits = DEFAULT_BUDGET): FightBudget
+{
+	return {states: [createBudgetState(), createBudgetState()], limits};
+}
+
+/** May this bot still be called at all? */
+export function mayAct(state: BotBudgetState): boolean
+{
+	return !state.exhausted;
+}
+
+/**
+ * Record what one call cost.
+ *
+ * A non-finite elapsed time is ignored rather than charged, and a negative one cannot refund
+ * budget — `Date.now()` can step backwards on an NTP correction or a VM migration, and that
+ * must not become a way to earn compute.
+ */
+export function recordSpend(
+	state: BotBudgetState,
+	limits: BudgetLimits,
+	elapsedMs: number,
+): BotBudgetState
+{
+	if (!Number.isFinite(elapsedMs) || elapsedMs <= 0) return state;
+
+	const spentMs = state.spentMs + elapsedMs;
+	return {spentMs, exhausted: state.exhausted || spentMs > limits.totalMs};
+}

package/src/engine/bundle-fight.ts

@@ -19,11 +19,34 @@ import ivm from 'isolated-vm';
 import {build} from 'esbuild';
 import {getEngineDir} from './sandbox-compile.js';
 import type {FightResult, SimulateResult} from './simulation.js';
+import {DEFAULT_FIGHT_BACKSTOP_MS} from './bot-compute-budget.js';
 
 /** Memory limit per sandbox isolate (MB). */
 const MEMORY_LIMIT_MB = 256;
-/** Timeout per fight (ms). */
-const FIGHT_TIMEOUT_MS = 60_000;
+/**
+ * Default timeout per fight (ms).
+ *
+ * This is a real safety limit: it stops a malicious or looping bot burning server time in
+ * the matchmaker, so the DEFAULT must not move. It was previously hardcoded and unreachable
+ * from any option, which made the suite unusable on a busy machine — one e2e fight exceeded
+ * it and blocked seven consecutive commits, while a comparable fight run to the tick cap
+ * finished in 1.3s on the same machine at the same moment. The limit was not catching a
+ * runaway bot; it was catching load.
+ */
+export const DEFAULT_FIGHT_TIMEOUT_MS = DEFAULT_FIGHT_BACKSTOP_MS;
+
+/**
+ * Resolve the effective fight timeout.
+ *
+ * Only ever EXTENDS the default. A caller who knows the work is legitimate (a test on a
+ * slow machine) can ask for more; nobody can quietly ask for less, because weakening a
+ * safety limit by accident is the direction that turns it into a flaky one.
+ */
+export function resolveFightTimeout(requested: number | undefined): number
+{
+	if (typeof requested !== 'number' || !Number.isFinite(requested)) return DEFAULT_FIGHT_TIMEOUT_MS;
+	return Math.max(DEFAULT_FIGHT_TIMEOUT_MS, requested);
+}
 
 const FREEZE_BANNER = `
 Object.freeze(Object.prototype);
@@ -74,6 +97,7 @@ export function buildMatchTemplate(): Promise<string>
 			const entryPoint = `
 import {fight, simulate} from '${coreSrc}/engine/simulation.ts';
 import {wrapWithParams} from '${coreSrc}/engine/params-runtime.ts';
+import {DEFAULT_BUDGET} from '${coreSrc}/engine/bot-compute-budget.ts';
 
 const __Bot1 = (globalThis as any).__injectedBot1;
 const __Bot2 = (globalThis as any).__injectedBot2;
@@ -82,14 +106,18 @@ if (!__Bot1) throw new Error('Bot 1 not injected (set globalThis.__injectedBot1)
 if (!__Bot2) throw new Error('Bot 2 not injected (set globalThis.__injectedBot2)');
 
 (globalThis as any).__fight = function __fight(options: any) {
-	return fight(__Bot1, __Bot2, options);
+	// Same per-bot compute budget the server uses, so a runaway bot fails the same way in
+	// the CLI as it will on the ladder — and so it cannot hang someone's terminal.
+	return fight(__Bot1, __Bot2, {budgetLimits: DEFAULT_BUDGET, ...options});
 };
 
 (globalThis as any).__simulate = function __simulate(options: any) {
 	const {params1, params2, ...simOptions} = options;
 	const bot1 = params1 ? wrapWithParams(__Bot1, params1) : __Bot1;
 	const bot2 = params2 ? wrapWithParams(__Bot2, params2) : __Bot2;
-	return simulate(bot1, bot2, simOptions);
+	// Budgeted like __fight — this is the CLI's trace/optimize path, and its backstop went
+	// up to 110s with everything else, so leaving it out would make it worse than before.
+	return simulate(bot1, bot2, {budgetLimits: DEFAULT_BUDGET, ...simOptions});
 };
 `;
 
@@ -121,6 +149,8 @@ export interface RunBundleFightOptions
 	seed: number;
 	/** Prebuilt match template (e.g. the committed Cloud Functions one). Built lazily if omitted. */
 	matchTemplate?: string;
+	/** Extend the per-fight isolate timeout. Can only raise it above the default. */
+	fightTimeoutMs?: number;
 	/** Skip per-tick history in the result (smaller copy out of the isolate). Default true. */
 	skipHistory?: boolean;
 }
@@ -139,6 +169,7 @@ export async function runBundleFight(
 ): Promise<FightResult>
 {
 	const template = options.matchTemplate ?? await buildMatchTemplate();
+	const fightTimeoutMs = resolveFightTimeout(options.fightTimeoutMs);
 	const skipHistory = options.skipHistory ?? true;
 
 	// Freeze prototypes/globals BEFORE the untrusted bot bundles run. The bundles
@@ -165,13 +196,13 @@ export async function runBundleFight(
 		await jail.set('global', jail.derefInto());
 
 		const script = await isolate.compileScript(code);
-		await script.run(context, {timeout: FIGHT_TIMEOUT_MS});
+		await script.run(context, {timeout: fightTimeoutMs});
 
 		const fightFn = await jail.get('__fight');
 		const result = await fightFn.apply(
 			undefined,
 			[new ivm.ExternalCopy({seed: options.seed, skipHistory}).copyInto()],
-			{timeout: FIGHT_TIMEOUT_MS, result: {copy: true}},
+			{timeout: fightTimeoutMs, result: {copy: true}},
 		);
 
 		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- isolated-vm returns unknown
@@ -189,6 +220,8 @@ export interface RunBundleSimulateOptions
 	spawnDistance?: number;
 	maxTicks?: number;
 	matchTemplate?: string;
+	/** Extend the per-fight isolate timeout. Can only raise it above the default. */
+	fightTimeoutMs?: number;
 }
 
 /**
@@ -203,6 +236,7 @@ export async function runBundleSimulate(
 ): Promise<SimulateResult>
 {
 	const template = options.matchTemplate ?? await buildMatchTemplate();
+	const fightTimeoutMs = resolveFightTimeout(options.fightTimeoutMs);
 
 	// Freeze before the untrusted bundles run (see runBundleFight).
 	const code = FREEZE_BANNER + '\n' + bundle1
@@ -224,7 +258,7 @@ export async function runBundleSimulate(
 		await jail.set('global', jail.derefInto());
 
 		const script = await isolate.compileScript(code);
-		await script.run(context, {timeout: FIGHT_TIMEOUT_MS});
+		await script.run(context, {timeout: fightTimeoutMs});
 
 		const simulateFn = await jail.get('__simulate');
 		const simOptions = {
@@ -235,7 +269,7 @@ export async function runBundleSimulate(
 		const result = await simulateFn.apply(
 			undefined,
 			[new ivm.ExternalCopy(simOptions).copyInto()],
-			{timeout: FIGHT_TIMEOUT_MS, result: {copy: true}},
+			{timeout: fightTimeoutMs, result: {copy: true}},
 		);
 
 		// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- isolated-vm returns unknown

package/src/engine/sandbox-browser.ts

@@ -23,6 +23,7 @@ import type {GameState, ProjectileState, WizardActions} from '../types.js';
 import type {MissileFunction} from '../hooks/types.js';
 import type {BotError, FightResult, MatchWinner, SimulateResult} from './simulation.js';
 import type {StepResult} from './manual-match.js';
+import {DEFAULT_FIGHT_BACKSTOP_MS} from './bot-compute-budget.js';
 
 // ============================================================
 // WORKER PROTOCOL
@@ -191,7 +192,12 @@ export class BrowserMatchSandbox
 		options?: BrowserSandboxOptions,
 	): Promise<BrowserMatchSandbox>
 	{
-		const timeout = options?.timeoutMs ?? 30000;
+		// Was 30000, which the per-bot compute budget made incoherent: one bot may
+		// legitimately spend 45s before it stops being called, so a 30s cap here would kill
+		// fights the budget considers perfectly fine — and browser workers are slower than
+		// the server besides. Same backstop as every other path. This runs in a Worker, so a
+		// long fight does not freeze the page.
+		const timeout = options?.timeoutMs ?? DEFAULT_FIGHT_BACKSTOP_MS;
 		const code = createWorkerScript(bundle);
 
 		let worker: WorkerLike;

package/src/engine/sandbox-harness.ts

@@ -89,9 +89,14 @@ import {${bot1ExportName} as __Bot1} from '${bot1Path}';
 import {${bot2ExportName} as __Bot2} from '${bot2Path}';
 import {fight, simulate} from '${srcPath}/engine/simulation.ts';
 import {wrapWithParams} from '${srcPath}/engine/params-runtime.ts';
+import {DEFAULT_BUDGET} from '${srcPath}/engine/bot-compute-budget.ts';
 
 globalThis.__fight = function __fight(options) {
-	const result = fight(__Bot1, __Bot2, options);
+	// Budgeted like every other fight path. This one matters MORE than it looks: it is what
+	// sandboxFight uses, so it is the MCP fight tools and the CLI — the place a user's
+	// runaway bot most directly burns server time. Leaving it unbudgeted while the backstop
+	// moved from 60s to 110s would have made this path strictly worse than before.
+	const result = fight(__Bot1, __Bot2, {budgetLimits: DEFAULT_BUDGET, ...options});
 	return result;
 };
 
@@ -99,7 +104,10 @@ globalThis.__simulate = function __simulate(options) {
 	const {params1, params2, ...simOptions} = options;
 	const bot1 = params1 ? wrapWithParams(__Bot1, params1) : __Bot1;
 	const bot2 = params2 ? wrapWithParams(__Bot2, params2) : __Bot2;
-	const result = simulate(bot1, bot2, simOptions);
+	// Budgeted like __fight. This path is trace and the optimizer — a single match rather
+	// than ten — and leaving it out would have made it strictly worse than before, since the
+	// same change raised its backstop from 60s to 110s.
+	const result = simulate(bot1, bot2, {budgetLimits: DEFAULT_BUDGET, ...simOptions});
 	return result;
 };
 `;
@@ -280,10 +288,12 @@ import {${bot1ExportName} as __Bot1} from '${bot1Path}';
 import {${bot2ExportName} as __Bot2} from '${bot2Path}';
 import {fight, simulate} from '${srcPath}/engine/simulation.ts';
 import {wrapWithParams} from '${srcPath}/engine/params-runtime.ts';
+import {DEFAULT_BUDGET} from '${srcPath}/engine/bot-compute-budget.ts';
 
 globalThis.__fightJSON = function __fightJSON(optionsJSON) {
 	const options = JSON.parse(optionsJSON);
-	const result = fight(__Bot1, __Bot2, options);
+	// Budgeted, same as the non-JSON variant — two generators, one contract.
+	const result = fight(__Bot1, __Bot2, {budgetLimits: DEFAULT_BUDGET, ...options});
 	return JSON.stringify(result);
 };
 
@@ -292,7 +302,8 @@ globalThis.__simulateJSON = function __simulateJSON(optionsJSON) {
 	const {params1, params2, ...simOptions} = options;
 	const bot1 = params1 ? wrapWithParams(__Bot1, params1) : __Bot1;
 	const bot2 = params2 ? wrapWithParams(__Bot2, params2) : __Bot2;
-	const result = simulate(bot1, bot2, simOptions);
+	// Budgeted, same as the non-JSON variant — two generators, one contract.
+	const result = simulate(bot1, bot2, {budgetLimits: DEFAULT_BUDGET, ...simOptions});
 	return JSON.stringify(result);
 };
 `;

package/src/engine/sandbox.ts

@@ -20,6 +20,7 @@
 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
@@ -86,7 +87,11 @@ export class MatchSandbox
 	): Promise<MatchSandbox>
 	{
 		const memoryLimitMB = options?.memoryLimitMB ?? 512;
-		const timeoutMs = options?.timeoutMs ?? 60000;
+		// 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);
@@ -133,7 +138,11 @@ export class MatchSandbox
 	): Promise<MatchSandbox>
 	{
 		const memoryLimitMB = options?.memoryLimitMB ?? 512;
-		const timeoutMs = options?.timeoutMs ?? 60000;
+		// 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});
 

package/src/engine/simulation.ts

@@ -30,6 +30,7 @@ import {moveWizard, moveProjectile, sweptCircleCollision, clampToArena, resolveW
 import {applyDamage, updateShield, startCast, completeCast} from './spells.js';
 import {runWithHooks, resetAllHooks, clearHooks} from './hooks-runtime.js';
 import {angleTo, normalizeAngle, angleDiff} from '../utils/angles.js';
+import {createBudgetState, createFightBudget, recordSpend, mayAct, type BotBudgetState, type BudgetLimits, type FightBudget} from './bot-compute-budget.js';
 import {createRandom, createEntitySeed} from '../utils/random.js';
 
 export interface InternalWizardState extends WizardState
@@ -158,12 +159,14 @@ export function tick(
 	projectiles: ProjectileState[],
 	missileAIs: Map<string, MissileFunction>,
 	matchSeed: number,
+	budgets?: {states: [BotBudgetState, BotBudgetState]; limits: BudgetLimits},
 ): {
 	nextTick: number;
 	wizards: InternalWizardState[];
 	projectiles: ProjectileState[];
 	events: SimEvent[];
 	errors: BotError[];
+	budgets?: [BotBudgetState, BotBudgetState];
 }
 {
 	const nextTick = currentTick + 1;
@@ -176,29 +179,68 @@ export function tick(
 	const random2 = createRandom(createEntitySeed(matchSeed, wizards[1]!.id, nextTick));
 
 	// Wrap AI calls in try-catch - if AI throws, wizard does nothing (Lesson #21)
-	let actions1: WizardActions = {move: {x: 0, y: 0}};
-	try
+	const IDLE_ACTION = (): WizardActions => ({move: {x: 0, y: 0}});
+
+	// Budget state is threaded through rather than mutated, so tick() stays as pure as it
+	// was. When no budget is supplied (manual play, most tests) this is all inert and the
+	// clock is never read.
+	const nextBudgets: [BotBudgetState, BotBudgetState] | undefined = budgets
+		? [budgets.states[0], budgets.states[1]]
+		: undefined;
+
+	/**
+	 * Call one bot under its compute budget.
+	 *
+	 * Measuring NEVER changes this tick's action. That is deliberate and load-bearing: this
+	 * engine is deterministic, and an earlier version of this guard discarded the action of
+	 * any call over 50ms, which made outcomes depend on GC pauses and machine load. The only
+	 * thing the budget changes is whether a bot is called AT ALL, and only once it has spent
+	 * its whole fight allowance — which an honest bot never approaches. See
+	 * bot-compute-budget.ts.
+	 *
+	 * Exhaustion is never recorded as an error either. In-sim errors feed consecutiveCrashes
+	 * and auto-deactivate a bot at three; being slow on a busy server must not do that.
+	 */
+	const runBot = (index: 0 | 1, entityId: string, invoke: () => WizardActions): WizardActions =>
+	{
+		const state = nextBudgets?.[index];
+
+		// An exhausted bot is not called at all, so its remaining ticks are free.
+		if (state && !mayAct(state)) return IDLE_ACTION();
+
+		const startedAt = state ? Date.now() : 0;
+		let action: WizardActions;
+		try
+		{
+			action = invoke();
+		}
+		catch(e)
+		{
+			errors.push({tick: nextTick, entityId, message: e instanceof Error ? e.message : String(e)});
+			action = IDLE_ACTION();
+		}
+
+		if (state && budgets)
+		{
+			// A throw is charged too — it still consumed the time.
+			nextBudgets![index] = recordSpend(state, budgets.limits, Date.now() - startedAt);
+		}
+		return action;
+	};
+
+	const actions1 = runBot(0, 'wizard-1', () =>
 	{
 		const stateView1 = getPlayerStateView(0, wizards, projectiles, nextTick);
 		const ctx1: WizardContext = buildWizardContext(stateView1, config, random1);
-		actions1 = runWithHooks(wizards[0]!.id, () => extractAction(withWizardContext(ctx1, wizard1AI))) ?? {move: {x: 0, y: 0}};
-	}
-	catch(e)
-	{
-		errors.push({tick: nextTick, entityId: 'wizard-1', message: e instanceof Error ? e.message : String(e)});
-	}
+		return runWithHooks(wizards[0]!.id, () => extractAction(withWizardContext(ctx1, wizard1AI))) ?? IDLE_ACTION();
+	});
 
-	let actions2: WizardActions = {move: {x: 0, y: 0}};
-	try
+	const actions2 = runBot(1, 'wizard-2', () =>
 	{
 		const stateView2 = getPlayerStateView(1, wizards, projectiles, nextTick);
 		const ctx2: WizardContext = buildWizardContext(stateView2, config, random2);
-		actions2 = runWithHooks(wizards[1]!.id, () => extractAction(withWizardContext(ctx2, wizard2AI))) ?? {move: {x: 0, y: 0}};
-	}
-	catch(e)
-	{
-		errors.push({tick: nextTick, entityId: 'wizard-2', message: e instanceof Error ? e.message : String(e)});
-	}
+		return runWithHooks(wizards[1]!.id, () => extractAction(withWizardContext(ctx2, wizard2AI))) ?? IDLE_ACTION();
+	});
 
 	const actions = [actions1, actions2];
 
@@ -602,6 +644,7 @@ export function tick(
 		projectiles: remainingProjectiles,
 		events,
 		errors,
+		budgets: nextBudgets,
 	};
 }
 
@@ -839,6 +882,11 @@ export function fight(
 	options: {
 		seed?: number;
 		maxTicks?: number;
+		/**
+		 * Per-bot compute budget for the WHOLE fight — all ten matches share it. Omitted
+		 * means unbudgeted. See bot-compute-budget.ts.
+		 */
+		budgetLimits?: BudgetLimits;
 	} = {},
 ): FightResult
 {
@@ -847,6 +895,9 @@ export function fight(
 	let wizard2Wins = 0;
 	let draws = 0;
 
+	// One budget for the fight, not one per match — see FightBudget.
+	const budget = options.budgetLimits ? createFightBudget(options.budgetLimits) : undefined;
+
 	for (const spawnDistance of FIGHT_SPAWN_DISTANCES)
 	{
 		// Normal side: wizard1 on left, wizard2 on right
@@ -854,6 +905,7 @@ export function fight(
 			seed: options.seed,
 			maxTicks: options.maxTicks,
 			spawnDistance,
+			budget,
 		});
 
 		matches.push(result);
@@ -873,13 +925,27 @@ export function fight(
 
 		// Swapped side: wizard2 on left, wizard1 on right
 		// skipHistory: swapped matches are only for scoring, not visual playback
+		//
+		// Budget states are indexed by POSITION, so they must be swapped alongside the bots
+		// or each bot is charged for the other's time — which would let a runaway bot burn
+		// its opponent's budget and get its own back.
+		const swappedBudget = budget
+			? {states: [budget.states[1], budget.states[0]] as [BotBudgetState, BotBudgetState], limits: budget.limits}
+			: undefined;
+
 		const swapped = simulate(wizard2AI, wizard1AI, {
 			seed: options.seed,
 			maxTicks: options.maxTicks,
 			spawnDistance,
 			skipHistory: true,
+			budget: swappedBudget,
 		});
 
+		if (budget && swappedBudget)
+		{
+			budget.states = [swappedBudget.states[1], swappedBudget.states[0]];
+		}
+
 		// Don't push swapped match to matches array (it's only for scoring)
 		if (swapped.winner === 'wizard-1')
 		{
@@ -919,6 +985,19 @@ export function simulate(
 		seed?: number;
 		spawnDistance?: number;
 		skipHistory?: boolean;
+		/**
+		 * Per-bot compute budget for this match alone. Omitted means unbudgeted, which is
+		 * what manual play and most tests want — the clock is then never read at all. See
+		 * bot-compute-budget.ts for why exceeding it costs a bot its action rather than
+		 * producing an error.
+		 */
+		budgetLimits?: BudgetLimits;
+		/**
+		 * A budget SHARED across every match of a fight, updated in place as this match
+		 * runs. This is what `fight()` passes, because a fight is ten matches and a
+		 * per-match budget would bound nothing. Takes precedence over `budgetLimits`.
+		 */
+		budget?: FightBudget;
 	} = {},
 ): SimulateResult
 {
@@ -992,9 +1071,26 @@ export function simulate(
 
 	let deathTick: number | null = null;
 
+	// A shared fight budget wins over per-match limits: a fight is ten matches, and only the
+	// shared one can bound the whole thing.
+	const sharedBudget = options.budget;
+	const budgetLimits = sharedBudget?.limits ?? options.budgetLimits;
+	let budgets: [BotBudgetState, BotBudgetState] | undefined = sharedBudget
+		? sharedBudget.states
+		: (budgetLimits ? [createBudgetState(), createBudgetState()] : undefined);
+
 	while (currentTick < maxTicks)
 	{
-		const result = tick(currentTick, wizard1AI, wizard2AI, config, wizards, projectiles, missileAIs, seed);
+		const result = tick(
+			currentTick, wizard1AI, wizard2AI, config, wizards, projectiles, missileAIs, seed,
+			budgetLimits && budgets ? {states: budgets, limits: budgetLimits} : undefined,
+		);
+		if (result.budgets)
+		{
+			budgets = result.budgets;
+			// Write the spend back so it survives into the fight's remaining matches.
+			if (sharedBudget) sharedBudget.states = result.budgets;
+		}
 		currentTick = result.nextTick;
 		wizards = result.wizards;
 		projectiles = result.projectiles;

package/src/engine-version.ts

@@ -9,4 +9,4 @@
  * Used to gate spectator replays: a recorded match can only be re-simulated when
  * the runtime engine version matches the version that produced the match.
  */
-export const ENGINE_VERSION = 1203306608058186;
+export const ENGINE_VERSION = 1709865010946010;

package/src/index.ts

@@ -2,6 +2,8 @@ export * from './types.js';
 export * from './rules.js';
 export * from './engine-version.js';
 export * from './engine/simulation.js';
+export {DEFAULT_BUDGET, DEFAULT_FIGHT_BACKSTOP_MS, createBudgetState, createFightBudget, recordSpend, mayAct} from './engine/bot-compute-budget.js';
+export type {BudgetLimits, BotBudgetState, FightBudget} from './engine/bot-compute-budget.js';
 export * from './engine/hooks-runtime.js';
 export * from './engine/physics.js';
 export * from './engine/spells.js';