@irtio/bots 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { AnySchema, Delta, PlainState, TypeDesc } from '@irtio/schema';
-import { Room, RelayRoom, Transport, JoinOptions } from '@irtio/client';
+import { PlainState, AnySchema, Delta, TypeDesc } from '@irtio/schema';
+import { Correction, Room, RelayRoom, Transport, JoinOptions } from '@irtio/client';
 
 /**
  * The built-in invariants, and the pure checkers behind the two that need real protocol knowledge.
@@ -14,7 +14,7 @@ import { Room, RelayRoom, Transport, JoinOptions } from '@irtio/client';
  */
 
 /** The invariants every simulation checks, in report order. */
-declare const INVARIANT_NAMES: readonly ["schema-validity", "visibility-leak", "bandwidth", "handler-error", "correction-storm", "disconnects"];
+declare const INVARIANT_NAMES: readonly ["schema-validity", "visibility-leak", "bandwidth", "handler-error", "correction-storm", "misprediction", "snaps", "disconnects"];
 type InvariantName = (typeof INVARIANT_NAMES)[number];
 interface InvariantResult {
     readonly name: InvariantName;
@@ -23,6 +23,27 @@ interface InvariantResult {
     /** One line a human can act on: the threshold, the peak, the first offenders. */
     readonly detail: string;
 }
+interface SpatialVisibilityContext {
+    /**
+     * The state the anchor and the judged positions are read from. Server truth when a test has it
+     * (the runtime harness does); a bot has none and passes its **own materialized view** instead —
+     * see `slackCells` and `BotObserver` for why that still answers the AOI question honestly.
+     */
+    readonly authority: PlainState;
+    readonly clientId: string;
+    /** Ids this viewer was previously sent, so a legitimate AOI departure remove is allowed. */
+    readonly seen?: ReadonlyMap<string, ReadonlySet<string>>;
+    /**
+     * Extra cells added to every grid radius before judging. Defaults to 0 — server truth needs no
+     * slack — but a viewer judging from its own view has an anchor that may be one tick stale
+     * relative to the frame in hand, so a record sitting exactly on the boundary could be flagged
+     * for a move the viewer has not been told about yet. Widening the neighbourhood can only ever
+     * make the detector *miss* a marginal leak; it can never make it invent one. That asymmetry is
+     * the whole justification: a checker that under-reports is a checker, a checker that
+     * over-reports is noise that gets switched off.
+     */
+    readonly slackCells?: number;
+}
 /** Thresholds the counting invariants compare against. */
 interface InvariantThresholds {
     /** `bandwidth`: inbound bytes per second, per bot. */
@@ -31,19 +52,27 @@ interface InvariantThresholds {
     readonly correctionsPerSecMax: number;
     /** `handler-error`: tolerated REPLY errors + non-fatal ERROR frames across the whole run. */
     readonly handlerErrorsMax: number;
+    /**
+     * `misprediction`: numeric distance one correction may snap a bot's prediction, summed over the
+     * fields it carried. Infinite by default — the invariant reports the measured numbers and only
+     * fails when a run tightens this.
+     */
+    readonly mispredictionMagnitudeMax: number;
+    /** `snaps`: tolerated cap-exceeded reconciliations (corrections past the resim window), per run. */
+    readonly snapsMax: number;
 }
 declare const DEFAULT_THRESHOLDS: InvariantThresholds;
 /**
  * Collections a `DELTA` named that `role` is not allowed to see. An op count of zero is not a
  * leak — an empty collection entry carries no information — but any add, update or remove is.
  */
-declare function deltaVisibilityLeaks(ext: AnySchema, role: string, delta: Delta): string[];
+declare function deltaVisibilityLeaks(ext: AnySchema, role: string, delta: Delta, spatial?: SpatialVisibilityContext): string[];
 /**
  * The same rule for a join snapshot. The wire format always has a slot for every collection —
  * a hidden one is encoded empty — so the leak is *content*: an entity collection with records in
  * it, or a singleton holding anything other than its zero record.
  */
-declare function snapshotVisibilityLeaks(ext: AnySchema, role: string, state: PlainState): string[];
+declare function snapshotVisibilityLeaks(ext: AnySchema, role: string, state: PlainState, spatial?: Omit<SpatialVisibilityContext, 'seen'>): string[];
 /**
  * The socket-free entry point for the frames that carry a delta (`DELTA`, `CORRECT`): hand it the
  * frame type and its payload and it decodes and checks. Any other type returns `[]` — a join
@@ -51,7 +80,7 @@ declare function snapshotVisibilityLeaks(ext: AnySchema, role: string, state: Pl
  * rather than being one. A payload that will not decode throws, and the caller counts that as a
  * `schema-validity` violation rather than a visibility one.
  */
-declare function frameVisibilityLeaks(ext: AnySchema, role: string, type: number, payload: Uint8Array): string[];
+declare function frameVisibilityLeaks(ext: AnySchema, role: string, type: number, payload: Uint8Array, spatial?: SpatialVisibilityContext): string[];
 
 /**
  * The trace recorder: every frame in and out, per bot, with a timestamp and the decoded frame
@@ -126,6 +155,28 @@ interface BotStats {
     readonly bytesIn: number;
     readonly bytesOut: number;
     readonly corrections: number;
+    /**
+     * D22: corrections that touched **only** simulation-owned body fields. Not a disagreement —
+     * the client cannot write those fields, so it never predicted them; this is how a
+     * server-authoritative body reaches its owner, once per tick, by design. Counted apart from
+     * `corrections` so a healthy physics room does not read as a correction storm. Week 10 changes
+     * the meaning: once the client re-steps predicted bodies, these become real mispredictions.
+     */
+    readonly syncCorrections: number;
+    /**
+     * D22 part 2: predicted-body corrections whose values matched the local prediction within the
+     * epsilon — authority confirming the prediction, not disagreeing with it. Counted apart so a
+     * healthy predicted body's steady state stays quiet.
+     */
+    readonly suppressedCorrections: number;
+    /** Correction *ops* seen via the room's `correct` event (a `CORRECT` frame may carry several). */
+    readonly mispredictions: number;
+    /** Summed numeric distance between predicted and corrected values, across the run. */
+    readonly mispredictionMagnitude: number;
+    /** The single worst correction's numeric distance. */
+    readonly mispredictionMax: number;
+    /** Corrections that outran the resim window and snapped instead of replaying. */
+    readonly snaps: number;
     /** Outbound `CALL` frames: RPCs this bot asked the server for. */
     readonly calls: number;
     /** Error replies plus non-fatal `ERROR` frames. */
@@ -162,8 +213,8 @@ interface ObserverOptions {
 declare class BotObserver {
     private readonly options;
     readonly ring: TraceRing;
-    readonly violations: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "disconnects", string[]>;
-    readonly counts: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "disconnects", number>;
+    readonly violations: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "misprediction" | "snaps" | "disconnects", string[]>;
+    readonly counts: Map<"schema-validity" | "visibility-leak" | "bandwidth" | "handler-error" | "correction-storm" | "misprediction" | "snaps" | "disconnects", number>;
     id: string;
     role: string;
     roomId: string;
@@ -174,14 +225,47 @@ declare class BotObserver {
     bytesIn: number;
     bytesOut: number;
     corrections: number;
+    syncCorrections: number;
+    suppressedCorrections: number;
+    mispredictions: number;
+    /**
+     * Does this bot's client currently predict `collection[id]` in a local world? Assigned by
+     * `spawnBots` once the room exists (`room.prediction`); prediction status is client-local, so
+     * it cannot be derived from the bytes the observer otherwise sticks to.
+     */
+    predictsBody: ((collection: string, id: string) => boolean) | undefined;
+    mispredictionMagnitude: number;
+    mispredictionMax: number;
+    snaps: number;
     calls: number;
     errors: number;
     disconnects: number;
     peakBytesInPerSec: number;
     peakCorrectionsPerSec: number;
+    /**
+     * Spatial-grid ops actually put to the AOI policy. Zero on a run whose room has no spatial
+     * collection; zero on a run that *does* and would mean the invariant passed vacuously, which is
+     * exactly the bug this counter exists to make visible in the report.
+     */
+    spatialOpsJudged: number;
+    /**
+     * The bot's own materialized view: the `WELCOME` snapshot, plus every `DELTA`/`CORRECT` since.
+     *
+     * This is not server truth and never claims to be. It is what the AOI contract is *about*: the
+     * viewer's anchor is the record in the same collection whose id is the viewer's client id, and
+     * that record is always visible to its own client, so the bot holds its own true anchor. Every
+     * other record's position arrives inside the very op being judged — a record the server should
+     * not have sent is convicted by the position the server itself reported for it. The question
+     * answered is "was I sent something outside my own radius", which is the whole contract.
+     */
+    private view;
+    /** Ids delivered so far, per collection, so an AOI departure `remove` is not read as a leak. */
+    private readonly seen;
     private readonly bytesWindow;
     private readonly correctWindow;
     private readonly cooldown;
+    /** The last inbound `CORRECT` trace entry, so `onCorrection` can finish its note. */
+    private lastCorrectEntry;
     constructor(options: ObserverOptions);
     get stats(): BotStats;
     /** Counts a violation always; keeps an example, rate-limited per invariant when asked. */
@@ -195,6 +279,25 @@ declare class BotObserver {
     private onWelcome;
     private onDelta;
     private onCorrect;
+    /**
+     * The room's `correct` event, one per correction op — the only source of `previous` (the local
+     * prediction the server overrode) and of the `snapped` flag, neither of which a frame-level
+     * decode can know. Wired up by `spawnBots` via `room.on('correct', ...)`.
+     */
+    onCorrection(correction: Correction): void;
+    private spatialContext;
+    /**
+     * Applies the delta to the bot's view *first*, then judges: a record the server should not have
+     * sent has to be in the view for its own reported position to convict it. `seen` is updated
+     * afterwards, so a `remove` is judged against what the bot had been told about before this
+     * frame — a departing neighbour, not a leak.
+     */
+    private checkVisibility;
+    private countSpatialDelta;
+    private countSpatialSnapshot;
+    private ids;
+    private rememberSnapshot;
+    private remember;
     private onError;
     private onReply;
     private eachScalar;
@@ -277,6 +380,18 @@ interface SimulationTotals {
     readonly bytesIn: number;
     readonly bytesOut: number;
     readonly corrections: number;
+    /** D22: corrections carrying only simulated body state — the sync path, not a disagreement. */
+    readonly syncCorrections: number;
+    /** D22 part 2: predicted-body corrections matching the prediction within epsilon (quiet). */
+    readonly suppressedCorrections: number;
+    /** Correction ops seen via the rooms' `correct` events, across every bot. */
+    readonly mispredictions: number;
+    /** Summed numeric misprediction magnitude across every bot. */
+    readonly mispredictionMagnitude: number;
+    /** The single worst correction's numeric magnitude, across every bot. */
+    readonly mispredictionMax: number;
+    /** Cap-exceeded reconciliations (corrections past the resim window), across every bot. */
+    readonly snaps: number;
     readonly calls: number;
     readonly errors: number;
 }
@@ -382,6 +497,10 @@ interface SpawnOptionsBase {
     readonly correctionsPerSecMax?: number;
     /** `handler-error` tolerance for a run that expects some RPCs to be refused. */
     readonly handlerErrorsMax?: number;
+    /** `misprediction` threshold: numeric units one correction may snap. Default: infinite. */
+    readonly mispredictionMagnitudeMax?: number;
+    /** `snaps` tolerance: cap-exceeded reconciliations per bot. Default: infinite. */
+    readonly snapsMax?: number;
     /** @internal Wrap `webSocketTransport` to get at the socket (the reconnection scenarios). */
     readonly transport?: Transport;
 }
@@ -390,6 +509,12 @@ interface SpawnOptions<S extends AnySchema> extends SpawnOptionsBase {
     readonly script?: BotScript<S>;
     /** Implementations for server → client RPCs, shared by every bot. */
     readonly rpc?: JoinOptions<S>['rpc'];
+    /**
+     * D22 part 2: the shared world-builder, passed to every bot's `joinRoom({ physics })`. With
+     * it, bots predict physics bodies exactly as a browser client would, and body-field
+     * corrections classify as real mispredictions (in world units) instead of `syncCorrections`.
+     */
+    readonly physics?: JoinOptions<S>['physics'];
 }
 /** Schema-less relay: no schema, so `joinRelay` and a `RelayRoom`. */
 interface RelaySpawnOptions extends SpawnOptionsBase {
@@ -466,4 +591,4 @@ interface RelayEchoScriptOptions {
  */
 declare function relayEchoScript(options?: RelayEchoScriptOptions): BotScript<undefined>;
 
-export { type Bot, BotObserver, type BotRoom, type BotRunner, type BotScript, type BotStats, type BuildReportOptions, type ConvergenceStats, DEFAULT_SEED, DEFAULT_THRESHOLDS, DEFAULT_TRACE_LIMIT, INVARIANT_NAMES, type InvariantName, type InvariantResult, type InvariantThresholds, type ObserverOptions, type RandomScriptOptions, type RelayEchoScriptOptions, type RelaySpawnOptions, type Rng, type SimulationReport, type SimulationTotals, type SpawnOptions, type Trace, type TraceDump, type TraceEntry, TraceRing, type UntilOptions, type ValueContext, WriteLog, buildReport, convergenceStats, deltaVisibilityLeaks, frameName, frameVisibilityLeaks, freshValue, makeRng, makeTrace, nextValue, randomScript, relayEchoScript, snapshotVisibilityLeaks, spawnBots };
+export { type Bot, BotObserver, type BotRoom, type BotRunner, type BotScript, type BotStats, type BuildReportOptions, type ConvergenceStats, DEFAULT_SEED, DEFAULT_THRESHOLDS, DEFAULT_TRACE_LIMIT, INVARIANT_NAMES, type InvariantName, type InvariantResult, type InvariantThresholds, type ObserverOptions, type RandomScriptOptions, type RelayEchoScriptOptions, type RelaySpawnOptions, type Rng, type SimulationReport, type SimulationTotals, type SpatialVisibilityContext, type SpawnOptions, type Trace, type TraceDump, type TraceEntry, TraceRing, type UntilOptions, type ValueContext, WriteLog, buildReport, convergenceStats, deltaVisibilityLeaks, frameName, frameVisibilityLeaks, freshValue, makeRng, makeTrace, nextValue, randomScript, relayEchoScript, snapshotVisibilityLeaks, spawnBots };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/invariants.ts
 import { FrameType } from "@irtio/protocol";
-import { visibleNames } from "@irtio/runtime";
+import { createVisibilityPolicy, visibleNames } from "@irtio/runtime";
 import {
   decodeDelta,
   defaultRecord
@@ -11,21 +11,60 @@ var INVARIANT_NAMES = [
   "bandwidth",
   "handler-error",
   "correction-storm",
+  "misprediction",
+  "snaps",
   "disconnects"
 ];
 var DEFAULT_THRESHOLDS = {
   budgetBytesPerSec: 128e3,
   correctionsPerSecMax: 5,
-  handlerErrorsMax: 0
+  handlerErrorsMax: 0,
+  mispredictionMagnitudeMax: Number.POSITIVE_INFINITY,
+  snapsMax: Number.POSITIVE_INFINITY
 };
-function deltaVisibilityLeaks(ext, role, delta) {
+var widenedSchemas = /* @__PURE__ */ new WeakMap();
+function widenGrids(ext, slack) {
+  if (slack === 0) return ext;
+  let bySlack = widenedSchemas.get(ext);
+  if (!bySlack) {
+    bySlack = /* @__PURE__ */ new Map();
+    widenedSchemas.set(ext, bySlack);
+  }
+  const cached = bySlack.get(slack);
+  if (cached) return cached;
+  const collections = ext.collections.map(
+    (desc) => desc.visibility === "spatial-grid" && desc.grid ? { ...desc, grid: { ...desc.grid, radius: desc.grid.radius + slack } } : desc
+  );
+  const widened = { ...ext, collections };
+  bySlack.set(slack, widened);
+  return widened;
+}
+function policyFor(ext, role, spatial) {
+  if (!spatial) return void 0;
+  const slack = spatial.slackCells ?? 0;
+  return createVisibilityPolicy(widenGrids(ext, slack), spatial.authority, spatial.clientId, role);
+}
+function radiusText(desc, spatial) {
+  const slack = spatial?.slackCells ?? 0;
+  return `${desc.grid?.radius ?? "?"}${slack > 0 ? ` (+${slack} slack)` : ""}`;
+}
+function deltaVisibilityLeaks(ext, role, delta, spatial) {
   const allowed = visibleNames(ext, role);
+  const policy = policyFor(ext, role, spatial);
   const leaks = [];
   for (const collection of delta.collections) {
-    if (allowed.has(collection.name)) continue;
-    if (collection.ops.length === 0) continue;
-    const ops = collection.ops.map((op) => op.op).join(",");
-    leaks.push(`delta@${delta.tick} carried ${collection.name} (${ops}) to role ${role || '""'}`);
+    const desc = ext.collection(collection.name);
+    const bad = collection.ops.filter((op) => {
+      if (!allowed.has(collection.name)) return true;
+      if (desc.visibility !== "spatial-grid" || !policy) return false;
+      if (op.op === "remove") return !(spatial?.seen?.get(desc.name)?.has(op.id) ?? false);
+      return !policy.maySeeEntity(desc, op.id);
+    });
+    if (bad.length === 0) continue;
+    const ops = bad.map((op) => `${op.op}:${op.id}`).join(",");
+    leaks.push(
+      `delta@${delta.tick} carried ${collection.name} (${ops}) to ${spatial?.clientId ?? `role ${role || '""'}`}` + (desc.visibility === "spatial-grid" ? ` outside radius ${radiusText(desc, spatial)} from anchor ${spatial?.clientId ?? "?"}` : "")
+    );
   }
   return leaks;
 }
@@ -36,10 +75,21 @@ function isDefaultRecord(desc, value) {
   }
   return true;
 }
-function snapshotVisibilityLeaks(ext, role, state) {
+function snapshotVisibilityLeaks(ext, role, state, spatial) {
   const allowed = visibleNames(ext, role);
+  const policy = policyFor(ext, role, spatial);
   const leaks = [];
   for (const desc of ext.collections) {
+    if (desc.visibility === "spatial-grid" && policy) {
+      const collection = state[desc.name];
+      const ids = collection ? [...collection.ids()].filter((id) => !policy.maySeeEntity(desc, id)) : [];
+      if (ids.length > 0) {
+        leaks.push(
+          `snapshot carried ${desc.name}[${ids.join(",")}] to ${spatial?.clientId ?? "?"} outside radius ${radiusText(desc, spatial)}`
+        );
+      }
+      continue;
+    }
     if (allowed.has(desc.name)) continue;
     if (desc.kind === "entity") {
       const size = state[desc.name]?.size ?? 0;
@@ -53,9 +103,9 @@ function snapshotVisibilityLeaks(ext, role, state) {
   }
   return leaks;
 }
-function frameVisibilityLeaks(ext, role, type, payload) {
+function frameVisibilityLeaks(ext, role, type, payload, spatial) {
   if (type !== FrameType.DELTA && type !== FrameType.CORRECT) return [];
-  return deltaVisibilityLeaks(ext, role, decodeDelta(ext, payload));
+  return deltaVisibilityLeaks(ext, role, decodeDelta(ext, payload), spatial);
 }
 
 // src/observer.ts
@@ -65,10 +115,14 @@ import {
   decodeFrame,
   decodeReply,
   decodeWelcome,
-  errorByCode
+  errorByCode,
+  readCorrectClientTick
 } from "@irtio/protocol";
 import {
+  ByteReader,
+  applyDelta,
   decodeDelta as decodeDelta2,
+  decodeDeltaFrom,
   decodeSnapshot
 } from "@irtio/schema";
 
@@ -136,6 +190,28 @@ function makeTrace(startedAt, rings) {
 }
 
 // src/observer.ts
+function simulationOnly(ext, delta, predicts) {
+  let sawSync = false;
+  let sawPredicted = false;
+  for (const dc of delta.collections) {
+    const desc = ext.collections.find((c) => c.name === dc.name);
+    const physics = desc?.physics;
+    if (!desc || !physics) return "mixed";
+    for (const op of dc.ops) {
+      if (op.op !== "update") return "mixed";
+      const predicted = predicts(dc.name, op.id);
+      for (const index of op.mask.fields) {
+        const field = desc.fields[index];
+        if (!field || !physics.bodyFields.has(field.name)) return "mixed";
+        if (predicted) sawPredicted = true;
+        else sawSync = true;
+      }
+    }
+  }
+  if (sawPredicted && !sawSync) return "predicted";
+  if (sawSync && !sawPredicted) return "sync";
+  return "mixed";
+}
 var WriteLog = class {
   constructor(limit = 4096) {
     this.limit = limit;
@@ -177,6 +253,7 @@ var SecondWindow = class {
     return this.sum;
   }
 };
+var SPATIAL_SLACK_CELLS = 1;
 var DETAIL_LIMIT = 5;
 var VIOLATION_COOLDOWN_MS = 1e3;
 var BotObserver = class {
@@ -198,14 +275,47 @@ var BotObserver = class {
   bytesIn = 0;
   bytesOut = 0;
   corrections = 0;
+  syncCorrections = 0;
+  suppressedCorrections = 0;
+  mispredictions = 0;
+  /**
+   * Does this bot's client currently predict `collection[id]` in a local world? Assigned by
+   * `spawnBots` once the room exists (`room.prediction`); prediction status is client-local, so
+   * it cannot be derived from the bytes the observer otherwise sticks to.
+   */
+  predictsBody;
+  mispredictionMagnitude = 0;
+  mispredictionMax = 0;
+  snaps = 0;
   calls = 0;
   errors = 0;
   disconnects = 0;
   peakBytesInPerSec = 0;
   peakCorrectionsPerSec = 0;
+  /**
+   * Spatial-grid ops actually put to the AOI policy. Zero on a run whose room has no spatial
+   * collection; zero on a run that *does* and would mean the invariant passed vacuously, which is
+   * exactly the bug this counter exists to make visible in the report.
+   */
+  spatialOpsJudged = 0;
+  /**
+   * The bot's own materialized view: the `WELCOME` snapshot, plus every `DELTA`/`CORRECT` since.
+   *
+   * This is not server truth and never claims to be. It is what the AOI contract is *about*: the
+   * viewer's anchor is the record in the same collection whose id is the viewer's client id, and
+   * that record is always visible to its own client, so the bot holds its own true anchor. Every
+   * other record's position arrives inside the very op being judged — a record the server should
+   * not have sent is convicted by the position the server itself reported for it. The question
+   * answered is "was I sent something outside my own radius", which is the whole contract.
+   */
+  view;
+  /** Ids delivered so far, per collection, so an AOI departure `remove` is not read as a leak. */
+  seen = /* @__PURE__ */ new Map();
   bytesWindow = new SecondWindow();
   correctWindow = new SecondWindow();
   cooldown = /* @__PURE__ */ new Map();
+  /** The last inbound `CORRECT` trace entry, so `onCorrection` can finish its note. */
+  lastCorrectEntry;
   get stats() {
     return {
       index: this.options.index,
@@ -216,6 +326,12 @@ var BotObserver = class {
       bytesIn: this.bytesIn,
       bytesOut: this.bytesOut,
       corrections: this.corrections,
+      syncCorrections: this.syncCorrections,
+      suppressedCorrections: this.suppressedCorrections,
+      mispredictions: this.mispredictions,
+      mispredictionMagnitude: this.mispredictionMagnitude,
+      mispredictionMax: this.mispredictionMax,
+      snaps: this.snaps,
       calls: this.calls,
       errors: this.errors,
       disconnects: this.disconnects,
@@ -268,7 +384,7 @@ var BotObserver = class {
       note = err instanceof Error ? err.message : String(err);
       this.violate("schema-validity", `${frameName(type)} did not decode: ${note}`);
     }
-    this.ring.push({
+    const entry = {
       at: now - this.options.startedAt,
       bot: this.options.index,
       dir,
@@ -276,7 +392,9 @@ var BotObserver = class {
       frame: frameName(type),
       bytes: bytes.length,
       ...note !== void 0 ? { note } : {}
-    });
+    };
+    this.ring.push(entry);
+    if (dir === "in" && type === FrameType3.CORRECT) this.lastCorrectEntry = entry;
   }
   /** Decodes the payload independently. Throws on a bad frame; the caller counts that. */
   inspect(dir, type, bytes, now) {
@@ -291,8 +409,11 @@ var BotObserver = class {
         return this.onWelcome(decodeWelcome(payload));
       case FrameType3.DELTA:
         return this.onDelta(decodeDelta2(this.options.ext, payload), now);
-      case FrameType3.CORRECT:
-        return this.onCorrect(decodeDelta2(this.options.ext, payload), now);
+      case FrameType3.CORRECT: {
+        const r = new ByteReader(payload);
+        const delta = decodeDeltaFrom(this.options.ext, r);
+        return this.onCorrect(delta, readCorrectClientTick(r), now);
+      }
       case FrameType3.ERROR:
         return this.onError(payload);
       case FrameType3.REPLY:
@@ -306,23 +427,40 @@ var BotObserver = class {
     this.role = welcome.role;
     this.roomId = welcome.roomId;
     const snapshot = decodeSnapshot(this.options.ext, welcome.snapshot);
-    for (const leak of snapshotVisibilityLeaks(this.options.ext, this.role, snapshot.state)) {
+    this.view = snapshot.state;
+    this.rememberSnapshot(snapshot.state);
+    this.countSpatialSnapshot(snapshot.state);
+    for (const leak of snapshotVisibilityLeaks(
+      this.options.ext,
+      this.role,
+      snapshot.state,
+      this.spatialContext()
+    )) {
       this.violate("visibility-leak", leak);
     }
     return `joined ${welcome.roomId} as ${welcome.clientId}/${welcome.role || "default"}`;
   }
   onDelta(delta, now) {
-    for (const leak of deltaVisibilityLeaks(this.options.ext, this.role, delta)) {
-      this.violate("visibility-leak", leak);
-    }
+    this.checkVisibility(delta);
     this.matchWrites(delta, now);
     return void 0;
   }
-  onCorrect(delta, now) {
-    this.corrections++;
-    for (const leak of deltaVisibilityLeaks(this.options.ext, this.role, delta)) {
-      this.violate("visibility-leak", leak);
+  onCorrect(delta, clientTick, now) {
+    this.checkVisibility(delta);
+    const names = delta.collections.map((c) => c.name).join(",");
+    const kind = simulationOnly(
+      this.options.ext,
+      delta,
+      (c, id) => this.predictsBody ? this.predictsBody(c, id) : false
+    );
+    if (kind === "sync") {
+      this.syncCorrections++;
+      return `synced ${names}`;
     }
+    if (kind === "predicted") {
+      return `judged ${names}${clientTick !== void 0 ? ` (clientTick ${clientTick})` : ""}`;
+    }
+    this.corrections++;
     const perSec = this.correctWindow.add(now, 1);
     if (perSec > this.peakCorrectionsPerSec) this.peakCorrectionsPerSec = perSec;
     if (perSec > this.options.thresholds.correctionsPerSecMax) {
@@ -332,7 +470,137 @@ var BotObserver = class {
         true
       );
     }
-    return `corrected ${delta.collections.map((c) => c.name).join(",")}`;
+    return `corrected ${names}${clientTick !== void 0 ? ` (clientTick ${clientTick})` : ""}`;
+  }
+  /**
+   * The room's `correct` event, one per correction op — the only source of `previous` (the local
+   * prediction the server overrode) and of the `snapped` flag, neither of which a frame-level
+   * decode can know. Wired up by `spawnBots` via `room.on('correct', ...)`.
+   */
+  onCorrection(correction) {
+    if (correction.simulation) return;
+    if (correction.suppressed) {
+      this.suppressedCorrections++;
+      return;
+    }
+    const desc = this.options.ext.collections.find(
+      (c) => c.name === correction.collection
+    );
+    const predictedBody = desc?.physics !== void 0 && correction.fields.length > 0 && correction.fields.every((f) => desc.physics?.bodyFields.has(f));
+    if (predictedBody) {
+      this.corrections++;
+      const now = Date.now();
+      const perSec = this.correctWindow.add(now, 1);
+      if (perSec > this.peakCorrectionsPerSec) this.peakCorrectionsPerSec = perSec;
+      if (perSec > this.options.thresholds.correctionsPerSecMax) {
+        this.violate(
+          "correction-storm",
+          `${perSec} corrections/s over the ${this.options.thresholds.correctionsPerSecMax}/s threshold`,
+          true
+        );
+      }
+    }
+    let magnitude = 0;
+    for (const field of correction.fields) {
+      const prev = correction.previous[field];
+      const next = correction.patch[field];
+      if (typeof prev === "number" && typeof next === "number") {
+        magnitude += Math.abs(next - prev);
+      }
+    }
+    this.mispredictions++;
+    this.mispredictionMagnitude += magnitude;
+    if (magnitude > this.mispredictionMax) this.mispredictionMax = magnitude;
+    const thresholds = this.options.thresholds;
+    if (magnitude > thresholds.mispredictionMagnitudeMax) {
+      this.violate(
+        "misprediction",
+        `${correction.collection}[${correction.id}] snapped ${magnitude.toFixed(1)} units, over the ${thresholds.mispredictionMagnitudeMax} threshold`,
+        true
+      );
+    }
+    if (correction.snapped) {
+      this.snaps++;
+      if (this.snaps > thresholds.snapsMax) {
+        this.violate(
+          "snaps",
+          `snap #${this.snaps} (${correction.collection}[${correction.id}] @tick ${correction.tick}) over the tolerated ${thresholds.snapsMax}`
+        );
+      }
+    }
+    const entry = this.lastCorrectEntry;
+    if (entry) {
+      const what = correction.snapped ? `${correction.collection}[${correction.id}] snapped \u0394${magnitude.toFixed(1)}` : `${correction.collection}[${correction.id}] \u0394${magnitude.toFixed(1)} replayed ${correction.replayed}`;
+      entry.note = entry.note === void 0 ? what : `${entry.note} | ${what}`;
+    }
+  }
+  // -- visibility -----------------------------------------------------------
+  spatialContext() {
+    if (!this.view || this.id === "") return void 0;
+    return {
+      authority: this.view,
+      clientId: this.id,
+      seen: this.seen,
+      slackCells: SPATIAL_SLACK_CELLS
+    };
+  }
+  /**
+   * Applies the delta to the bot's view *first*, then judges: a record the server should not have
+   * sent has to be in the view for its own reported position to convict it. `seen` is updated
+   * afterwards, so a `remove` is judged against what the bot had been told about before this
+   * frame — a departing neighbour, not a leak.
+   */
+  checkVisibility(delta) {
+    if (this.view) applyDelta(this.options.ext, this.view, delta);
+    this.countSpatialDelta(delta);
+    for (const leak of deltaVisibilityLeaks(
+      this.options.ext,
+      this.role,
+      delta,
+      this.spatialContext()
+    )) {
+      this.violate("visibility-leak", leak);
+    }
+    this.remember(delta);
+  }
+  countSpatialDelta(delta) {
+    if (!this.view || this.id === "") return;
+    for (const collection of delta.collections) {
+      const desc = this.options.ext.collection(collection.name);
+      if (desc.visibility === "spatial-grid") this.spatialOpsJudged += collection.ops.length;
+    }
+  }
+  countSpatialSnapshot(state) {
+    for (const desc of this.options.ext.collections) {
+      if (desc.visibility !== "spatial-grid") continue;
+      this.spatialOpsJudged += state[desc.name]?.size ?? 0;
+    }
+  }
+  ids(collection) {
+    let ids = this.seen.get(collection);
+    if (!ids) {
+      ids = /* @__PURE__ */ new Set();
+      this.seen.set(collection, ids);
+    }
+    return ids;
+  }
+  rememberSnapshot(state) {
+    for (const desc of this.options.ext.collections) {
+      if (desc.kind !== "entity") continue;
+      const collection = state[desc.name];
+      if (!collection) continue;
+      const ids = this.ids(desc.name);
+      for (const id of collection.ids()) ids.add(id);
+    }
+  }
+  remember(delta) {
+    for (const collection of delta.collections) {
+      const ids = this.ids(collection.name);
+      for (const op of collection.ops) {
+        if (op.op === "remove") ids.delete(op.id);
+        else ids.add(op.id);
+      }
+    }
   }
   onError(payload) {
     const error = decodeErrorPayload(payload);
@@ -503,8 +771,11 @@ function detailFor(name, observers, violations, thresholds) {
   switch (name) {
     case "schema-validity":
       return violations === 0 ? "every snapshot and delta decoded" : `${violations} frame(s) failed to decode${examples(observers, name)}`;
-    case "visibility-leak":
-      return violations === 0 ? "no collection reached a role that cannot see it" : `${violations} leak(s)${examples(observers, name)}`;
+    case "visibility-leak": {
+      const spatial = observers.reduce((sum, o) => sum + o.spatialOpsJudged, 0);
+      const judged = `, ${spatial} spatial-grid op(s) judged against each bot's own anchor`;
+      return violations === 0 ? `no collection reached a role that cannot see it${judged}` : `${violations} leak(s)${judged}${examples(observers, name)}`;
+    }
     case "bandwidth": {
       const worst = peak(observers, (o) => o.peakBytesInPerSec);
       return `peak ${worst} B/s in per bot, budget ${thresholds.budgetBytesPerSec} B/s${violations === 0 ? "" : examples(observers, name)}`;
@@ -515,8 +786,24 @@ function detailFor(name, observers, violations, thresholds) {
     }
     case "correction-storm": {
       const corrections = observers.reduce((sum, o) => sum + o.corrections, 0);
+      const synced = observers.reduce((sum, o) => sum + o.syncCorrections, 0);
+      const suppressed = observers.reduce((sum, o) => sum + o.suppressedCorrections, 0);
       const worst = peak(observers, (o) => o.peakCorrectionsPerSec);
-      return `${corrections} correction(s), peak ${worst}/s per bot, threshold ${thresholds.correctionsPerSecMax}/s${violations === 0 ? "" : examples(observers, name)}`;
+      return `${corrections} correction(s), peak ${worst}/s per bot, threshold ${thresholds.correctionsPerSecMax}/s${synced > 0 ? ` (+${synced} body-sync)` : ""}${suppressed > 0 ? ` (+${suppressed} within-epsilon)` : ""}${violations === 0 ? "" : examples(observers, name)}`;
+    }
+    case "misprediction": {
+      const count = observers.reduce((sum, o) => sum + o.mispredictions, 0);
+      if (count === 0) return "no corrections, nothing mispredicted";
+      const totalMagnitude = observers.reduce((sum, o) => sum + o.mispredictionMagnitude, 0);
+      const worst = peak(observers, (o) => o.mispredictionMax);
+      const cap = thresholds.mispredictionMagnitudeMax;
+      return `peak ${round(worst)} units, mean ${round(totalMagnitude / count)} over ${count} correction(s)${Number.isFinite(cap) ? `, threshold ${cap}` : ""}${violations === 0 ? "" : examples(observers, name)}`;
+    }
+    case "snaps": {
+      const count = observers.reduce((sum, o) => sum + o.snaps, 0);
+      if (count === 0) return "no snaps (every correction replayed within the resim window)";
+      const cap = thresholds.snapsMax;
+      return `${count} snap(s) (cap-exceeded reconciliations)${Number.isFinite(cap) ? `, tolerated ${cap}` : ""}${violations === 0 ? "" : examples(observers, name)}`;
     }
     case "disconnects": {
       const count = observers.reduce((sum, o) => sum + o.disconnects, 0);
@@ -541,6 +828,12 @@ function buildReport(options) {
     bytesIn: perBot.reduce((sum, b) => sum + b.bytesIn, 0),
     bytesOut: perBot.reduce((sum, b) => sum + b.bytesOut, 0),
     corrections: perBot.reduce((sum, b) => sum + b.corrections, 0),
+    syncCorrections: perBot.reduce((sum, b) => sum + b.syncCorrections, 0),
+    suppressedCorrections: perBot.reduce((sum, b) => sum + b.suppressedCorrections, 0),
+    mispredictions: perBot.reduce((sum, b) => sum + b.mispredictions, 0),
+    mispredictionMagnitude: perBot.reduce((sum, b) => sum + b.mispredictionMagnitude, 0),
+    mispredictionMax: perBot.reduce((max, b) => Math.max(max, b.mispredictionMax), 0),
+    snaps: perBot.reduce((sum, b) => sum + b.snaps, 0),
     calls: perBot.reduce((sum, b) => sum + b.calls, 0),
     errors: perBot.reduce((sum, b) => sum + b.errors, 0)
   };
@@ -570,6 +863,11 @@ function ownableCollections(schema) {
     (c) => c.kind === "entity" && !c.serverOwned
   );
 }
+function writableFields(desc, cheat) {
+  if (!desc.physics || cheat) return desc.fields;
+  const intents = new Set(desc.physics.intents);
+  return desc.fields.filter((f) => intents.has(f.name));
+}
 function voidServerRpcs(schema) {
   return rpcTable(schema).filter((r) => r.direction === "server" && r.returns === void 0);
 }
@@ -603,14 +901,17 @@ function randomScript(schema, options = {}) {
     }
   };
   function writeFields(bot, desc, id, instance, origins) {
-    const count = Math.min(fieldsPerStep, desc.fields.length);
+    const fields = writableFields(desc, cheat);
+    if (fields.length === 0) return;
+    const count = Math.min(fieldsPerStep, fields.length);
     for (let i = 0; i < count; i++) {
-      const field = bot.rng.pick(desc.fields);
+      const field = bot.rng.pick(fields);
       if (!field) continue;
       const current = instance[field.name];
       const key = `${desc.name} ${id} ${field.name}`;
       if (typeof current === "number" && !origins.has(key)) origins.set(key, current);
-      const value = nextValue(bot.rng, field.type, current, {
+      const isIntent = !cheat && desc.physics?.intents.includes(field.name) === true;
+      const value = isIntent ? Math.fround(bot.rng.float(-1, 1)) : nextValue(bot.rng, field.type, current, {
         step,
         cheat,
         origin: origins.get(key)
@@ -732,7 +1033,9 @@ async function spawnBots(n, options = {}) {
   const thresholds = {
     budgetBytesPerSec: options.budgetBytesPerSec ?? DEFAULT_THRESHOLDS.budgetBytesPerSec,
     correctionsPerSecMax: options.correctionsPerSecMax ?? DEFAULT_THRESHOLDS.correctionsPerSecMax,
-    handlerErrorsMax: options.handlerErrorsMax ?? DEFAULT_THRESHOLDS.handlerErrorsMax
+    handlerErrorsMax: options.handlerErrorsMax ?? DEFAULT_THRESHOLDS.handlerErrorsMax,
+    mispredictionMagnitudeMax: options.mispredictionMagnitudeMax ?? DEFAULT_THRESHOLDS.mispredictionMagnitudeMax,
+    snapsMax: options.snapsMax ?? DEFAULT_THRESHOLDS.snapsMax
   };
   const ext = options.schema ? withBuiltins(options.schema) : relaySchema;
   const seed = options.seed ?? DEFAULT_SEED;
@@ -766,8 +1069,12 @@ async function spawnBots(n, options = {}) {
     const room = options.schema ? await joinRoom(options.schema, {
       ...common,
       ...options.flushMs !== void 0 ? { writeIntervalMs: options.flushMs } : {},
-      ...options.rpc !== void 0 ? { rpc: options.rpc } : {}
+      ...options.rpc !== void 0 ? { rpc: options.rpc } : {},
+      ...options.physics !== void 0 ? { physics: options.physics } : {}
     }) : await joinRelay(common);
+    room.on("correct", (correction) => observer.onCorrection(correction));
+    const prediction = room.prediction;
+    if (prediction) observer.predictsBody = (c, id) => prediction.predicts(c, id);
     observers[index] = observer;
     return new BotImpl(index, room, observer, seed + index, startedAt);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/bots",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "irtio bot runtime: N real clients, scripted behaviours, trace recorder, built-in invariants",
   "license": "MIT",
   "publishConfig": {
@@ -19,10 +19,10 @@
     "dist"
   ],
   "dependencies": {
-    "@irtio/client": "0.1.0",
-    "@irtio/protocol": "0.1.0",
-    "@irtio/schema": "0.1.0",
-    "@irtio/runtime": "0.1.0"
+    "@irtio/runtime": "0.2.0",
+    "@irtio/client": "0.2.0",
+    "@irtio/protocol": "0.2.0",
+    "@irtio/schema": "0.2.0"
   },
   "scripts": {
     "build": "tsup",