@homie-rocks/studio 0.35.0 → 0.36.0

package/rules/host.ts

@@ -43,7 +43,7 @@
  * after five of them, not after five seconds' worth of ticks at its rate.
  * =============================================================================
  */
-import { useAgents, type Agents, type AgentsSaved, type Vocabulary } from '../agents/agents.ts';
+import { AGENT_RULES, useAgents, type Agents, type AgentsSaved, type Vocabulary } from '../agents/agents.ts';
 import { DEFAULT_POLICY, type Netplay, type Peer, type Policy, type Slot } from '../netplay/netplay.ts';
 import { createCore } from './core.ts';
 import type { Core, CoreOut, Driver, SavedCore, StepInput } from './core.ts';
@@ -58,6 +58,10 @@ export interface HostClock {
 }
 export interface HostOptions {
   game: string;
+  /** Told of every handler as it ends, and what it threw if it threw (core.ts `observe`): the build check listens. */
+  observe?(kind: string, handler: string, error?: string): void;
+  /** Told of a written value the runtime changed to make it fit (core.ts `noted`): the build check listens. */
+  noted?(kind: string, handler: string, what: string, at: string, written: string): void;
   /** The game's build, for the log. */
   build?: string;
   compiled: Compiled;
@@ -72,11 +76,15 @@ export interface HostOptions {
   restoreEpoch?: number;
   startDelayMs?: number;
   onTick?(): void;
+  /** Only the shared server isolate can attribute timer lateness to another tick. */
+  enforceOverrun?: boolean;
   log?(line: Record<string, unknown>): void;
   /** A number in [0, 1) for a fresh epoch and seed. */
   random?(): number;
   /** A room saved by `save()`, to carry on from. */
   restore?: Uint8Array | null;
+  /** A browser promotion starts immediately; server recovery starts paused by default. */
+  startPaused?: boolean;
   stage?: string;
   onPause?(): void;
   onResume?(): void;
@@ -94,6 +102,8 @@ export interface Host {
   start(): void;
   pause(): void;
   resume(): void;
+  /** Publish the round, the roster, the shared state and the capabilities again (a browser host's relay restarted). */
+  announce(): void;
   /** Stop for good: the room has ended. */
   stop(): void;
   /** Run the next tick now, whatever the clock says (tests, and the build check's runs). Like the timer's own tick, it never throws. */
@@ -157,7 +167,40 @@ export function createHost(o: HostOptions): Host {
   if (saved) {
     const check = (ok: unknown): void => { if (!ok) throw new Error('saved host inputs are invalid'); };
     const uint = (n: unknown): boolean => Number.isSafeInteger(n) && (n as number) >= 0;
+    check(Object.keys(saved).every(k => ['v', 'core', 'names', 'agents', 'guideViews', 'queues', 'inputs'].includes(k)));
     check(saved.core && Array.isArray(saved.names) && Array.isArray(saved.queues));
+    if (saved.agents !== undefined) {
+      const tables = ['goals', 'asks', 'avoid', 'sayAt', 'viewAt', 'floorAt', 'askAt'];
+      check(saved.agents && Object.keys(saved.agents).every(k => tables.includes(k)));
+      const data = (v: unknown): boolean => Boolean(v && typeof v === 'object' && !Array.isArray(v));
+      const stamp = (v: unknown, future = 0): boolean => typeof v === 'number' && Number.isFinite(v) && v >= 0 && v <= saved.core.tick * period + future;
+      for (const key of tables) {
+        const rows = own(saved.agents, key) as any;
+        check(Array.isArray(rows) && rows.length <= c.seats);
+        const seats = new Set();
+        for (const row of rows) {
+          check(Array.isArray(row) && row.length === 2 && uint(row[0]) && row[0] < c.seats && !seats.has(row[0])); seats.add(row[0]);
+          const v = row[1];
+          if (key === 'goals') check(data(v) && Object.keys(v).every(k => ['goal', 'args', 'from', 'at', 'state', 'asked'].includes(k)) && typeof v.goal === 'string' && data(v.args) && ['brain', 'floor'].includes(v.from) && ['active', 'done', 'failed'].includes(v.state) && stamp(v.at) && (v.asked === undefined || typeof v.asked === 'boolean'));
+          else if (key === 'asks') {
+            check(Array.isArray(v) && v.length <= 3);
+            for (const a of v) check(data(a) && Object.keys(a).every(k => ['k', 'args', 'from', 'at'].includes(k)) && typeof a.k === 'string' && data(a.args) && uint(a.from) && a.from < c.seats && stamp(a.at));
+          } else if (key === 'avoid') {
+            check(Array.isArray(v) && v.length <= c.seats && new Set(v.map(a => a?.[0])).size === v.length);
+            for (const a of v) check(Array.isArray(a) && a.length === 2 && uint(a[0]) && a[0] < c.seats && stamp(a[1], AGENT_RULES.leaveMs));
+          } else check(stamp(v));
+        }
+      }
+    }
+    if (saved.guideViews !== undefined) {
+      check(Array.isArray(saved.guideViews) && saved.guideViews.length <= c.seats && new Set(saved.guideViews.map(row => row?.[0])).size === saved.guideViews.length);
+      for (const row of saved.guideViews) {
+        check(Array.isArray(row) && row.length === 2);
+        const [seat, v] = row;
+        check(uint(seat) && seat < c.seats && v && Object.keys(v).every(k => ['id', 'at', 'value'].includes(k)) && typeof v.id === 'string' && uint(v.at) && v.at <= saved.core.tick);
+        check(JSON.stringify(v.value) === JSON.stringify(coerceFields(c.view, v.value, c.dims)));
+      }
+    }
     check(saved.names.length <= c.seats && saved.queues.length <= c.seats);
     for (const rows of [saved.names, saved.queues, ...(saved.inputs === undefined ? [] : [saved.inputs])]) {
       check(Array.isArray(rows) && rows.every((row) => Array.isArray(row)));
@@ -183,9 +226,9 @@ export function createHost(o: HostOptions): Host {
     }
   }
   if (saved && saved.v !== 1) throw new Error('this save was written by another version of the runtime');
-  const core = createCore(c, { seed: Math.floor(random() * 4294967296) >>> 0, epoch: (Math.floor(random() * 4294967295) >>> 0) + 1, restore: saved?.core ?? null, restoreEpoch: o.restoreEpoch, stage: o.stage, decisions: !o.check });
+  const core = createCore(c, { observe: o.observe, noted: o.noted, seed: Math.floor(random() * 4294967296) >>> 0, epoch: saved ? undefined : (Math.floor(random() * 4294967295) >>> 0) + 1, restore: saved?.core ?? null, restoreEpoch: o.restoreEpoch, stage: o.stage, decisions: !o.check });
   let epoch = core.epoch;
-  if (saved && o.restoreEpoch !== undefined) for (const body of core.bodies()) if (body.driver !== 'bot' && body.owner !== 'reserved') core.seatAway(body.seat, true);
+  if (saved && (o.startPaused ?? o.restoreEpoch !== undefined)) for (const body of core.bodies()) if (body.driver !== 'bot' && body.owner !== 'reserved') core.seatAway(body.seat, true);
   let lastSaveAt = o.clock.now();
   let saveTick = core.tick;
   let forceSave = false;
@@ -203,7 +246,7 @@ export function createHost(o: HostOptions): Host {
   let savedAgents = saved?.agents;
   const guideOwners = new Map(core.bodies().map((b) => [b.seat, `${b.id}/${b.owner}/${b.driver}`]));
   const guideViews = new Map<number, { id: string; at: number; value: Record<string, unknown> }>();
-  for (const [seat, v] of (Array.isArray(saved?.guideViews) ? saved.guideViews : []).filter((v) => Array.isArray(v) && v.length === 2).slice(0, c.seats)) if (v && core.bodyOf(seat)?.id === v.id) guideViews.set(seat, { id: v.id, at: typeof v.at === 'number' && Number.isFinite(v.at) ? Math.max(0, Math.min(core.tick, v.at)) : 0, value: coerceFields(c.view, v.value, c.dims) });
+  for (const [seat, v] of saved?.guideViews ?? []) if (core.bodyOf(seat)?.id === v.id) guideViews.set(seat, v);
   const agentEvents = new Set<(m: any) => void>();
   let agentInbox: Record<string, unknown>[] = [];
   function agentSlots(brainsOnly = false): Slot[] {
@@ -238,7 +281,7 @@ export function createHost(o: HostOptions): Host {
       send: (k: string, d: unknown, to?: number) => o.send({ t: 'ev', k, d, ...(to !== undefined ? { to } : {}) }),
     } as unknown as Netplay;
     agents = useAgents(net, vocab, { roles: ['guide', 'party'], manual: true, carryFloor: true, now: () => core.tick * period, restore: savedAgents,
-      view: agentView, decide: (v, ctx) => core.guide(ctx.slot, v),
+      view: agentView, decide: (v, ctx) => core.guide(ctx.slot, { ...v, goal: ctx.goal ? { ...ctx.goal, at: Math.round(ctx.goal.at / period) } : null }),
     });
     savedAgents = undefined;
     agents.on('goal', (d) => o.send({ t: 'ev', k: 'agent:goal', d }));
@@ -269,7 +312,7 @@ export function createHost(o: HostOptions): Host {
     }
   }
   let running = false;
-  let paused = Boolean(saved && o.restoreEpoch !== undefined);
+  let paused = Boolean(saved && (o.startPaused ?? o.restoreEpoch !== undefined));
   let ended = false;
   /** The pending timer, and whether there is one. `armed` is the truth: a clock may hand back any value as its handle. */
   let timer: unknown = null;
@@ -288,6 +331,14 @@ export function createHost(o: HostOptions): Host {
   let overTicks = 0;
   let overBlamed = 0;
   let lastStart = 0;
+  let roundRebaseAt = -Infinity;
+  let roundRebasePending = false;
+  function publishRebase(now: number): void {
+    roundRebasePending = true;
+    if (now - roundRebaseAt < 250) return;
+    roundRebaseAt = now; roundRebasePending = false;
+    const { results, ...round } = core.round(); handle([round], now, true);
+  }
   /** When the run of failed ticks this room is in began, or null. */
   let failingSince: number | null = null;
   /** Where in a tick the runtime is, for the log line of a fault. */
@@ -391,9 +442,11 @@ export function createHost(o: HostOptions): Host {
         names.set(seat, typeof p.name === 'string' ? p.name.slice(0, 40) : '');
         present.set(seat, driver === 'person');
         // The relay numbers every stay in a seat (`occ`): the same number is the same holder, back.
-        core.seatJoin({ seat, driver, owner: `p${Number.isInteger(p.occ) ? p.occ : typeof p.id === 'string' ? p.id.slice(0, 40) : seat}` });
+        const owner = `p${Number.isInteger(p.occ) ? p.occ : typeof p.id === 'string' ? p.id.slice(0, 40) : seat}`;
+        const previous = core.bodies().find((s) => s.seat === seat);
+        core.seatJoin({ seat, driver, owner });
         core.seatAway(seat, false);
-        queues.delete(seat);
+        if (!previous || previous.driver !== driver || previous.owner !== owner) queues.delete(seat);
         rosterText = '';
         if (people() > 0) { if (!running && !paused) start(); else if (paused) resume(); }
         return;
@@ -462,16 +515,16 @@ export function createHost(o: HostOptions): Host {
     rosterText = text;
     o.send({ t: 'roster', slots });
   }
-  function handle(out: CoreOut[], now: number): void {
+  function handle(out: CoreOut[], now: number, retime = false): void {
     let roster = false;
     for (const x of out) {
       if (x.t === 'round') {
         if (x.phase === 'over') forceSave = true;
         const ms = (t: number): number => Math.round(now + (t - core.tick) * period);
         const drivers = new Map(core.bodies().map((b) => [b.seat, b.driver]));
-        o.send({ t: 'round', round: {
+        o.send({ t: 'round', ...(retime ? { retime: true } : {}), round: {
           n: x.n, phase: x.phase, startedAt: ms(x.startedAt), endsAt: x.endsAt ? ms(x.endsAt) : ms(core.tick + 86_400 * tickHz),
-          ...(x.results ? { results: x.results.map((r) => ({ slot: r.seat, seat: r.driver === 'bot' ? null : r.seat, name: nameOf(r.seat, drivers.get(r.seat) ?? r.driver), score: r.score, bot: r.driver === 'bot', ...(r.driver === 'ai' ? { agent: true } : {}), place: r.place })) } : {}),
+          ...(!retime && x.results ? { results: x.results.map((r) => ({ slot: r.seat, seat: r.driver === 'bot' ? null : r.seat, name: nameOf(r.seat, drivers.get(r.seat) ?? r.driver), score: r.score, bot: r.driver === 'bot', ...(r.driver === 'ai' ? { agent: true } : {}), place: r.place })) } : {}),
         } });
       } else if (x.t === 'ask') o.send({ t: 'decide', n: x.n, state: x.state, questions: x.questions });
       else if (x.t === 'goalDone') agents?.done(x.seat, x.ok);
@@ -508,6 +561,7 @@ export function createHost(o: HostOptions): Host {
       for (const p of presses) values[p] = true;
       inputs.set(seat, { values, claim: q.claim });
     }
+    if (roundRebasePending) publishRebase(now);
     phase = 'step';
     core.step(inputs, guideBeat);
     phase = 'frames';
@@ -590,7 +644,14 @@ export function createHost(o: HostOptions): Host {
         const due = dueOf(core.tick + 1);
         if (now + 0.5 < due) break;
         // The overrun check: a tick that starts more than a period late blames the tick that held it up.
-        if (now - due > period) { stats.late += 1; blameLate(now, period); }
+        if (now - due > period) {
+          stats.late += 1;
+          if (o.enforceOverrun) blameLate(now, period);
+          // A browser cannot say whose fault a late timer is. Up to a tenth of a second late (two periods, if that
+          // is longer) it catches up as the server does: a 20-tick room on a timer every 70 ms, or a 60-tick room on
+          // one every 37 ms, runs at its rate. Later than that its clock runs slow, and a slow host yields.
+          else if (now - due > Math.max(2 * period, 100)) { base = { ms: now - period, tick: core.tick }; publishRebase(now); }
+        }
         // Blamed since its last tick began: a run of slow ticks begins (when the tick blamed did), or goes on.
         if (blamed) { if (overSince === null) { overSince = lastStart; overTicks = 0; overBlamed = 0; } overBlamed += 1; }
         blamed = false;
@@ -600,7 +661,7 @@ export function createHost(o: HostOptions): Host {
           // A room whose ticks have run slow for five seconds of the clock ends, and the log names the handler that used the most units.
           else if (now - overSince >= OVERRUN_MS) { end('overrun', { worst: core.stats.worst, maxUnits: core.stats.maxUnits, seconds: Math.round((now - overSince) / 100) / 10 }); return; }
         }
-        recent.push({ who: self, at: now });
+        if (o.enforceOverrun) recent.push({ who: self, at: now });
         if (recent.length > 8) recent.shift();
         lastStart = now;
         tick(now);
@@ -608,7 +669,7 @@ export function createHost(o: HostOptions): Host {
       }
       // Far behind (the isolate was busy, or the machine slept): the clock runs slow. It never jumps to catch up.
       // The tick after a slip starts on time by the new clock, so the tick that ran last is judged here, before the slip hides it.
-      if (running && o.clock.now() - dueOf(core.tick + 1) > 4 * period) { const now = o.clock.now(); blameLate(now, period); base = { ms: now, tick: core.tick }; stats.slips += 1; }
+      if (running && o.clock.now() - dueOf(core.tick + 1) > 4 * period) { const now = o.clock.now(); if (o.enforceOverrun) blameLate(now, period); base = { ms: now, tick: core.tick }; stats.slips += 1; publishRebase(now); }
     } catch (error) {
       // Thrown outside any tick (the clock, the blame): a failed turn of the loop, counted like a failed tick.
       fault('wake', error);
@@ -629,6 +690,7 @@ export function createHost(o: HostOptions): Host {
       const caps = c.kinds.some((k) => k.think) ? ['skill'] : [];
       if (c.kinds.some((k) => k.guide && k.think)) caps.push('agents');
       if (caps.length) o.send({ t: 'caps', caps });
+      if (saved) { handle([core.round()], base.ms); }
       log({ ev: 'host-start', game: o.game, tick: core.tick, epoch, tickHz });
     } catch (error) { fault('start', error); } finally { keepTime(); }
   }
@@ -647,11 +709,24 @@ export function createHost(o: HostOptions): Host {
       // The room resumes at the tick it paused on: no tick is skipped and no timer fires for the gap.
       base = { ms: o.clock.now() + (firstTick ? o.startDelayMs ?? 0 : 0), tick: core.tick };
       overSince = null; blamed = false; failingSince = null; lastStart = base.ms;
+      handle([core.round()], base.ms);
       for (const q of queues.values()) q.lastFrameTick = core.tick;
       log({ ev: 'host-resume', game: o.game, tick: core.tick });
       o.onResume?.();
     } catch (error) { fault('resume', error); } finally { keepTime(); }
   }
+  /** What a relay keeps for whoever joins next, said again: the round with its results, the roster, the shared state, the capabilities. */
+  function announce(): void {
+    if (ended) return;
+    try {
+      const caps = c.kinds.some((k) => k.think) ? ['skill'] : [];
+      if (c.kinds.some((k) => k.guide && k.think)) caps.push('agents');
+      if (caps.length) o.send({ t: 'caps', caps });
+      rosterText = '';
+      handle([core.round()], o.clock.now());
+      o.send({ t: 'state', k: 'shared', d: core.shared() });
+    } catch (error) { fault('announce', error); }
+  }
   function stop(): void {
     running = false; paused = false; ended = true;
     disarm();
@@ -691,7 +766,7 @@ export function createHost(o: HostOptions): Host {
     get running() { return running; },
     get paused() { return paused; },
     get people() { return people(); },
-    frame, start, pause, resume, stop,
+    frame, start, pause, resume, stop, announce,
     tickNow: () => {
       if (ended) return;
       let now = lastStart;

package/rules/math.ts

@@ -13,6 +13,7 @@
  * =============================================================================
  */
 import { brand, charge, own, put } from './guard.ts';
+import { num } from './pack.ts';
 
 export interface Vec3 { readonly x: number; readonly y: number; readonly z: number }
 
@@ -264,3 +265,18 @@ export function sweepMap(map: MapShapes, body: unknown, delta: unknown, radius:
   put(body, 'pos', at);
   return Object.freeze({ at, normal: v(h.nx, h.ny, 0) });
 }
+
+/**
+ * What a browser hands the game's `move` as `ctx`: the tick, the step, the public tunables, this maths and the static
+ * map. One function, so that the browser (view.ts) and the person the build check plays hold the same one. The
+ * server's own (core.ts `moveCtx`) is made beside the rest of its world, and charges as that does.
+ */
+export function moveContext(o: { tick: () => number; tickHz: number; tune: unknown; map: MapShapes; name: string; spots: Readonly<Record<string, readonly unknown[]>>; radius: () => number; dims: number }): unknown {
+  const none = Object.freeze([]);
+  return brand(Object.freeze({
+    get tick() { return o.tick(); }, dt: 1 / o.tickHz, tune: o.tune, math,
+    // As the server's `ctx.ticks` reads it: a plain number, or nothing.
+    ticks: (seconds: unknown): number => { const s = num(seconds); const n = Math.round(s * o.tickHz); return s > 0 && Number.isFinite(n) ? Math.max(1, n) : 0; },
+    map: brand(Object.freeze({ name: o.name, spot: (name: string) => (own(o.spots, name) as readonly unknown[] | undefined)?.[0], spots: (name: string) => own(o.spots, name) ?? none, sweep: (body: unknown, delta: unknown) => sweepMap(o.map, body, delta, o.radius(), o.dims) })),
+  }));
+}

package/rules/pack.ts

@@ -19,7 +19,7 @@
  */
 import { cellsOf } from './rules.ts';
 import type { Field, FieldList, Vec3 } from './rules.ts';
-import { charge, keyCount, own, refusedName } from './guard.ts';
+import { G, charge, keyCount, own, refusedName } from './guard.ts';
 
 const RANGE: Record<string, [number, number]> = { u8: [0, 255], u16: [0, 65535], u32: [0, 4294967295], i8: [-128, 127], i16: [-32768, 32767], i32: [-2147483648, 2147483647], tick: [0, 4294967295], ticks: [0, 4294967295] };
 /** `f.fix`: steps of 1/4096, to plus or minus 2^31 (a tick count with a fraction fits for the life of any room). */
@@ -45,6 +45,14 @@ const fr = Math.fround;
  *                                whatever was handed in, and `est` says in a few steps how much that will be, so the
  *                                caller charges the running handler before the work is done.
  *
+ * WHAT IT CHANGED IS SAID, TO WHOEVER ASKS. A value that does not fit is stored as something else, here and nowhere
+ * else: a number that is not one becomes 0, a list is cut to its size. A room does that in silence, as it always has, and
+ * a handler is never stopped for it. The build check wants to know, so while a handler runs for a room that was given a
+ * listener (`G.note`, set by core.ts `run`), each such change is told to it with the field's name (`trail`) and what
+ * was done (`Adjusted`). With no listener nothing is built, counted or charged: one test of `G.note` and no more.
+ * Not told, because nothing is lost that a game would not mean: rounding (a fraction in a whole number, a number to a
+ * 32-bit float), an absent value taking the zero of its type, and a property a struct does not declare.
+ *
  * What comes out is plain data, frozen: a list, a map and a struct are new frozen objects, a vector is a frozen
  * `{ x, y, z }`. Stored state is therefore read-only everywhere, and a query result or an event can hand it out as it
  * is, with no copy. A handler that changes a list in place is handed a copy to change (`thaw`), which is held to its
@@ -67,8 +75,39 @@ const DIRS = new WeakSet<object>();
 /** Lists, maps and structs this file made, each with the declaration it was held to: the same value under the same declaration is not read twice. */
 const MADE = new WeakMap<object, Field>();
 const INIT = new WeakMap<Field, { v: unknown }>();
-const mk = (x: number, y: number, z: number): Vec3 => { const p = Object.freeze({ x, y, z }); VECS.add(p); return p; };
-const f32 = (a: unknown): number => { const x = fr(num(a)); return Number.isFinite(x) ? x : 0; };
+/*
+ * ONE ZERO. JavaScript has two, and the save and every frame are JSON, which writes both as `0`. A room that kept `-0`
+ * would divide by it one way before a restart and the other way after, and a browser would never have seen it at all. So
+ * every number that enters state has `+ 0` added, which changes `-0` to `0` and nothing else.
+ */
+const mk = (x: number, y: number, z: number): Vec3 => { const p = Object.freeze({ x: x + 0, y: y + 0, z: z + 0 }); VECS.add(p); return p; };
+
+/**
+ * What was done to a written value that did not fit:
+ *   nan      not a number at all (NaN, or a text, a list, nothing a number can be read from): stored as 0
+ *   infinite an infinite number where a fraction or a vector belongs: stored as 0
+ *   range    a whole number outside its range, an infinite one included: held to the nearest end of the range
+ *   text     a text longer than declared: cut
+ *   list     a list longer than declared: cut
+ *   map      a map with more keys than declared: the keys past its size dropped
+ *   key      a map key over 32 characters, or a name every object has: dropped
+ *   kind     something that is not a list where a list belongs, or not a plain object where a map or a struct does: stored empty
+ */
+export type Adjusted = 'nan' | 'infinite' | 'range' | 'text' | 'list' | 'map' | 'key' | 'kind';
+/** The field being held to its type, outermost first (`['runner.fields', 'bag', 3]`), kept only while somebody listens. */
+const trail: (string | number)[] = [];
+/** Name what is about to be held to its type (core.ts, before each `coerce` of something the rules wrote); with no name, forget it. */
+export function naming(...parts: (string | number)[]): void { if (G.note !== null) { trail.length = 0; for (const p of parts) trail.push(p); } }
+function note(what: Adjusted, written: unknown): void {
+  let at = '';
+  for (const p of trail) at += typeof p === 'number' ? `[${p}]` : at ? `.${p}` : p;
+  (G.note as NonNullable<typeof G.note>)(what, at, said(written));
+}
+/** What the rules wrote where a list, a map or a struct belongs and is none. Absent (`undefined`, `null`) is the empty one, and is not said. */
+const wrongKind = (v: unknown): void => { if (G.note !== null && v !== undefined && v !== null) note('kind', v instanceof Map ? 'a Map' : v instanceof Set ? 'a Set' : v); };
+/** A number that is to be 0 because it is not finite: said, when it was written and not merely absent. */
+function zeroed(v: unknown, x: number): 0 { if (G.note !== null && v !== undefined) note(x === Infinity || x === -Infinity ? 'infinite' : 'nan', v); return 0; }
+const f32 = (a: unknown): number => { const n = num(a); const x = fr(n); return Number.isFinite(x) ? x : zeroed(a, n !== n ? n : x); };
 
 export const ZERO: Vec3 = mk(0, 0, 0);
 export const AHEAD: Vec3 = mk(1, 0, 0);
@@ -78,7 +117,9 @@ DIRS.add(AHEAD);
 export function vec3(v: unknown, dims: number): Vec3 {
   if (v === null || typeof v !== 'object') return ZERO;
   if (VECS.has(v)) { const p = v as Vec3; return dims === 2 && p.z !== 0 ? mk(p.x, p.y, 0) : p; }
-  return mk(f32(own(v, 'x')), f32(own(v, 'y')), dims === 2 ? 0 : f32(own(v, 'z')));
+  if (G.note === null) return mk(f32(own(v, 'x')), f32(own(v, 'y')), dims === 2 ? 0 : f32(own(v, 'z')));
+  trail.push('x'); const x = f32(own(v, 'x')); trail[trail.length - 1] = 'y'; const y = f32(own(v, 'y')); trail[trail.length - 1] = 'z'; const z = dims === 2 ? 0 : f32(own(v, 'z')); trail.pop();
+  return mk(x, y, z);
 }
 /** A unit vector on the ground plane, as 32-bit floats. Too short to have a direction: +x. One that is already a unit vector is kept as it is, so a direction packs and unpacks to itself. */
 export function dir(v: unknown, dims: number): Vec3 {
@@ -99,24 +140,31 @@ const made = <T extends object>(fd: Field, o: T): T => { Object.freeze(o); MADE.
 export function coerce(fd: Field, v: unknown, dims: number): unknown {
   switch (fd.t) {
     case 'bit': case 'press': return v === true || v === 1;
-    case 'fix': { const n = Math.round(num(v) * FIX_STEP) / FIX_STEP; return Number.isFinite(n) ? Math.max(-FIX_MAX, Math.min(FIX_MAX, n)) : 0; }
+    case 'fix': { const x = num(v); const n = Math.round(x * FIX_STEP) / FIX_STEP; return Number.isFinite(n) ? Math.max(-FIX_MAX, Math.min(FIX_MAX, n)) + 0 : zeroed(v, x); }
     case 'vec3': return vec3(v, dims);
     case 'dir': return dir(v, dims);
     case 'ref': return typeof v === 'string' ? v.slice(0, 24) : '';
-    case 'text': return (typeof v === 'string' ? v : typeof v === 'number' || typeof v === 'boolean' ? String(v) : '').slice(0, fd.max);
+    case 'text': {
+      const text = typeof v === 'string' ? v : typeof v === 'number' || typeof v === 'boolean' ? String(v) : '';
+      if (G.note !== null && text.length > (fd.max as number)) note('text', `${text.length} characters for a size of ${fd.max}`);
+      return text.slice(0, fd.max);
+    }
     case 'list': {
-      if (!Array.isArray(v)) return made(fd, []);
+      if (!Array.isArray(v)) { wrongKind(v); return made(fd, []); }
       if (MADE.get(v) === fd) return v;
       // An array's length is its own data property. No more than the declared size is read, however long the list is.
       const n = Math.min(v.length, fd.max as number);
       const out = new Array(n);
-      for (let i = 0; i < n; i += 1) out[i] = coerce(fd.of as Field, own(v, i), dims);
+      if (G.note === null) { for (let i = 0; i < n; i += 1) out[i] = coerce(fd.of as Field, own(v, i), dims); return made(fd, out); }
+      if (v.length > n) note('list', `${v.length} entries for a size of ${fd.max}`);
+      for (let i = 0; i < n; i += 1) { trail.push(i); out[i] = coerce(fd.of as Field, own(v, i), dims); trail.pop(); }
       return made(fd, out);
     }
     case 'map': {
       const out: Record<string, unknown> = Object.create(null);
-      if (v === null || typeof v !== 'object') return made(fd, out);
+      if (v === null || typeof v !== 'object') { wrongKind(v); return made(fd, out); }
       if (MADE.get(v) === fd) return v;
+      if (G.note !== null && (v instanceof Map || v instanceof Set)) wrongKind(v);
       // The one cost here that the declaration does not bound: how many keys the value handed in has. The running handler
       // pays for each: before they are listed when the count is known (a module's constant), after when the handler made
       // the value itself (and so has already paid a unit and more for every key).
@@ -126,23 +174,28 @@ export function coerce(fd: Field, v: unknown, dims: number): unknown {
       if (known === undefined) charge(16 * keys.length);
       let n = 0;
       for (const key of keys) {
-        if (n >= (fd.max as number)) break;
-        if (key.length > 32 || refusedName(key)) continue;
-        out[key] = coerce(fd.of as Field, own(v, key), dims); n += 1;
+        if (n >= (fd.max as number)) { if (G.note !== null) note('map', `${keys.length} keys for a size of ${fd.max}`); break; }
+        if (key.length > 32 || refusedName(key)) { if (G.note !== null) note('key', key); continue; }
+        if (G.note === null) out[key] = coerce(fd.of as Field, own(v, key), dims);
+        else { trail.push(key); out[key] = coerce(fd.of as Field, own(v, key), dims); trail.pop(); }
+        n += 1;
       }
       return made(fd, out);
     }
     case 'struct': {
       if (v !== null && typeof v === 'object' && MADE.get(v) === fd) return v;
       const out: Record<string, unknown> = {};
-      for (const [key, sub] of Object.entries(fd.fields ?? {})) out[key] = coerce(sub, own(v, key), dims);
+      if (G.note === null) { for (const [key, sub] of Object.entries(fd.fields ?? {})) out[key] = coerce(sub, own(v, key), dims); return made(fd, out); }
+      if (typeof v !== 'object' || v instanceof Map || v instanceof Set) wrongKind(v);
+      for (const [key, sub] of Object.entries(fd.fields ?? {})) { trail.push(key); out[key] = coerce(sub, own(v, key), dims); trail.pop(); }
       return made(fd, out);
     }
     default: {
       const [lo, hi] = RANGE[fd.t];
       const x = num(v);
       const n = Math.round(x);
-      return Number.isFinite(n) ? Math.max(lo, Math.min(hi, n)) : x === Infinity ? hi : x === -Infinity ? lo : 0;
+      if (G.note !== null && v !== undefined) { if (x !== x) note('nan', v); else if (n < lo || n > hi) note('range', v); }
+      return Number.isFinite(n) ? Math.max(lo, Math.min(hi, n)) + 0 : x === Infinity ? hi : x === -Infinity ? lo : 0;
     }
   }
 }
@@ -189,12 +242,35 @@ export function thawFields(list: FieldList, values: Record<string, unknown>): Re
 /** The value a field starts with: its `init`, else the zero of its type. Made once for each declaration, and shared: it is frozen. */
 export function initOf(fd: Field, dims: number): unknown {
   let hit = INIT.get(fd);
-  if (!hit) { hit = { v: coerce(fd, fd.init, dims) }; INIT.set(fd, hit); }
+  if (!hit) {
+    // A declaration is read here, by whichever handler needs it first: it is not that handler's write, so nobody is told.
+    const listener = G.note; G.note = null;
+    try { hit = { v: coerce(fd, fd.init, dims) }; } finally { G.note = listener; }
+    INIT.set(fd, hit);
+  }
   return hit.v;
 }
 /** Whether a field's value is changed in place (a list, a map, a struct), so a handler is handed a copy of it and the runtime holds the copy to its type again when the handler ends. */
 export const mutable = (fd: Field): boolean => fd.t === 'list' || fd.t === 'map' || fd.t === 'struct';
 
+/** A body as `move` is handed it. */
+export interface MoveBody { pos: Vec3; vel: Vec3; heading: Vec3; grounded: boolean; motion: Record<string, unknown> }
+/**
+ * One step of a body by the game's own guarded `move`, as a browser takes it for its own body (rules/view.ts) and as the
+ * build check takes it when it plays that browser: counted against `quota` as the server counts a handler, and what it
+ * left rounded to 32-bit floats and held to the declared shapes as the server does it, so both hold the same numbers.
+ * `used` is the units it took. What it throws goes to `failed` (the budget's own stop too) and the body is still read.
+ */
+export function stepMove(fn: (body: MoveBody, input: unknown, ctx: unknown) => void, body: MoveBody, input: Readonly<Record<string, unknown>>, ctx: unknown, quota: number, motion: FieldList, dims: number, failed: (error: unknown) => void): MoveBody & { used: number } {
+  G.left = quota;
+  try { fn(body, input, ctx); } catch (error) { failed(error); }
+  const used = quota - (G.left > 0 ? G.left : 0);
+  G.left = Infinity;
+  naming('body', 'pos'); const pos = vec3(body.pos, dims); naming('body', 'vel'); const vel = vec3(body.vel, dims); naming('body', 'heading'); const heading = dir(body.heading, dims);
+  naming('body', 'motion'); const held = thawFields(motion, coerceFields(motion, body.motion, dims)); naming();
+  return { pos, vel, heading, grounded: body.grounded === true, motion: held, used };
+}
+
 /** How many values `pack` has packed since this was last set to 0: the core reads it to charge a tick for the state it sends. */
 export const packed = { n: 0 };
 
@@ -205,7 +281,7 @@ export function pack(fd: Field, v: unknown, dims: number): unknown {
     case 'bit': case 'press': return v ? 1 : 0;
     case 'vec3': case 'dir': { const p = v as Vec3; return dims === 2 ? [p.x, p.y] : [p.x, p.y, p.z]; }
     case 'list': return (v as unknown[]).map((x) => pack(fd.of as Field, x, dims));
-    case 'map': return Object.keys(v as object).sort().map((key) => [key, pack(fd.of as Field, (v as Record<string, unknown>)[key], dims)]);
+    case 'map': return Object.keys(v as object).map((key) => [key, pack(fd.of as Field, (v as Record<string, unknown>)[key], dims)]);
     case 'struct': return Object.entries(fd.fields ?? {}).map(([key, sub]) => pack(sub, (v as Record<string, unknown>)[key], dims));
     default: return v;
   }
@@ -242,7 +318,8 @@ export function initFields(list: FieldList, dims: number): Record<string, unknow
 export function coerceFields(list: FieldList, values: unknown, dims: number): Record<string, unknown> {
   const v = values !== null && typeof values === 'object' ? values : null;
   const out: Record<string, unknown> = {};
-  for (const [name, fd] of list) { const x = v ? own(v, name) : undefined; out[name] = x === undefined ? initOf(fd, dims) : coerce(fd, x, dims); }
+  if (G.note === null) { for (const [name, fd] of list) { const x = v ? own(v, name) : undefined; out[name] = x === undefined ? initOf(fd, dims) : coerce(fd, x, dims); } return out; }
+  for (const [name, fd] of list) { const x = v ? own(v, name) : undefined; if (x === undefined) out[name] = initOf(fd, dims); else { trail.push(name); out[name] = coerce(fd, x, dims); trail.pop(); } }
   return out;
 }
 

package/rules/rules.ts

@@ -26,6 +26,13 @@ import { brand, deepFreeze, own, plainData } from './guard.ts';
 
 /** The version of the rules contract this runtime runs. Today's netplay contract is version 1. */
 export const RULES_CONTRACT = 2;
+/**
+ * The revision of a saved room (core.ts `SavedCore`). It is raised whenever a save written before would be read
+ * differently now. It is part of every game's state hash (lib/rules-check.mjs `stateHash`), so a room saved by an
+ * earlier revision starts a fresh match instead of being restored wrongly. 2: a map keeps its keys in JavaScript's own
+ * order (1 sorted them), and a round or a match asked to end on the tick of the save is carried.
+ */
+export const SAVE_REVISION = 2;
 /** How far a query, a ray or an area event reaches, in metres. */
 export const REACH_M = 64;
 /** The most entities one room holds. A spawn past it throws in the handler that asked. */
@@ -108,18 +115,16 @@ export const cellsOfList = (list: FieldList): number => { let n = 0; for (const
 /* ------------------------------------------------------------------ what a module declares */
 
 export interface Vec3 { readonly x: number; readonly y: number; readonly z: number }
-/**
- * What handlers are handed. The build's type check of rules (always on from the release that ships the build check)
- * narrows these per kind from the declarations; until then they are deliberately loose.
- */
-export type World = Record<string, any>;
-export type Self = Record<string, any>;
-export type Handler = (world: World, self: Self, e?: any) => void;
-export type RoomHandler = (world: World, e?: any) => void;
+/** Public faces are specialised by the build from declarations. Internal dispatch accepts compiled tables. */
+export type { World, Self, MoveBody, MoveContext, ReadonlyState } from './types.ts';
+type RuntimeWorld = Record<string, any>;
+type RuntimeSelf = Record<string, any>;
+export type Handler = (world: RuntimeWorld, self: RuntimeSelf, e?: any) => void;
+export type RoomHandler = (world: RuntimeWorld, e?: any) => void;
 export type MoveFn = (body: any, input: any, ctx: any) => void;
 
 export interface BodyDef { shape: 'circle' | 'sphere' | 'capsule' | 'box'; radius: number; height?: number; maxSpeed: number; sweep?: boolean; move?: 'owner' }
-export interface GuideDef { view: (world: World, self: Self) => unknown; floor?: (world: World, self: Self, view: any) => unknown }
+export interface GuideDef { view: (world: RuntimeWorld, self: RuntimeSelf) => unknown; floor?: (world: RuntimeWorld, self: RuntimeSelf, view: any) => unknown }
 export interface EntityDef {
   player?: true | { away?: 'neutral' | 'think'; leave?: 'despawn' | 'bot' };
   fields?: Fields;
@@ -128,7 +133,7 @@ export interface EntityDef {
   body?: BodyDef;
   guide?: GuideDef;
   tick?: Handler;
-  think?: (world: World, self: Self) => Record<string, unknown>;
+  think?: (world: RuntimeWorld, self: RuntimeSelf) => Record<string, unknown>;
   on?: Record<string, Handler>;
   commands?: Record<string, Handler>;
   onRoom?: Record<string, Handler>;
@@ -294,6 +299,8 @@ export interface KindTable {
 }
 export interface Compiled {
   contract: 2;
+  /** `SAVE_REVISION`, so that what hashes these declarations hashes it too. */
+  save: number;
   dims: 2 | 3;
   kinds: KindTable[];
   kindOf: Record<string, KindTable>;
@@ -437,7 +444,7 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
   const view = fieldList(d.shapes?.view, 'shapes.view');
 
   const move = d.move as (Record<string, MoveFn> & Record<string, unknown>) | undefined;
-  if (move !== undefined && (typeof move !== 'object' || move[MOVE] !== true)) throw new Error('move is what move.ts exports: `export const move = defineMove({ … })`');
+  if (move !== undefined && (typeof move !== 'object' || (move as Record<string, unknown>)[MOVE] !== true)) throw new Error('move is what move.ts exports: `export const move = defineMove({ … })`');
 
   const kinds: KindTable[] = [];
   const kindOf: Record<string, KindTable> = {};
@@ -506,12 +513,13 @@ export function compileRules(def: RulesDef, env: CompileEnv = {}): Compiled {
   if (players.length && typeof room.join !== 'function') throw new Error('room.join(ctx, player) says where a player\'s body starts: return { kind, at }');
   const asks: Compiled['asks'] = {};
   for (const [key, a] of Object.entries(d.asks ?? {})) {
-    if (!a || typeof a.floor !== 'function' || !a.questions || typeof a.questions !== 'object') throw new Error(`asks.${key} is { state, questions, floor(state) }`);
+    if (!a || typeof a.floor !== 'function') throw new Error(`asks.${key} needs a local floor(state) function that returns every declared question's pick; for example floor(state) { return { advance: true }; }`);
+    if (!a.questions || typeof a.questions !== 'object') throw new Error(`asks.${key}.questions is required; for example { advance: { type: 'noul', instructions: 'Should the party advance?' } }`);
     asks[key] = { ...a, stateFields: fieldList(a.state, `asks.${key}.state`) };
   }
   const seats = Math.max(1, Math.min(SEATS_MAX, Math.floor(Number(env.seats)) || 8));
   return {
-    contract: RULES_CONTRACT, dims, kinds, kindOf, events, commands, effects, effectNames: Object.keys(effects),
+    contract: RULES_CONTRACT, save: SAVE_REVISION, dims, kinds, kindOf, events, commands, effects, effectNames: Object.keys(effects),
     shared: fieldList(d.shared, 'shared'), view, rounds, bots: Math.min(keep, seats), start: room.start ?? null, join: room.join ?? null, roomOn, asks,
     tune, publicTune, map, settings, seats,
   };