@irtio/cli 0.5.2 → 0.7.0

package/dist/simulate.js

@@ -1,18 +1,204 @@
+import {
+  formatProfileTable
+} from "./chunk-ZK5JLUD4.js";
 import {
   HelpRequested,
   helpFor,
   helpRequested,
   trailerFor
-} from "./chunk-TV66QHFP.js";
+} from "./chunk-OCVALOGK.js";
+import "./chunk-IDF46P7R.js";
+import "./chunk-UPHQM6NZ.js";
 
 // src/simulate.ts
+import { existsSync as existsSync2 } from "fs";
+import { mkdir as mkdir2, writeFile } from "fs/promises";
+import * as path2 from "path";
+import { fileURLToPath as fileURLToPath2, pathToFileURL as pathToFileURL2 } from "url";
+import {
+  captureClientState,
+  cheatPredicate,
+  correlateShots,
+  describeConditions,
+  diffAgainstSave,
+  hasConditions,
+  makeTimeline,
+  randomScript,
+  relayEchoScript,
+  spawnBots
+} from "@irtio/bots";
+import { decodeSave } from "@irtio/runtime";
+import * as esbuild2 from "esbuild";
+import pc from "picocolors";
+
+// src/scenario.ts
 import { existsSync } from "fs";
 import { mkdir } from "fs/promises";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL } from "url";
-import { randomScript, relayEchoScript, spawnBots } from "@irtio/bots";
+import { looksLikeScenario } from "@irtio/bots";
 import * as esbuild from "esbuild";
-import pc from "picocolors";
+var TIMELINE_TIMEOUT_MS = 15e3;
+var ScenarioNotRunError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+  }
+  cause;
+  name = "ScenarioNotRunError";
+};
+var importSeq = 0;
+function monorepoScenarioPackages() {
+  const packagesDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+  const out = {};
+  for (const name of ["bots", "client", "schema", "protocol", "server", "runtime"]) {
+    const src = path.join(packagesDir, name, "src/index.ts");
+    if (existsSync(src)) out[`@irtio/${name}`] = src;
+  }
+  return out;
+}
+async function loadScenario(options) {
+  const entry = path.resolve(options.cwd, options.file);
+  if (!existsSync(entry)) {
+    throw new ScenarioNotRunError(
+      `irtio simulate: no scenario file at ${entry}.
+  --scenario takes a path to a module whose default export is defineScenario({ ... })`
+    );
+  }
+  await mkdir(options.outDir, { recursive: true });
+  const outfile = path.join(options.outDir, "scenario.mjs");
+  const alias = { ...monorepoScenarioPackages(), ...options.irtioPackages ?? {} };
+  try {
+    await esbuild.build({
+      entryPoints: [entry],
+      bundle: true,
+      format: "esm",
+      platform: "node",
+      outfile,
+      // The physics engine is resolved at runtime by whoever needs it, never bundled twice.
+      external: ["@dimforge/rapier3d-compat"],
+      ...Object.keys(alias).length > 0 ? { alias } : {}
+    });
+  } catch (err) {
+    throw new ScenarioNotRunError(
+      `irtio simulate: ${path.relative(options.cwd, entry)} did not compile.
+  ` + (err instanceof Error ? err.message : String(err)),
+      err
+    );
+  }
+  let module;
+  try {
+    module = await import(`${pathToFileURL(outfile).href}?v=${Date.now()}-${importSeq++}`);
+  } catch (err) {
+    throw new ScenarioNotRunError(
+      `irtio simulate: ${path.relative(options.cwd, entry)} threw while loading.
+  ` + (err instanceof Error ? err.message : String(err)),
+      err
+    );
+  }
+  const scenario = module.default ?? module.scenario;
+  if (!looksLikeScenario(scenario)) {
+    const names = Object.keys(module).join(", ") || "nothing";
+    throw new ScenarioNotRunError(
+      `irtio simulate: ${path.relative(options.cwd, entry)} does not export a scenario.
+  it exports: ${names}
+  add \`export default defineScenario({ bots, script, assert })\` from \`@irtio/bots\``
+    );
+  }
+  return { scenario, file: entry };
+}
+function inspectorUrlFor(wsUrl, route) {
+  let parsed;
+  try {
+    parsed = new URL(wsUrl);
+  } catch {
+    return void 0;
+  }
+  if (parsed.protocol === "ws:") parsed.protocol = "http:";
+  else if (parsed.protocol === "wss:") parsed.protocol = "https:";
+  else if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return void 0;
+  parsed.pathname = `/__irt/${route}`;
+  parsed.search = "";
+  return parsed.toString();
+}
+function noTap(wsUrl, what) {
+  return new ScenarioNotRunError(
+    `irtio simulate: could not ${what} at ${wsUrl}.
+  Scenarios read the authoritative timeline, which only \`irtio dev\` exposes. Start the
+  room with \`irtio dev\` and point --url at it. A deployed tenant has no timeline tap yet.`
+  );
+}
+async function startTimeline(wsUrl, roomId, caps = {}) {
+  const base = inspectorUrlFor(wsUrl, "record.json");
+  if (base === void 0) throw noTap(wsUrl, "derive an inspector URL");
+  const url = new URL(base);
+  url.searchParams.set("room", roomId);
+  if (caps.maxTicks !== void 0) url.searchParams.set("maxTicks", String(caps.maxTicks));
+  if (caps.maxRecords !== void 0) url.searchParams.set("maxRecords", String(caps.maxRecords));
+  let response;
+  try {
+    response = await fetch(url, { signal: AbortSignal.timeout(TIMELINE_TIMEOUT_MS) });
+  } catch (err) {
+    throw noTap(
+      wsUrl,
+      `reach the timeline route (${err instanceof Error ? err.message : String(err)})`
+    );
+  }
+  if (!response.ok) {
+    throw noTap(wsUrl, `start recording room ${roomId} (the server answered ${response.status})`);
+  }
+}
+async function readTimeline(wsUrl, roomId) {
+  const base = inspectorUrlFor(wsUrl, "timeline.json");
+  if (base === void 0) throw noTap(wsUrl, "derive an inspector URL");
+  const url = new URL(base);
+  url.searchParams.set("room", roomId);
+  let response;
+  try {
+    response = await fetch(url, { signal: AbortSignal.timeout(TIMELINE_TIMEOUT_MS) });
+  } catch (err) {
+    throw noTap(wsUrl, `read the timeline (${err instanceof Error ? err.message : String(err)})`);
+  }
+  if (!response.ok) {
+    throw noTap(
+      wsUrl,
+      `read the timeline for room ${roomId} (the server answered ${response.status})`
+    );
+  }
+  const dump = await response.json();
+  if (!Array.isArray(dump?.frames)) {
+    throw noTap(wsUrl, `read the timeline for room ${roomId} (the answer had no frames)`);
+  }
+  return dump;
+}
+async function fetchSave(wsUrl, roomId) {
+  const base = inspectorUrlFor(wsUrl, "save.json");
+  if (base === void 0) {
+    return { error: `no inspector URL can be derived from ${wsUrl}` };
+  }
+  const url = new URL(base);
+  url.searchParams.set("room", roomId);
+  let response;
+  try {
+    response = await fetch(url, { signal: AbortSignal.timeout(TIMELINE_TIMEOUT_MS) });
+  } catch (err) {
+    return {
+      error: `the save route at ${wsUrl} could not be reached (${err instanceof Error ? err.message : String(err)}). Only \`irtio dev\` serves one.`
+    };
+  }
+  if (!response.ok) {
+    return { error: `the server answered ${response.status} when asked to save room ${roomId}` };
+  }
+  const body = await response.json();
+  if (typeof body.saveId !== "string" || typeof body.bytes !== "string") {
+    return { error: `the save route answered without bytes for room ${roomId}` };
+  }
+  return {
+    save: { saveId: body.saveId, bytes: new Uint8Array(Buffer.from(body.bytes, "base64")) }
+  };
+}
+
+// src/simulate.ts
 var DEFAULT_URL = "ws://localhost:7070";
 var DEFAULT_BOTS = 5;
 var DEFAULT_SECONDS = 10;
