@vibemancer/core 1.0.5 → 1.0.7

package/src/index.ts

@@ -1,6 +1,7 @@
 export * from './types.js';
 export * from './rules.js';
 export * from './engine-version.js';
+export * from './replay-compat.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';

package/src/replay-compat.ts

@@ -0,0 +1,35 @@
+/**
+ * Whether a stored match can still be replayed by the running engine.
+ *
+ * Spectate re-simulates a recorded match from its seed, so it may only do that when the
+ * engine is the one that produced it. The check used to be `match.engineVersion ===
+ * ENGINE_VERSION`, which is right in spirit and slightly too strict in fact.
+ *
+ * ENGINE_VERSION is a CONTENT HASH, so it answers "is this the same source?" rather than
+ * "is this the same behaviour?". Those come apart when the hashing itself is corrected. On
+ * 2026-09-09 the comment stripper was fixed — it had been hashing most comments as if they
+ * were code — and the value moved from 1688330189011034 to 3884810833238487 without
+ * packages/core/src changing by a byte. Under an exact comparison that would have stranded
+ * 26,948 of the 42,896 stored matches, 63% of them, for no reason a player could act on.
+ *
+ * So the gate consults a short list of historical values known to describe the same engine.
+ * See scripts/engine-version-equivalents.json for what may go in it, and for why a wrong
+ * entry is the dangerous kind of wrong: it fails OPEN.
+ */
+
+import {ENGINE_VERSION, EQUIVALENT_ENGINE_VERSIONS} from './engine-version.js';
+
+/**
+ * @param matchEngineVersion the `engineVersion` field as read from a stored match.
+ *   Deliberately typed to admit the junk a database can hand back: a document written
+ *   before the field existed returns undefined, and a missing version is never a match.
+ */
+export function canReplayMatch(matchEngineVersion: number | null | undefined): boolean
+{
+	if (typeof matchEngineVersion !== 'number') return false;
+	// NaN would fail `===` against everything, so an exact gate happened to reject it. Being
+	// explicit keeps that true now that the comparison is a lookup.
+	if (!Number.isSafeInteger(matchEngineVersion)) return false;
+	if (matchEngineVersion === ENGINE_VERSION) return true;
+	return EQUIVALENT_ENGINE_VERSIONS.includes(matchEngineVersion);
+}

package/src/utils/spatial.ts

@@ -43,8 +43,20 @@ export function directionAway(from: Position, to: Position): Position
 }
 
 /**
- * Clamp a position to valid arena bounds.
- * Note: For wizard-specific clamping with radius, use clampToArena from physics.ts
+ * Clamp a position into the arena rectangle — [0, ARENA_SIZE] on both axes.
+ *
+ * READ THIS BEFORE USING IT FOR SAFETY. It does NOT keep a wizard alive. The arena includes
+ * the 30-unit lava border, so clamping to it can hand you back a coordinate that is deep
+ * inside the lava — for example (0, 0), which is lethal. It used to be documented as
+ * clamping to "valid arena bounds", which reads like exactly the safety helper it is not:
+ * a player sanitising a blink target with this will blink into the fire.
+ *
+ * To stay ALIVE you want the safe box for a wizard's CENTRE, which is
+ * [ARENA_MIN + WIZARD_RADIUS, ARENA_MAX - WIZARD_RADIUS] — currently [35, 825], because
+ * `isInLava` tests your edge rather than your centre.
+ *
+ * For the engine's own wizard clamp (arena bounds minus the radius, still not lava-safe),
+ * see clampToArena in physics.ts.
  */
 export function clampPositionToArena(position: Position): Position
 {