@irtio/bots 0.5.2 → 0.7.0

package/dist/index.js

@@ -14,7 +14,14 @@ var INVARIANT_NAMES = [
   "misprediction",
   "snaps",
   "disconnects",
-  "tick-health"
+  "tick-health",
+  // D70 (M6 lane C): typed peer messages a bot could not read. A shape mismatch between a bot
+  // script and the schema was previously a silent nothing-happened; this makes it a red run.
+  "typed-message-drops",
+  // M6 lane E (D73-c): every party's members share a room, and no room holds more bots than its
+  // ticket said it seats. Listed only on a run that queued — a run that built its own room has no
+  // parties to be intact, so the row is absent rather than unread. See `partyIntegrityResult`.
+  "party-integrity"
 ];
 var DEFAULT_THRESHOLDS = {
   budgetBytesPerSec: 128e3,
@@ -22,7 +29,8 @@ var DEFAULT_THRESHOLDS = {
   handlerErrorsMax: 0,
   mispredictionMagnitudeMax: Number.POSITIVE_INFINITY,
   snapsMax: Number.POSITIVE_INFINITY,
-  overrunsMax: 0
+  overrunsMax: 0,
+  typedMessageDropsMax: 0
 };
 var widenedSchemas = /* @__PURE__ */ new WeakMap();
 function widenGrids(ext, slack) {
@@ -110,29 +118,390 @@ function frameVisibilityLeaks(ext, role, type, payload, spatial) {
   return deltaVisibilityLeaks(ext, role, decodeDelta(ext, payload), spatial);
 }
 
+// src/conditions.ts
+import { FrameType as FrameType2 } from "@irtio/protocol";
+var STATE_FRAMES = /* @__PURE__ */ new Set([
+  FrameType2.WRITE,
+  FrameType2.DELTA,
+  FrameType2.CORRECT,
+  FrameType2.MSG
+]);
+var DUPLICATE_GAP_MS = 1;
+var DEFAULT_REORDER_MS = 50;
+function newConditionCounters() {
+  return {
+    droppedOut: 0,
+    droppedIn: 0,
+    duplicatedOut: 0,
+    duplicatedIn: 0,
+    reorderedOut: 0,
+    reorderedIn: 0,
+    delayed: 0
+  };
+}
+function hasConditions(c) {
+  if (!c) return false;
+  return (c.rttMs ?? 0) > 0 || (c.jitterMs ?? 0) > 0 || (c.loss ?? 0) > 0 || (c.duplicate ?? 0) > 0 || (c.reorder ?? 0) > 0;
+}
+function describeConditions(c) {
+  const parts = [];
+  if ((c.rttMs ?? 0) > 0) parts.push(`rtt ${c.rttMs} ms`);
+  if ((c.jitterMs ?? 0) > 0) parts.push(`jitter ${c.jitterMs} ms`);
+  if ((c.loss ?? 0) > 0) parts.push(`loss ${pct(c.loss ?? 0)}`);
+  if ((c.duplicate ?? 0) > 0) parts.push(`duplicate ${pct(c.duplicate ?? 0)}`);
+  if ((c.reorder ?? 0) > 0) {
+    parts.push(`reorder ${pct(c.reorder ?? 0)} within ${c.reorderMs ?? DEFAULT_REORDER_MS} ms`);
+  }
+  return parts.length === 0 ? "none" : parts.join(", ");
+}
+function pct(v) {
+  return `${Math.round(v * 1e3) / 10}%`;
+}
+var realTimers = {
+  now: () => Date.now(),
+  setTimeout(fn, ms) {
+    const timer = setTimeout(fn, ms);
+    timer.unref?.();
+    return () => clearTimeout(timer);
+  }
+};
+function conditionedTransport(base, conditions, rng, options = {}) {
+  const counters = options.counters ?? newConditionCounters();
+  const timers = options.timers ?? realTimers;
+  const rttMs = Math.max(0, conditions.rttMs ?? 0);
+  const jitterMs = Math.max(0, conditions.jitterMs ?? 0);
+  const loss = clamp01(conditions.loss ?? 0);
+  const duplicate = clamp01(conditions.duplicate ?? 0);
+  const reorder = clamp01(conditions.reorder ?? 0);
+  const reorderMs = Math.max(0, conditions.reorderMs ?? DEFAULT_REORDER_MS);
+  return {
+    connect(url) {
+      const socket = base.connect(url);
+      const cancels = /* @__PURE__ */ new Set();
+      let closed = false;
+      let nextIn = 0;
+      let nextOut = 0;
+      function schedule(delayMs, run) {
+        if (closed) return;
+        counters.delayed++;
+        let cancel = () => void 0;
+        const fire = () => {
+          cancels.delete(cancel);
+          if (!closed) run();
+        };
+        if (delayMs <= 0) {
+          cancel = timers.setTimeout(fire, 0);
+        } else {
+          cancel = timers.setTimeout(fire, delayMs);
+        }
+        cancels.add(cancel);
+      }
+      function deliver(dir, bytes, run) {
+        const type = bytes.length > 0 ? bytes[0] ?? -1 : -1;
+        const stateful = STATE_FRAMES.has(type);
+        if (stateful && loss > 0 && rng.next() < loss) {
+          if (dir === "in") counters.droppedIn++;
+          else counters.droppedOut++;
+          return;
+        }
+        const now = timers.now();
+        let at = now + rttMs / 2 + (jitterMs > 0 ? rng.next() * jitterMs : 0);
+        const reordered = stateful && reorder > 0 && rng.next() < reorder;
+        if (reordered) {
+          at += reorderMs > 0 ? rng.next() * reorderMs : 0;
+          if (dir === "in") counters.reorderedIn++;
+          else counters.reorderedOut++;
+        } else {
+          const floor = dir === "in" ? nextIn : nextOut;
+          at = Math.max(at, floor);
+          if (dir === "in") nextIn = at;
+          else nextOut = at;
+        }
+        schedule(at - now, run);
+        if (stateful && duplicate > 0 && rng.next() < duplicate) {
+          if (dir === "in") counters.duplicatedIn++;
+          else counters.duplicatedOut++;
+          schedule(at - now + DUPLICATE_GAP_MS, run);
+        }
+      }
+      const wrapper = {
+        onopen: null,
+        onmessage: null,
+        onclose: null,
+        onerror: null,
+        send(bytes) {
+          const copy = bytes.slice();
+          deliver("out", copy, () => socket.send(copy));
+        },
+        close() {
+          closed = true;
+          for (const cancel of cancels) cancel();
+          cancels.clear();
+          socket.close();
+        }
+      };
+      socket.onopen = () => wrapper.onopen?.();
+      socket.onmessage = (bytes) => {
+        const copy = bytes.slice();
+        deliver("in", copy, () => wrapper.onmessage?.(copy));
+      };
+      socket.onclose = (info) => {
+        closed = true;
+        for (const cancel of cancels) cancel();
+        cancels.clear();
+        wrapper.onclose?.(info);
+      };
+      socket.onerror = (error) => wrapper.onerror?.(error);
+      return wrapper;
+    }
+  };
+}
+function clamp01(v) {
+  return Math.min(1, Math.max(0, v));
+}
+
+// src/hits.ts
+function entityValue(frameState, collection, id) {
+  const table = frameState[collection];
+  if (typeof table !== "object" || table === null) return void 0;
+  const record = table[id];
+  if (typeof record !== "object" || record === null) return void 0;
+  const value = record.value;
+  return typeof value === "object" && value !== null ? value : void 0;
+}
+function correlateShots(shots, dump) {
+  const frames = dump.frames;
+  return shots.map((shot) => {
+    const exact = shot.serverTick !== void 0;
+    const frame = exact ? frames.find((f) => f.tick === shot.serverTick) : frames.find((f) => f.at >= shot.sentAt + shot.uplinkMs);
+    const estimated = !exact && shot.uplinkMs > 0;
+    const rewound = shot.rewound;
+    if (frame === void 0) {
+      return {
+        ...shot,
+        serverTick: exact ? shot.serverTick : void 0,
+        estimated,
+        rewound,
+        authoritative: void 0,
+        missDistance: void 0,
+        unresolved: frames.length === 0 ? "nothing was recorded, so there is no tick to judge this shot against" : exact ? `the room judged this shot at tick ${shot.serverTick}, which is not in the recording` : `the shot lands after the last recorded tick (${frames[frames.length - 1]?.tick})`
+      };
+    }
+    const value = entityValue(frame.state, shot.collection, shot.target);
+    if (value === void 0) {
+      return {
+        ...shot,
+        serverTick: frame.tick,
+        estimated,
+        rewound,
+        authoritative: void 0,
+        missDistance: void 0,
+        unresolved: `${shot.collection}.${shot.target} is not in the recording at tick ${frame.tick}`
+      };
+    }
+    const authoritative = {};
+    let sum = 0;
+    let missing;
+    for (const [field, aimed] of Object.entries(shot.aim)) {
+      const actual = value[field];
+      if (typeof actual !== "number") {
+        missing ??= `${shot.collection}.${shot.target}.${field} is not a number on the timeline`;
+        continue;
+      }
+      authoritative[field] = actual;
+      sum += (actual - aimed) ** 2;
+    }
+    if (missing !== void 0) {
+      return {
+        ...shot,
+        serverTick: frame.tick,
+        estimated,
+        rewound,
+        authoritative,
+        missDistance: void 0,
+        unresolved: missing
+      };
+    }
+    return {
+      ...shot,
+      serverTick: frame.tick,
+      estimated,
+      rewound,
+      authoritative,
+      missDistance: Math.sqrt(sum)
+    };
+  });
+}
+
+// src/truth.ts
+function captureClientState(schema, state) {
+  const view = state ?? {};
+  const out = {};
+  for (const desc of schema.collections) {
+    const raw = view[desc.name];
+    if (raw === void 0) continue;
+    const collection = asCollection(raw);
+    if (collection) {
+      const records = {};
+      for (const id of collection.ids()) {
+        const value = collection.get(id);
+        if (value === void 0) continue;
+        records[id] = { owner: collection.ownerOf(id), value: plain(value) };
+      }
+      out[desc.name] = records;
+    } else {
+      out[desc.name] = plain(raw);
+    }
+  }
+  return out;
+}
+function asCollection(value) {
+  return value !== null && typeof value === "object" && typeof value.ownerOf === "function" ? value : void 0;
+}
+function plain(value) {
+  if (value === null || typeof value !== "object") return value;
+  const out = {};
+  for (const [k, v] of Object.entries(value)) out[k] = plain(v);
+  return out;
+}
+function diffAgainstSave(clients, saveState, meta) {
+  const bots = [];
+  const all = [];
+  let compared = 0;
+  for (const client of clients) {
+    const differences = [];
+    let seen = 0;
+    for (const [collection, held] of Object.entries(client.state)) {
+      const authoritative = saveState[collection];
+      if (isTable(held)) {
+        const table = isTable(authoritative) ? authoritative : {};
+        for (const [id, record] of Object.entries(held)) {
+          seen++;
+          const mine = record;
+          const theirs = table[id];
+          if (theirs === void 0) {
+            differences.push({
+              bot: client.bot,
+              collection,
+              id,
+              client: mine.value,
+              save: void 0,
+              detail: `bot ${client.bot} holds ${collection}.${id}, which the save does not have. A client holding an entity authority does not is a desync, not a visibility gap.`
+            });
+            continue;
+          }
+          if (mine.owner !== theirs.owner) {
+            differences.push({
+              bot: client.bot,
+              collection,
+              id,
+              field: "owner",
+              client: mine.owner,
+              save: theirs.owner,
+              detail: `bot ${client.bot} has ${collection}.${id} owned by ${String(mine.owner)}, the save says ${String(theirs.owner)}`
+            });
+          }
+          compareValues(client.bot, collection, id, mine.value, theirs.value, differences);
+        }
+      } else {
+        seen++;
+        compareValues(client.bot, collection, void 0, held, authoritative, differences);
+      }
+    }
+    compared += seen;
+    bots.push({ bot: client.bot, compared: seen, differences, ok: differences.length === 0 });
+    all.push(...differences);
+  }
+  return {
+    ok: all.length === 0,
+    bots,
+    compared,
+    differences: all,
+    saveTick: meta.saveTick,
+    saveVersion: meta.saveVersion
+  };
+}
+function isTable(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function compareValues(bot, collection, id, client, save, out) {
+  const where = id === void 0 ? collection : `${collection}.${id}`;
+  if (!isTable(client)) {
+    if (!same(client, save)) {
+      out.push({
+        bot,
+        collection,
+        ...id !== void 0 ? { id } : {},
+        client,
+        save,
+        detail: `bot ${bot} has ${where} = ${show(client)}, the save has ${show(save)}`
+      });
+    }
+    return;
+  }
+  const theirs = isTable(save) ? save : void 0;
+  for (const [field, value] of Object.entries(client)) {
+    const actual = theirs?.[field];
+    if (same(value, actual)) continue;
+    out.push({
+      bot,
+      collection,
+      ...id !== void 0 ? { id } : {},
+      field,
+      client: value,
+      save: actual,
+      detail: `bot ${bot} has ${where}.${field} = ${show(value)}, the save has ${show(actual)}`
+    });
+  }
+}
+function same(a, b) {
+  if (a === b) return true;
+  if (typeof a === "number" && typeof b === "number") {
+    return Number.isNaN(a) && Number.isNaN(b);
+  }
+  if (isTable(a) && isTable(b)) {
+    const keys = /* @__PURE__ */ new Set([...Object.keys(a), ...Object.keys(b)]);
+    for (const k of keys) if (!same(a[k], b[k])) return false;
+    return true;
+  }
+  return false;
+}
+function show(value) {
+  if (value === void 0) return "nothing";
+  if (typeof value === "number") return String(Math.round(value * 1e3) / 1e3);
+  if (typeof value === "string") return JSON.stringify(value);
+  if (isTable(value)) return JSON.stringify(value);
+  return String(value);
+}
+
 // src/observer.ts
 import {
-  FrameType as FrameType3,
+  FrameType as FrameType4,
   decodeErrorPayload,
   decodeFrame,
+  decodeMsg,
   decodeReply,
   decodeWelcome,
   errorByCode,
-  readCorrectClientTick
+  readCorrectClientTick,
+  readSchemaPayload,
+  withBuiltins
 } from "@irtio/protocol";
 import {
   ByteReader,
   applyDelta,
   decodeDelta as decodeDelta2,
   decodeDeltaFrom,
-  decodeSnapshot
+  decodeFields,
+  decodeSnapshot,
+  schemaFromCanonical
 } from "@irtio/schema";
 
 // src/trace.ts
 import { writeFile } from "fs/promises";
-import { FrameType as FrameType2 } from "@irtio/protocol";
+import { FrameType as FrameType3 } from "@irtio/protocol";
 var FRAME_NAMES = new Map(
-  Object.entries(FrameType2).map(([name, value]) => [value, name])
+  Object.entries(FrameType3).map(([name, value]) => [value, name])
 );
 function frameName(type) {
   return FRAME_NAMES.get(type) ?? `UNKNOWN(${type})`;
@@ -192,27 +561,38 @@ function makeTrace(startedAt, rings) {
 }
 
 // src/observer.ts
-function simulationOnly(ext, delta, predicts) {
+function simulationOnly(ext, delta, kindOf) {
   let sawSync = false;
   let sawPredicted = false;
+  let sawProxied = 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);
+      const kind = kindOf(dc.name, op.id);
+      const predicted = kind === "predicted";
       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 (!field) return "mixed";
+        if (physics.bodyFields.has(field.name)) {
+          if (predicted) sawPredicted = true;
+          else if (kind === "proxied") sawProxied = true;
+          else sawSync = true;
+        } else if (!predicted && !physics.intents.includes(field.name)) {
+          sawSync = true;
+        } else {
+          return "mixed";
+        }
       }
     }
   }
-  if (sawPredicted && !sawSync) return "predicted";
-  if (sawSync && !sawPredicted) return "sync";
-  return "mixed";
+  const kinds = Number(sawPredicted) + Number(sawSync) + Number(sawProxied);
+  if (kinds !== 1) return "mixed";
+  if (sawPredicted) return "predicted";
+  if (sawProxied) return "proxied";
+  return "sync";
 }
 var WriteLog = class {
   constructor(limit = 4096) {
@@ -262,11 +642,22 @@ var BotObserver = class {
   constructor(options) {
     this.options = options;
     this.ring = new TraceRing(options.traceLimit);
+    this.ext = options.ext;
   }
   options;
   ring;
   violations = /* @__PURE__ */ new Map();
   counts = /* @__PURE__ */ new Map();
+  /**
+   * Bug #28: the decode extension, *mutable*. It starts as `options.ext` (the schema the run was
+   * spawned with) and is rebuilt in place when an inbound `SCHEMA` frame (13) lands — a D50
+   * additive `migrate` swaps the wire mid-session, the real client rebuilds its own decoders
+   * (`session.swapSchema`), and an observer still holding the v1 descriptor underruns on the v2
+   * resync WELCOME and fails `schema-validity` on a swap that was perfect.
+   */
+  ext;
+  /** How many `SCHEMA` frames rebuilt {@link ext}. For tests and the trace, like the client's. */
+  schemaSwaps = 0;
   id = "";
   role = "";
   roomId = "";
@@ -284,14 +675,29 @@ var BotObserver = class {
   bytesOut = 0;
   corrections = 0;
   syncCorrections = 0;
+  proxiedCorrections = 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.
+   * M6 lane E (D73-b): what this bot's client's local world holds for `collection[id]` right now.
+   * Assigned by `spawnBots` once the room exists (`room.prediction`); the local world's shape is
+   * client-local, so it cannot be derived from the bytes the observer otherwise sticks to.
+   *
+   * Unset means "no local world at all", which answers `absent` for everything — the behaviour a
+   * bot without physics has always had.
+   */
+  bodyKind;
+  /**
+   * M6 lane E (D73-a): the client's own `room.prediction`, when this bot joined with `physics` or
+   * `physics2d`. Held rather than copied because `active` flips once the engine has loaded, which
+   * happens off the join path — a boolean read at join time would say `false` on every run.
    */
-  predictsBody;
+  prediction;
+  /** D73-a: latched true the first time {@link prediction} reported an active local world. */
+  predicted = false;
+  /** D73-b: the high-water marks of `prediction.stats.proxies` / `.absent` across the run. */
+  proxies = 0;
+  absent = 0;
   mispredictionMagnitude = 0;
   mispredictionMax = 0;
   snaps = 0;
@@ -300,6 +706,10 @@ var BotObserver = class {
   disconnects = 0;
   peakBytesInPerSec = 0;
   peakCorrectionsPerSec = 0;
+  /** D70: peer-message counters, filled by `inspect`'s MSG case in both directions. */
+  messagesSent = 0;
+  messagesReceived = 0;
+  messagesDropped = 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
@@ -335,6 +745,7 @@ var BotObserver = class {
       bytesOut: this.bytesOut,
       corrections: this.corrections,
       syncCorrections: this.syncCorrections,
+      proxiedCorrections: this.proxiedCorrections,
       suppressedCorrections: this.suppressedCorrections,
       mispredictions: this.mispredictions,
       mispredictionMagnitude: this.mispredictionMagnitude,
@@ -344,7 +755,13 @@ var BotObserver = class {
       errors: this.errors,
       disconnects: this.disconnects,
       peakBytesInPerSec: this.peakBytesInPerSec,
-      peakCorrectionsPerSec: this.peakCorrectionsPerSec
+      peakCorrectionsPerSec: this.peakCorrectionsPerSec,
+      messagesSent: this.messagesSent,
+      messagesReceived: this.messagesReceived,
+      messagesDropped: this.messagesDropped,
+      predicting: this.predicted,
+      proxies: this.proxies,
+      absent: this.absent
     };
   }
   /** Counts a violation always; keeps an example, rate-limited per invariant when asked. */
@@ -370,6 +787,12 @@ var BotObserver = class {
   /** The `onFrame` hook. `bytes` is the whole frame, envelope byte included. */
   onFrame(dir, type, bytes) {
     const now = Date.now();
+    const prediction = this.prediction;
+    if (prediction?.active === true) {
+      this.predicted = true;
+      if (prediction.stats.proxies > this.proxies) this.proxies = prediction.stats.proxies;
+      if (prediction.stats.absent > this.absent) this.absent = prediction.stats.absent;
+    }
     let note;
     if (dir === "in") {
       this.framesIn++;
@@ -403,44 +826,101 @@ var BotObserver = class {
       ...note !== void 0 ? { note } : {}
     };
     this.ring.push(entry);
-    if (dir === "in" && type === FrameType3.CORRECT) this.lastCorrectEntry = entry;
+    if (dir === "in" && type === FrameType4.CORRECT) this.lastCorrectEntry = entry;
   }
   /** Decodes the payload independently. Throws on a bad frame; the caller counts that. */
   inspect(dir, type, bytes, now) {
     const payload = decodeFrame(bytes).payload;
     if (dir === "out") {
-      if (type === FrameType3.CALL) this.calls++;
-      if (type === FrameType3.WRITE) this.recordWrites(decodeDelta2(this.options.ext, payload), now);
+      if (type === FrameType4.CALL) this.calls++;
+      if (type === FrameType4.WRITE) this.recordWrites(decodeDelta2(this.ext, payload), now);
+      if (type === FrameType4.MSG) return this.onMsg("out", payload);
       return void 0;
     }
     switch (type) {
-      case FrameType3.WELCOME:
+      case FrameType4.WELCOME:
         return this.onWelcome(decodeWelcome(payload));
-      case FrameType3.DELTA:
-        return this.onDelta(decodeDelta2(this.options.ext, payload), now);
-      case FrameType3.CORRECT: {
+      case FrameType4.DELTA:
+        return this.onDelta(decodeDelta2(this.ext, payload), now);
+      case FrameType4.CORRECT: {
         const r = new ByteReader(payload);
-        const delta = decodeDeltaFrom(this.options.ext, r);
+        const delta = decodeDeltaFrom(this.ext, r);
         return this.onCorrect(delta, readCorrectClientTick(r), now);
       }
-      case FrameType3.ERROR:
+      case FrameType4.ERROR:
         return this.onError(payload);
-      case FrameType3.REPLY:
+      case FrameType4.REPLY:
         return this.onReply(payload);
+      case FrameType4.SCHEMA:
+        return this.onSchema(payload);
+      case FrameType4.MSG:
+        return this.onMsg("in", payload);
       default:
         return void 0;
     }
   }
+  /**
+   * D70: one peer message, in either direction, as a trace note.
+   *
+   * Before this, `MSG` fell through to `undefined` and a trace showed a frame with a byte count
+   * and nothing else — which was tolerable while every message was opaque bytes and is not now
+   * that some of them have declared shapes. A raw message notes its target; a typed one notes its
+   * name and its value when this bot holds the schema, and its index when it does not.
+   *
+   * A typed message this bot cannot read is counted as a **drop**, which is what the
+   * `typed-message-drops` invariant fails a run on. That is the whole point of the counter: a
+   * scenario sending a shape the schema does not describe used to be a message that silently
+   * never arrived.
+   */
+  onMsg(dir, payload) {
+    let msg;
+    try {
+      msg = decodeMsg(payload);
+    } catch (err) {
+      const why = err instanceof Error ? err.message : String(err);
+      if (dir === "in") this.dropTyped(`a MSG frame did not decode: ${why}`);
+      return `msg undecodable (${why})`;
+    }
+    const who = msg.target.kind === "client" ? msg.target.clientId : msg.target.kind === "role" ? `role:${msg.target.role}` : msg.target.kind;
+    if (!msg.typed) {
+      if (dir === "out") this.messagesSent++;
+      else this.messagesReceived++;
+      return `msg raw ${who} (${msg.payload.length}B)`;
+    }
+    const desc = (this.ext.messages ?? [])[msg.typed.index];
+    if (!desc) {
+      if (dir === "out") this.messagesSent++;
+      else this.dropTyped(`no message with index ${msg.typed.index} in this schema`);
+      return `msg typed #${msg.typed.index} (undecodable)`;
+    }
+    let value;
+    try {
+      value = decodeFields(desc.fields, msg.payload);
+    } catch {
+      if (dir === "out") this.messagesSent++;
+      else this.dropTyped(`${desc.name} did not decode against this schema`);
+      return `msg ${desc.name} (undecodable)`;
+    }
+    if (dir === "out") this.messagesSent++;
+    else this.messagesReceived++;
+    const arrow = dir === "out" ? "->" : "<-";
+    return `msg ${desc.name} ${arrow} ${who} ${JSON.stringify(value)}`;
+  }
+  /** D70: one typed message this bot could not read — a counter and an invariant violation. */
+  dropTyped(why) {
+    this.messagesDropped++;
+    this.violate("typed-message-drops", why, true);
+  }
   onWelcome(welcome) {
     this.id = welcome.clientId;
     this.role = welcome.role;
     this.roomId = welcome.roomId;
-    const snapshot = decodeSnapshot(this.options.ext, welcome.snapshot);
+    const snapshot = decodeSnapshot(this.ext, welcome.snapshot);
     this.view = snapshot.state;
     this.rememberSnapshot(snapshot.state);
     this.countSpatialSnapshot(snapshot.state);
     for (const leak of snapshotVisibilityLeaks(
-      this.options.ext,
+      this.ext,
       this.role,
       snapshot.state,
       this.spatialContext()
@@ -449,6 +929,22 @@ var BotObserver = class {
     }
     return `joined ${welcome.roomId} as ${welcome.clientId}/${welcome.role || "default"}`;
   }
+  /**
+   * Bug #28: a `SCHEMA` frame (D50 additive migrate). Rebuild the decode extension from the
+   * descriptor the frame carries, exactly as the real client's `swapSchema` does, so the resync
+   * WELCOME about to arrive decodes under the schema it was encoded with. The old view and
+   * seen-ids are dropped — they were laid out by descriptors that no longer exist, and the resync
+   * WELCOME re-seeds both (`onWelcome`).
+   */
+  onSchema(payload) {
+    const canonical = readSchemaPayload(payload);
+    const next = schemaFromCanonical(canonical);
+    this.ext = withBuiltins(next);
+    this.schemaSwaps++;
+    this.view = void 0;
+    this.seen.clear();
+    return `schema swapped (hash ${next.hash}) \u2014 decode extension rebuilt`;
+  }
   onDelta(delta, now) {
     this.checkVisibility(delta);
     this.matchWrites(delta, now);
@@ -458,14 +954,18 @@ var BotObserver = class {
     this.checkVisibility(delta);
     const names = delta.collections.map((c) => c.name).join(",");
     const kind = simulationOnly(
-      this.options.ext,
+      this.ext,
       delta,
-      (c, id) => this.predictsBody ? this.predictsBody(c, id) : false
+      (c, id) => this.bodyKind ? this.bodyKind(c, id) : "absent"
     );
     if (kind === "sync") {
       this.syncCorrections++;
       return `synced ${names}`;
     }
+    if (kind === "proxied") {
+      this.proxiedCorrections++;
+      return `proxied ${names}`;
+    }
     if (kind === "predicted") {
       return `judged ${names}${clientTick !== void 0 ? ` (clientTick ${clientTick})` : ""}`;
     }
@@ -479,7 +979,20 @@ var BotObserver = class {
         true
       );
     }
-    return `corrected ${names}${clientTick !== void 0 ? ` (clientTick ${clientTick})` : ""}`;
+    const fields = /* @__PURE__ */ new Set();
+    for (const dc of delta.collections) {
+      const desc = this.ext.collections.find(
+        (c) => c.name === dc.name
+      );
+      for (const op of dc.ops) {
+        if (op.op !== "update") {
+          fields.add(`${op.op} ${op.id}`);
+          continue;
+        }
+        for (const index of op.mask.fields) fields.add(desc?.fields[index]?.name ?? `#${index}`);
+      }
+    }
+    return `corrected ${names} [${[...fields].join(" ")}]${clientTick !== void 0 ? ` (clientTick ${clientTick})` : ""}`;
   }
   /**
    * The room's `correct` event, one per correction op — the only source of `previous` (the local
@@ -492,7 +1005,7 @@ var BotObserver = class {
       this.suppressedCorrections++;
       return;
     }
-    const desc = this.options.ext.collections.find(
+    const desc = this.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));
@@ -560,14 +1073,9 @@ var BotObserver = class {
    * frame — a departing neighbour, not a leak.
    */
   checkVisibility(delta) {
-    if (this.view) applyDelta(this.options.ext, this.view, delta);
+    if (this.view) applyDelta(this.ext, this.view, delta);
     this.countSpatialDelta(delta);
-    for (const leak of deltaVisibilityLeaks(
-      this.options.ext,
-      this.role,
-      delta,
-      this.spatialContext()
-    )) {
+    for (const leak of deltaVisibilityLeaks(this.ext, this.role, delta, this.spatialContext())) {
       this.violate("visibility-leak", leak);
     }
     this.remember(delta);
@@ -575,12 +1083,12 @@ var BotObserver = class {
   countSpatialDelta(delta) {
     if (!this.view || this.id === "") return;
     for (const collection of delta.collections) {
-      const desc = this.options.ext.collection(collection.name);
+      const desc = this.ext.collection(collection.name);
       if (desc.visibility === "spatial-grid") this.spatialOpsJudged += collection.ops.length;
     }
   }
   countSpatialSnapshot(state) {
-    for (const desc of this.options.ext.collections) {
+    for (const desc of this.ext.collections) {
       if (desc.visibility !== "spatial-grid") continue;
       this.spatialOpsJudged += state[desc.name]?.size ?? 0;
     }
@@ -594,7 +1102,7 @@ var BotObserver = class {
     return ids;
   }
   rememberSnapshot(state) {
-    for (const desc of this.options.ext.collections) {
+    for (const desc of this.ext.collections) {
       if (desc.kind !== "entity") continue;
       const collection = state[desc.name];
       if (!collection) continue;
@@ -619,6 +1127,7 @@ var BotObserver = class {
     } catch {
       name = `code ${error.code}`;
     }
+    if (name === "E_STARTING") return `${name} (room starting \u2014 not counted)`;
     if (!error.fatal) {
       this.errors++;
       this.violate("handler-error", `${name}: ${error.message}`);
@@ -747,6 +1256,59 @@ function freshValue(rng, desc, ctx) {
 }
 
 // src/report.ts
+import { mergeProfiles } from "@irtio/protocol";
+function matchmakingSummary(reading) {
+  const waits = [...reading.tickets.map((t) => t.waitedMs)].sort((a, b) => a - b);
+  const rooms = /* @__PURE__ */ new Map();
+  for (const t of reading.tickets) {
+    const room = rooms.get(t.room) ?? { bots: 0, size: t.size };
+    room.bots += 1;
+    room.size = Math.max(room.size, t.size);
+    rooms.set(t.room, room);
+  }
+  const byParty = /* @__PURE__ */ new Map();
+  for (const t of reading.tickets) {
+    if (t.party === void 0) continue;
+    const seen = byParty.get(t.party) ?? /* @__PURE__ */ new Set();
+    seen.add(t.room);
+    byParty.set(t.party, seen);
+  }
+  const splitParties = [...byParty].filter(([, seen]) => seen.size > 1).map(([party, seen]) => ({ party, rooms: [...seen] }));
+  const overfullRooms = [...rooms].filter(([, r]) => r.size > 0 && r.bots > r.size).map(([room, r]) => ({ room, bots: r.bots, size: r.size }));
+  return {
+    tickets: reading.tickets.length,
+    rooms: rooms.size,
+    waitP50Ms: percentile(waits, 50),
+    waitP95Ms: percentile(waits, 95),
+    waitMaxMs: waits[waits.length - 1] ?? 0,
+    timeouts: reading.failures.filter((f) => f.code === "E_NO_MATCH").length,
+    failures: reading.failures.filter((f) => f.code !== "E_NO_MATCH"),
+    backfills: reading.tickets.filter((t) => t.backfill).length,
+    partiesIntact: byParty.size - splitParties.length,
+    parties: byParty.size,
+    overfullRooms,
+    splitParties
+  };
+}
+function partyIntegrityResult(reading) {
+  const summary = matchmakingSummary(reading);
+  const violations = summary.splitParties.length + summary.overfullRooms.length;
+  const detail = violations === 0 ? `${summary.parties} part${summary.parties === 1 ? "y" : "ies"} landed whole across ${summary.rooms} room(s), and no room held more bots than its ticket seats` : [
+    ...summary.splitParties.map(
+      (p) => `party ${p.party} was split across ${p.rooms.join(", ")}`
+    ),
+    ...summary.overfullRooms.map(
+      (r) => `room ${r.room} holds ${r.bots} bots on a ticket that seats ${r.size}`
+    )
+  ].join("; ");
+  return {
+    name: "party-integrity",
+    ok: violations === 0,
+    state: violations === 0 ? "ok" : "violation",
+    violations,
+    detail
+  };
+}
 function percentile(sorted, p) {
   if (sorted.length === 0) return 0;
   const index = Math.min(sorted.length - 1, Math.max(0, Math.ceil(p / 100 * sorted.length) - 1));
@@ -796,9 +1358,12 @@ 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 proxied = observers.reduce((sum, o) => sum + o.proxiedCorrections, 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${synced > 0 ? ` (+${synced} body-sync)` : ""}${suppressed > 0 ? ` (+${suppressed} within-epsilon)` : ""}${violations === 0 ? "" : examples(observers, name)}`;
+      return `${corrections} correction(s), peak ${worst}/s per bot, threshold ${thresholds.correctionsPerSecMax}/s${synced > 0 ? ` (+${synced} body-sync)` : ""}${// D73-b: named apart from body-sync, because a proxy correction says something else —
+      // the server disagreeing with what this client drew.
+      proxied > 0 ? ` (+${proxied} proxied)` : ""}${suppressed > 0 ? ` (+${suppressed} within-epsilon)` : ""}${violations === 0 ? "" : examples(observers, name)}`;
     }
     case "misprediction": {
       const count = observers.reduce((sum, o) => sum + o.mispredictions, 0);
@@ -818,7 +1383,14 @@ function detailFor(name, observers, violations, thresholds) {
       const count = observers.reduce((sum, o) => sum + o.disconnects, 0);
       return count === 0 ? "every bot stayed connected" : `${count} disconnect(s)${examples(observers, name)}`;
     }
+    case "typed-message-drops": {
+      const dropped = observers.reduce((sum, o) => sum + o.messagesDropped, 0);
+      const received = observers.reduce((sum, o) => sum + o.messagesReceived, 0);
+      const sent = observers.reduce((sum, o) => sum + o.messagesSent, 0);
+      return `${sent} message(s) sent, ${received} received, ${dropped} dropped, tolerated ${thresholds.typedMessageDropsMax}` + (violations === 0 ? "" : `${examples(observers, name)} \u2014 a dropped typed message means the sender's shape is not one this schema declares`);
+    }
     case "tick-health":
+    case "party-integrity":
       return "";
   }
 }
@@ -857,10 +1429,19 @@ function buildReport(options) {
   const thresholds = options.thresholds ?? DEFAULT_THRESHOLDS;
   const durationMs = Math.max(1, options.durationMs);
   const seconds = durationMs / 1e3;
-  const invariants = INVARIANT_NAMES.map((name) => {
+  const matchmaking = options.matchmaking;
+  const invariants = INVARIANT_NAMES.filter(
+    // D73-c: a run that did not queue has no parties, so the row is absent rather than unread.
+    (name) => name !== "party-integrity" || matchmaking !== void 0
+  ).map((name) => {
     if (name === "tick-health") return tickHealthResult(options.tickHealth, thresholds);
+    if (name === "party-integrity") return partyIntegrityResult(matchmaking);
     const violations = total(observers, name);
-    const ok = name === "handler-error" ? violations <= thresholds.handlerErrorsMax : violations === 0;
+    const ok = name === "handler-error" ? violations <= thresholds.handlerErrorsMax : (
+      // D70: a budget too, for the same reason `handler-error` has one — a scenario that
+      // deliberately sends a shape the room does not declare says so with `--typed-drops-max`.
+      name === "typed-message-drops" ? violations <= thresholds.typedMessageDropsMax : violations === 0
+    );
     const state = ok ? "ok" : "violation";
     return {
       name,
@@ -878,16 +1459,26 @@ function buildReport(options) {
     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),
+    proxiedCorrections: perBot.reduce((sum, b) => sum + b.proxiedCorrections, 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)
+    errors: perBot.reduce((sum, b) => sum + b.errors, 0),
+    messagesSent: perBot.reduce((sum, b) => sum + b.messagesSent, 0),
+    messagesReceived: perBot.reduce((sum, b) => sum + b.messagesReceived, 0),
+    messagesDropped: perBot.reduce((sum, b) => sum + b.messagesDropped, 0)
   };
   const bots = Math.max(1, perBot.length);
   const convergence = convergenceStats(lags);
+  const predicting = perBot.filter((b) => b.predicting);
+  const prediction = predicting.length === 0 ? void 0 : {
+    bots: predicting.length,
+    proxies: predicting.reduce((sum, b) => sum + b.proxies, 0),
+    absent: predicting.reduce((sum, b) => sum + b.absent, 0)
+  };
   return {
     ok: invariants.every((i) => i.ok),
     bots: perBot.length,
@@ -901,10 +1492,125 @@ function buildReport(options) {
     bytesOutPerSecondPerBot: round(totals.bytesOut / seconds / bots),
     convergence,
     convergenceLagMs: convergence?.p50Ms,
-    tracePath: options.tracePath
+    tracePath: options.tracePath,
+    ...options.profiles !== void 0 && options.profiles.length > 0 ? { profile: options.profiles.reduce(mergeProfiles) } : {},
+    ...prediction !== void 0 ? { prediction } : {},
+    ...options.matchmaking !== void 0 ? { matchmaking: matchmakingSummary(options.matchmaking) } : {}
   };
 }
 
+// src/match.ts
+import { MatchError, createParty, findMatch } from "@irtio/client";
+var DEFAULT_MATCH_TIMEOUT_MS = 2e4;
+function describe(err) {
+  if (err instanceof MatchError) return { code: err.code, message: err.message };
+  return { code: "E_MATCH_FAILED", message: err instanceof Error ? err.message : String(err) };
+}
+async function matchBots(n, options) {
+  if (!Number.isInteger(n) || n < 1) {
+    throw new Error(`irtio bots: matchBots needs at least one bot, got ${String(n)}`);
+  }
+  const groups = /* @__PURE__ */ new Map();
+  for (let i = 0; i < n; i++) {
+    const key = options.party?.(i);
+    if (key === void 0) continue;
+    const members = groups.get(key) ?? [];
+    members.push(i);
+    groups.set(key, members);
+  }
+  const parties = /* @__PURE__ */ new Map();
+  const partyErrors = /* @__PURE__ */ new Map();
+  for (const [key, members] of groups) {
+    if (members.length < 2) continue;
+    try {
+      const minted = await createParty(options.project, {
+        size: members.length,
+        controlUrl: options.controlUrl,
+        ...options.fetch !== void 0 ? { fetch: options.fetch } : {}
+      });
+      parties.set(key, minted.party);
+    } catch (err) {
+      partyErrors.set(key, describe(err));
+    }
+  }
+  const timeoutMs = options.timeoutMs ?? DEFAULT_MATCH_TIMEOUT_MS;
+  const attempts = await Promise.all(
+    Array.from({ length: n }, async (_unused, index) => {
+      const key = options.party?.(index);
+      const party = key !== void 0 && parties.has(key) ? parties.get(key) : void 0;
+      const startedAt = Date.now();
+      const failed = key !== void 0 ? partyErrors.get(key) : void 0;
+      if (failed !== void 0) {
+        return { index, waitedMs: 0, error: failed, ...key !== void 0 ? { party: key } : {} };
+      }
+      const identity = options.identity?.(index);
+      try {
+        const ticket = await findMatch(options.project, {
+          controlUrl: options.controlUrl,
+          timeoutMs,
+          ...options.queue !== void 0 ? { queue: options.queue } : {},
+          ...party !== void 0 ? { party } : {},
+          ...identity !== void 0 ? { identity } : {},
+          ...options.fetch !== void 0 ? { fetch: options.fetch } : {}
+        });
+        return {
+          index,
+          ticket,
+          waitedMs: Date.now() - startedAt,
+          ...key !== void 0 ? { party: key } : {}
+        };
+      } catch (err) {
+        return {
+          index,
+          waitedMs: Date.now() - startedAt,
+          error: describe(err),
+          ...key !== void 0 ? { party: key } : {}
+        };
+      }
+    })
+  );
+  const tickets = [];
+  const failures = [];
+  for (const attempt of attempts) {
+    if (attempt.ticket === void 0) {
+      failures.push({
+        requested: attempt.index,
+        code: attempt.error?.code ?? "E_MATCH_FAILED",
+        message: attempt.error?.message ?? "no ticket and no error",
+        waitedMs: attempt.waitedMs,
+        ...attempt.party !== void 0 ? { party: attempt.party } : {}
+      });
+      continue;
+    }
+    tickets.push({
+      bot: tickets.length,
+      requested: attempt.index,
+      ticket: attempt.ticket,
+      waitedMs: attempt.waitedMs,
+      ...attempt.party !== void 0 ? { party: attempt.party } : {}
+    });
+  }
+  return { tickets, failures, parties };
+}
+function roomsOf(tickets) {
+  const rooms = /* @__PURE__ */ new Map();
+  for (const t of tickets) {
+    const bots = rooms.get(t.ticket.room) ?? [];
+    bots.push(t.bot);
+    rooms.set(t.ticket.room, bots);
+  }
+  return rooms;
+}
+
+// src/scenario.ts
+function defineScenario(scenario) {
+  return scenario;
+}
+function looksLikeScenario(value) {
+  const s = value;
+  return typeof s === "object" && s !== null && Number.isInteger(s.bots) && s.bots > 0 && typeof s.script === "function" && typeof s.assert === "function";
+}
+
 // src/script.ts
 import { rpcTable } from "@irtio/protocol";
 function ownableCollections(schema) {
@@ -920,11 +1626,16 @@ function writableFields(desc, cheat) {
 function voidServerRpcs(schema) {
   return rpcTable(schema).filter((r) => r.direction === "server" && r.returns === void 0);
 }
-function asCollection(value) {
+function asCollection2(value) {
   return value && typeof value.ownerOf === "function" ? value : void 0;
 }
+function cheatPredicate(cheat) {
+  if (cheat === void 0) return () => false;
+  if (typeof cheat === "function") return (index) => cheat(index) === true;
+  return () => cheat;
+}
 function randomScript(schema, options = {}) {
-  const cheat = options.cheat ?? false;
+  const cheats = cheatPredicate(options.cheat);
   const stepMs = options.stepMs ?? 50;
   const step = options.step ?? 8;
   const rpcChance = options.rpcChance ?? 0.05;
@@ -932,24 +1643,25 @@ function randomScript(schema, options = {}) {
   const collections = ownableCollections(schema);
   const rpcs = voidServerRpcs(schema);
   return async (bot) => {
+    const cheat = cheats(bot.index);
     const room = bot.room;
     const origins = /* @__PURE__ */ new Map();
     while (!bot.stopped) {
       for (const desc of collections) {
-        const collection = asCollection(room.state[desc.name]);
+        const collection = asCollection2(room.state[desc.name]);
         if (!collection) continue;
         for (const id of [...collection.ids()]) {
           if (collection.ownerOf(id) !== room.me) continue;
           const instance = collection.get(id);
           if (!instance) continue;
-          writeFields(bot, desc, id, instance, origins);
+          writeFields(bot, desc, id, instance, origins, cheat);
         }
       }
       if (rpcs.length > 0 && bot.rng.chance(rpcChance)) await callRandomRpc(bot, room.call, rpcs);
       await bot.wait(stepMs);
     }
   };
-  function writeFields(bot, desc, id, instance, origins) {
+  function writeFields(bot, desc, id, instance, origins, cheat) {
     const fields = writableFields(desc, cheat);
     if (fields.length === 0) return;
     const count = Math.min(fieldsPerStep, fields.length);
@@ -999,7 +1711,7 @@ import {
   joinRoom,
   webSocketTransport
 } from "@irtio/client";
-import { relaySchema, withBuiltins } from "@irtio/protocol";
+import { relaySchema, withBuiltins as withBuiltins2 } from "@irtio/protocol";
 var DEFAULT_SEED = 96016;
 var DEFAULT_TRACE_LIMIT = 4096;
 var DEFAULT_JOIN_TIMEOUT_MS = 2e4;
@@ -1010,20 +1722,34 @@ function per(value, index) {
   return typeof value === "function" ? value(index) : value;
 }
 var BotImpl = class {
-  constructor(index, room, observer, seed, startedAt) {
+  constructor(index, room, observer, seed, startedAt, conditions, shots) {
     this.index = index;
     this.room = room;
     this.observer = observer;
     this.startedAt = startedAt;
+    this.conditions = conditions;
+    this.shots = shots;
     this.rng = makeRng(seed);
   }
   index;
   room;
   observer;
   startedAt;
+  conditions;
+  shots;
   stopped = false;
   rng;
   stopListeners = /* @__PURE__ */ new Set();
+  shot(request) {
+    const tick = this.room.tick;
+    this.shots.push({
+      ...request,
+      bot: this.index,
+      sentAt: Date.now(),
+      clientTick: typeof tick === "number" ? tick : void 0,
+      uplinkMs: (this.conditions?.rttMs ?? 0) / 2
+    });
+  }
   get id() {
     return this.observer.id;
   }
@@ -1114,10 +1840,16 @@ async function withJoinTimeout(joining, index, timeoutMs, observer, sockets) {
     if (timer !== void 0) clearTimeout(timer);
   }
 }
+var CONDITIONS_SEED_OFFSET = 377022;
 async function spawnBots(n, options = {}) {
   if (!Number.isInteger(n) || n < 1) {
     throw new Error(`irtio bots: spawnBots needs at least one bot, got ${String(n)}`);
   }
+  if (options.physics !== void 0 && options.physics2d !== void 0) {
+    throw new Error(
+      "irtio: joinRoom was given both { physics } and { physics2d }. A room runs one engine and the client predicts with that one, so pass the option matching the engine your room config declares."
+    );
+  }
   const startedAt = Date.now();
   const thresholds = {
     budgetBytesPerSec: options.budgetBytesPerSec ?? DEFAULT_THRESHOLDS.budgetBytesPerSec,
@@ -1125,15 +1857,18 @@ async function spawnBots(n, options = {}) {
     handlerErrorsMax: options.handlerErrorsMax ?? DEFAULT_THRESHOLDS.handlerErrorsMax,
     mispredictionMagnitudeMax: options.mispredictionMagnitudeMax ?? DEFAULT_THRESHOLDS.mispredictionMagnitudeMax,
     snapsMax: options.snapsMax ?? DEFAULT_THRESHOLDS.snapsMax,
-    overrunsMax: options.overrunsMax ?? DEFAULT_THRESHOLDS.overrunsMax
+    overrunsMax: options.overrunsMax ?? DEFAULT_THRESHOLDS.overrunsMax,
+    typedMessageDropsMax: options.typedMessageDropsMax ?? DEFAULT_THRESHOLDS.typedMessageDropsMax
   };
-  const ext = options.schema ? withBuiltins(options.schema) : relaySchema;
+  const ext = options.schema ? withBuiltins2(options.schema) : relaySchema;
   const seed = options.seed ?? DEFAULT_SEED;
   const traceLimit = options.traceLimit ?? DEFAULT_TRACE_LIMIT;
   const writeLog = new WriteLog();
   const lags = [];
   const observers = [];
   const bots = [];
+  const shots = [];
+  const conditions = [];
   const joinTimeoutMs = options.joinTimeoutMs ?? DEFAULT_JOIN_TIMEOUT_MS;
   const roomGoneGraceMs = options.roomGoneGraceMs ?? DEFAULT_ROOM_GONE_GRACE_MS;
   const baseTransport = options.transport ?? webSocketTransport;
@@ -1150,13 +1885,25 @@ async function spawnBots(n, options = {}) {
     const role = per(options.role, index);
     const name = per(options.name, index);
     const sockets = [];
-    const transport = {
+    const asked = per(options.conditions, index);
+    const injected = hasConditions(asked) ? asked : void 0;
+    const counters = newConditionCounters();
+    conditions[index] = { bot: index, conditions: injected, counters };
+    const recording = {
       connect(url) {
         const socket = baseTransport.connect(url);
         sockets.push(socket);
         return socket;
       }
     };
+    const transport = injected === void 0 ? recording : conditionedTransport(
+      recording,
+      injected,
+      makeRng(seed + index + CONDITIONS_SEED_OFFSET),
+      {
+        counters
+      }
+    );
     const common = {
       room: roomId2,
       ...options.url !== void 0 ? { url: options.url } : {},
@@ -1171,14 +1918,67 @@ async function spawnBots(n, options = {}) {
       ...common,
       ...options.flushMs !== void 0 ? { writeIntervalMs: options.flushMs } : {},
       ...options.rpc !== void 0 ? { rpc: options.rpc } : {},
-      ...options.physics !== void 0 ? { physics: options.physics } : {}
+      ...options.physics !== void 0 ? { physics: options.physics } : {},
+      ...options.physics2d !== void 0 ? { physics2d: options.physics2d } : {},
+      ...options.profile === true ? { profile: true } : {}
     }) : joinRelay(common);
     const room = await withJoinTimeout(joining, index, joinTimeoutMs, observer, sockets);
     room.on("correct", (correction) => observer.onCorrection(correction));
     const prediction = room.prediction;
-    if (prediction) observer.predictsBody = (c, id) => prediction.predicts(c, id);
+    if (prediction) {
+      observer.bodyKind = (c, id) => prediction.predicts(c, id) ? "predicted" : prediction.proxied(c, id) ? "proxied" : "absent";
+      observer.prediction = prediction;
+    }
     observers[index] = observer;
-    return new BotImpl(index, room, observer, seed + index, startedAt);
+    return new BotImpl(
+      index,
+      room,
+      observer,
+      seed + index,
+      startedAt,
+      injected,
+      shots
+    );
+  }
+  if (options.match !== void 0) {
+    const matched = await matchBots(n, options.match);
+    if (matched.tickets.length === 0) {
+      const first2 = matched.failures[0];
+      throw new Error(
+        `irtio bots: no bot got a ticket from the ${options.match.queue ?? "default"} queue at ${options.match.controlUrl}, so there is no room to run in` + (first2 !== void 0 ? ` (${first2.code}: ${first2.message})` : "")
+      );
+    }
+    const joined = await Promise.allSettled(
+      matched.tickets.map((t) => joinOne(t.bot, t.ticket.room))
+    );
+    const failure = joined.find((r) => r.status === "rejected");
+    if (failure !== void 0) {
+      for (const settled of joined) {
+        if (settled.status === "fulfilled") settled.value.room.leave();
+      }
+      throw failure.reason;
+    }
+    for (const settled of joined) {
+      if (settled.status === "fulfilled") bots.push(settled.value);
+    }
+    return finishRun(bots, {
+      roomId: matched.tickets[0]?.ticket.room ?? "",
+      matches: matched.tickets,
+      rooms: roomsOf(matched.tickets),
+      matchFailures: matched.failures,
+      matchmaking: {
+        tickets: matched.tickets.map((t) => ({
+          bot: t.bot,
+          room: t.ticket.room,
+          queue: t.ticket.queue,
+          size: t.ticket.size,
+          backfill: t.ticket.backfill,
+          waitedMs: t.waitedMs,
+          ...t.party !== void 0 ? { party: t.party } : {}
+        })),
+        failures: matched.failures.map((f) => ({ requested: f.requested, code: f.code }))
+      }
+    });
   }
   const first = await joinOne(0, options.room ?? "");
   bots.push(first);
@@ -1199,117 +1999,287 @@ async function spawnBots(n, options = {}) {
       if (settled.status === "fulfilled") bots.push(settled.value);
     }
   }
-  const scriptErrors = [];
-  let firstError;
-  const script = options.script;
-  const scripts = bots.map(async (bot) => {
-    if (!script) {
-      await bot.until(() => bot.stopped, { label: "the run to end", timeoutMs: 24 * 36e5 });
-      return;
-    }
-    try {
-      await script(bot);
-    } catch (error) {
-      scriptErrors.push({ bot: bot.index, error });
-      firstError ??= error;
-    }
+  return finishRun(bots, {
+    roomId,
+    matches: [],
+    rooms: /* @__PURE__ */ new Map([[roomId, bots.map((b) => b.index)]]),
+    matchFailures: []
   });
-  const finished = Promise.all(scripts).then(() => void 0);
-  let endedBy;
-  let deadline;
-  if (options.durationMs !== void 0) {
-    deadline = setTimeout(() => {
-      endedBy ??= "duration";
-      for (const bot of bots) bot.stop();
-    }, options.durationMs);
-  }
-  let goneSince = 0;
-  let goneTimer;
-  if (roomGoneGraceMs > 0) {
-    goneTimer = setInterval(() => {
-      const down = observers.every(
-        (o) => o.lastStatus === "reconnecting" || o.lastStatus === "closed"
-      );
-      if (!down) {
-        goneSince = 0;
+  function finishRun(bots2, placement) {
+    const roomId2 = placement.roomId;
+    const scriptErrors = [];
+    let firstError;
+    const script = options.script;
+    const scripts = bots2.map(async (bot) => {
+      if (!script) {
+        await bot.until(() => bot.stopped, { label: "the run to end", timeoutMs: 24 * 36e5 });
         return;
       }
-      goneSince ||= Date.now();
-      if (Date.now() - goneSince < roomGoneGraceMs) return;
-      endedBy ??= "room-gone";
-      for (const bot of bots) bot.stop();
-    }, ROOM_GONE_POLL_MS);
-    goneTimer.unref?.();
-  }
-  void finished.then(() => {
-    endedBy ??= "scripts";
-    if (deadline) clearTimeout(deadline);
-    if (goneTimer) clearInterval(goneTimer);
-  });
-  let stoppedAt;
-  let tickHealth;
-  const rings = () => observers.map((o) => o.ring);
-  const runner = {
-    bots,
-    roomId,
-    trace: makeTrace(startedAt, rings),
-    scriptErrors,
-    get endedBy() {
-      return endedBy;
-    },
-    [Symbol.iterator]: () => bots[Symbol.iterator](),
-    async done() {
-      await finished;
-      if (firstError !== void 0) throw firstError;
+      try {
+        await script(bot);
+      } catch (error) {
+        scriptErrors.push({ bot: bot.index, error });
+        firstError ??= error;
+      }
+    });
+    const finished = Promise.all(scripts).then(() => void 0);
+    let endedBy;
+    let deadline;
+    if (options.durationMs !== void 0) {
+      deadline = setTimeout(() => {
+        endedBy ??= "duration";
+        for (const bot of bots2) bot.stop();
+      }, options.durationMs);
+    }
+    let goneSince = 0;
+    let goneTimer;
+    if (roomGoneGraceMs > 0) {
+      goneTimer = setInterval(() => {
+        const down = observers.every(
+          (o) => o.lastStatus === "reconnecting" || o.lastStatus === "closed"
+        );
+        if (!down) {
+          goneSince = 0;
+          return;
+        }
+        goneSince ||= Date.now();
+        if (Date.now() - goneSince < roomGoneGraceMs) return;
+        endedBy ??= "room-gone";
+        for (const bot of bots2) bot.stop();
+      }, ROOM_GONE_POLL_MS);
+      goneTimer.unref?.();
+    }
+    void finished.then(() => {
+      endedBy ??= "scripts";
+      if (deadline) clearTimeout(deadline);
+      if (goneTimer) clearInterval(goneTimer);
+    });
+    let stoppedAt;
+    let tickHealth;
+    const rings = () => observers.map((o) => o.ring);
+    let profiles;
+    const runner = {
+      bots: bots2,
+      roomId: roomId2,
+      matches: placement.matches,
+      rooms: placement.rooms,
+      matchFailures: placement.matchFailures,
+      trace: makeTrace(startedAt, rings),
+      scriptErrors,
+      shots,
+      conditions,
+      get endedBy() {
+        return endedBy;
+      },
+      [Symbol.iterator]: () => bots2[Symbol.iterator](),
+      async done() {
+        await finished;
+        if (firstError !== void 0) throw firstError;
+      },
+      recordTickHealth(reading) {
+        tickHealth = reading;
+      },
+      report() {
+        if (options.profile === true) {
+          const live = bots2.map((bot) => bot.room.profile?.total()).filter((p) => p !== void 0);
+          if (live.length > 0) profiles = live;
+        }
+        return buildReport({
+          observers,
+          roomId: roomId2,
+          durationMs: (stoppedAt ?? Date.now()) - startedAt,
+          lags,
+          thresholds,
+          tickHealth,
+          ...placement.matchmaking !== void 0 ? { matchmaking: placement.matchmaking } : {},
+          ...profiles !== void 0 ? { profiles } : {}
+        });
+      },
+      async stop() {
+        if (deadline) clearTimeout(deadline);
+        if (goneTimer) clearInterval(goneTimer);
+        for (const bot of bots2) bot.stop();
+        await finished;
+        stoppedAt ??= Date.now();
+        for (const observer of observers) observer.stopping = true;
+        for (const bot of bots2) bot.room.leave();
+        return this.report();
+      }
+    };
+    return runner;
+  }
+}
+
+// src/timeline.ts
+var Collection = class {
+  constructor(raw, entity) {
+    this.raw = raw;
+    this.entity = entity;
+  }
+  raw;
+  entity;
+  entry(id) {
+    if (!this.entity) return void 0;
+    const row = this.raw[id];
+    return typeof row === "object" && row !== null ? row : void 0;
+  }
+  get(id) {
+    const value = this.entry(id)?.value;
+    return typeof value === "object" && value !== null ? value : void 0;
+  }
+  has(id) {
+    return this.entity && Object.hasOwn(this.raw, id);
+  }
+  ids() {
+    return this.entity ? Object.keys(this.raw) : [];
+  }
+  get size() {
+    return this.entity ? Object.keys(this.raw).length : 0;
+  }
+  owner(id) {
+    const owner = this.entry(id)?.owner;
+    return typeof owner === "string" && owner !== "" ? owner : void 0;
+  }
+  get value() {
+    return this.entity ? void 0 : this.raw;
+  }
+};
+var UnknownCollectionError = class extends Error {
+  name = "UnknownCollectionError";
+  constructor(collection, known) {
+    super(
+      `irtio scenario: this room has no collection named "${collection}". It has: ${known.length > 0 ? known.join(", ") : "none"}.`
+    );
+  }
+};
+var TickNotRecordedError = class extends Error {
+  constructor(tick, first, last, dropped) {
+    super(
+      first === void 0 ? `irtio scenario: nothing was recorded, so tick ${tick} cannot be read.` : `irtio scenario: tick ${tick} is not in the recording, which holds ticks ${first} to ${last}` + (dropped > 0 ? `. ${dropped} earlier tick(s) were dropped by the recorder's cap, so raise it or shorten the run.` : ".")
+    );
+    this.tick = tick;
+  }
+  tick;
+  name = "TickNotRecordedError";
+};
+function momentOf(dump, index, read) {
+  const frame = dump.frames[index];
+  read(frame.tick);
+  const known = Object.keys(dump.collections);
+  const cache = /* @__PURE__ */ new Map();
+  return new Proxy({}, {
+    get(_target, property) {
+      if (typeof property !== "string") return void 0;
+      const cached = cache.get(property);
+      if (cached) return cached;
+      const kind = dump.collections[property];
+      if (kind === void 0) throw new UnknownCollectionError(property, known);
+      const raw = frame.state[property];
+      const view = new Collection(
+        typeof raw === "object" && raw !== null ? raw : {},
+        kind === "entity"
+      );
+      cache.set(property, view);
+      return view;
     },
-    recordTickHealth(reading) {
-      tickHealth = reading;
+    has: (_target, property) => typeof property === "string" && property in dump.collections,
+    ownKeys: () => [...known],
+    getOwnPropertyDescriptor: () => ({ enumerable: true, configurable: true })
+  });
+}
+function makeTimeline(dump) {
+  const index = /* @__PURE__ */ new Map();
+  dump.frames.forEach((f, i) => index.set(f.tick, i));
+  const ticks = dump.frames.map((f) => f.tick);
+  const results = [];
+  let readTicks = [];
+  const read = (tick) => {
+    readTicks.push(tick);
+  };
+  const at = (tick) => {
+    const i = index.get(tick);
+    if (i === void 0) {
+      throw new TickNotRecordedError(tick, ticks[0], ticks[ticks.length - 1], dump.dropped);
+    }
+    return momentOf(dump, i, read);
+  };
+  return {
+    roomId: dump.roomId,
+    ticks,
+    dropped: dump.dropped,
+    at,
+    find(match) {
+      for (let i = 0; i < dump.frames.length; i++) {
+        const tick = dump.frames[i].tick;
+        const state = momentOf(dump, i, read);
+        if (match(state, tick)) return { tick, state };
+      }
+      return void 0;
     },
-    report() {
-      return buildReport({
-        observers,
-        roomId,
-        durationMs: (stoppedAt ?? Date.now()) - startedAt,
-        lags,
-        thresholds,
-        tickHealth
-      });
+    check(name, assertion) {
+      readTicks = [];
+      try {
+        assertion();
+        results.push({
+          name,
+          ok: true,
+          ...readTicks.length > 0 ? { tick: readTicks[readTicks.length - 1] } : {},
+          detail: readTicks.length === 0 ? "held (read no tick)" : `held, reading tick ${readTicks[readTicks.length - 1]}` + (readTicks.length > 1 ? ` (${readTicks.length} ticks read)` : "")
+        });
+      } catch (err) {
+        results.push({
+          name,
+          ok: false,
+          ...readTicks.length > 0 ? { tick: readTicks[readTicks.length - 1] } : {},
+          detail: err instanceof Error ? err.message : String(err)
+        });
+      }
     },
-    async stop() {
-      if (deadline) clearTimeout(deadline);
-      if (goneTimer) clearInterval(goneTimer);
-      for (const bot of bots) bot.stop();
-      await finished;
-      stoppedAt ??= Date.now();
-      for (const observer of observers) observer.stopping = true;
-      for (const bot of bots) bot.room.leave();
-      return this.report();
+    get results() {
+      return results;
     }
   };
-  return runner;
 }
 export {
   BotObserver,
   DEFAULT_JOIN_TIMEOUT_MS,
+  DEFAULT_MATCH_TIMEOUT_MS,
+  DEFAULT_REORDER_MS,
   DEFAULT_ROOM_GONE_GRACE_MS,
   DEFAULT_SEED,
   DEFAULT_THRESHOLDS,
   DEFAULT_TRACE_LIMIT,
   INVARIANT_NAMES,
   JoinTimeoutError,
+  TickNotRecordedError,
   TraceRing,
+  UnknownCollectionError,
   WriteLog,
   buildReport,
+  captureClientState,
+  cheatPredicate,
+  conditionedTransport,
   convergenceStats,
+  correlateShots,
+  defineScenario,
   deltaVisibilityLeaks,
+  describeConditions,
+  diffAgainstSave,
   frameName,
   frameVisibilityLeaks,
   freshValue,
+  hasConditions,
+  looksLikeScenario,
   makeRng,
+  makeTimeline,
   makeTrace,
+  matchBots,
+  matchmakingSummary,
+  newConditionCounters,
   nextValue,
   randomScript,
   relayEchoScript,
+  roomsOf,
   snapshotVisibilityLeaks,
   spawnBots
 };