@irtio/cli 0.6.0 → 0.7.0

package/dist/simulate.d.ts

@@ -80,8 +80,14 @@ interface SimulateArgs {
     profile?: boolean;
     /** D65: rows in that table. Implies `profile`. */
     profileTop?: number;
+    /** Queue for rooms instead of building one. Needs `control`. */
+    queue?: string;
+    /** The control plane the queue lives on. `irtio dev` runs none. */
+    control?: string;
+    /** Group this many consecutive bots into one party each. */
+    party?: number;
 }
-declare const USAGE = "usage: irtio simulate [options]\n\nDrives N real clients at a running room and checks the built-in invariants. Run it from a project\ndirectory so it can load irtio/schema.ts; without one it falls back to a relay run.\n\noptions:\n  --bots <n>                  how many clients to spawn (default 5)\n  --seconds <n>               how long to play for (default 10)\n  --room <code>               join this room instead of creating one\n  --url <ws://...>            where to connect (default ws://localhost:7070)\n  --key <projectKey>          the project key to present\n  --trace <path>              write the frame trace here\n  --scenario <file>           run a scenario module and assert against the recorded timeline\n  --cheat                     send illegal writes and expect corrections, from every bot\n  --cheat-bot <index>         only this bot cheats (repeatable)\n  --conditions <json>         inject network conditions into every bot, e.g.\n                              '{\"rttMs\":200,\"jitterMs\":20,\"loss\":0.02}'. Keys: rttMs, jitterMs,\n                              loss, duplicate, reorder, reorderMs. Loss, duplicate and reorder\n                              touch state frames only, so a join always completes\n  --conditions-bot <i>:<json> conditions for one bot, overriding --conditions (repeatable)\n  --truth                     save the room at the end and diff it against what each client\n                              received, within that client's visibility\n  --misprediction-max <units> fail if one correction snaps a prediction further than this\n  --snaps-max <n>             fail above this many cap-exceeded reconciliations\n  --corrections-max <perSec>  fail above this correction rate per bot\n  --overruns-max <n>          fail above this many server tick overruns in the run window\n                              (default 0; the count is read from the server, and the run says\n                              so when it could not be read)\n  --profile                   print where the run's bytes went, by collection and field, as the\n                              bots saw them\n  --profile-top <n>           rows in that table (default 12; implies --profile)\n  -h, --help                  print this\n\nexit codes: 0 every invariant held, 1 something was measured and failed, 2 the run could not be\nperformed (nobody joined, or it passed its wall-clock ceiling).\n";
+declare const USAGE = "usage: irtio simulate [options]\n\nDrives N real clients at a running room and checks the built-in invariants. Run it from a project\ndirectory so it can load irtio/schema.ts; without one it falls back to a relay run.\n\noptions:\n  --bots <n>                  how many clients to spawn (default 5)\n  --seconds <n>               how long to play for (default 10)\n  --room <code>               join this room instead of creating one\n  --url <ws://...>            where to connect (default ws://localhost:7070)\n  --key <projectKey>          the project key to present\n  --trace <path>              write the frame trace here\n  --scenario <file>           run a scenario module and assert against the recorded timeline\n  --cheat                     send illegal writes and expect corrections, from every bot\n  --cheat-bot <index>         only this bot cheats (repeatable)\n  --conditions <json>         inject network conditions into every bot, e.g.\n                              '{\"rttMs\":200,\"jitterMs\":20,\"loss\":0.02}'. Keys: rttMs, jitterMs,\n                              loss, duplicate, reorder, reorderMs. Loss, duplicate and reorder\n                              touch state frames only, so a join always completes\n  --conditions-bot <i>:<json> conditions for one bot, overriding --conditions (repeatable)\n  --truth                     save the room at the end and diff it against what each client\n                              received, within that client's visibility\n  --misprediction-max <units> fail if one correction snaps a prediction further than this\n  --snaps-max <n>             fail above this many cap-exceeded reconciliations\n  --corrections-max <perSec>  fail above this correction rate per bot\n  --overruns-max <n>          fail above this many server tick overruns in the run window\n                              (default 0; the count is read from the server, and the run says\n                              so when it could not be read)\n  --queue <name>              queue for rooms through the matchmaker instead of creating one:\n                              every bot calls the real match API and joins the room its ticket\n                              names. Needs --control\n  --control <https://...>     the control plane the queue lives on. `irtio dev` runs none, so a\n                              queued run points at a real one (staging, or a test plane)\n  --party <n>                 group each n consecutive bots into one party, so they queue\n                              together and land in one room. Needs --queue\n  --profile                   print where the run's bytes went, by collection and field, as the\n                              bots saw them\n  --profile-top <n>           rows in that table (default 12; implies --profile)\n  -h, --help                  print this\n\nexit codes: 0 every invariant held, 1 something was measured and failed, 2 the run could not be\nperformed (nobody joined, or it passed its wall-clock ceiling).\n";
 /** Hand-rolled, like `parseDevArgs`: the CLI has no argument-parsing dependency. */
 declare function parseSimulateArgs(args: readonly string[]): SimulateArgs;
 interface LoadSchemaOptions {
@@ -100,6 +106,7 @@ declare function loadProjectSchema(options: LoadSchemaOptions): Promise<{
 } | undefined>;
 /** The shared world-builder's exports, as `joinRoom({ physics })` wants them. */
 interface LoadedWorld {
+    readonly engine: 'rapier3d';
     readonly gravity: {
         x: number;
         y: number;
@@ -112,18 +119,87 @@ interface LoadedWorld {
     readonly file: string;
 }
 /**
- * Bundles and imports the project's shared world-builder module, so the bots predict physics the
- * way a browser client would. The engine stays external — it must be the project's own copy,
- * resolved at import time, exactly as a room bundle resolves it.
+ * D73-a: a matter2d world, as `joinRoom({ physics2d })` wants it.
+ *
+ * `bugs.md` #21 taught this loader to *recognise* a 2D world rather than refuse it, and stopped
+ * there, on a comment saying matter2d had no client prediction. That stopped being true when
+ * `joinRoom({ physics2d })` shipped (M5 part 4.5), so a 2D world is now loaded to be predicted
+ * with, exactly as the Rapier one is.
+ *
+ * The source is the shared world module, which exports `gravity` (2D) and whichever of `timestep`,
+ * `setup`, `bodies`, `intents` and `settle` it has — the same object a browser hands
+ * `joinRoom({ physics2d })`. The room's own `physics` declaration is deliberately **not** a
+ * source: it is the server's half, and the client half (`settle`, the per-step force over the
+ * bodies nobody steers, and the exact timestep) is written on the client. A world built from the
+ * room alone would leave every unsteered body hanging in the air locally and be corrected on
+ * every tick, which is a worse answer than not predicting.
+ */
+interface LoadedWorld2d {
+    readonly engine: 'matter2d';
+    readonly gravity: {
+        x: number;
+        y: number;
+    };
+    readonly timestep?: number | undefined;
+    readonly setup?: ((engine: unknown, matter: unknown) => void) | undefined;
+    readonly bodies?: Record<string, (...args: never[]) => unknown> | undefined;
+    readonly intents?: Record<string, (...args: never[]) => void> | undefined;
+    readonly settle?: Record<string, (...args: never[]) => void> | undefined;
+    /**
+     * The three tuning numbers `ClientPhysics2dOptions` takes, when the world module states them.
+     *
+     * `epsilon` is the one that matters and it is the one nobody expects: it is a distance in the
+     * world's own units, and its default (0.05) is sized for a metre-scale world. A matter.js world
+     * in pixels — matter's own convention, and what every matter.js tutorial writes — is two orders
+     * of magnitude coarser, so the default calls every ordinary contact resolution a misprediction.
+     * A world that states its scale here gets the same suppression a metre-scale world gets for free.
+     */
+    readonly epsilon?: number | undefined;
+    readonly maxPredictedBodies?: number | undefined;
+    readonly smoothingHalfLifeMs?: number | undefined;
+    readonly file: string;
+}
+/**
+ * A matter2d project this loader recognises and cannot predict from: run it, say why in one
+ * sentence, and never pretend to a predictor that does not exist.
+ *
+ * `bugs.md` #21 introduced this for every matter2d project, because there was no client
+ * prediction at all. D73-a narrows it to the two cases that are still true: a world module with
+ * no `bodies` (there is nothing to build), and an **inert** one — no `intents`, no `settle`, and
+ * zero gravity, so nothing in a local world built from it could ever move a body.
+ * `examples/matter-chase` is the second case by design: its room applies thrust by hand inside
+ * `tick()`, so there is no steering hook to share and its own client does not predict either.
  */
-/** `bugs.md` #21: a 2D world module, recognised rather than refused. There is nothing to predict
- *  from it in this release, so the caller drops the predicted-world path and runs anyway. */
 interface UnpredictedWorld {
-    readonly unpredicted: 'matter2d';
+    readonly engine: 'matter2d';
+    /** One sentence, printed by the run, naming what would have to change. */
+    readonly why: string;
     readonly file: string;
 }
-declare function isUnpredictedWorld(world: LoadedWorld | UnpredictedWorld | undefined): world is UnpredictedWorld;
-declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedWorld | UnpredictedWorld | undefined>;
+type LoadedAnyWorld = LoadedWorld | LoadedWorld2d | UnpredictedWorld;
+/** Narrows a loaded world to a matter2d one bots can predict with. */
+declare function is2dWorld(world: LoadedAnyWorld | undefined): world is LoadedWorld2d;
+declare function isUnpredictedWorld(world: LoadedAnyWorld | undefined): world is UnpredictedWorld;
+/**
+ * D73-a: does this project's room declare matter2d?
+ *
+ * The one question the room module is asked, and the reason it is asked at all: a matter2d project
+ * whose world module is not a client world — `games/dive`, whose engine gravity is zero and
+ * applied per body, so there is no `gravity` to export and its `physics2d` block is composed in
+ * `main.ts` — used to be refused at the door with "does not export a { x, y, z } gravity", which
+ * is why `irtio simulate` had never been run against dive at all. Recognising it here turns that
+ * refusal into a run with a sentence.
+ *
+ * `undefined` for every other answer: no room module, one that will not build or import, or one
+ * declaring another engine. None of those is an error here — the world module's own error is the
+ * right one to raise.
+ */
+declare function detectMatter2dRoom(options: LoadSchemaOptions): Promise<string | undefined>;
+/**
+ * Bundles and imports the project's shared world-builder module, so the bots predict physics the
+ * way a browser client would.
+ */
+declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedAnyWorld | undefined>;
 /**
  * The build-twice determinism check: builds two worlds from the shared `setup` and compares
  * Rapier's own snapshots byte for byte. A builder that is not pure over synced inputs
@@ -132,6 +208,23 @@ declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedWor
  * description, or `undefined` when the worlds agree.
  */
 declare function checkWorldDeterminism(world: LoadedWorld): Promise<string | undefined>;
+/**
+ * D73-a: the matter2d determinism check.
+ *
+ * The Rapier check compares two `takeSnapshot()` byte strings, and matter.js has no snapshot at
+ * all (`packages/runtime/src/core/matter.ts`'s header says so), so this one is built the only way
+ * that is left: build the world twice through the engine the runtime loads, step both the same
+ * number of times with the same (empty) intent stream, and compare every body's pose and velocity
+ * through a canonical encoding. Two builds that disagree came from a builder that is not pure over
+ * synced inputs, which is the same fault the Rapier check catches and the same reason it matters —
+ * every "misprediction" it causes is blamed on netcode.
+ *
+ * Stepping, rather than comparing the two worlds as built, is what makes it catch randomness that
+ * is small at t=0: a crate spawned a thousandth of a unit off lands in a different place. The body
+ * factories are exercised too, against each collection's zero record, so a `Math.random()` in a
+ * factory is caught and not only one in `setup`.
+ */
+declare function checkWorld2dDeterminism(world: LoadedWorld2d, schema?: AnySchema): Promise<string | undefined>;
 /**
  * The dev server's JSON view, which is where a local run reads the server's own tick counters.
  * `irtio dev` serves it on the socket's own port; nothing else does, and that is deliberate — a
@@ -221,6 +314,12 @@ interface RunSimulationOptions extends Partial<SimulateArgs> {
      * is a fatal run condition, not a clean end.
      */
     readonly ceilingMs?: number;
+    /**
+     * D73-c: how long a queued bot waits for its ticket. The control plane caps this at two minutes
+     * and applies its own default (30 s) when it is omitted; a run that wants to see a queue *not*
+     * fill needs a bound shorter than its own patience.
+     */
+    readonly matchTimeoutMs?: number;
     /** @internal Test seam, same as `startDev`'s. */
     readonly irtioPackages?: Record<string, string> | undefined;
 }
@@ -296,6 +395,12 @@ interface SimulationRun {
     readonly schema: boolean;
     /** `true` when the bots predicted physics from a shared world-builder module (D22 part 2). */
     readonly predicted: boolean;
+    /** D73-c: bots that never got a ticket. Empty on a run that did not queue. */
+    readonly matchFailures: readonly {
+        requested: number;
+        code: string;
+        message: string;
+    }[];
     /** Result of the build-twice world-builder check: the failure text, or `undefined` if it held
      *  (or did not apply). A failure also fails the run. */
     readonly worldError?: string;
@@ -312,4 +417,4 @@ interface SimulationRun {
 declare function runSimulation(options?: RunSimulationOptions): Promise<SimulationRun>;
 declare function simulate(args: readonly string[]): Promise<void>;
 
-export { type AdversarialRun, type BuildIdentity, type LoadSchemaOptions, RunNotPerformedError, type RunSimulationOptions, ScenarioNotRunError, type ScenarioRun, type SimulateArgs, type SimulationEnd, type SimulationRun, type TruthRun, USAGE, type UnpredictedWorld, ceilingFor, checkWorldDeterminism, formatBuildIdentity, isUnpredictedWorld, loadProjectSchema, loadProjectWorld, loadScenario, parseSimulateArgs, readBuildIdentity, readTickCounters, runSimulation, simulate, stateUrlFor, tickHealthFrom };
+export { type AdversarialRun, type BuildIdentity, type LoadSchemaOptions, type LoadedAnyWorld, type LoadedWorld2d, RunNotPerformedError, type RunSimulationOptions, ScenarioNotRunError, type ScenarioRun, type SimulateArgs, type SimulationEnd, type SimulationRun, type TruthRun, USAGE, type UnpredictedWorld, ceilingFor, checkWorld2dDeterminism, checkWorldDeterminism, detectMatter2dRoom, formatBuildIdentity, is2dWorld, isUnpredictedWorld, loadProjectSchema, loadProjectWorld, loadScenario, parseSimulateArgs, readBuildIdentity, readTickCounters, runSimulation, simulate, stateUrlFor, tickHealthFrom };

package/dist/simulate.js

@@ -6,8 +6,8 @@ import {
   helpFor,
   helpRequested,
   trailerFor
-} from "./chunk-ZD4ND6X6.js";
-import "./chunk-RNAH5T4W.js";
+} from "./chunk-OCVALOGK.js";
+import "./chunk-IDF46P7R.js";
 import "./chunk-UPHQM6NZ.js";
 
 // src/simulate.ts
@@ -276,6 +276,13 @@ options:
   --overruns-max <n>          fail above this many server tick overruns in the run window
                               (default 0; the count is read from the server, and the run says
                               so when it could not be read)
+  --queue <name>              queue for rooms through the matchmaker instead of creating one:
+                              every bot calls the real match API and joins the room its ticket
+                              names. Needs --control
+  --control <https://...>     the control plane the queue lives on. \`irtio dev\` runs none, so a
+                              queued run points at a real one (staging, or a test plane)
+  --party <n>                 group each n consecutive bots into one party, so they queue
+                              together and land in one room. Needs --queue
   --profile                   print where the run's bytes went, by collection and field, as the
                               bots saw them
   --profile-top <n>           rows in that table (default 12; implies --profile)
@@ -350,6 +357,21 @@ function parseSimulateArgs(args) {
       case "--truth":
         parsed.truth = true;
         break;
+      // ---- M6 lane E: testing parity ---- (D73-c)
+      case "--queue":
+        parsed.queue = value();
+        break;
+      case "--control":
+        parsed.control = value();
+        break;
+      case "--party": {
+        const size = positive(value(), "--party");
+        if (!Number.isInteger(size) || size < 2) {
+          throw new Error("irtio simulate: --party must be a whole number of bots, at least 2");
+        }
+        parsed.party = size;
+        break;
+      }
       case "--profile":
         parsed.profile = true;
         break;
@@ -378,6 +400,16 @@ function parseSimulateArgs(args) {
         throw new Error(`irtio simulate: unknown option ${JSON.stringify(arg)}`);
     }
   }
+  if (parsed.queue !== void 0 && parsed.control === void 0) {
+    throw new Error(
+      "irtio simulate: --queue needs --control. The matchmaker lives on the control plane and `irtio dev` runs none, so there is no queue at a dev server to join."
+    );
+  }
+  if (parsed.party !== void 0 && parsed.queue === void 0) {
+    throw new Error(
+      "irtio simulate: --party needs --queue. A party is a group that queues together, and a run that is not queueing has nothing to group."
+    );
+  }
   return parsed;
 }
 function monorepoPackages() {
@@ -423,16 +455,15 @@ async function loadProjectSchema(options) {
   }
   return { schema, file: entry };
 }
+function is2dWorld(world) {
+  return world !== void 0 && world.engine === "matter2d" && !("why" in world);
+}
 function isUnpredictedWorld(world) {
-  return world !== void 0 && "unpredicted" in world;
+  return world !== void 0 && "why" in world;
 }
-async function loadProjectWorld(options) {
-  const entry = WORLD_CANDIDATES.map((c) => path2.resolve(options.cwd, c)).find(
-    (f) => existsSync2(f)
-  );
-  if (entry === void 0) return void 0;
+var ROOM_CANDIDATES = ["irtio/room.ts", "irtio/room.js", "room.ts"];
+async function bundleAndImport(entry, outfile, options) {
   await mkdir2(options.outDir, { recursive: true });
-  const outfile = path2.join(options.outDir, "world.mjs");
   const alias = options.irtioPackages ?? monorepoPackages();
   await esbuild2.build({
     entryPoints: [entry],
@@ -440,34 +471,93 @@ async function loadProjectWorld(options) {
     format: "esm",
     platform: "node",
     outfile,
-    external: ["@dimforge/rapier3d-compat"],
+    external: ["@dimforge/rapier3d-compat", "matter-js"],
     ...alias !== void 0 ? { alias } : {}
   });
-  const module = await import(`${pathToFileURL2(outfile).href}?v=${Date.now()}-${importSeq2++}`);
+  return await import(`${pathToFileURL2(outfile).href}?v=${Date.now()}-${importSeq2++}`);
+}
+function hookMap(value) {
+  return typeof value === "object" && value !== null ? value : void 0;
+}
+async function detectMatter2dRoom(options) {
+  const entry = ROOM_CANDIDATES.map((c) => path2.resolve(options.cwd, c)).find((f) => existsSync2(f));
+  if (entry === void 0) return void 0;
+  let module;
+  try {
+    module = await bundleAndImport(entry, path2.join(options.outDir, "room-engine.mjs"), options);
+  } catch {
+    return void 0;
+  }
+  const definition = module.default ?? module.room;
+  return definition?.config?.physics?.engine === "matter2d" ? entry : void 0;
+}
+function whyNotPredictable(world) {
+  if (world.bodies === void 0 || Object.keys(world.bodies).length === 0) {
+    return `${world.file} exports no \`bodies\`, so there are no shapes to build a local world from; bots run without client prediction.
+  export the body factories your client passes to \`joinRoom({ physics2d })\`.`;
+  }
+  const steered = world.intents !== void 0 || world.settle !== void 0;
+  if (!steered && world.gravity.x === 0 && world.gravity.y === 0) {
+    return `${world.file} exports no \`intents\` and no \`settle\`, and its gravity is zero, so nothing in a local world built from it could ever move a body; bots run without client prediction.
+  export the steering hooks your client passes to \`joinRoom({ physics2d })\` (a room that applies its forces inside \`tick()\` has none to share).`;
+  }
+  return void 0;
+}
+async function loadProjectWorld(options) {
+  const entry = WORLD_CANDIDATES.map((c) => path2.resolve(options.cwd, c)).find(
+    (f) => existsSync2(f)
+  );
+  const matter2dRoom = async (why) => {
+    const room = await detectMatter2dRoom(options);
+    return room === void 0 ? void 0 : { engine: "matter2d", why: why(room), file: room };
+  };
+  if (entry === void 0) {
+    return matter2dRoom(
+      (room) => `${room} declares a matter2d room and there is no shared world module beside it, so bots run without client prediction.
+  export the \`physics2d\` block your client passes to \`joinRoom\` from \`irtio/world.ts\` (gravity, bodies, intents, settle) to predict.`
+    );
+  }
+  const module = await bundleAndImport(entry, path2.join(options.outDir, "world.mjs"), options);
   const gravity = module.gravity;
-  if (typeof gravity !== "object" || gravity === null || typeof gravity.x !== "number") {
-    throw new Error(
-      `irtio simulate: ${entry} does not export a { x, y, z } gravity.
+  const notAWorld = new Error(
+    `irtio simulate: ${entry} does not export a { x, y, z } gravity.
   the shared world-builder must export the same gravity the room config uses
   (this is what \`irtio init --physics\` writes)`
+  );
+  if (typeof gravity !== "object" || gravity === null || typeof gravity.x !== "number") {
+    const recognised = await matter2dRoom(
+      () => `${entry} exports no gravity, so it is not the client world a matter2d room predicts from; bots run without client prediction.
+  export the \`physics2d\` block your client passes to \`joinRoom\` (gravity, bodies, intents, settle) from this module to predict.`
     );
+    if (recognised !== void 0) return recognised;
+    throw notAWorld;
   }
   if (typeof gravity.z !== "number") {
-    return { unpredicted: "matter2d", file: entry };
-  }
-  if (typeof gravity.y !== "number") {
-    throw new Error(
-      `irtio simulate: ${entry} does not export a { x, y, z } gravity.
-  the shared world-builder must export the same gravity the room config uses
-  (this is what \`irtio init --physics\` writes)`
-    );
+    if (typeof gravity.y !== "number") throw notAWorld;
+    const world2d = {
+      engine: "matter2d",
+      gravity: { x: gravity.x, y: gravity.y },
+      ...typeof module.timestep === "number" ? { timestep: module.timestep } : {},
+      ...typeof module.setup === "function" ? { setup: module.setup } : {},
+      ...hookMap(module.bodies) !== void 0 ? { bodies: module.bodies } : {},
+      ...hookMap(module.intents) !== void 0 ? { intents: module.intents } : {},
+      ...hookMap(module.settle) !== void 0 ? { settle: module.settle } : {},
+      ...typeof module.epsilon === "number" ? { epsilon: module.epsilon } : {},
+      ...typeof module.maxPredictedBodies === "number" ? { maxPredictedBodies: module.maxPredictedBodies } : {},
+      ...typeof module.smoothingHalfLifeMs === "number" ? { smoothingHalfLifeMs: module.smoothingHalfLifeMs } : {},
+      file: entry
+    };
+    const why = whyNotPredictable(world2d);
+    return why === void 0 ? world2d : { engine: "matter2d", why, file: entry };
   }
+  if (typeof gravity.y !== "number") throw notAWorld;
   return {
+    engine: "rapier3d",
     gravity,
     ...typeof module.timestep === "number" ? { timestep: module.timestep } : {},
     ...typeof module.setup === "function" ? { setup: module.setup } : {},
-    ...typeof module.bodies === "object" && module.bodies !== null ? { bodies: module.bodies } : {},
-    ...typeof module.intents === "object" && module.intents !== null ? { intents: module.intents } : {},
+    ...hookMap(module.bodies) !== void 0 ? { bodies: module.bodies } : {},
+    ...hookMap(module.intents) !== void 0 ? { intents: module.intents } : {},
     file: entry
   };
 }
@@ -493,6 +583,48 @@ function everyByteEqual(a, b) {
   for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
   return true;
 }
+var DETERMINISM_STEPS_2D = 60;
+function canonicalMatterWorld(matter, engine) {
+  return matter.Composite.allBodies(engine.world).map(
+    (b) => [b.position.x, b.position.y, b.angle, b.velocity.x, b.velocity.y, b.angularVelocity].join(
+      ","
+    )
+  ).join(";");
+}
+async function checkWorld2dDeterminism(world, schema) {
+  const factories = world.bodies ?? {};
+  const exercised = schema ? schema.collections.filter(
+    (c) => c.physics !== void 0 && factories[c.name] !== void 0
+  ) : [];
+  if (!world.setup && exercised.length === 0) return void 0;
+  const { initMatter } = await import("@irtio/runtime");
+  const { defaultRecord } = await import("@irtio/schema");
+  const matter = await initMatter();
+  const stepMs = (world.timestep ?? 1 / 60) * 1e3;
+  const build3 = () => {
+    const engine = matter.Engine.create();
+    engine.gravity.x = world.gravity.x;
+    engine.gravity.y = world.gravity.y;
+    try {
+      world.setup?.(engine, matter);
+      for (const desc of exercised) {
+        try {
+          const spec = factories[desc.name](matter, defaultRecord(desc), "irtio-determinism-check");
+          if (spec?.body !== void 0) matter.Composite.add(engine.world, spec.body);
+        } catch {
+        }
+      }
+      for (let i = 0; i < DETERMINISM_STEPS_2D; i++) matter.Engine.update(engine, stepMs);
+      return canonicalMatterWorld(matter, engine);
+    } finally {
+      matter.Engine.clear(engine);
+    }
+  };
+  const first = build3();
+  const second = build3();
+  if (first === second) return void 0;
+  return `the world builder is not deterministic: two builds of ${world.file} disagree after ${DETERMINISM_STEPS_2D} steps. It must be pure over synced inputs \u2014 no Math.random(), no clock, no module state; put seeds and level parameters in synced state instead.`;
+}
 var TICK_HEALTH_TIMEOUT_MS = 2e3;
 function stateUrlFor(wsUrl) {
   let parsed;
@@ -647,11 +779,30 @@ function formatReport(report, schemaLoaded) {
   const convergence = report.convergenceLagMs === void 0 ? "convergence not sampled" : `convergence ${report.convergenceLagMs} ms (p50 of ${report.convergence?.samples ?? 0})`;
   const { mispredictions, mispredictionMagnitude, mispredictionMax, snaps } = report.totals;
   const misprediction = mispredictions === 0 ? "misprediction 0" : `misprediction mean ${(mispredictionMagnitude / mispredictions).toFixed(1)} max ${mispredictionMax.toFixed(1)}`;
+  const { messagesSent, messagesReceived, messagesDropped } = report.totals;
+  const messages = messagesSent + messagesReceived + messagesDropped === 0 ? "" : ` \xB7 ${messagesSent} msg out / ${messagesReceived} in` + (messagesDropped > 0 ? ` / ${messagesDropped} dropped` : "");
   lines.push(
     pc.dim(
-      `  ${report.framesPerSecond} frames/s \xB7 in ${rate(report.bytesInPerSecondPerBot)}/bot \xB7 out ${rate(report.bytesOutPerSecondPerBot)}/bot \xB7 ${report.totals.corrections} corrections \xB7 ${misprediction} \xB7 ${snaps} snap(s) \xB7 ${convergence}`
+      `  ${report.framesPerSecond} frames/s \xB7 in ${rate(report.bytesInPerSecondPerBot)}/bot \xB7 out ${rate(report.bytesOutPerSecondPerBot)}/bot \xB7 ${report.totals.corrections} corrections \xB7 ${misprediction} \xB7 ${snaps} snap(s) \xB7 ${convergence}${messages}`
     )
   );
+  const prediction = report.prediction;
+  if (prediction !== void 0) {
+    const { syncCorrections, proxiedCorrections, suppressedCorrections } = report.totals;
+    lines.push(
+      pc.dim(
+        `  prediction: ${prediction.bots}/${report.bots} bot(s) held a local world \xB7 peak ${prediction.proxies} proxied, ${prediction.absent} absent \xB7 ${mispredictions} misprediction(s), ${suppressedCorrections} within-epsilon, ${proxiedCorrections} proxied, ${syncCorrections} body-sync`
+      )
+    );
+    if (prediction.absent > 0) {
+      lines.push(
+        pc.yellow(
+          `  ${prediction.absent} instance(s) had no body in a local world at once, so predicted bodies passed through them.
+  raise maxProxyBodies, or give the collection a body factory on the client.`
+        )
+      );
+    }
+  }
   if (report.tracePath !== void 0) lines.push(pc.dim(`  trace: ${report.tracePath}`));
   lines.push("");
   const failed = report.invariants.filter((i) => !i.ok);
@@ -742,7 +893,8 @@ function formatHits(rows) {
     `  ${pc.bold("hit registration")} ${pc.dim(`(${rows.length} shot(s))`)}`
   ];
   for (const row of rows) {
-    const at = row.serverTick === void 0 ? "no tick" : `tick ${row.serverTick}${row.estimated ? " (estimated)" : ""}`;
+    const marks = [row.estimated ? "estimated" : void 0, row.rewound ? "rewound" : void 0].filter((m) => m !== void 0).map((m) => ` (${m})`).join("");
+    const at = row.serverTick === void 0 ? "no tick" : `tick ${row.serverTick}${marks}`;
     if (row.missDistance === void 0) {
       lines.push(
         pc.yellow(
@@ -758,12 +910,46 @@ function formatHits(rows) {
   const measured = rows.filter((r) => r.missDistance !== void 0);
   if (measured.length > 0) {
     const mean = measured.reduce((s, r) => s + (r.missDistance ?? 0), 0) / measured.length;
+    const worst = Math.max(...measured.map((r) => r.missDistance ?? 0));
+    const rewound = measured.filter((r) => r.rewound === true).length;
+    const verdict = rewound === 0 ? "Nothing here compensates for lag; this is what a player at this latency would experience." : `${rewound} of ${measured.length} shot(s) were resolved through room.rewind, against the world the shooter was looking at.`;
     lines.push(
       pc.dim(
-        `  mean miss ${mean.toFixed(2)} over ${measured.length} shot(s). Nothing here compensates for lag; this is what a player at this latency would experience.`
+        `  mean miss ${mean.toFixed(2)}, worst ${worst.toFixed(2)} over ${measured.length} shot(s). ${verdict}`
+      )
+    );
+  }
+  return lines;
+}
+function formatMatchmaking(summary, failures) {
+  const lines = ["", `  ${pc.bold("matchmaking")}`];
+  lines.push(
+    pc.dim(
+      `  ${summary.tickets} ticket(s), ${summary.rooms} room(s), wait p50 ${summary.waitP50Ms} ms p95 ${summary.waitP95Ms} ms max ${summary.waitMaxMs} ms, ${summary.timeouts} timeout(s)` + (summary.backfills > 0 ? `, ${summary.backfills} backfill(s)` : "") + (summary.parties > 0 ? `, parties intact ${summary.partiesIntact}/${summary.parties}` : "")
+    )
+  );
+  for (const split of summary.splitParties) {
+    lines.push(
+      pc.red(
+        `  FAIL party ${split.party} was split across ${split.rooms.length} rooms: ` + split.rooms.join(", ")
+      )
+    );
+  }
+  for (const room of summary.overfullRooms) {
+    lines.push(
+      pc.red(
+        `  FAIL room ${room.room} holds ${room.bots} bots on a ticket that seats ${room.size}`
       )
     );
   }
+  for (const failure of failures) {
+    lines.push(
+      pc.red(`  FAIL bot ${failure.requested} got no ticket: ${failure.code} \u2014 ${failure.message}`)
+    );
+  }
+  if (summary.splitParties.length === 0 && summary.overfullRooms.length === 0 && failures.length === 0) {
+    lines.push(pc.green("  every bot was answered, and every party landed in one room."));
+  }
   return lines;
 }
 function point(p) {
@@ -856,15 +1042,18 @@ async function runSimulation(options = {}) {
     (c) => c.physics !== void 0
   );
   const loadedWorld = hasPhysics ? await loadProjectWorld({ cwd, outDir, irtioPackages: options.irtioPackages }) : void 0;
-  if (isUnpredictedWorld(loadedWorld)) {
-    log(
-      `physics: ${loadedWorld.file} is a 2D (matter2d) world; bots run without client prediction`
-    );
+  const world2d = is2dWorld(loadedWorld) ? loadedWorld : void 0;
+  const world = is2dWorld(loadedWorld) || isUnpredictedWorld(loadedWorld) ? void 0 : loadedWorld;
+  if (world2d !== void 0) {
+    log(`physics: ${world2d.file} is a matter2d world; bots predict with physics2d`);
+  } else if (isUnpredictedWorld(loadedWorld)) {
+    log(pc.yellow(`physics: ${loadedWorld.why}`));
   }
-  const world = isUnpredictedWorld(loadedWorld) ? void 0 : loadedWorld;
   let worldError;
   if (world) {
     worldError = await checkWorldDeterminism(world);
+  } else if (world2d) {
+    worldError = await checkWorld2dDeterminism(world2d, loaded?.schema);
   }
   const conditionsSpec = scenario?.conditions ?? conditionsFrom(options);
   const cheatSpec = scenario?.cheat ?? cheatFrom(options);
@@ -883,9 +1072,27 @@ async function runSimulation(options = {}) {
     ...options.overrunsMax !== void 0 ? { overrunsMax: options.overrunsMax } : {},
     ...options.profile === true ? { profile: true } : {}
   };
-  const predicted = world !== void 0 && worldError === void 0;
+  const predicted = (world !== void 0 || world2d !== void 0) && worldError === void 0;
+  const projectKey = options.key ?? loaded?.schema?.project;
+  if (options.queue !== void 0 && (projectKey === void 0 || projectKey === "")) {
+    throw new RunNotPerformedError(
+      "irtio simulate: --queue needs a project key, and this schema carries none.\n  build the schema with `irtio` so it names its project, or pass --key."
+    );
+  }
+  const match = options.queue !== void 0 && options.control !== void 0 ? {
+    controlUrl: options.control,
+    project: projectKey,
+    queue: options.queue,
+    ...options.matchTimeoutMs !== void 0 ? { timeoutMs: options.matchTimeoutMs } : {},
+    ...options.party !== void 0 ? (
+      // Consecutive groups of `n`: bots 0..n-1 are party 0, n..2n-1 are party 1. A
+      // trailing group smaller than `n` is still a party, of whatever is left.
+      { party: (index) => Math.floor(index / options.party) }
+    ) : {}
+  } : void 0;
   const spawn = {
     ...common,
+    ...match !== void 0 ? { match } : {},
     ...options.joinTimeoutMs !== void 0 ? { joinTimeoutMs: options.joinTimeoutMs } : {},
     ...options.roomGoneGraceMs !== void 0 ? { roomGoneGraceMs: options.roomGoneGraceMs } : {}
   };
@@ -895,7 +1102,7 @@ async function runSimulation(options = {}) {
       ...spawn,
       schema: loaded.schema,
       script: scenario?.script ?? randomScript(loaded.schema, { cheat: cheatSpec ?? false }),
-      ...predicted ? {
+      ...predicted && world !== void 0 ? {
         physics: {
           gravity: world.gravity,
           ...world.timestep !== void 0 ? { timestep: world.timestep } : {},
@@ -903,6 +1110,20 @@ async function runSimulation(options = {}) {
           ...world.bodies !== void 0 ? { bodies: world.bodies } : {},
           ...world.intents !== void 0 ? { intents: world.intents } : {}
         }
+      } : {},
+      // ---- M6 lane E: testing parity ---- (D73-a)
+      ...predicted && world2d !== void 0 ? {
+        physics2d: {
+          gravity: world2d.gravity,
+          ...world2d.timestep !== void 0 ? { timestep: world2d.timestep } : {},
+          ...world2d.setup !== void 0 ? { setup: world2d.setup } : {},
+          ...world2d.bodies !== void 0 ? { bodies: world2d.bodies } : {},
+          ...world2d.intents !== void 0 ? { intents: world2d.intents } : {},
+          ...world2d.settle !== void 0 ? { settle: world2d.settle } : {},
+          ...world2d.epsilon !== void 0 ? { epsilon: world2d.epsilon } : {},
+          ...world2d.maxPredictedBodies !== void 0 ? { maxPredictedBodies: world2d.maxPredictedBodies } : {},
+          ...world2d.smoothingHalfLifeMs !== void 0 ? { smoothingHalfLifeMs: world2d.smoothingHalfLifeMs } : {}
+        }
       } : {}
     }) : await spawnBots(bots, { ...spawn, script: relayEchoScript() });
   } catch (err) {
@@ -1049,6 +1270,9 @@ async function runSimulation(options = {}) {
   if (report.profile !== void 0) {
     for (const line of formatRunProfile(report, options.profileTop)) log(line);
   }
+  if (report.matchmaking !== void 0) {
+    for (const line of formatMatchmaking(report.matchmaking, runner.matchFailures)) log(line);
+  }
   if (adversarial !== void 0) for (const line of formatAdversarial(adversarial)) log(line);
   if (hits.length > 0) for (const line of formatHits(hits)) log(line);
   if (truth !== void 0) for (const line of formatTruth(truth)) log(line);
@@ -1059,11 +1283,14 @@ async function runSimulation(options = {}) {
     log(pc.red(`  FAIL world-builder: ${worldError}`));
   } else if (predicted) {
     const suppressed = report.totals.suppressedCorrections;
+    const engine = world2d !== void 0 ? "matter2d" : "rapier3d";
     log(
       pc.dim(
-        `  bots predicted physics from ${path2.relative(cwd, world?.file ?? "")} (build-twice check held; ${suppressed} within-epsilon correction(s) suppressed)`
+        `  bots predicted ${engine} physics from ${path2.relative(cwd, world?.file ?? world2d?.file ?? "")} (build-twice check held; ${suppressed} within-epsilon correction(s) suppressed)`
       )
     );
+  } else if (hasPhysics && isUnpredictedWorld(loadedWorld)) {
+    log(pc.yellow("  bots interpolated instead of predicting; see the physics line above."));
   } else if (hasPhysics) {
     log(
       pc.yellow(
@@ -1075,7 +1302,10 @@ async function runSimulation(options = {}) {
     log(pc.red(`  bot ${failure.bot} script failed: ${String(failure.error)}`));
   }
   if (fatal !== void 0) log(pc.red(`  run ended early: ${fatal}`));
-  const exitCode = endedBy === "ceiling" ? 2 : !report.ok || worldError !== void 0 || runner.scriptErrors.length > 0 || scenarioRun?.ok === false || // D43: a difference between what the clients held and what the save says the server
+  const exitCode = endedBy === "ceiling" ? 2 : !report.ok || worldError !== void 0 || runner.scriptErrors.length > 0 || // D73-c: a bot that never got a ticket is a measured failure of the front door, so it
+  // is exit 1 like every other one. The run still happened for the bots that got in, and
+  // the matchmaking section names the ones that did not.
+  runner.matchFailures.length > 0 || scenarioRun?.ok === false || // D43: a difference between what the clients held and what the save says the server
   // held is a measured violation, so it is exit 1 like every other one. A run that could
   // not take a save at all is not: nothing was measured, and the section says so in
   // words rather than turning "unread" into a verdict, which is D36's `unavailable` rule
@@ -1091,6 +1321,7 @@ async function runSimulation(options = {}) {
     ...truth !== void 0 ? { truth } : {},
     schema: loaded !== void 0,
     predicted,
+    matchFailures: runner.matchFailures,
     ...worldError !== void 0 ? { worldError } : {},
     endedBy,
     ...fatal !== void 0 ? { fatal } : {},
@@ -1129,8 +1360,11 @@ export {
   ScenarioNotRunError,
   USAGE,
   ceilingFor,
+  checkWorld2dDeterminism,
   checkWorldDeterminism,
+  detectMatter2dRoom,
   formatBuildIdentity,
+  is2dWorld,
   isUnpredictedWorld,
   loadProjectSchema,
   loadProjectWorld,