@vibemancer/core 1.0.10 → 1.0.12

package/src/engine/simulation.ts

@@ -32,6 +32,7 @@ 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';
+import {describeThrown, cappedNotice, MAX_ERRORS_PER_MATCH} from './bot-error-capture.js';
 
 export interface InternalWizardState extends WizardState
 {
@@ -159,6 +160,33 @@ function buildWizardContext(state: GameState, config: GameConfig, random: () =>
 /**
  * Process one game tick.
  */
+
+/**
+ * Name the first non-finite number a bot handed the engine this tick, or null.
+ *
+ * Checks the three doors that were each found separately: the move vector, the blink target,
+ * and the aim angle. Returns WHICH field so the message can point at the player's own call
+ * rather than saying "something went wrong".
+ */
+function nonFiniteField(
+	move: {x?: number; y?: number},
+	action: {startCast?: {spell?: string; target?: {x?: number; y?: number}}; aimDirection?: number},
+	wizard: {blinkTarget?: {x?: number; y?: number}},
+): {what: string; value: string} | null
+{
+	const bad = (v: unknown): boolean => typeof v === 'number' && !Number.isFinite(v);
+	if (bad(move?.x)) return {what: 'move(x, y): x', value: String(move.x)};
+	if (bad(move?.y)) return {what: 'move(x, y): y', value: String(move.y)};
+
+	const target = action.startCast?.spell === 'blink' ? action.startCast.target : undefined;
+	if (bad(target?.x)) return {what: 'blink(x, y): x', value: String(target!.x)};
+	if (bad(target?.y)) return {what: 'blink(x, y): y', value: String(target!.y)};
+	if (bad(wizard.blinkTarget?.x)) return {what: 'blink(x, y): x', value: String(wizard.blinkTarget!.x)};
+	if (bad(wizard.blinkTarget?.y)) return {what: 'blink(x, y): y', value: String(wizard.blinkTarget!.y)};
+
+	if (bad(action.aimDirection)) return {what: 'aim(degrees)', value: String(action.aimDirection)};
+	return null;
+}
 export function tick(
 	currentTick: number,
 	wizard1AI: WizardFunction,
@@ -175,11 +203,14 @@ export function tick(
 	projectiles: ProjectileState[];
 	events: SimEvent[];
 	errors: BotError[];
+	budgetExhausted: BudgetExhaustion[];
 	budgets?: [BotBudgetState, BotBudgetState];
 }
 {
 	const nextTick = currentTick + 1;
 	const errors: BotError[] = [];
+	const budgetExhausted: BudgetExhaustion[] = [];
+
 	const events: SimEvent[] = [];
 
 	// 1. Run wizard AIs with isolated random generators
@@ -215,7 +246,17 @@ export function tick(
 		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();
+		if (state && !mayAct(state))
+		{
+			// Reported once, on the tick it is first refused. The bot is skipped for thousands
+			// of ticks afterwards, and thousands of identical records is not a report.
+			if (!state.reported)
+			{
+				state.reported = true;
+				budgetExhausted.push({tick: nextTick, entityId, spentMs: state.spentMs});
+			}
+			return IDLE_ACTION();
+		}
 
 		const startedAt = state ? Date.now() : 0;
 		let action: WizardActions;
@@ -225,7 +266,13 @@ export function tick(
 		}
 		catch(e)
 		{
-			errors.push({tick: nextTick, entityId, message: e instanceof Error ? e.message : String(e)});
+			const alreadyDead = (wizards[index]?.health ?? 1) <= 0;
+			errors.push({
+				tick: nextTick,
+				entityId,
+				message: describeThrown(e),
+				...(alreadyDead ? {afterDeath: true} : {}),
+			});
 			action = IDLE_ACTION();
 		}
 
@@ -356,12 +403,24 @@ export function tick(
 				}
 				else if (spell === 'blink' && wizard.blinkTarget)
 				{
-					// Clamp blink target to RULES.BLINK_RANGE from current position
-					const dx = wizard.blinkTarget.x - wizard.position.x;
-					const dy = wizard.blinkTarget.y - wizard.position.y;
+					// A bot's coordinates are untrusted input, exactly like its move vector.
+					//
+					// blink(NaN, NaN) used to make the wizard's position NaN — isInLava reads
+					// that as false so nobody dies, and resolveWizardCollision then divided by
+					// a NaN distance and wrote NaN into the OPPONENT's position too. Both
+					// wizards froze and every match was a silent draw. calculateBlinkCooldown
+					// went NaN with it, and `NaN > 0` is false, so the cooldown gate stopped
+					// working as well.
+					//
+					// moveWizard was hardened for this and blink was not, so the same one-line
+					// exploit just moved to the other door. A non-finite target blinks NOWHERE.
+					const targetX = Number.isFinite(wizard.blinkTarget.x) ? wizard.blinkTarget.x : wizard.position.x;
+					const targetY = Number.isFinite(wizard.blinkTarget.y) ? wizard.blinkTarget.y : wizard.position.y;
+					const dx = targetX - wizard.position.x;
+					const dy = targetY - wizard.position.y;
 					const distance = Math.sqrt(dx * dx + dy * dy);
 
-					let targetPos = wizard.blinkTarget;
+					let targetPos = {x: targetX, y: targetY};
 					if (distance > RULES.BLINK_RANGE)
 					{
 						// Clamp to max range in the same direction
@@ -398,6 +457,35 @@ export function tick(
 		// Handle movement (default to no movement if bot didn't provide move)
 		const oldPos = wizard.position;
 		const move = action.move ?? {x: 0, y: 0};
+
+		// The non-finite guards work, and were completely silent. A bot that divides by zero
+		// somewhere just stops moving; the guard saves the match but tells the author nothing,
+		// which is the same "looks passive, is broken" failure as an unreported throw — and
+		// reached by accident rather than by anything hostile.
+		//
+		// Reporting deliberately does NOT change behaviour: the clamp still stands and the
+		// match plays out identically. Throwing instead would alter results for bots already
+		// on the ladder and could feed crash-deactivation, which is far too large a
+		// consequence to attach to a diagnostic.
+		// The flag lives on the WIZARD, not in a Set here: tick() runs afresh every frame, so a
+		// Set declared inside it deduped nothing and the first version of this reported the
+		// same paragraph 500 times, straight into the error cap.
+		if (!wizard.advised?.nonFinite)
+		{
+			const bad = nonFiniteField(move, action, wizard);
+			if (bad)
+			{
+				wizard.advised = {...wizard.advised, nonFinite: true};
+				errors.push({
+					tick: nextTick,
+					entityId: wizard.id,
+					message: `${bad.what} is not a finite number (it was ${bad.value}). The engine ignored it `
+						+ 'to keep the match running — the value is treated as zero, so your wizard simply does '
+						+ 'not do what you asked. This is almost always a divide-by-zero or a subtraction of '
+						+ 'two equal positions somewhere in your maths. Reported once per match.',
+				});
+			}
+		}
 		wizard.position = moveWizard(wizard, move, 1);
 
 		// Process delayed knockback (apply impulse after delay expires)
@@ -468,6 +556,32 @@ export function tick(
 				startCast(wizard, castingSpell, castingSpell === 'missile' ? action.startCast.config : undefined);
 				if (castingSpell === 'missile')
 				{
+					// A cast longer than the whole match can never complete, so the wizard
+					// stands still until time runs out and NOTHING is reported. Every field is
+					// clamped by validateMissileConfig — nothing here is NaN — but turnRate is
+					// clamped only to `>= 0`, and turnRate 9999 prices the cast at 130,017
+					// ticks against a 30,000-tick match. Measured against TargetDummy, a bot
+					// that does nothing at all, the result was ten draws: the bot could not
+					// even lose in a way that hinted at the cause.
+					//
+					// The cast is still allowed — refusing it would silently change what bots
+					// do, and the defect was never the cast, it was the silence.
+					if ((wizard.castDuration ?? 0) > MATCH_DURATION && !wizard.advised?.unfinishableCast)
+					{
+						wizard.advised = {...wizard.advised, unfinishableCast: true};
+						const config = action.startCast.config;
+						errors.push({
+							tick: nextTick,
+							entityId: wizard.id,
+							message: `This missile takes ${wizard.castDuration} ticks to cast, but a match `
+								+ `is only ${MATCH_DURATION} ticks long, so the cast can never finish and this `
+								+ 'wizard will stand still for the rest of the match. The cost is dominated by '
+								+ `turnRate (${config?.turnRate ?? '?'}) — it is the most expensive field by far, and `
+								+ 'unlike the others it is not clamped to a sane maximum. Try a turnRate in the '
+								+ 'single digits, then use missile-calc or getMissileCastTime() to check the cast '
+								+ 'time before committing to a config.',
+						});
+					}
 					wizard.missileConfig = action.startCast.config;
 					wizard.missileAI = action.startCast.missileAI;
 					if (action.startCast.direction !== undefined)
@@ -558,7 +672,7 @@ export function tick(
 				}
 				catch(e)
 				{
-					errors.push({tick: nextTick, entityId: projectile.id, message: e instanceof Error ? e.message : String(e)});
+					errors.push({tick: nextTick, entityId: projectile.id, message: describeThrown(e)});
 				}
 
 				targetAngle = missileActions.turnToward
@@ -569,7 +683,13 @@ export function tick(
 			}
 		} // end else (not guided)
 
-		if (targetAngle !== null)
+		// A missile AI's steering is untrusted input too. `turnToward(NaN, NaN)` sent a NaN
+		// angle into angleDiff, so the projectile's rotation and position went NaN and it
+		// could never hit anything — and nothing was reported, because returning nonsense is
+		// not throwing. A bot doing this LOST silently; the same bot throwing got a full
+		// report. Ignoring the instruction means the missile flies straight, which is what a
+		// missile with no steering does.
+		if (targetAngle !== null && Number.isFinite(targetAngle))
 		{
 			const diff = angleDiff(projectile.rotation, targetAngle);
 			const turn = Math.max(-projectile.turnRate, Math.min(projectile.turnRate, diff));
@@ -668,6 +788,7 @@ export function tick(
 		projectiles: remainingProjectiles,
 		events,
 		errors,
+		budgetExhausted,
 		budgets: nextBudgets,
 	};
 }
@@ -851,11 +972,44 @@ export type FightWinner = 'wizard-1' | 'wizard-2' | 'draw';
  * Result of a simulation.
  */
 /** A runtime error captured from a bot or missile AI function. */
+/**
+ * A bot that ran out of its compute budget and stopped being called.
+ *
+ * Deliberately NOT a BotError. Errors feed `consecutiveCrashes` on the ladder and
+ * auto-deactivate a wizard at three; being slow on a loaded server must never cost someone
+ * their bot. But it was recorded NOWHERE, so a bot that burned its allowance stood still for
+ * the rest of the fight and reported a clean scoreline — measured, a certain 10-0 became 1
+ * win and 9 draws with nothing saying why.
+ */
+export interface BudgetExhaustion
+{
+	entityId: string;
+	/** The tick the bot was first refused. */
+	tick: number;
+	/** How much it had spent when it was cut off, in milliseconds. */
+	spentMs: number;
+	/** 1-based match index within a fight; set by `fight()`, absent from a lone simulate(). */
+	match?: number;
+}
+
 export interface BotError
 {
 	tick: number;
 	entityId: string;
 	message: string;
+	/**
+	 * True when the wizard was ALREADY DEAD on the tick this was thrown.
+	 *
+	 * The engine keeps calling a bot after its health reaches zero and discards the action, so
+	 * these errors change nothing. Unmarked they are actively misleading in two ways: a player
+	 * sees a fault spanning hundreds of ticks with no hint the wizard was dead for all of
+	 * them, and the ladder counts them toward consecutiveCrashes — so a bot can be
+	 * auto-deactivated for errors the guide itself calls harmless.
+	 *
+	 * The engine is the only place that knows, so it is recorded here rather than guessed
+	 * downstream from a reconstructed death tick.
+	 */
+	afterDeath?: boolean;
 	/**
 	 * 1-based index within the fight's TEN matches, present only on `FightResult.allErrors`.
 	 *
@@ -876,6 +1030,15 @@ export interface SimulateResult
 	history: GameState[];
 	/** Runtime errors thrown by bot or missile AI functions (empty if no errors). */
 	errors: BotError[];
+	/**
+	 * Bots that ran out of compute and stopped being called (empty if nobody did).
+	 *
+	 * Separate from `errors` on purpose: errors feed consecutiveCrashes and deactivate a
+	 * wizard at three, and being slow must never do that. But it has to be reported SOMEWHERE
+	 * — a bot cut off in match 1 stands still for the rest of the fight, and without this the
+	 * player sees a clean scoreline and rewrites a strategy that was never the problem.
+	 */
+	budgetExhausted: BudgetExhaustion[];
 }
 
 /**
@@ -906,6 +1069,14 @@ export interface FightResult
 	 * raw would blame each side's faults on the other.
 	 */
 	allErrors: BotError[];
+	/**
+	 * Bots cut off by the compute budget, across all ten matches.
+	 *
+	 * The budget is FIGHT-scoped, so this is where it belongs: exhausting it in match 1
+	 * freezes the bot for the other nine. Ids are in the caller's frame, mirrored out of the
+	 * swapped matches like allErrors.
+	 */
+	budgetExhausted: BudgetExhaustion[];
 }
 
 /**
@@ -956,6 +1127,7 @@ export function fight(
 {
 	const matches: SimulateResult[] = [];
 	const allErrors: BotError[] = [];
+	const allBudgetExhausted: BudgetExhaustion[] = [];
 	// 1..10 in the order matches are played, so the number a player is shown is the number
 	// every tool description promises.
 	let matchNumber = 1;
@@ -978,6 +1150,7 @@ export function fight(
 
 		matches.push(result);
 		allErrors.push(...result.errors.map((e) => ({...e, match: matchNumber})));
+		allBudgetExhausted.push(...result.budgetExhausted.map((b) => ({...b, match: matchNumber})));
 		matchNumber++;
 
 		if (result.winner === 'wizard-1')
@@ -1021,6 +1194,7 @@ export function fight(
 		// into the caller's frame first: this match ran bot 2 as "wizard-1", so passing the
 		// records through raw would report each bot's faults against the other.
 		allErrors.push(...swapped.errors.map((e) => ({...e, entityId: swapSide(e.entityId), match: matchNumber})));
+		allBudgetExhausted.push(...swapped.budgetExhausted.map((b) => ({...b, entityId: swapSide(b.entityId), match: matchNumber})));
 		matchNumber++;
 
 		// Don't push swapped match to matches array (it's only for scoring)
@@ -1043,7 +1217,7 @@ export function fight(
 		: wizard2Wins > wizard1Wins ? 'wizard-2'
 			: 'draw';
 
-	return {wizard1Wins, wizard2Wins, draws, winner, matches, allErrors};
+	return {wizard1Wins, wizard2Wins, draws, winner, matches, allErrors, budgetExhausted: allBudgetExhausted};
 }
 
 /**
@@ -1145,6 +1319,7 @@ export function simulate(
 	let projectiles: ProjectileState[] = [];
 	const missileAIs = new Map<string, MissileFunction>();
 	const allErrors: BotError[] = [];
+	const allBudgetExhausted: BudgetExhaustion[] = [];
 
 	let deathTick: number | null = null;
 
@@ -1171,7 +1346,23 @@ export function simulate(
 		currentTick = result.nextTick;
 		wizards = result.wizards;
 		projectiles = result.projectiles;
-		if (result.errors.length > 0) allErrors.push(...result.errors);
+		// Bounded on purpose. This array lives for the whole match, so leaving it unbounded
+		// lets a bot choose how much memory the engine allocates — and a ~2KB message thrown
+		// every tick genuinely exhausts the isolate, after which the failure surfaces as an
+		// infrastructure fault and, on the ladder, is blamed on nobody or on the opponent.
+		for (const error of result.errors)
+		{
+			if (allErrors.length > MAX_ERRORS_PER_MATCH) break;
+			if (allErrors.length === MAX_ERRORS_PER_MATCH)
+			{
+				// Announce the cap; going quiet here would recreate the silent failure that
+				// surfacing bot errors existed to fix.
+				allErrors.push(cappedNotice(error.entityId, error.tick));
+				break;
+			}
+			allErrors.push(error);
+		}
+		if (result.budgetExhausted.length > 0) allBudgetExhausted.push(...result.budgetExhausted);
 
 		if (!skipHistory)
 		{
@@ -1216,5 +1407,6 @@ export function simulate(
 		finalState,
 		history: skipHistory ? [] : history,
 		errors: allErrors,
+		budgetExhausted: allBudgetExhausted,
 	};
 }

package/src/engine/spells.ts

@@ -4,6 +4,7 @@ import {
 	TICKS_PER_SECOND,
 	calculateMissileCastTime,
 	calculateWarmupMultiplier,
+	validateMissileConfig,
 } from '../rules.js';
 
 /**
@@ -19,8 +20,19 @@ export function startCast(wizard: WizardState, spell: 'missile' | 'shield' | 'bl
 	// Stryker disable next-line ConditionalExpression: `true && config` equivalent for valid calls (spell is always correct type)
 	if (spell === 'missile' && config)
 	{
+		// VALIDATE FIRST. This used to pass the raw config, and the raw formula returns NaN for
+		// a config a beginner can easily type — `{damage: -999, speed: 0, duration: -5}` —
+		// because of the powers and divisions inside it. `Math.max(1, Math.round(NaN))` is NaN,
+		// not 1, so castDuration became NaN and `castProgress >= castDuration` was never true:
+		// the cast could NEVER complete and the wizard stood still for the whole match, silently.
+		// Measured against TargetDummy, a bot that does nothing: ten draws, zero errors.
+		//
+		// getMissileCastTime — the function bots call to PREDICT this exact number — has always
+		// validated first, so the engine and its own prediction disagreed for precisely the
+		// configs where a player most needed them to agree.
+		const validated = validateMissileConfig(config);
 		// calculateMissileCastTime includes warmup when lastMissileConfig is passed
-		const castTimeSec = calculateMissileCastTime(config, wizard.lastMissileConfig);
+		const castTimeSec = calculateMissileCastTime(validated, wizard.lastMissileConfig);
 		wizard.castDuration = Math.max(1, Math.round(castTimeSec * TICKS_PER_SECOND));
 		// Store warmup multiplier for visualization
 		wizard.warmupMultiplier = calculateWarmupMultiplier(wizard.lastMissileConfig, config);

package/src/engine-version.ts

@@ -9,7 +9,7 @@
  * 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 = 293192982913104;
+export const ENGINE_VERSION = 4256327861353618;
 
 /**
  * Historical versions that denote the SAME engine as `ENGINE_VERSION`.

package/src/hooks/action-builders.ts

@@ -90,7 +90,7 @@ export function shield(): ActionBuilder
  * Cast a missile spell.
  *
  * Cast time scales with damage, speed, duration, and turn rate — bigger missiles
- * take longer to cast. While casting you move at 50% speed. After firing, 100-tick
+ * take longer to cast. While casting you move at 33% speed. After firing, 100-tick
  * (1s) GCD before next spell.
  *
  * Repeated similar missiles cast 20% faster (warmup bonus). Switching styles
@@ -158,13 +158,16 @@ export function aim(degrees: number): ActionBuilder
  *
  * Max range: 300 units from current position (clamped by engine if further).
  * Cast time: 10 ticks (0.1s). Cooldown scales with distance:
- *   - 100 units → 100 ticks (1s)
+ *   - 10 units → 100 ticks (1s); 100 units → 667 ticks; 150 → 1000 (10s); 300 → 2000 (20s).
+ *     The cooldown scales with DISTANCE — a micro-blink costs a second, a full-range one
+ *     costs twenty. This line used to claim 100 units → 100 ticks, understating it 6.7x.
  *   - 300 units → 2000 ticks (20s)
  *
  * Cannot chain .move() — blink IS the movement.
  *
- * @param x - Target X position (0-800, absolute world coordinate)
- * @param y - Target Y position (0-800, absolute world coordinate)
+ * @param x - Target X position (absolute world coordinate; arena is 0-860, and the
+ *            survivable playfield is [30, 830] — outside that band is lava)
+ * @param y - Target Y position (absolute world coordinate; see x)
  *
  * @example
  *   return blink(400, 400);                              // blink to center
@@ -276,12 +279,47 @@ export function flyStraight(): MissileAction
 	};
 }
 
+/**
+ * Name what a bot handed back, for an error message it can act on.
+ *
+ * Named specifically rather than by bare typeof: "a object" is both ungrammatical and
+ * unhelpful, and the realistic version of this mistake is `async function MyBot()`, where the
+ * value is a Promise and the fix is to remove the `async`.
+ */
+function describeReturned(value: unknown): string
+{
+	if (value === null) return 'null';
+	if (value === undefined) return 'undefined';
+	if (Array.isArray(value)) return 'an array';
+	if (typeof value === 'object')
+	{
+		if ('then' in value && typeof (value as {then?: unknown}).then === 'function')
+		{
+			return 'a Promise — your function is `async`, and it must not be: remove the async keyword';
+		}
+		return 'a plain object';
+	}
+	return `a ${typeof value}`;
+}
+
 /**
  * Extract MissileActions from a MissileAction.
  * Used by the engine to get the actual missile action.
  */
 export function extractMissileAction(action: MissileAction): MissileActions
 {
+	// The wizard-level path got a readable message for a bad return; this one did not, and a
+	// missile AI is the SECOND function a player writes. Returning `{}` from it produced
+	// "TypeError: action._toMissileAction is not a function" over an engine-internal stack —
+	// naming a private field that appears nowhere in the API, 84 times in one match.
+	if (action === null || action === undefined || typeof action._toMissileAction !== 'function')
+	{
+		throw new Error(
+			`Your missile AI returned ${describeReturned(action)}. Return turnToward(x, y), `
+			+ 'turnToAngle(degrees) or flyStraight(). The missile AI runs once per tick for every '
+			+ 'missile you have in flight, and it must return one of those every time.',
+		);
+	}
 	return action._toMissileAction();
 }
 
@@ -295,5 +333,94 @@ export function extractMissileAction(action: MissileAction): MissileActions
  */
 export function extractAction(finalAction: FinalAction): WizardActions
 {
-	return finalAction._toAction();
+	// Checked rather than assumed, because the failure message is what a player debugs from.
+	//
+	// This used to be a bare `finalAction._toAction()`, so returning undefined gave "Cannot
+	// read properties of undefined (reading '_toAction')" and returning a plain object gave
+	// "finalAction._toAction is not a function". `_toAction` is internal and appears nowhere
+	// in the player-facing API, so the message named the one thing they cannot look up.
+	//
+	// Returning `{move: {x: 1, y: 0}}` is the most common version of this mistake — it is
+	// exactly the shape of WizardActions — which made the likeliest error the least useful.
+	if (finalAction === null || finalAction === undefined || typeof finalAction._toAction !== 'function')
+	{
+		// Named specifically rather than by bare typeof: "a object" is both ungrammatical and
+		// unhelpful, and the realistic version of this mistake is `async function MyBot()`,
+		// where the value is a Promise and the fix is to remove the `async`.
+		const got = describeReturned(finalAction);
+		throw new Error(
+			`Your bot returned ${got}. Return one of: idle(), move(x, y), missile(config, ai, angle), `
+			+ 'shield(), blink(x, y), cancel() or aim(degrees). '
+			+ 'A bot must return an action every tick — returning nothing throws, it does not skip the tick.',
+		);
+	}
+	// Read every number the engine will later use, HERE — inside the bot's own try/catch.
+	//
+	// A bot can hand back an object with a throwing `valueOf`, and the engine reads those
+	// coordinates later, outside runBot's try/catch: `wizard.blinkTarget.x - position.x` at
+	// blink completion. The throw then escaped tick -> simulate -> fight and surfaced as a
+	// bare fight failure with NO bot named. Two things followed, both serious:
+	//
+	//   - the ladder blamed whichever wizard happened to be PICKED, giving an innocent bot a
+	//     loss, a lastError and a crash strike toward deactivation;
+	//   - the message was forgeable. `throw new Error('Script execution timed out')` from a
+	//     valueOf never passes through the harness, so it matched the INFRASTRUCTURE markers
+	//     and the ladder SKIPPED the match — an unlosable bot — while the fight tool printed a
+	//     confident explanation about infinite loops for a bot containing no loop.
+	//
+	// Forcing the conversion now means a hostile valueOf throws where every other bot fault
+	// throws: inside the try, attributed to the bot that wrote it.
+	const action = finalAction._toAction();
+
+	// The shape was checked and the RESULT was trusted. `{_toAction: () => 'junk'}` therefore
+	// passed straight through: ten draws, zero errors, nothing reported — the same silent
+	// failure this area exists to remove, one level further in. An action without a `move` is
+	// not an action, whatever produced it.
+	if (action === null || typeof action !== 'object' || typeof (action as WizardActions).move !== 'object'
+		|| (action as WizardActions).move === null)
+	{
+		throw new Error(
+			'Your bot returned something that is not a valid action. Build actions with the provided '
+			+ 'functions — idle(), move(x, y), missile(config, ai, angle), shield(), blink(x, y), '
+			+ 'cancel() or aim(degrees) — rather than constructing the object yourself.',
+		);
+	}
+
+	return normaliseActionNumbers(action);
+}
+
+/**
+ * Coerce an action's numeric fields eagerly, so lazy getters cannot fire inside the engine.
+ *
+ * Deliberately NOT a validation pass — invalid values are still handled where they always
+ * were (moveWizard, the blink guard, validateMissileConfig). This only decides WHEN the
+ * numbers are read, and therefore who gets blamed when reading one throws.
+ */
+function normaliseActionNumbers(action: WizardActions): WizardActions
+{
+	const num = (value: unknown): number => Number(value);
+
+	const normalised: WizardActions = {
+		...action,
+		move: {x: num(action.move?.x), y: num(action.move?.y)},
+	};
+
+	if (action.aimDirection !== undefined) normalised.aimDirection = num(action.aimDirection);
+
+	if (action.startCast?.spell === 'missile')
+	{
+		normalised.startCast = {
+			...action.startCast,
+			...(action.startCast.direction !== undefined ? {direction: num(action.startCast.direction)} : {}),
+		};
+	}
+	else if (action.startCast?.spell === 'blink')
+	{
+		normalised.startCast = {
+			...action.startCast,
+			target: {x: num(action.startCast.target?.x), y: num(action.startCast.target?.y)},
+		};
+	}
+
+	return normalised;
 }