@vibemancer/core 1.0.3 → 1.0.5

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,6 +19,7 @@ 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;
@@ -32,7 +33,7 @@ const MEMORY_LIMIT_MB = 256;
  * 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 = 60_000;
+export const DEFAULT_FIGHT_TIMEOUT_MS = DEFAULT_FIGHT_BACKSTOP_MS;
 
 /**
  * Resolve the effective fight timeout.
@@ -96,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;
@@ -104,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});
 };
 `;
 

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 = 4221126750888319;
+export const ENGINE_VERSION = 4396905295552957;

package/src/hooks/action-builders.ts

@@ -4,9 +4,10 @@
  * Fluent API for constructing bot actions with type-safe chaining.
  *
  * UNITS REFERENCE (100 ticks = 1 second):
- *   Position:   absolute world coordinates, 0-800 on each axis (800×800 arena)
+ *   Position:   absolute world coordinates, 0-860 on each axis (860×860 arena, of which
+ *               the outer 30 units on every side are lethal lava — playfield is [30, 830])
  *   Movement:   direction vector, magnitude clamped to max 1 (speed in [0, 1])
- *   Speed:      units per tick (player moves at 1 unit/tick = 100 units/sec)
+ *   Speed:      units per tick (player moves at 1.5 units/tick = 150 units/sec)
  *   Duration:   ticks (divide by 100 for seconds)
  *   Angles:     degrees (0°=right, 90°=down, 180°=left, 270°=up)
  *   Damage:     raw HP removed on hit (wizard has 60 HP)

package/src/hooks/state-hooks.ts

@@ -5,7 +5,8 @@
  * These handle the "subconscious" perception that humans do instinctively.
  *
  * UNITS REFERENCE (100 ticks = 1 second):
- *   Position:   absolute world coordinates, 0-800 on each axis (800×800 arena)
+ *   Position:   absolute world coordinates, 0-860 on each axis. The arena is 860x860,
+ *               but only [30, 830] is safe — the outer 30 units are lethal lava.
  *   Velocity:   units per tick on each axis (player max speed = 1 u/t)
  *   Health:     hit points (max 60)
  *   Ticks:      game ticks (10ms each, 100/sec). Divide by 100 for seconds.
@@ -41,8 +42,15 @@ export function useHealth(): number
 }
 
 /**
- * Get your current position as {x, y} in world coordinates (0-800).
- * Position is clamped to [5, 795] (arena bounds minus wizard radius).
+ * Get your current position as {x, y} in world coordinates (0-860).
+ *
+ * Clamped to [5, 855] — the ARENA bounds minus the wizard radius, NOT the playfield. That
+ * distinction is the difference between living and dying: the playfield is [30, 830] and
+ * everything outside it is lava, so you can walk straight out of the safe area and be
+ * killed. Nothing stops you. Check against ARENA_MIN/ARENA_MAX, not against these numbers.
+ *
+ * (This previously quoted the playfield-sized bounds as the clamp, which told the reader
+ * they were safely fenced in. They are not — see docs-match-engine.test.ts.)
  */
 export function usePosition(): Position
 {
@@ -298,8 +306,11 @@ export function useLastHitTick(): number
 // ============================================================
 
 /**
- * Get arena dimensions. Default: {width: 800, height: 800}.
- * Wizards are clamped to [5, 795] on each axis (radius = 5).
+ * Get arena dimensions. Default: {width: 860, height: 860} — the FULL arena, lava included.
+ * The safe playfield is [30, 830]; the outer 30 units on every side are lethal.
+ *
+ * Wizards are clamped to [5, 855] (arena bounds minus the radius of 5), which does not keep
+ * them out of the lava.
  */
 export function useArenaSize(): {width: number; height: number}
 {

package/src/hooks/types.ts

@@ -4,7 +4,8 @@
  * Types for the hooks-based bot API.
  *
  * UNITS REFERENCE (100 ticks = 1 second):
- *   Position:   absolute world coordinates, 0-800 on each axis (800×800 arena)
+ *   Position:   absolute world coordinates, 0-860 on each axis. The arena is 860x860,
+ *               but only [30, 830] is safe — the outer 30 units are lethal lava.
  *   Velocity:   units per tick on each axis (player max speed = 1 u/t)
  *   Health:     hit points (max 60)
  *   Ticks:      game ticks (10ms each, 100/sec). Divide by 100 for seconds.

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';