@irtio/bots 0.6.0 → 0.8.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) {
@@ -264,16 +272,19 @@ function entityValue(frameState, collection, id) {
 function correlateShots(shots, dump) {
   const frames = dump.frames;
   return shots.map((shot) => {
-    const arrivedAt = shot.sentAt + shot.uplinkMs;
-    const frame = frames.find((f) => f.at >= arrivedAt);
+    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: void 0,
-        estimated: shot.uplinkMs > 0,
+        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" : `the shot lands after the last recorded tick (${frames[frames.length - 1]?.tick})`
+        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);
@@ -281,7 +292,8 @@ function correlateShots(shots, dump) {
       return {
         ...shot,
         serverTick: frame.tick,
-        estimated: shot.uplinkMs > 0,
+        estimated,
+        rewound,
         authoritative: void 0,
         missDistance: void 0,
         unresolved: `${shot.collection}.${shot.target} is not in the recording at tick ${frame.tick}`
@@ -303,7 +315,8 @@ function correlateShots(shots, dump) {
       return {
         ...shot,
         serverTick: frame.tick,
-        estimated: shot.uplinkMs > 0,
+        estimated,
+        rewound,
         authoritative,
         missDistance: void 0,
         unresolved: missing
@@ -312,7 +325,8 @@ function correlateShots(shots, dump) {
     return {
       ...shot,
       serverTick: frame.tick,
-      estimated: shot.uplinkMs > 0,
+      estimated,
+      rewound,
       authoritative,
       missDistance: Math.sqrt(sum)
     };
@@ -465,6 +479,7 @@ import {
   FrameType as FrameType4,
   decodeErrorPayload,
   decodeFrame,
+  decodeMsg,
   decodeReply,
   decodeWelcome,
   errorByCode,
@@ -477,6 +492,7 @@ import {
   applyDelta,
   decodeDelta as decodeDelta2,
   decodeDeltaFrom,
+  decodeFields,
   decodeSnapshot,
   schemaFromCanonical
 } from "@irtio/schema";
@@ -545,21 +561,24 @@ 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) 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;
@@ -569,9 +588,11 @@ function simulationOnly(ext, delta, predicts) {
       }
     }
   }
-  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) {
@@ -654,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;
@@ -670,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
@@ -705,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,
@@ -714,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. */
@@ -740,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++;
@@ -781,6 +834,7 @@ var BotObserver = class {
     if (dir === "out") {
       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) {
@@ -799,10 +853,64 @@ var BotObserver = class {
         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;
@@ -848,12 +956,16 @@ var BotObserver = class {
     const kind = simulationOnly(
       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})` : ""}`;
     }
@@ -1145,6 +1257,58 @@ 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));
@@ -1194,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);
@@ -1216,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 "";
   }
 }
@@ -1255,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,
@@ -1276,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,
@@ -1300,10 +1493,115 @@ function buildReport(options) {
     convergence,
     convergenceLagMs: convergence?.p50Ms,
     tracePath: options.tracePath,
-    ...options.profiles !== void 0 && options.profiles.length > 0 ? { profile: options.profiles.reduce(mergeProfiles) } : {}
+    ...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;
@@ -1547,6 +1845,11 @@ 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,
@@ -1554,7 +1857,8 @@ 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 ? withBuiltins2(options.schema) : relaySchema;
   const seed = options.seed ?? DEFAULT_SEED;
@@ -1615,12 +1919,16 @@ async function spawnBots(n, options = {}) {
       ...options.flushMs !== void 0 ? { writeIntervalMs: options.flushMs } : {},
       ...options.rpc !== void 0 ? { rpc: options.rpc } : {},
       ...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,
@@ -1632,6 +1940,46 @@ async function spawnBots(n, options = {}) {
       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);
   const roomId = first.room.id;
@@ -1651,102 +1999,115 @@ 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);
-  let profiles;
-  const runner = {
-    bots,
-    roomId,
-    trace: makeTrace(startedAt, rings),
-    scriptErrors,
-    shots,
-    conditions,
-    get endedBy() {
-      return endedBy;
-    },
-    [Symbol.iterator]: () => bots[Symbol.iterator](),
-    async done() {
-      await finished;
-      if (firstError !== void 0) throw firstError;
-    },
-    recordTickHealth(reading) {
-      tickHealth = reading;
-    },
-    report() {
-      if (options.profile === true) {
-        const live = bots.map((bot) => bot.room.profile?.total()).filter((p) => p !== void 0);
-        if (live.length > 0) profiles = live;
+      try {
+        await script(bot);
+      } catch (error) {
+        scriptErrors.push({ bot: bot.index, error });
+        firstError ??= error;
       }
-      return buildReport({
-        observers,
-        roomId,
-        durationMs: (stoppedAt ?? Date.now()) - startedAt,
-        lags,
-        thresholds,
-        tickHealth,
-        ...profiles !== void 0 ? { profiles } : {}
-      });
-    },
-    async stop() {
+    });
+    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);
-      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();
-    }
-  };
-  return runner;
+    });
+    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
@@ -1882,6 +2243,7 @@ function makeTimeline(dump) {
 export {
   BotObserver,
   DEFAULT_JOIN_TIMEOUT_MS,
+  DEFAULT_MATCH_TIMEOUT_MS,
   DEFAULT_REORDER_MS,
   DEFAULT_ROOM_GONE_GRACE_MS,
   DEFAULT_SEED,
@@ -1911,10 +2273,13 @@ export {
   makeRng,
   makeTimeline,
   makeTrace,
+  matchBots,
+  matchmakingSummary,
   newConditionCounters,
   nextValue,
   randomScript,
   relayEchoScript,
+  roomsOf,
   snapshotVisibilityLeaks,
   spawnBots
 };