@@ -32,6 +218,36 @@ function nonNegativeInt(raw, flag) {
   }
   return value;
 }
+var CONDITION_KEYS = ["rttMs", "jitterMs", "loss", "duplicate", "reorder", "reorderMs"];
+function parseConditions(raw, flag) {
+  let value;
+  try {
+    value = JSON.parse(raw);
+  } catch {
+    throw new Error(
+      `irtio simulate: ${flag} needs a JSON object, for example '{"rttMs":200,"loss":0.02}'. Got ${JSON.stringify(raw)}`
+    );
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`irtio simulate: ${flag} needs a JSON object, got ${JSON.stringify(raw)}`);
+  }
+  const out = {};
+  for (const [key, v] of Object.entries(value)) {
+    if (!CONDITION_KEYS.includes(key)) {
+      throw new Error(
+        `irtio simulate: ${flag} has no key "${key}". It takes ${CONDITION_KEYS.join(", ")}.`
+      );
+    }
+    if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
+      throw new Error(`irtio simulate: ${flag} key "${key}" must be a non-negative number`);
+    }
+    if ((key === "loss" || key === "duplicate" || key === "reorder") && v > 1) {
+      throw new Error(`irtio simulate: ${flag} key "${key}" is a probability, so it is 0 to 1`);
+    }
+    out[key] = v;
+  }
+  return out;
+}
 var USAGE = `usage: irtio simulate [options]
 
 Drives N real clients at a running room and checks the built-in invariants. Run it from a project
@@ -44,13 +260,32 @@ options:
   --url <ws://...>            where to connect (default ${DEFAULT_URL})
   --key <projectKey>          the project key to present
   --trace <path>              write the frame trace here
-  --cheat                     send illegal writes and expect corrections
+  --scenario <file>           run a scenario module and assert against the recorded timeline
+  --cheat                     send illegal writes and expect corrections, from every bot
+  --cheat-bot <index>         only this bot cheats (repeatable)
+  --conditions <json>         inject network conditions into every bot, e.g.
+                              '{"rttMs":200,"jitterMs":20,"loss":0.02}'. Keys: rttMs, jitterMs,
+                              loss, duplicate, reorder, reorderMs. Loss, duplicate and reorder
+                              touch state frames only, so a join always completes
+  --conditions-bot <i>:<json> conditions for one bot, overriding --conditions (repeatable)
+  --truth                     save the room at the end and diff it against what each client
+                              received, within that client's visibility
   --misprediction-max <units> fail if one correction snaps a prediction further than this
   --snaps-max <n>             fail above this many cap-exceeded reconciliations
   --corrections-max <perSec>  fail above this correction rate per bot
   --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)
   -h, --help                  print this
 
 exit codes: 0 every invariant held, 1 something was measured and failed, 2 the run could not be
@@ -92,9 +327,63 @@ function parseSimulateArgs(args) {
       case "--trace":
         parsed.trace = value();
         break;
+      case "--scenario":
+        parsed.scenario = value();
+        break;
       case "--cheat":
         parsed.cheat = true;
         break;
+      case "--cheat-bot":
+        (parsed.cheatBots ??= []).push(nonNegativeInt(value(), "--cheat-bot"));
+        break;
+      case "--conditions":
+        parsed.conditions = parseConditions(value(), "--conditions");
+        break;
+      case "--conditions-bot": {
+        const raw = value();
+        const colon = raw.indexOf(":");
+        if (colon === -1) {
+          throw new Error(
+            `irtio simulate: --conditions-bot takes <index>:<json>, for example 0:{"rttMs":200}. Got ${JSON.stringify(raw)}`
+          );
+        }
+        const index = nonNegativeInt(raw.slice(0, colon), "--conditions-bot");
+        (parsed.conditionsPerBot ??= {})[index] = parseConditions(
+          raw.slice(colon + 1),
+          "--conditions-bot"
+        );
+        break;
+      }
+      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;
+      case "--profile-top": {
+        const n = Number(value());
+        if (!Number.isInteger(n) || n < 1 || n > 200) {
+          throw new Error("irtio simulate: --profile-top must be a row count between 1 and 200");
+        }
+        parsed.profile = true;
+        parsed.profileTop = n;
+        break;
+      }
       case "--misprediction-max":
         parsed.mispredictionMax = positive(value(), "--misprediction-max");
         break;
@@ -111,32 +400,42 @@ 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() {
-  const packagesDir = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-  const schema = path.join(packagesDir, "schema/src/index.ts");
-  if (!existsSync(schema)) return void 0;
+  const packagesDir = path2.resolve(path2.dirname(fileURLToPath2(import.meta.url)), "../..");
+  const schema = path2.join(packagesDir, "schema/src/index.ts");
+  if (!existsSync2(schema)) return void 0;
   return {
     "@irtio/schema": schema,
-    "@irtio/protocol": path.join(packagesDir, "protocol/src/index.ts"),
-    "@irtio/server": path.join(packagesDir, "server/src/index.ts")
+    "@irtio/protocol": path2.join(packagesDir, "protocol/src/index.ts"),
+    "@irtio/server": path2.join(packagesDir, "server/src/index.ts")
   };
 }
-var importSeq = 0;
+var importSeq2 = 0;
 function looksLikeSchema(value) {
   const candidate = value;
   return typeof candidate === "object" && candidate !== null && Array.isArray(candidate.collections) && candidate.hash8 instanceof Uint8Array;
 }
 async function loadProjectSchema(options) {
-  const entry = SCHEMA_CANDIDATES.map((c) => path.resolve(options.cwd, c)).find(
-    (f) => existsSync(f)
+  const entry = SCHEMA_CANDIDATES.map((c) => path2.resolve(options.cwd, c)).find(
+    (f) => existsSync2(f)
   );
   if (entry === void 0) return void 0;
-  await mkdir(options.outDir, { recursive: true });
-  const outfile = path.join(options.outDir, "schema.mjs");
+  await mkdir2(options.outDir, { recursive: true });
+  const outfile = path2.join(options.outDir, "schema.mjs");
   const alias = options.irtioPackages ?? monorepoPackages();
-  await esbuild.build({
+  await esbuild2.build({
     entryPoints: [entry],
     bundle: true,
     format: "esm",
@@ -144,7 +443,7 @@ async function loadProjectSchema(options) {
     outfile,
     ...alias !== void 0 ? { alias } : {}
   });
-  const module = await import(`${pathToFileURL(outfile).href}?v=${Date.now()}-${importSeq++}`);
+  const module = await import(`${pathToFileURL2(outfile).href}?v=${Date.now()}-${importSeq2++}`);
   const schema = module.schema ?? module.default;
   if (!looksLikeSchema(schema)) {
     const names = Object.keys(module).join(", ") || "nothing";
@@ -156,38 +455,109 @@ async function loadProjectSchema(options) {
   }
   return { schema, file: entry };
 }
-async function loadProjectWorld(options) {
-  const entry = WORLD_CANDIDATES.map((c) => path.resolve(options.cwd, c)).find(
-    (f) => existsSync(f)
-  );
-  if (entry === void 0) return void 0;
-  await mkdir(options.outDir, { recursive: true });
-  const outfile = path.join(options.outDir, "world.mjs");
+function is2dWorld(world) {
+  return world !== void 0 && world.engine === "matter2d" && !("why" in world);
+}
+function isUnpredictedWorld(world) {
+  return world !== void 0 && "why" in world;
+}
+var ROOM_CANDIDATES = ["irtio/room.ts", "irtio/room.js", "room.ts"];
+async function bundleAndImport(entry, outfile, options) {
+  await mkdir2(options.outDir, { recursive: true });
   const alias = options.irtioPackages ?? monorepoPackages();
-  await esbuild.build({
+  await esbuild2.build({
     entryPoints: [entry],
     bundle: true,
     format: "esm",
     platform: "node",
     outfile,
-    external: ["@dimforge/rapier3d-compat"],
+    external: ["@dimforge/rapier3d-compat", "matter-js"],
     ...alias !== void 0 ? { alias } : {}
   });
-  const module = await import(`${pathToFileURL(outfile).href}?v=${Date.now()}-${importSeq++}`);
+  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" || typeof gravity.y !== "number" || typeof gravity.z !== "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") {
+    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
   };
 }
@@ -195,7 +565,7 @@ async function checkWorldDeterminism(world) {
   if (!world.setup) return void 0;
   const { initPhysics } = await import("@irtio/runtime");
   const rapier = await initPhysics();
-  const build2 = () => {
+  const build3 = () => {
     const w = new rapier.World({ ...world.gravity });
     try {
       world.setup(w, rapier);
@@ -204,8 +574,8 @@ async function checkWorldDeterminism(world) {
       w.free();
     }
   };
-  const first = build2();
-  const second = build2();
+  const first = build3();
+  const second = build3();
   if (first.length === second.length && everyByteEqual(first, second)) return void 0;
   return `the world builder is not deterministic: two builds of setup() from ${world.file} disagree. 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.`;
 }
@@ -213,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;
@@ -228,6 +640,51 @@ function stateUrlFor(wsUrl) {
   parsed.search = "";
   return parsed.toString();
 }
+async function readBuildIdentity(wsUrl) {
+  const stateUrl = stateUrlFor(wsUrl);
+  if (stateUrl === void 0) {
+    return { unavailable: `cannot derive an inspector URL from ${wsUrl}` };
+  }
+  let body;
+  try {
+    const response = await fetch(stateUrl, {
+      signal: AbortSignal.timeout(TICK_HEALTH_TIMEOUT_MS)
+    });
+    if (!response.ok) {
+      return {
+        unavailable: `${stateUrl} answered ${response.status}` + (response.status === 404 ? ": only `irtio dev` serves the inspector, so a deployed tenant cannot name its build here" : "")
+      };
+    }
+    body = await response.json();
+  } catch (err) {
+    return {
+      unavailable: `could not reach ${stateUrl} (${err instanceof Error ? err.message : String(err)})`
+    };
+  }
+  const state = body;
+  const bundleHash = typeof state?.bundle?.hash === "string" ? state.bundle.hash : void 0;
+  const schemaHash = typeof state?.bundle?.schemaHash === "string" ? state.bundle.schemaHash : void 0;
+  const startedAt = typeof state?.startedAt === "number" ? state.startedAt : void 0;
+  if (bundleHash === void 0 && startedAt === void 0) {
+    return { unavailable: `${stateUrl} named no bundle and no start time`, source: stateUrl };
+  }
+  return {
+    ...bundleHash !== void 0 ? { bundleHash } : {},
+    ...schemaHash !== void 0 ? { schemaHash } : {},
+    ...startedAt !== void 0 ? { startedAt } : {},
+    source: stateUrl
+  };
+}
+function formatBuildIdentity(build3) {
+  if (build3.unavailable !== void 0) return `build unknown: ${build3.unavailable}`;
+  const parts = [];
+  parts.push(`bundle ${build3.bundleHash ?? "unknown"}`);
+  if (build3.schemaHash !== void 0) parts.push(`schema ${build3.schemaHash}`);
+  parts.push(
+    build3.startedAt !== void 0 ? `server up since ${new Date(build3.startedAt).toISOString()}` : "server start time unknown"
+  );
+  return parts.join(" \xB7 ");
+}
 async function readTickCounters(wsUrl, roomId) {
   const stateUrl = stateUrlFor(wsUrl);
   if (stateUrl === void 0) {
@@ -280,6 +737,13 @@ function tickHealthFrom(before, after) {
   };
 }
 var STOP_GRACE_MS = 5e3;
+var TRUTH_SETTLE_MS = 400;
+function delay(ms) {
+  return new Promise((resolve3) => {
+    const timer = setTimeout(resolve3, ms);
+    timer.unref?.();
+  });
+}
 function ceilingFor(seconds) {
   return seconds * 3e3 + 3e4;
 }
@@ -294,7 +758,18 @@ var RunNotPerformedError = class extends Error {
 function rate(bytesPerSecond) {
   return bytesPerSecond >= 1e3 ? `${(bytesPerSecond / 1e3).toFixed(1)} kB/s` : `${Math.round(bytesPerSecond)} B/s`;
 }
-function formatReport(report, schemaLoaded, cheating) {
+function formatRunProfile(report, top) {
+  const profile = report.profile;
+  if (!profile) return [];
+  const seconds = Math.max(1e-3, report.durationMs / 1e3);
+  const bots = Math.max(1, report.bots);
+  return [
+    `${pc.bold("bandwidth")} ${pc.dim("as seen by the bots, per bot per second")}`,
+    ...formatProfileTable(profile, { seconds, per: bots, ...top !== void 0 ? { top } : {} }),
+    ""
+  ];
+}
+function formatReport(report, schemaLoaded) {
   const lines = [];
   for (const invariant of report.invariants) {
     const mark = invariant.state === "unavailable" ? pc.yellow("n/a ") : invariant.ok ? pc.green("ok  ") : pc.red("FAIL");
@@ -304,11 +779,30 @@ function formatReport(report, schemaLoaded, cheating) {
   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);
@@ -324,59 +818,281 @@ function formatReport(report, schemaLoaded, cheating) {
       pc.red(`  ${failed.length} invariant(s) failed: ${failed.map((i) => i.name).join(", ")}`)
     );
   }
-  if (cheating && report.totals.corrections === 0) {
+  if (!schemaLoaded) {
     lines.push(
       pc.yellow(
-        "  --cheat drew no corrections: the room accepted every illegal write.\n  add rules to `validate` in irtio/room.ts (reject by returning `prev`, or clamp)."
+        "  no irtio/schema.ts here, so this was a schema-less relay run: presence and messages only.\n  run it from a project directory to simulate your room."
       )
     );
   }
-  if (!schemaLoaded) {
+  return lines;
+}
+function formatScenario(run, cwd) {
+  const lines = [""];
+  lines.push(
+    `  ${pc.bold("scenario")} ${pc.dim(path2.relative(cwd, run.file))} ` + pc.dim(`(${run.ticks} recorded tick(s))`)
+  );
+  if (run.assertions.length === 0) {
     lines.push(
       pc.yellow(
-        "  no irtio/schema.ts here, so this was a schema-less relay run: presence and messages only.\n  run it from a project directory to simulate your room."
+        "  the scenario ran no assertions, so it proved nothing. Call timeline.check(name, fn), or throw from assert."
       )
     );
   }
+  for (const assertion of run.assertions) {
+    const mark = assertion.ok ? pc.green("ok  ") : pc.red("FAIL");
+    const where = assertion.tick !== void 0 ? `tick ${assertion.tick}: ` : "";
+    lines.push(`  ${mark} ${assertion.name.padEnd(17)} ${pc.dim(`${where}${assertion.detail}`)}`);
+  }
+  if (run.dropped > 0) {
+    lines.push(
+      pc.yellow(
+        `  the recorder dropped ${run.dropped} tick(s) at its cap, so this recording is a tail. Shorten the run or raise the cap before trusting a pass.`
+      )
+    );
+  }
+  lines.push(pc.dim(`  timeline: ${run.timelinePath}`));
+  const failed = run.assertions.filter((a) => !a.ok);
+  lines.push(
+    failed.length === 0 && run.assertions.length > 0 ? pc.green(`  every scenario assertion held (${run.assertions.length}).`) : pc.red(`  ${failed.length} scenario assertion(s) failed.`)
+  );
+  return lines;
+}
+function formatAdversarial(run) {
+  const lines = ["", `  ${pc.bold("adversarial")}`];
+  for (const entry of run.conditions) {
+    if (entry.conditions === void 0) continue;
+    const c = entry.counters;
+    const did = `dropped ${c.droppedOut} out / ${c.droppedIn} in, duplicated ${c.duplicatedOut}/${c.duplicatedIn}, reordered ${c.reorderedOut}/${c.reorderedIn}`;
+    lines.push(
+      `  ${pc.dim("bot")} ${String(entry.bot).padEnd(3)} ${describeConditions(entry.conditions)}`
+    );
+    lines.push(`      ${pc.dim(did)}`);
+  }
+  for (let i = 0; i < run.cheated.length; i++) {
+    const bot = run.cheated[i] ?? 0;
+    const corrections = run.correctionsPerCheater[i] ?? 0;
+    if (corrections > 0) {
+      lines.push(
+        `  ${pc.green("ok  ")} bot ${bot} cheated and drew ${corrections} correction(s): the room refused the illegal writes.`
+      );
+    } else {
+      lines.push(
+        pc.yellow(
+          `  HOLE bot ${bot} cheated and drew 0 corrections: the room accepted every illegal write it sent.
+       Add rules to \`validate\` in irtio/room.ts: reject by returning \`prev\`, or clamp the value.`
+        )
+      );
+    }
+  }
   return lines;
 }
