@series-inc/rundot-kinetix 0.0.0-bootstrap.0

package/src/kinetix-fixed1000-runtime.mjs

@@ -0,0 +1,954 @@
+import { sha256Hex } from './shared/sha256.mjs';
+
+export { sha256Hex } from './shared/sha256.mjs';
+
+// Browser-safe sim core for the deterministic fixed-point component runtime
+// (pack profile "fixed-1000"). Generic, parameterized component families —
+// every constant comes from the data pack, no game-specific literals live
+// here. The families:
+//
+//   FixedTurnsMath      — scale-N integer math + turns-based polynomial trig
+//   GridCellCodec       — 3-byte base64url grid-cell decode
+//   GridTrackCollider   — grid cells → static wall boxes (straight sides,
+//                         corner arc segments, pass-through cells skipped)
+//   ArenaBounds         — bounded square free-roam arena (4 static walls)
+//   ArcadeDriftVehicle  — heading/speed/velocity traction model (velocity
+//                         lags heading above the slip speed = drift)
+//   WaypointRingDriver  — pure-pursuit bot over a CCW-sorted cell-centre ring
+//   LapProgress         — checkpoint bitmask + forward line-crossing detector
+//                         with anti-farming reset and finish/DNF frames
+//   GridSpawn           — 2-wide staggered start grid behind the finish line
+//   ScatterSpawn        — spread grid inside the arena
+//   MatchPhaseMachine   — frame-counted lobby/countdown/active/finished loop
+//   BotSlotResolution   — null input packet → bot, present packet → human
+//   PhysicsWriteback    — transient physics world per tick (statics + dynamic
+//                         spheres), one cold solve, positions-only rounded
+//                         readback
+//
+// Numeric contract: plain JS numbers holding integers only; Math.round /
+// Math.trunc / Math.floor on integer-valued expressions; zero RNG, zero
+// clock, zero transcendentals (trig is an integer polynomial in turns).
+//
+// The physics solver is injected (options.createPhysicsWorld /
+// options.stepPhysicsWorld) so this module stays dependency-free; the caller
+// wires in the deterministic 3D physics slice.
+//
+// Canonical hash layout (canonicalFixedTickHash / canonicalFixedStateBytes):
+//   u64le frame
+//   str   track            (u32le byte length + utf8 bytes)
+//   i64le phase, phaseStartFrame, lobbyDeadlineFrame
+//   field-major per-slot arrays, in state order:
+//     carX, carZ, carVX, carVZ, speed, yawTurns  (i64le each element)
+//     drifting                                    (u8 each element)
+//     lap, cellsVisited, lapProj, finishFrame     (i64le each element)
+//     isBot                                       (u8 each element)
+//   tickHash = sha256(buffer) hex.
+
+// ─── FixedTurnsMath ──────────────────────────────────────────────────────────
+
+export function createFixedTurnsMath(scale) {
+  const ONE = scale;
+  const mul = (a, b) => Math.trunc((a * b) / ONE);
+  const div = (a, b) => (b === 0 ? 0 : Math.trunc((a * ONE) / b));
+  const clamp = (v, min, max) => (v < min ? min : v > max ? max : v);
+  const fabs = (v) => (v < 0 ? -v : v);
+  const fsign = (v) => (v > 0 ? 1 : v < 0 ? -1 : 0);
+  const lerp = (a, b, t) => a + mul(b - a, t);
+
+  // 5th-order odd minimax fit of sin over the first quarter turn, evaluated in
+  // fixed point. Angles are in TURNS (one revolution == ONE).
+  function sinQuarter(x) {
+    const u = div(x, ONE / 4);
+    const u2 = mul(u, u);
+    const u3 = mul(u2, u);
+    const u5 = mul(u3, u2);
+    const a1 = 1571;
+    const a3 = -646;
+    const a5 = 80;
+    return mul(a1, u) + mul(a3, u3) + mul(a5, u5);
+  }
+
+  function fsin(turns) {
+    const t = ((turns % ONE) + ONE) % ONE;
+    if (t < ONE / 4) return clamp(sinQuarter(t), -ONE, ONE);
+    if (t < ONE / 2) return clamp(sinQuarter(ONE / 2 - t), -ONE, ONE);
+    if (t < (3 * ONE) / 4) return clamp(-sinQuarter(t - ONE / 2), -ONE, ONE);
+    return clamp(-sinQuarter(ONE - t), -ONE, ONE);
+  }
+
+  const fcos = (turns) => fsin(turns + ONE / 4);
+  const F = (value) => Math.round(value * ONE);
+
+  return { ONE, F, mul, div, clamp, fabs, fsign, lerp, fsin, fcos };
+}
+
+// ─── GridCellCodec (3-byte base64url) ────────────────────────────────────────
+
+const B64URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_';
+const B64URL_LOOKUP = (() => {
+  const table = new Int16Array(128).fill(-1);
+  for (let i = 0; i < B64URL_ALPHABET.length; i += 1) table[B64URL_ALPHABET.charCodeAt(i)] = i;
+  return table;
+})();
+
+function base64urlToBytes(str) {
+  const clean = str.replace(/=+$/, '');
+  const byteLength = Math.floor((clean.length * 6) / 8);
+  const bytes = new Uint8Array(byteLength);
+  let bits = 0;
+  let bitCount = 0;
+  let out = 0;
+  for (let i = 0; i < clean.length; i += 1) {
+    const value = B64URL_LOOKUP[clean.charCodeAt(i)];
+    if (value === undefined || value < 0) {
+      throw new Error(`base64urlToBytes: invalid character '${clean[i]}' at index ${i}`);
+    }
+    bits = (bits << 6) | value;
+    bitCount += 6;
+    if (bitCount >= 8) {
+      bitCount -= 8;
+      bytes[out++] = (bits >> bitCount) & 0xff;
+    }
+  }
+  return bytes;
+}
+
+export function decodeGridCells(encoded) {
+  if (encoded === '') return [];
+  const bytes = base64urlToBytes(encoded);
+  const cells = [];
+  for (let i = 0; i + 2 < bytes.length; i += 3) {
+    const gridX = bytes[i] - 128;
+    const gridZ = bytes[i + 1] - 128;
+    const packed = bytes[i + 2];
+    const typeId = (packed >> 2) & 0x3f;
+    const orientation = packed & 0x03;
+    cells.push({ gridX, gridZ, typeId, orientation });
+  }
+  return cells;
+}
+
+// ─── Shared grid helpers ─────────────────────────────────────────────────────
+
+function orientTurnsTable(ONE) {
+  return [0, ONE / 4, ONE / 2, (3 * ONE) / 4];
+}
+
+// ─── GridTrackCollider ───────────────────────────────────────────────────────
+
+export function cookGridTrackColliders(cells, grid, params, math) {
+  const { ONE, mul, fsin, fcos } = math;
+  const S = grid.gridScale;
+  const CELL_HALF = grid.cellRaw / 2;
+  const H_THICK = mul(params.wallHalfThick, S);
+  const H_HEIGHT = mul(params.wallHalfHeightRaw, S);
+  const H_LEN = mul(CELL_HALF, S);
+  const ARC_SPAN_TURNS = -(ONE / 4);
+  const ARC_CENTER_X = -CELL_HALF;
+  const ARC_CENTER_Z = CELL_HALF;
+  const OUTER_R = 2 * CELL_HALF - params.wallHalfThick;
+  const OUTER_SEG = params.outerArcSegments;
+  const OUTER_SEG_HALF_LEN = mul(Math.trunc(mul(OUTER_R, params.halfPiFixed) / (OUTER_SEG * 2)), S);
+  const INNER_R = params.wallHalfThick;
+  const INNER_SEG = params.innerArcSegments;
+  const INNER_SEG_HALF_LEN = mul(Math.trunc(mul(INNER_R, params.halfPiFixed) / (INNER_SEG * 2)), S);
+  const ORIENT_TURNS = orientTurnsTable(ONE);
+  const cornerTypeIds = new Set(grid.cornerTypeIds);
+  const passThroughTypeIds = new Set(grid.passThroughTypeIds);
+
+  const turnsToRadians = (turns) => mul(turns, params.twoPiFixed);
+  const box = (id, x, z, ryTurns, half) => ({
+    id,
+    kind: 'static',
+    x,
+    y: params.wallY,
+    z,
+    vx: 0,
+    vy: 0,
+    vz: 0,
+    ry: turnsToRadians(ryTurns),
+    shape: { type: 'box', halfX: half[0], halfY: half[1], halfZ: half[2] },
+    layer: params.layer,
+    mask: params.mask,
+  });
+
+  const bodies = [];
+  let n = 0;
+  const addArcWall = (wcx, wcz, arcStartTurns, radius, numSeg, segHalfLen) => {
+    for (let i = 0; i < numSeg; i += 1) {
+      const frac = Math.trunc(((2 * i + 1) * ONE) / (2 * numSeg));
+      const aMid = arcStartTurns + mul(frac, ARC_SPAN_TURNS);
+      const wx = wcx + mul(mul(radius, fcos(aMid)), S);
+      const wz = wcz + mul(mul(radius, fsin(aMid)), S);
+      bodies.push(box(`${params.bodyIdPrefix}${n++}`, wx, wz, -aMid, [H_THICK, H_HEIGHT, segHalfLen]));
+    }
+  };
+
+  for (const cell of cells) {
+    const { gridX, gridZ, typeId, orientation } = cell;
+    if (passThroughTypeIds.has(typeId)) continue;
+
+    const cx = mul((2 * gridX + 1) * (grid.cellRaw / 2), S);
+    const cz = mul((2 * gridZ + 1) * (grid.cellRaw / 2), S);
+    const turns = ORIENT_TURNS[orientation] ?? 0;
+    const cr = fcos(turns);
+    const sr = fsin(turns);
+
+    if (cornerTypeIds.has(typeId)) {
+      const wcx = cx + mul(mul(ARC_CENTER_X, cr) + mul(ARC_CENTER_Z, sr), S);
+      const wcz = cz + mul(mul(-ARC_CENTER_X, sr) + mul(ARC_CENTER_Z, cr), S);
+      const arcStartTurns = -turns;
+      addArcWall(wcx, wcz, arcStartTurns, OUTER_R, OUTER_SEG, OUTER_SEG_HALF_LEN);
+      addArcWall(wcx, wcz, arcStartTurns, INNER_R, INNER_SEG, INNER_SEG_HALF_LEN);
+    } else {
+      for (const side of [-1, 1]) {
+        const lx = side * params.wallLateral;
+        const wx = cx + mul(mul(lx, cr), S);
+        const wz = cz + mul(mul(-lx, sr), S);
+        bodies.push(box(`${params.bodyIdPrefix}${n++}`, wx, wz, turns, [H_THICK, H_HEIGHT, H_LEN]));
+      }
+    }
+  }
+  return bodies;
+}
+
+// ─── ArenaBounds ─────────────────────────────────────────────────────────────
+
+export function cookArenaBounds(params, math) {
+  const { ONE } = math;
+  const halfF = params.halfUnits * ONE;
+  const wall = (id, x, z, hx, hz) => ({
+    id,
+    kind: 'static',
+    x,
+    y: params.wallY,
+    z,
+    vx: 0,
+    vy: 0,
+    vz: 0,
+    shape: { type: 'box', halfX: hx, halfY: params.wallHalfHeight, halfZ: hz },
+    layer: params.layer,
+    mask: params.mask,
+  });
+  const span = halfF + params.wallThick;
+  const [north, south, west, east] = params.bodyIds;
+  return [
+    wall(north, params.centerX, params.centerZ - halfF, span, params.wallThick),
+    wall(south, params.centerX, params.centerZ + halfF, span, params.wallThick),
+    wall(west, params.centerX - halfF, params.centerZ, params.wallThick, span),
+    wall(east, params.centerX + halfF, params.centerZ, params.wallThick, span),
+  ];
+}
+
+// ─── ScatterSpawn (arena) ────────────────────────────────────────────────────
+
+export function deriveScatterSpawns(slotCount, arenaParams, params) {
+  const cols = params.cols;
+  const spacing = params.spacing;
+  const poses = [];
+  for (let i = 0; i < slotCount; i += 1) {
+    const col = i % cols;
+    const row = Math.floor(i / cols);
+    poses.push({
+      x: arenaParams.centerX + (col - (cols - 1) / 2) * spacing,
+      z: arenaParams.centerZ + (row - 1) * spacing,
+      yawTurns: 0,
+    });
+  }
+  return poses;
+}
+
+// ─── GridSpawn (race grid behind the finish line) ────────────────────────────
+
+export function findFinishCell(cells, finishTypeId) {
+  return cells.find((c) => c.typeId === finishTypeId) ?? null;
+}
+
+export function deriveGridSpawns(cells, slotCount, grid, params, math) {
+  const { ONE, mul, fsin, fcos } = math;
+  if (slotCount < params.minSlots || slotCount > params.maxSlots) {
+    throw new Error(`deriveGridSpawns: slotCount ${slotCount} out of range [${params.minSlots}, ${params.maxSlots}]`);
+  }
+  const finish = findFinishCell(cells, grid.finishTypeId);
+  if (!finish) {
+    throw new Error(`deriveGridSpawns: grid has no finish cell (typeId ${grid.finishTypeId}) — cannot seat the field`);
+  }
+  const rowsNeeded = Math.ceil(slotCount / 2);
+  if (cells.length < rowsNeeded) {
+    throw new Error(
+      `deriveGridSpawns: grid too small to seat ${slotCount} slots ` +
+        `(needs ${rowsNeeded} rows, grid has ${cells.length} cells)`,
+    );
+  }
+
+  const S = grid.gridScale;
+  const baseX = mul((2 * finish.gridX + 1) * (grid.cellRaw / 2), S);
+  const baseZ = mul((2 * finish.gridZ + 1) * (grid.cellRaw / 2), S);
+  const ORIENT_TURNS = orientTurnsTable(ONE);
+  const turns = ORIENT_TURNS[finish.orientation] ?? 0;
+  const cos = fcos(turns);
+  const sin = fsin(turns);
+
+  const poses = [];
+  for (let i = 0; i < slotCount; i += 1) {
+    const col = i % 2;
+    const row = Math.floor(i / 2);
+    const lateral = (col === 0 ? -1 : 1) * params.lateral;
+    const back = -row * params.rowBack;
+    poses.push({
+      x: baseX + mul(lateral, cos) - mul(back, sin),
+      z: baseZ + mul(lateral, sin) + mul(back, cos),
+      yawTurns: turns,
+    });
+  }
+  return poses;
+}
+
+// ─── WaypointRingDriver ──────────────────────────────────────────────────────
+
+function upperHalf(x, z) {
+  return z < 0 || (z === 0 && x < 0) ? 1 : 0;
+}
+
+export function buildWaypointRing(cells, grid, math) {
+  const { mul } = math;
+  const centre = (g) => mul((2 * g + 1) * (grid.cellRaw / 2), grid.gridScale);
+  const pts = cells.map((c) => ({ x: centre(c.gridX), z: centre(c.gridZ) }));
+  if (pts.length === 0) return { wx: [], wz: [] };
+  let sx = 0;
+  let sz = 0;
+  for (const p of pts) {
+    sx += p.x;
+    sz += p.z;
+  }
+  const cxc = Math.trunc(sx / pts.length);
+  const czc = Math.trunc(sz / pts.length);
+  const rel = pts.map((p) => ({ x: p.x - cxc, z: p.z - czc }));
+  rel.sort((a, b) => {
+    const ha = upperHalf(a.x, a.z);
+    const hb = upperHalf(b.x, b.z);
+    if (ha !== hb) return ha - hb;
+    const cross = a.x * b.z - a.z * b.x;
+    if (cross > 0) return -1;
+    if (cross < 0) return 1;
+    return a.x * a.x + a.z * a.z - (b.x * b.x + b.z * b.z);
+  });
+  return { wx: rel.map((r) => r.x + cxc), wz: rel.map((r) => r.z + czc) };
+}
+
+function approxMag(x, z, math) {
+  const ax = math.fabs(x);
+  const az = math.fabs(z);
+  const hi = ax > az ? ax : az;
+  const lo = ax > az ? az : ax;
+  return hi + Math.trunc(lo / 2);
+}
+
+export function waypointRingDrive(ring, view, params, math) {
+  const { ONE, mul, div, clamp, fsin, fcos } = math;
+  const n = ring.wx.length;
+  if (n === 0) return { steerX: 0, throttle: 0, handbrake: false, bot: true };
+
+  let nearest = 0;
+  let best = Infinity;
+  for (let i = 0; i < n; i += 1) {
+    const dx = ring.wx[i] - view.x;
+    const dz = ring.wz[i] - view.z;
+    const d = dx * dx + dz * dz;
+    if (d < best) {
+      best = d;
+      nearest = i;
+    }
+  }
+  const t = (nearest + params.lookahead) % n;
+  const dirX = ring.wx[t] - view.x;
+  const dirZ = ring.wz[t] - view.z;
+
+  const fx = fsin(view.yawTurns);
+  const fz = fcos(view.yawTurns);
+  const mag = approxMag(dirX, dirZ, math);
+  if (mag === 0) return { steerX: 0, throttle: ONE, handbrake: false, bot: true };
+
+  const lateral = div(mul(fz, dirX) - mul(fx, dirZ), mag);
+  const forward = div(mul(fx, dirX) + mul(fz, dirZ), mag);
+  const steerX = clamp(mul(params.steerGain, lateral), -ONE, ONE);
+  const throttle = forward > 0 ? ONE : params.sharpTurnThrottle;
+  return { steerX, throttle, handbrake: false, bot: true };
+}
+
+// ─── LapProgress ─────────────────────────────────────────────────────────────
+
+const cellKey = (gx, gz) => `${gx},${gz}`;
+
+export function buildLapProgressInfo(cells, grid, params, math) {
+  const { ONE, mul, fsin, fcos } = math;
+  const finish = findFinishCell(cells, grid.finishTypeId);
+  if (!finish) {
+    return { enabled: false, cx: 0, cz: 0, fwdX: 0, fwdZ: 0, rightX: 0, rightZ: 0, requiredBit: new Map(), requiredMask: 0 };
+  }
+  const cx = mul((2 * finish.gridX + 1) * (grid.cellRaw / 2), grid.gridScale);
+  const cz = mul((2 * finish.gridZ + 1) * (grid.cellRaw / 2), grid.gridScale);
+  const ORIENT_TURNS = orientTurnsTable(ONE);
+  const turns = ORIENT_TURNS[finish.orientation] ?? 0;
+  const fwdX = fsin(turns);
+  const fwdZ = fcos(turns);
+
+  const required = cells
+    .filter((c) => c.typeId !== grid.finishTypeId)
+    .slice()
+    .sort((a, b) => (a.gridX - b.gridX) || (a.gridZ - b.gridZ));
+  const requiredBit = new Map();
+  let bit = 0;
+  for (const c of required) {
+    if (bit >= params.maxRequiredBits) break;
+    requiredBit.set(cellKey(c.gridX, c.gridZ), bit);
+    bit += 1;
+  }
+  const requiredMask = bit === 0 ? 0 : (bit >= 31 ? 0x7fffffff : (1 << bit) - 1);
+
+  return { enabled: true, cx, cz, fwdX, fwdZ, rightX: fwdZ, rightZ: -fwdX, requiredBit, requiredMask };
+}
+
+export function stepLapProgress(info, car, frame, grid, params, math) {
+  const { mul, fabs } = math;
+  if (!info.enabled || car.finishFrame >= 0) {
+    return { ...car, justFinished: false };
+  }
+
+  const cellWorld = mul(grid.cellRaw, grid.gridScale);
+  const lateralOnLine = Math.trunc(cellWorld / 2);
+
+  let cellsVisited = car.cellsVisited;
+  const gx = Math.floor(car.x / cellWorld);
+  const gz = Math.floor(car.z / cellWorld);
+  const bit = info.requiredBit.get(cellKey(gx, gz));
+  if (bit !== undefined) cellsVisited |= 1 << bit;
+
+  const relX = car.x - info.cx;
+  const relZ = car.z - info.cz;
+  const forwardProj = mul(relX, info.fwdX) + mul(relZ, info.fwdZ);
+  const lateralProj = fabs(mul(relX, info.rightX) + mul(relZ, info.rightZ));
+
+  let lap = car.lap;
+  let finishFrame = car.finishFrame;
+  let justFinished = false;
+
+  const onLine = lateralProj <= lateralOnLine;
+  const noTeleport = fabs(forwardProj - car.lapProj) < params.noTeleport;
+  const crossedForward = car.lapProj < 0 && forwardProj >= 0;
+  if (onLine && noTeleport && crossedForward) {
+    if (cellsVisited === info.requiredMask && info.requiredMask > 0) {
+      lap += 1;
+      cellsVisited = 0;
+      if (lap >= params.totalLaps) {
+        finishFrame = frame;
+        justFinished = true;
+      }
+    } else {
+      cellsVisited = 0;
+    }
+  }
+
+  return { ...car, cellsVisited, lap, finishFrame, lapProj: forwardProj, justFinished };
+}
+
+// ─── ArcadeDriftVehicle ──────────────────────────────────────────────────────
+
+export function stepArcadeDriftVehicle(car, steerX, throttle, params, math) {
+  const { ONE, mul, div, clamp, lerp, fabs, fsign, fsin, fcos } = math;
+  const steer = clamp(steerX, -ONE, ONE);
+  const thr = clamp(throttle, -ONE, ONE);
+
+  const target = thr >= 0 ? mul(thr, params.maxSpeed) : mul(thr, params.maxReverse);
+  const braking = thr < 0 && car.speed > 0;
+  const rate = braking ? params.brakeRate : params.accelRate;
+  let speed = lerp(car.speed, target, rate);
+  if (fabs(speed) < params.stopDeadband) speed = 0;
+
+  const grip = clamp(div(fabs(speed), params.maxSpeed), params.gripMin, ONE);
+  const dir = speed === 0 ? 0 : fsign(speed);
+  const yawDelta = mul(mul(steer, params.turnPerTick), grip) * dir;
+  let yawTurns = (car.yawTurns + yawDelta) % ONE;
+  if (yawTurns < 0) yawTurns += ONE;
+
+  const fx = fsin(yawTurns);
+  const fz = fcos(yawTurns);
+  const desiredVX = mul(fx, speed);
+  const desiredVZ = mul(fz, speed);
+  const drifting = fabs(speed) > params.slipSpeed && fabs(steer) > params.driftSteer;
+  const traction = fabs(speed) > params.slipSpeed ? params.tractionFast : params.tractionSlow;
+  const vx = lerp(car.vx, desiredVX, traction);
+  const vz = lerp(car.vz, desiredVZ, traction);
+
+  return { yawTurns, speed, vx, vz, drifting };
+}
+
+// ─── MatchPhaseMachine constants ─────────────────────────────────────────────
+
+export const PHASE_LOBBY = 0;
+export const PHASE_COUNTDOWN = 1;
+export const PHASE_ACTIVE = 2;
+export const PHASE_FINISHED = 3;
+
+const PHASE_BY_NAME = { lobby: PHASE_LOBBY, countdown: PHASE_COUNTDOWN, active: PHASE_ACTIVE, finished: PHASE_FINISHED };
+const PHASE_NAMES = ['lobby', 'countdown', 'active', 'finished'];
+
+// ─── Runtime ─────────────────────────────────────────────────────────────────
+
+function requireOption(options, name) {
+  const value = options?.[name];
+  if (typeof value !== 'function') {
+    throw new Error(`createFixedRuntime: options.${name} must be a function (inject the deterministic physics slice)`);
+  }
+  return value;
+}
+
+function toPhysicsBody(body, scale) {
+  const shape = body.shape.type === 'box'
+    ? {
+        type: 'box',
+        halfX: body.shape.halfX / scale,
+        halfY: body.shape.halfY / scale,
+        halfZ: body.shape.halfZ / scale,
+      }
+    : { type: 'sphere', radius: body.shape.radius / scale };
+  return {
+    ...body,
+    x: body.x / scale,
+    y: body.y / scale,
+    z: body.z / scale,
+    vx: body.vx / scale,
+    vy: body.vy / scale,
+    vz: body.vz / scale,
+    rx: body.rx === undefined ? undefined : body.rx / scale,
+    ry: body.ry === undefined ? undefined : body.ry / scale,
+    rz: body.rz === undefined ? undefined : body.rz / scale,
+    avx: body.avx === undefined ? undefined : body.avx / scale,
+    avy: body.avy === undefined ? undefined : body.avy / scale,
+    avz: body.avz === undefined ? undefined : body.avz / scale,
+    shape,
+  };
+}
+
+export function createFixedRuntime(pack, options = {}) {
+  if (pack.numericProfile !== 'fixed-1000') {
+    throw new Error(`createFixedRuntime: unsupported numericProfile '${pack.numericProfile}' (expected 'fixed-1000')`);
+  }
+  const createPhysicsWorld = requireOption(options, 'createPhysicsWorld');
+  const createTrustedPhysicsWorld = options.createTrustedPhysicsWorld ?? createPhysicsWorld;
+  if (typeof createTrustedPhysicsWorld !== 'function') {
+    throw new Error('createFixedRuntime: options.createTrustedPhysicsWorld must be a function');
+  }
+  const stepPhysicsWorld = requireOption(options, 'stepPhysicsWorld');
+
+  const math = createFixedTurnsMath(pack.scale);
+  const grid = pack.grid;
+  const c = pack.components;
+  const cells = decodeGridCells(grid.encoded);
+
+  const initialPhase = PHASE_BY_NAME[pack.initialPhase];
+  if (initialPhase === undefined) {
+    throw new Error(`createFixedRuntime: unknown initialPhase '${pack.initialPhase}'`);
+  }
+  const slotCount = pack.slotCount;
+
+  const cooked = {
+    cells,
+    walls: cookGridTrackColliders(cells, grid, c.gridTrackCollider, math),
+    arenaWalls: cookArenaBounds(c.arenaBounds, math),
+    lapInfo: buildLapProgressInfo(cells, grid, c.lapProgress, math),
+    botRing: buildWaypointRing(cells, grid, math),
+  };
+  createPhysicsWorld(cooked.walls.map((body) => toPhysicsBody(body, pack.scale)));
+  createPhysicsWorld(cooked.arenaWalls.map((body) => toPhysicsBody(body, pack.scale)));
+
+  const spawns = initialPhase === PHASE_LOBBY
+    ? deriveScatterSpawns(slotCount, c.arenaBounds, c.scatterSpawn)
+    : deriveGridSpawns(cells, slotCount, grid, c.gridSpawn, math);
+  const fill = (v) => new Array(slotCount).fill(v);
+
+  const state = {
+    frame: 0,
+    track: grid.encoded,
+    phase: initialPhase,
+    phaseStartFrame: 0,
+    lobbyDeadlineFrame: initialPhase === PHASE_LOBBY ? c.matchPhaseMachine.lobbyInitialFrames : 0,
+    carX: spawns.map((s) => s.x),
+    carZ: spawns.map((s) => s.z),
+    carVX: fill(0),
+    carVZ: fill(0),
+    speed: fill(0),
+    yawTurns: spawns.map((s) => s.yawTurns),
+    drifting: fill(false),
+    lap: fill(0),
+    cellsVisited: fill(0),
+    lapProj: fill(0),
+    finishFrame: fill(-1),
+    isBot: Array.from({ length: slotCount }, (_, i) => i >= pack.humanCount),
+  };
+
+  return { pack, math, cooked, state, physics: { createPhysicsWorld: createTrustedPhysicsWorld, stepPhysicsWorld } };
+}
+
+// BotSlotResolution: null packet → bot marker, present packet → human input.
+function decodeSlotInput(raw) {
+  if (raw === null || raw === undefined) {
+    return { steerX: 0, throttle: 0, handbrake: false, bot: true };
+  }
+  if (typeof raw !== 'object') throw new Error('KINETIX_FIXED_INPUT_INVALID');
+  const keys = Reflect.ownKeys(raw);
+  if (keys.length !== 3
+    || !keys.includes('steerX') || !keys.includes('throttle') || !keys.includes('handbrake')
+    || !Number.isSafeInteger(raw.steerX) || raw.steerX < -1000 || raw.steerX > 1000
+    || !Number.isSafeInteger(raw.throttle) || raw.throttle < -1000 || raw.throttle > 1000
+    || typeof raw.handbrake !== 'boolean') {
+    throw new Error('KINETIX_FIXED_INPUT_INVALID');
+  }
+  return { steerX: raw.steerX, throttle: raw.throttle, handbrake: raw.handbrake === true, bot: false };
+}
+
+function freezeSlot(i, speed, vx, vz, drifting) {
+  speed[i] = 0;
+  vx[i] = 0;
+  vz[i] = 0;
+  drifting[i] = false;
+}
+
+export function tickFixedRuntime(runtime, inputs) {
+  const { pack, math, cooked, state, physics } = runtime;
+  const c = pack.components;
+  const phaseParams = c.matchPhaseMachine;
+  const writeback = c.physicsWriteback;
+  const frame = state.frame;
+  const n = pack.slotCount;
+  if (!Array.isArray(inputs) || inputs.length !== n) {
+    throw new Error(`tickFixedRuntime: inputs must be an array of length ${n} (got ${inputs?.length})`);
+  }
+
+  const carX = state.carX.slice();
+  const carZ = state.carZ.slice();
+  const carVX = state.carVX.slice();
+  const carVZ = state.carVZ.slice();
+  const speed = state.speed.slice();
+  const yawTurns = state.yawTurns.slice();
+  const drifting = state.drifting.slice();
+  const lap = state.lap.slice();
+  const cellsVisited = state.cellsVisited.slice();
+  const lapProj = state.lapProj.slice();
+  const finishFrame = state.finishFrame.slice();
+  const isBot = state.isBot.slice();
+
+  let phase = state.phase;
+  let phaseStartFrame = state.phaseStartFrame;
+  let lobbyDeadlineFrame = state.lobbyDeadlineFrame;
+
+  // ── 1. Resolve input (bot vs human), detect joins, count present humans. ──
+  const cmds = [];
+  let humans = 0;
+  let joined = false;
+  for (let slot = 0; slot < n; slot += 1) {
+    const raw = decodeSlotInput(inputs[slot]);
+    const effectiveBot = raw.bot !== undefined ? raw.bot : isBot[slot];
+    if (state.isBot[slot] === true && effectiveBot === false) joined = true;
+    isBot[slot] = effectiveBot;
+    if (!effectiveBot) humans += 1;
+    cmds.push(raw);
+  }
+
+  const active = phase === PHASE_ACTIVE;
+  const inArena = phase === PHASE_LOBBY;
+
+  // ── 2. Drive each slot per phase and build its physics body. ──
+  const dynamicBodies = [];
+  for (let slot = 0; slot < n; slot += 1) {
+    const raw = cmds[slot];
+    const bot = isBot[slot];
+    const finished = finishFrame[slot] >= 0;
+
+    let steer = 0;
+    let throttle = 0;
+    let drive = false;
+    if (phase === PHASE_LOBBY) {
+      if (!bot) {
+        steer = raw.steerX;
+        throttle = raw.throttle;
+        drive = true;
+      }
+    } else if (phase === PHASE_ACTIVE && !finished) {
+      drive = true;
+      if (bot) {
+        const b = waypointRingDrive(
+          cooked.botRing,
+          { x: carX[slot], z: carZ[slot], yawTurns: yawTurns[slot] },
+          c.waypointRingDriver,
+          math,
+        );
+        steer = b.steerX;
+        throttle = b.throttle;
+      } else {
+        steer = raw.steerX;
+        throttle = raw.throttle;
+      }
+    }
+
+    if (drive) {
+      const kin = stepArcadeDriftVehicle(
+        { yawTurns: yawTurns[slot], speed: speed[slot], vx: carVX[slot], vz: carVZ[slot], drifting: drifting[slot] },
+        steer,
+        throttle,
+        c.arcadeDriftVehicle,
+        math,
+      );
+      yawTurns[slot] = kin.yawTurns;
+      speed[slot] = kin.speed;
+      drifting[slot] = kin.drifting;
+      carVX[slot] = kin.vx;
+      carVZ[slot] = kin.vz;
+    } else {
+      freezeSlot(slot, speed, carVX, carVZ, drifting);
+    }
+
+    dynamicBodies.push({
+      id: `${writeback.bodyIdPrefix}${slot}`,
+      kind: 'dynamic',
+      x: carX[slot],
+      y: writeback.bodyY,
+      z: carZ[slot],
+      vx: carVX[slot],
+      vy: 0,
+      vz: carVZ[slot],
+      shape: { type: 'sphere', radius: writeback.bodyRadius },
+      layer: writeback.layer,
+      mask: writeback.mask,
+    });
+  }
+
+  // ── 3. PhysicsWriteback: one cold solve in world units, rounded fixed readback. ──
+  const statics = inArena ? cooked.arenaWalls : cooked.walls;
+  const world = physics.createPhysicsWorld(
+    [...statics, ...dynamicBodies].map((body) => toPhysicsBody(body, pack.scale)),
+  );
+  const result = physics.stepPhysicsWorld(world, { gravityY: writeback.gravityY });
+  for (let slot = 0; slot < n; slot += 1) {
+    const body = result.world.bodies.find((b) => b.id === `${writeback.bodyIdPrefix}${slot}`);
+    if (body) {
+      carX[slot] = Math.round(body.x * pack.scale);
+      carZ[slot] = Math.round(body.z * pack.scale);
+      carVX[slot] = Math.round(body.vx * pack.scale);
+      carVZ[slot] = Math.round(body.vz * pack.scale);
+    }
+  }
+
+  // ── 4. LapProgress only while active. ──
+  if (active) {
+    for (let slot = 0; slot < n; slot += 1) {
+      const r = stepLapProgress(
+        cooked.lapInfo,
+        {
+          x: carX[slot],
+          z: carZ[slot],
+          lap: lap[slot],
+          cellsVisited: cellsVisited[slot],
+          finishFrame: finishFrame[slot],
+          lapProj: lapProj[slot],
+        },
+        frame,
+        pack.grid,
+        c.lapProgress,
+        math,
+      );
+      lap[slot] = r.lap;
+      cellsVisited[slot] = r.cellsVisited;
+      finishFrame[slot] = r.finishFrame;
+      lapProj[slot] = r.lapProj;
+    }
+  }
+
+  // ── 5. MatchPhaseMachine transitions (all frame-counted). ──
+  if (phase === PHASE_LOBBY) {
+    if (joined) {
+      lobbyDeadlineFrame = Math.min(
+        lobbyDeadlineFrame + phaseParams.lobbyExtendFrames,
+        phaseStartFrame + phaseParams.lobbyMaxFrames,
+      );
+    }
+    if (humans >= phaseParams.maxSlotsAutoStart || frame >= lobbyDeadlineFrame) {
+      const gridPoses = deriveGridSpawns(cooked.cells, n, pack.grid, c.gridSpawn, math);
+      for (let slot = 0; slot < n; slot += 1) {
+        carX[slot] = gridPoses[slot].x;
+        carZ[slot] = gridPoses[slot].z;
+        yawTurns[slot] = gridPoses[slot].yawTurns;
+        freezeSlot(slot, speed, carVX, carVZ, drifting);
+        lap[slot] = 0;
+        cellsVisited[slot] = 0;
+        lapProj[slot] = 0;
+        finishFrame[slot] = -1;
+      }
+      phase = PHASE_COUNTDOWN;
+      phaseStartFrame = frame;
+    }
+  } else if (phase === PHASE_COUNTDOWN) {
+    if (frame - phaseStartFrame >= phaseParams.countdownFrames) {
+      phase = PHASE_ACTIVE;
+      phaseStartFrame = frame;
+    }
+  } else if (phase === PHASE_ACTIVE) {
+    const everyoneDone = finishFrame.every((f) => f >= 0);
+    const capped = frame - phaseStartFrame >= c.lapProgress.maxRaceFrames;
+    if (everyoneDone || capped) {
+      phase = PHASE_FINISHED;
+      phaseStartFrame = frame;
+    }
+  } else if (phase === PHASE_FINISHED) {
+    if (frame - phaseStartFrame >= phaseParams.resultsHoldFrames) {
+      const lobby = deriveScatterSpawns(n, c.arenaBounds, c.scatterSpawn);
+      for (let slot = 0; slot < n; slot += 1) {
+        carX[slot] = lobby[slot].x;
+        carZ[slot] = lobby[slot].z;
+        yawTurns[slot] = lobby[slot].yawTurns;
+        freezeSlot(slot, speed, carVX, carVZ, drifting);
+        lap[slot] = 0;
+        cellsVisited[slot] = 0;
+        lapProj[slot] = 0;
+        finishFrame[slot] = -1;
+      }
+      phase = PHASE_LOBBY;
+      phaseStartFrame = frame;
+      lobbyDeadlineFrame = frame + phaseParams.lobbyInitialFrames;
+    }
+  }
+
+  runtime.state = {
+    ...state,
+    frame: frame + 1,
+    phase,
+    phaseStartFrame,
+    lobbyDeadlineFrame,
+    carX,
+    carZ,
+    carVX,
+    carVZ,
+    speed,
+    yawTurns,
+    drifting,
+    lap,
+    cellsVisited,
+    lapProj,
+    finishFrame,
+    isBot,
+  };
+  return runtime.state;
+}
+
+const fixedSystemOrder = Object.freeze([
+  'slot-input-resolution',
+  'vehicle-drive-body-build',
+  'vehicle-physics-step',
+  'vehicle-lap-finish',
+  'match-phase-transition',
+]);
+
+export function executeFixedRuntimeSystem(runtime, systemId, inputs) {
+  const pending = runtime.pendingInstalledTick ?? { index: 0, inputs };
+  if (fixedSystemOrder[pending.index] !== systemId) {
+    throw new Error(`KINETIX_FIXED_SYSTEM_ORDER_INVALID expected=${fixedSystemOrder[pending.index]} actual=${systemId}`);
+  }
+  if (pending.index === 0) runtime.pendingInstalledTick = pending;
+  pending.index += 1;
+  if (pending.index === fixedSystemOrder.length) {
+    delete runtime.pendingInstalledTick;
+    tickFixedRuntime(runtime, pending.inputs);
+  }
+  return runtime.state;
+}
+
+// ─── Canonical state serialization + hashing (browser-safe) ─────────────────
+
+const utf8Encoder = new TextEncoder();
+
+function makeWriter() {
+  const chunks = [];
+  return {
+    chunks,
+    u64(value) {
+      const bytes = new Uint8Array(8);
+      new DataView(bytes.buffer).setBigUint64(0, BigInt(value), true);
+      chunks.push(bytes);
+    },
+    i64(value) {
+      const bytes = new Uint8Array(8);
+      new DataView(bytes.buffer).setBigInt64(0, BigInt(value), true);
+      chunks.push(bytes);
+    },
+    u8(value) {
+      chunks.push(Uint8Array.of(value ? 1 : 0));
+    },
+    str(value) {
+      const bytes = utf8Encoder.encode(value);
+      const length = new Uint8Array(4);
+      new DataView(length.buffer).setUint32(0, bytes.length, true);
+      chunks.push(length, bytes);
+    },
+    concat() {
+      let total = 0;
+      for (const chunk of chunks) total += chunk.length;
+      const out = new Uint8Array(total);
+      let offset = 0;
+      for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+      }
+      return out;
+    },
+  };
+}
+
+export function canonicalFixedStateBytes(runtime) {
+  const s = runtime.state;
+  const w = makeWriter();
+  w.u64(s.frame);
+  w.str(s.track);
+  w.i64(s.phase);
+  w.i64(s.phaseStartFrame);
+  w.i64(s.lobbyDeadlineFrame);
+  for (const field of ['carX', 'carZ', 'carVX', 'carVZ', 'speed', 'yawTurns']) {
+    for (const value of s[field]) w.i64(value);
+  }
+  for (const value of s.drifting) w.u8(value);
+  for (const field of ['lap', 'cellsVisited', 'lapProj', 'finishFrame']) {
+    for (const value of s[field]) w.i64(value);
+  }
+  for (const value of s.isBot) w.u8(value);
+  return w.concat();
+}
+
+export function canonicalFixedTickHash(runtime) {
+  return sha256Hex(canonicalFixedStateBytes(runtime));
+}
+
+// ─── View accessor for the render core / scripted camera ────────────────────
+
+export function carViews(runtime) {
+  const s = runtime.state;
+  const scale = runtime.math.ONE;
+  const cars = [];
+  for (let slot = 0; slot < runtime.pack.slotCount; slot += 1) {
+    cars.push({
+      slot,
+      x: s.carX[slot] / scale,
+      z: s.carZ[slot] / scale,
+      yawTurns: s.yawTurns[slot] / scale,
+      isBot: s.isBot[slot],
+      lap: s.lap[slot],
+      finished: s.finishFrame[slot] >= 0,
+    });
+  }
+  return {
+    frame: s.frame,
+    phase: s.phase,
+    phaseName: PHASE_NAMES[s.phase],
+    phaseStartFrame: s.phaseStartFrame,
+    lobbyDeadlineFrame: s.lobbyDeadlineFrame,
+    cars,
+  };
+}