@irtio/cli 0.5.2 → 0.6.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-ZD4ND6X6.js";
+import "./chunk-RNAH5T4W.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,25 @@ 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)
+  --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 +320,48 @@ 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;
+      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;
@@ -114,29 +381,29 @@ function parseSimulateArgs(args) {
   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 +411,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,15 +423,18 @@ async function loadProjectSchema(options) {
   }
   return { schema, file: entry };
 }
+function isUnpredictedWorld(world) {
+  return world !== void 0 && "unpredicted" in world;
+}
 async function loadProjectWorld(options) {
-  const entry = WORLD_CANDIDATES.map((c) => path.resolve(options.cwd, c)).find(
-    (f) => existsSync(f)
+  const entry = WORLD_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, "world.mjs");
+  await mkdir2(options.outDir, { recursive: true });
+  const outfile = path2.join(options.outDir, "world.mjs");
   const alias = options.irtioPackages ?? monorepoPackages();
-  await esbuild.build({
+  await esbuild2.build({
     entryPoints: [entry],
     bundle: true,
     format: "esm",
@@ -173,9 +443,19 @@ async function loadProjectWorld(options) {
     external: ["@dimforge/rapier3d-compat"],
     ...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 gravity = module.gravity;
-  if (typeof gravity !== "object" || gravity === null || typeof gravity.x !== "number" || typeof gravity.y !== "number" || typeof gravity.z !== "number") {
+  if (typeof gravity !== "object" || gravity === null || typeof gravity.x !== "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.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
@@ -195,7 +475,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 +484,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.`;
 }
@@ -228,6 +508,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 +605,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 +626,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");
@@ -324,55 +667,221 @@ 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 at = row.serverTick === void 0 ? "no tick" : `tick ${row.serverTick}${row.estimated ? " (estimated)" : ""}`;
+    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;
+    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.`
+      )
+    );
+  }
+  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;
+  if (isUnpredictedWorld(loadedWorld)) {
+    log(
+      `physics: ${loadedWorld.file} is a 2D (matter2d) world; bots run without client prediction`
+    );
+  }
+  const world = isUnpredictedWorld(loadedWorld) ? void 0 : loadedWorld;
   let worldError;
   if (world) {
     worldError = await checkWorldDeterminism(world);
   }
+  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 spawn = {
@@ -385,7 +894,7 @@ async function runSimulation(options = {}) {
     runner = loaded ? await spawnBots(bots, {
       ...spawn,
       schema: loaded.schema,
-      script: randomScript(loaded.schema, { cheat: options.cheat ?? false }),
+      script: scenario?.script ?? randomScript(loaded.schema, { cheat: cheatSpec ?? false }),
       ...predicted ? {
         physics: {
           gravity: world.gravity,
@@ -405,57 +914,160 @@ 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 (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;
     log(
       pc.dim(
-        `  bots predicted physics from ${path.relative(cwd, world?.file ?? "")} (build-twice check held; ${suppressed} within-epsilon correction(s) suppressed)`
+        `  bots predicted physics from ${path2.relative(cwd, world?.file ?? "")} (build-twice check held; ${suppressed} within-epsilon correction(s) suppressed)`
       )
     );
   } 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,10 +1075,20 @@ 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 || 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,
     ...worldError !== void 0 ? { worldError } : {},
@@ -499,17 +1121,22 @@ 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,
   checkWorldDeterminism,
+  formatBuildIdentity,
+  isUnpredictedWorld,
   loadProjectSchema,
   loadProjectWorld,
+  loadScenario,
   parseSimulateArgs,
+  readBuildIdentity,
   readTickCounters,
   runSimulation,
   simulate,