+function formatHits(rows) {
+  const lines = [
+    "",
+    `  ${pc.bold("hit registration")} ${pc.dim(`(${rows.length} shot(s))`)}`
+  ];
+  for (const row of rows) {
+    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(
+          `  bot ${row.bot} at ${row.target}: ${at}, no distance: ${row.unresolved ?? "unknown"}`
+        )
+      );
+      continue;
+    }
+    lines.push(
+      `  ${pc.dim("bot")} ${row.bot} at ${row.collection}.${row.target}: ${at}, aimed ${point(row.aim)}, authority ${point(row.authoritative ?? {})}, ${pc.bold(`missed by ${row.missDistance.toFixed(2)}`)}`
+    );
+  }
+  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)}, 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) {
+  const parts = Object.entries(p).map(([k, v]) => `${k} ${Math.round(v * 100) / 100}`);
+  return parts.length === 0 ? "(none)" : `(${parts.join(", ")})`;
+}
+function formatTruth(run) {
+  const lines = ["", `  ${pc.bold("truth seam")}`];
+  if (run.diff === void 0) {
+    lines.push(
+      pc.yellow(
+        `  n/a  no save could be decoded, so nothing was compared: ${run.error ?? "unknown"}`
+      )
+    );
+    return lines;
+  }
+  const diff = run.diff;
+  lines.push(
+    pc.dim(
+      `  save ${run.saveId ?? "(unnamed)"} at tick ${diff.saveTick}, blob format v${diff.saveVersion}`
+    )
+  );
+  for (const bot of diff.bots) {
+    const mark = bot.ok ? pc.green("ok  ") : pc.red("FAIL");
+    lines.push(
+      `  ${mark} bot ${String(bot.bot).padEnd(3)} ${pc.dim(
+        bot.ok ? `${bot.compared} record(s) held, and every one matched the save` : `${bot.differences.length} difference(s) across ${bot.compared} record(s) held`
+      )}`
+    );
+    for (const d of bot.differences.slice(0, 5)) lines.push(pc.red(`       ${d.detail}`));
+    if (bot.differences.length > 5) {
+      lines.push(pc.dim(`       ... and ${bot.differences.length - 5} more`));
+    }
+  }
+  lines.push(
+    diff.ok ? pc.green(
+      `  every record the ${diff.bots.length} client(s) held matched the decoded save, and none was missing from it.`
+    ) : pc.red(
+      `  ${diff.differences.length} difference(s) between what the clients held and what the save says the server held.`
+    )
+  );
+  return lines;
+}
+function conditionsFrom(options) {
+  const all = options.conditions;
+  const perBot = options.conditionsPerBot;
+  if (perBot === void 0 || Object.keys(perBot).length === 0) {
+    return hasConditions(all) ? all : void 0;
+  }
+  return (index) => perBot[index] ?? all;
+}
+function cheatFrom(options) {
+  const named = options.cheatBots;
+  if (named !== void 0 && named.length > 0) {
+    const set = new Set(named);
+    return options.cheat === true ? true : (index) => set.has(index);
+  }
+  return options.cheat === true ? true : void 0;
+}
 async function runSimulation(options = {}) {
-  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const cwd = path2.resolve(options.cwd ?? process.cwd());
   const output = [];
   const log = (line) => {
     output.push(line);
     (options.log ?? ((l) => console.log(l)))(line);
   };
-  const bots = options.bots ?? DEFAULT_BOTS;
-  const seconds = options.seconds ?? DEFAULT_SECONDS;
   const url = options.url ?? DEFAULT_URL;
-  const outDir = path.join(cwd, ".irtio", "sim");
+  const outDir = path2.join(cwd, ".irtio", "sim");
+  const loadedScenario = options.scenario !== void 0 ? await loadScenario({
+    cwd,
+    outDir,
+    file: options.scenario,
+    irtioPackages: options.irtioPackages
+  }) : void 0;
+  const scenario = loadedScenario?.scenario;
+  const bots = scenario?.bots ?? options.bots ?? DEFAULT_BOTS;
+  const seconds = scenario?.seconds ?? options.seconds ?? DEFAULT_SECONDS;
   const loaded = await loadProjectSchema({
     cwd,
     outDir,
     irtioPackages: options.irtioPackages
   });
+  if (scenario !== void 0 && loaded === void 0) {
+    throw new ScenarioNotRunError(
+      `irtio simulate: a scenario needs the project schema, and there is no irtio/schema.ts under ${cwd}.
+  Scenarios assert on the room's own collections, so a relay run has nothing to assert about. Run it from the project directory.`
+    );
+  }
   const hasPhysics = loaded !== void 0 && loaded.schema.collections.some(
     (c) => c.physics !== void 0
   );
-  const world = hasPhysics ? await loadProjectWorld({ cwd, outDir, irtioPackages: options.irtioPackages }) : void 0;
+  const loadedWorld = hasPhysics ? await loadProjectWorld({ cwd, outDir, irtioPackages: options.irtioPackages }) : void 0;
+  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}`));
+  }
   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);
+  const cheats = cheatPredicate(cheatSpec);
+  const wantTruth = scenario?.truth === true || options.truth === true;
   const common = {
     url,
     durationMs: seconds * 1e3,
+    ...conditionsSpec !== void 0 ? { conditions: conditionsSpec } : {},
+    ...scenario?.seed !== void 0 ? { seed: scenario.seed } : {},
     ...options.key !== void 0 ? { key: options.key } : {},
     ...options.room !== void 0 ? { room: options.room } : {},
     ...options.correctionsPerSecMax !== void 0 ? { correctionsPerSecMax: options.correctionsPerSecMax } : options.correctionsMax !== void 0 ? { correctionsPerSecMax: options.correctionsMax } : {},
     ...options.mispredictionMax !== void 0 ? { mispredictionMagnitudeMax: options.mispredictionMax } : {},
     ...options.snapsMax !== void 0 ? { snapsMax: options.snapsMax } : {},
-    ...options.overrunsMax !== void 0 ? { overrunsMax: options.overrunsMax } : {}
+    ...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 } : {}
   };
@@ -385,8 +1101,8 @@ async function runSimulation(options = {}) {
     runner = loaded ? await spawnBots(bots, {
       ...spawn,
       schema: loaded.schema,
-      script: randomScript(loaded.schema, { cheat: options.cheat ?? false }),
-      ...predicted ? {
+      script: scenario?.script ?? randomScript(loaded.schema, { cheat: cheatSpec ?? false }),
+      ...predicted && world !== void 0 ? {
         physics: {
           gravity: world.gravity,
           ...world.timestep !== void 0 ? { timestep: world.timestep } : {},
@@ -394,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) {
@@ -405,57 +1135,166 @@ async function runSimulation(options = {}) {
   }
   log("");
   log(
-    `${pc.bold("irtio simulate")} \u2014 ${bots} bot${bots === 1 ? "" : "s"} \xD7 ${seconds}s on ${url} (room ${pc.bold(runner.roomId)})${options.cheat ? pc.yellow(" [cheat]") : ""}`
+    `${pc.bold("irtio simulate")}: ${bots} bot${bots === 1 ? "" : "s"} \xD7 ${seconds}s on ${url} (room ${pc.bold(runner.roomId)})${options.cheat ? pc.yellow(" [cheat]") : ""}`
   );
+  const build3 = await readBuildIdentity(url);
+  log(pc.dim(`  ${formatBuildIdentity(build3)}`));
   log("");
+  if (scenario !== void 0) {
+    try {
+      await startTimeline(url, runner.roomId);
+    } catch (err) {
+      await runner.stop().catch(() => void 0);
+      throw err;
+    }
+  }
   const tickBefore = await readTickCounters(url, runner.roomId);
   const ceilingMs = options.ceilingMs ?? ceilingFor(seconds);
   let ceilingHit = false;
-  const ceiling = new Promise((resolve2) => {
+  const ceiling = new Promise((resolve3) => {
     const timer = setTimeout(() => {
       ceilingHit = true;
-      resolve2();
+      resolve3();
     }, ceilingMs);
     void runner.done().catch(() => void 0).finally(() => {
       clearTimeout(timer);
-      resolve2();
+      resolve3();
     });
   });
   await ceiling;
+  let truth;
+  const clientStates = [];
+  if (wantTruth) {
+    if (loaded === void 0) {
+      truth = { error: "a relay run has no schema, so there is nothing to decode a save against" };
+    } else {
+      await delay(TRUTH_SETTLE_MS);
+      const fetched = await fetchSave(url, runner.roomId);
+      if ("error" in fetched) {
+        truth = { error: fetched.error };
+      } else {
+        await delay(TRUTH_SETTLE_MS);
+        for (const bot of runner.bots) {
+          clientStates.push({
+            bot: bot.index,
+            state: captureClientState(
+              loaded.schema,
+              bot.room.state
+            )
+          });
+        }
+        try {
+          const decoded = decodeSave(fetched.save.bytes, loaded.schema);
+          truth = {
+            saveId: fetched.save.saveId,
+            saveState: decoded.state,
+            diff: diffAgainstSave(clientStates, decoded.state, {
+              saveTick: decoded.tick,
+              saveVersion: decoded.version
+            })
+          };
+        } catch (err) {
+          truth = {
+            saveId: fetched.save.saveId,
+            error: `the save could not be decoded: ${err instanceof Error ? err.message : String(err)}`
+          };
+        }
+      }
+    }
+  }
   runner.recordTickHealth(tickHealthFrom(tickBefore, await readTickCounters(url, runner.roomId)));
+  let dump;
+  if (scenario !== void 0) {
+    try {
+      dump = await readTimeline(url, runner.roomId);
+    } catch (err) {
+      await runner.stop().catch(() => void 0);
+      throw err;
+    }
+  }
   const stopped = await Promise.race([
     runner.stop(),
-    new Promise((resolve2) => {
-      const timer = setTimeout(() => resolve2(runner.report()), STOP_GRACE_MS);
+    new Promise((resolve3) => {
+      const timer = setTimeout(() => resolve3(runner.report()), STOP_GRACE_MS);
       timer.unref?.();
     })
   ]);
   const endedBy = ceilingHit ? "ceiling" : runner.endedBy ?? "scripts";
   const fatal = endedBy === "ceiling" ? `the run passed its wall-clock ceiling of ${Math.round(ceilingMs / 1e3)}s without ending on its own, so it was cut short here` : endedBy === "room-gone" ? "every bot was disconnected at once and none rejoined, so the room is gone" : void 0;
-  await mkdir(outDir, { recursive: true });
-  const tracePath = path.resolve(
+  await mkdir2(outDir, { recursive: true });
+  const tracePath = path2.resolve(
     cwd,
-    options.trace ?? path.join(outDir, `trace-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.json`)
+    options.trace ?? path2.join(outDir, `trace-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.json`)
   );
-  await mkdir(path.dirname(tracePath), { recursive: true });
+  await mkdir2(path2.dirname(tracePath), { recursive: true });
   await runner.trace.save(tracePath);
   const report = { ...stopped, tracePath };
-  for (const line of formatReport(report, loaded !== void 0, options.cheat ?? false)) {
+  const hits = runner.shots.length > 0 && dump !== void 0 ? correlateShots(runner.shots, dump) : [];
+  const cheated = report.perBot.map((_, index) => index).filter((index) => cheats(index));
+  const injectedAny = runner.conditions.some((c) => c.conditions !== void 0);
+  const adversarial = injectedAny || cheated.length > 0 ? {
+    conditions: runner.conditions,
+    cheated,
+    correctionsPerCheater: cheated.map((index) => report.perBot[index]?.corrections ?? 0)
+  } : void 0;
+  let scenarioRun;
+  if (scenario !== void 0 && dump !== void 0 && loadedScenario !== void 0) {
+    const timeline = makeTimeline(dump);
+    const assertions = [];
+    let threw;
+    try {
+      await scenario.assert(timeline, { hits, truth: truth?.diff });
+    } catch (err) {
+      threw = err instanceof Error ? err.message : String(err);
+    }
+    assertions.push(...timeline.results);
+    if (threw !== void 0) assertions.push({ name: "assert", ok: false, detail: threw });
+    const timelinePath = path2.join(
+      path2.dirname(tracePath),
+      `${path2.basename(tracePath, ".json")}-timeline.json`
+    );
+    await writeFile(timelinePath, `${JSON.stringify(dump, null, 2)}
+`, "utf8");
+    scenarioRun = {
+      file: loadedScenario.file,
+      assertions,
+      ok: assertions.length > 0 && assertions.every((a) => a.ok),
+      ticks: dump.frames.length,
+      dropped: dump.dropped,
+      timelinePath
+    };
+  }
+  for (const line of formatReport(report, loaded !== void 0)) {
     log(line);
   }
+  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);
+  if (scenarioRun !== void 0) {
+    for (const line of formatScenario(scenarioRun, cwd)) log(line);
+  }
   if (worldError !== void 0) {
     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 ${path.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(
-        "  this schema has physics but no irtio/world.ts \u2014 bots interpolated instead of predicting, so body-field corrections count as body-sync, not misprediction.\n  export { gravity, setup, bodies, intents } from irtio/world.ts to simulate prediction (what `irtio init --physics` writes)."
+        "  this schema has physics but no irtio/world.ts, so bots interpolated instead of predicting, so body-field corrections count as body-sync, not misprediction.\n  export { gravity, setup, bodies, intents } from irtio/world.ts to simulate prediction (what `irtio init --physics` writes)."
       )
     );
   }
@@ -463,12 +1302,26 @@ 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 ? 1 : 0;
+  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
+  // applied to the truth seam.
+  truth?.diff?.ok === false ? 1 : 0;
   return {
     report,
     tracePath,
+    build: build3,
+    ...scenarioRun !== void 0 ? { scenario: scenarioRun } : {},
+    ...adversarial !== void 0 ? { adversarial } : {},
+    ...hits.length > 0 ? { hits } : {},
+    ...truth !== void 0 ? { truth } : {},
     schema: loaded !== void 0,
     predicted,
+    matchFailures: runner.matchFailures,
     ...worldError !== void 0 ? { worldError } : {},
     endedBy,
     ...fatal !== void 0 ? { fatal } : {},
@@ -499,17 +1352,25 @@ async function simulate(args) {
       ...err instanceof RunNotPerformedError && localDefault ? [`nothing is answering ${DEFAULT_URL}. Start the room with \`irtio dev\`, or pass --url.`] : []
     ]);
     if (trailer !== void 0) console.error(pc.dim(trailer));
-    process.exitCode = err instanceof RunNotPerformedError ? 2 : 1;
+    process.exitCode = err instanceof RunNotPerformedError || err instanceof ScenarioNotRunError ? 2 : 1;
   }
 }
 export {
   RunNotPerformedError,
+  ScenarioNotRunError,
   USAGE,
   ceilingFor,
+  checkWorld2dDeterminism,
   checkWorldDeterminism,
+  detectMatter2dRoom,
+  formatBuildIdentity,
+  is2dWorld,
+  isUnpredictedWorld,
   loadProjectSchema,
   loadProjectWorld,
+  loadScenario,
   parseSimulateArgs,
+  readBuildIdentity,
   readTickCounters,
   runSimulation,
   simulate,