@irtio/cli 0.1.0 → 0.3.0

package/dist/{logs-6GLBO3TP.js → logs-5OUDPAIX.js}

@@ -1,10 +1,10 @@
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-J3G6AUJY.js";
+} from "./chunk-I37DLT7K.js";
 import {
   resolveControlUrlForUser
-} from "./chunk-UYN5PWLT.js";
+} from "./chunk-NVUKSP5U.js";
 
 // src/logs.ts
 import { existsSync } from "fs";
@@ -28,6 +28,12 @@ function parseLogsArgs(args) {
         parsed.since = value;
         break;
       }
+      case "--room": {
+        const value = args[++i];
+        if (value === void 0) throw new Error("irtio logs: --room needs a value");
+        parsed.room = value;
+        break;
+      }
       case "--project": {
         const value = args[++i];
         if (value === void 0) throw new Error("irtio logs: --project needs a value");
@@ -63,7 +69,8 @@ async function runLogs(options) {
   let polls = 0;
   for (; ; ) {
     const rows = await client.get(`/v1/projects/${options.project}/logs`, {
-      since
+      since,
+      ...options.room !== void 0 ? { room: options.room } : {}
     });
     for (const row of rows) log(formatRow(row));
     const last = rows[rows.length - 1];
@@ -101,6 +108,7 @@ async function logs(args, deps = {}) {
       follow: parsed.follow,
       log,
       ...parsed.since !== void 0 ? { since: parsed.since } : {},
+      ...parsed.room !== void 0 ? { room: parsed.room } : {},
       ...parsed.url !== void 0 ? { controlUrl: parsed.url } : {},
       ...deps.client !== void 0 ? { client: deps.client } : {}
     });

package/dist/{migrate-FQIDF747.js → migrate-3R6VRW4J.js}

@@ -1,13 +1,13 @@
 import {
   bundleRoom
-} from "./chunk-ZWCLCYCS.js";
+} from "./chunk-KRQUAEN2.js";
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-J3G6AUJY.js";
+} from "./chunk-I37DLT7K.js";
 import {
   resolveControlUrlForUser
-} from "./chunk-UYN5PWLT.js";
+} from "./chunk-NVUKSP5U.js";
 
 // src/migrate.ts
 import { existsSync } from "fs";
@@ -101,8 +101,10 @@ export function up(state: MigrationState, s: MigrationHelpers): MigrationState {
   return state;
 }
 
-// \`down\` is scaffolded and stored but unused until rollback ships \u2014 uncomment and fill it
-// in if you want it recorded now.
+// \`down\` is scaffolded and stored, but nothing calls it. \`irtio rollback\` does NOT run it: it
+// restores the pre-migration save generation the \`migrate\` deploy wrote, which is how it can
+// undo a migration you never wrote a \`down\` for. Fill this in only if you want the inverse
+// transform recorded next to the forward one.
 //
 // export function down(state: MigrationState, s: MigrationHelpers): MigrationState {
 //   return state;

package/dist/rollback-CLQVYFHW.js

@@ -0,0 +1,122 @@
+import {
+  createApiClient,
+  isLoginRequired
+} from "./chunk-I37DLT7K.js";
+import {
+  resolveControlUrlForUser
+} from "./chunk-NVUKSP5U.js";
+
+// src/rollback.ts
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import * as path from "path";
+import pc from "picocolors";
+function parseRollbackArgs(args) {
+  const parsed = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--project": {
+        const value = args[++i];
+        if (value === void 0) throw new Error("irtio rollback: --project needs a value");
+        parsed.project = value;
+        break;
+      }
+      case "--url": {
+        const value = args[++i];
+        if (value === void 0) throw new Error("irtio rollback: --url needs a value");
+        parsed.url = value;
+        break;
+      }
+      default: {
+        if (parsed.version !== void 0) {
+          throw new Error(`irtio rollback: unknown option ${JSON.stringify(arg)}`);
+        }
+        const version = Number(arg);
+        if (!Number.isInteger(version) || version < 1) {
+          throw new Error("irtio rollback: <version> must be a positive integer");
+        }
+        parsed.version = version;
+      }
+    }
+  }
+  if (parsed.version === void 0) {
+    throw new Error("irtio rollback: a version is required \u2014 irtio rollback <version>");
+  }
+  return parsed;
+}
+async function runRollback(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  log(
+    `${pc.yellow("rolling back")} to v${options.version} \u2014 rooms that migrated past it ${pc.yellow("discard")} everything written since their migration`
+  );
+  const result = await client.post(`/v1/projects/${options.project}/rollback`, {
+    version: options.version
+  });
+  log(
+    pc.green(
+      `v${result.rolledBack.map((v) => `${v}`).join(", v")} rolled back; v${result.version} serves again`
+    )
+  );
+  for (const room of result.rooms) {
+    if (room.action === "restored") {
+      log(pc.dim(`  ${room.roomId}: restores its pre-migration state on its next start`));
+    } else {
+      log(pc.yellow(`  ${room.roomId}: untouched \u2014 ${room.reason ?? "no pre-migration state"}`));
+    }
+  }
+  if (result.rooms.length === 0) log(pc.dim("  no rooms on record for this project"));
+  if (result.applied === "stopped") {
+    log(pc.dim("the tenant was stopped; the next join brings rooms back on the older version"));
+  } else {
+    log(pc.dim("no tenant was running; the next placement serves the older version"));
+  }
+  return result;
+}
+async function readIrtioJsonProject(cwd) {
+  const file = path.join(cwd, "irtio.json");
+  if (!existsSync(file)) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    throw new Error(`irtio rollback: ${file} is not valid JSON`);
+  }
+  return typeof parsed.project === "string" && parsed.project.length > 0 ? parsed.project : void 0;
+}
+async function rollback(args, deps = {}) {
+  const log = deps.log ?? ((line) => console.log(line));
+  const errorLog = deps.errorLog ?? ((line) => console.error(line));
+  try {
+    const parsed = parseRollbackArgs(args);
+    const project = parsed.project ?? await readIrtioJsonProject(process.cwd());
+    if (project === void 0) {
+      throw new Error(
+        "irtio rollback: no project id \u2014 pass --project or run this from a project with irtio.json"
+      );
+    }
+    await runRollback({
+      project,
+      version: parsed.version,
+      log,
+      ...parsed.url !== void 0 ? { controlUrl: parsed.url } : {},
+      ...deps.client !== void 0 ? { client: deps.client } : {}
+    });
+  } catch (err) {
+    if (isLoginRequired(err)) {
+      errorLog(pc.red("not logged in"));
+      errorLog("run: irtio login");
+      process.exitCode = 1;
+      return;
+    }
+    errorLog(pc.red(err instanceof Error ? err.message : String(err)));
+    process.exitCode = 1;
+  }
+}
+export {
+  parseRollbackArgs,
+  rollback,
+  runRollback
+};

package/dist/rooms-OJ3JLYHD.js

@@ -0,0 +1,199 @@
+import {
+  createApiClient,
+  isLoginRequired
+} from "./chunk-I37DLT7K.js";
+import {
+  resolveControlUrlForUser
+} from "./chunk-NVUKSP5U.js";
+
+// src/rooms.ts
+import { existsSync } from "fs";
+import { readFile } from "fs/promises";
+import * as path from "path";
+import pc from "picocolors";
+function parseRoomsArgs(args) {
+  const parsed = { sub: "list" };
+  let rest = args;
+  const first = args[0];
+  if (first === "saves" || first === "restore") {
+    parsed.sub = first;
+    const room = args[1];
+    if (room === void 0 || room.startsWith("-")) {
+      throw new Error(`irtio rooms ${first}: needs a room id`);
+    }
+    parsed.room = room;
+    rest = args.slice(2);
+  }
+  for (let i = 0; i < rest.length; i++) {
+    const arg = rest[i];
+    switch (arg) {
+      case "--save": {
+        const value = rest[++i];
+        if (value === void 0) throw new Error("irtio rooms: --save needs a value");
+        parsed.save = value;
+        break;
+      }
+      case "--project": {
+        const value = rest[++i];
+        if (value === void 0) throw new Error("irtio rooms: --project needs a value");
+        parsed.project = value;
+        break;
+      }
+      case "--url": {
+        const value = rest[++i];
+        if (value === void 0) throw new Error("irtio rooms: --url needs a value");
+        parsed.url = value;
+        break;
+      }
+      default:
+        throw new Error(`irtio rooms: unknown option ${JSON.stringify(arg)}`);
+    }
+  }
+  if (parsed.sub === "restore" && parsed.save === void 0) {
+    throw new Error(
+      "irtio rooms restore: --save <id> is required \u2014 run `irtio rooms saves <room>` to see them"
+    );
+  }
+  return parsed;
+}
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+function formatAge(iso, now) {
+  const ms = now - Date.parse(iso);
+  if (!Number.isFinite(ms) || ms < 0) return "\u2014";
+  const mins = Math.floor(ms / 6e4);
+  if (mins < 1) return "just now";
+  if (mins < 60) return `${mins}m ago`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+function statusColor(status) {
+  return status === "active" || status === "running" ? pc.green(status) : status === "draining" ? pc.yellow(status) : pc.dim(status);
+}
+function formatTable(rows) {
+  if (rows.length === 0) return [pc.dim("no rooms")];
+  const idWidth = Math.max(4, ...rows.map((r) => r.roomId.length));
+  const out = [pc.dim(`${"ROOM".padEnd(idWidth)}  STATUS      LAST SEEN`)];
+  for (const r of rows) {
+    out.push(
+      `${r.roomId.padEnd(idWidth)}  ${statusColor(r.status).padEnd(10)}  ${pc.dim(r.lastSeen)}`
+    );
+  }
+  return out;
+}
+function formatSaves(rows, now) {
+  if (rows.length === 0) {
+    return [pc.dim("no saves"), pc.dim("a room writes one when its code calls room.save()")];
+  }
+  const idWidth = Math.max(7, ...rows.map((r) => r.saveId.length));
+  const out = [pc.dim(`${"SAVE ID".padEnd(idWidth)}  AGE         SIZE      DEPLOY`)];
+  for (const r of rows) {
+    out.push(
+      `${r.saveId.padEnd(idWidth)}  ${formatAge(r.createdAt, now).padEnd(10)}  ${formatBytes(r.bytes).padEnd(8)}  ${pc.dim(`v${r.version}`)}`
+    );
+  }
+  return out;
+}
+async function runSaves(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const rows = await client.get(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}/saves`
+  );
+  for (const line of formatSaves(rows, options.now ?? Date.now())) log(line);
+  return rows;
+}
+async function runRestore(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  log(
+    `${pc.yellow("discarding")} the current state of room ${pc.bold(options.room)} and restoring save ${pc.bold(options.saveId)}`
+  );
+  const result = await client.post(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}/restore`,
+    { saveId: options.saveId }
+  );
+  if (result.applied === "stopped") {
+    log(pc.green(`restored: ${options.room} was live, so its tenant was stopped`));
+    log(
+      pc.dim(
+        "the room comes back from the save on the next join; every other room in this project was stopped too and comes back from its own snapshot, unchanged"
+      )
+    );
+  } else {
+    log(pc.green(`queued: ${options.room} was not running`));
+    log(pc.dim("the restore is applied at the next placement \u2014 the next join starts it"));
+  }
+  return result;
+}
+async function runRooms(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const rows = await client.get(`/v1/projects/${options.project}/rooms`);
+  for (const line of formatTable(rows)) log(line);
+  return rows;
+}
+async function readIrtioJsonProject(cwd) {
+  const file = path.join(cwd, "irtio.json");
+  if (!existsSync(file)) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(file, "utf8"));
+  } catch {
+    throw new Error(`irtio rooms: ${file} is not valid JSON`);
+  }
+  return typeof parsed.project === "string" && parsed.project.length > 0 ? parsed.project : void 0;
+}
+async function rooms(args, deps = {}) {
+  const log = deps.log ?? ((line) => console.log(line));
+  const errorLog = deps.errorLog ?? ((line) => console.error(line));
+  try {
+    const parsed = parseRoomsArgs(args);
+    const project = parsed.project ?? await readIrtioJsonProject(process.cwd());
+    if (project === void 0) {
+      throw new Error(
+        "irtio rooms: no project id \u2014 pass --project or run this from a project with irtio.json"
+      );
+    }
+    const common = {
+      project,
+      log,
+      ...parsed.url !== void 0 ? { controlUrl: parsed.url } : {},
+      ...deps.client !== void 0 ? { client: deps.client } : {}
+    };
+    if (parsed.sub === "saves") {
+      await runSaves({ ...common, room: parsed.room });
+    } else if (parsed.sub === "restore") {
+      await runRestore({
+        ...common,
+        room: parsed.room,
+        saveId: parsed.save
+      });
+    } else {
+      await runRooms(common);
+    }
+  } catch (err) {
+    if (isLoginRequired(err)) {
+      errorLog(pc.red("not logged in"));
+      errorLog("run: irtio login");
+      process.exitCode = 1;
+      return;
+    }
+    errorLog(pc.red(err instanceof Error ? err.message : String(err)));
+    process.exitCode = 1;
+  }
+}
+export {
+  parseRoomsArgs,
+  rooms,
+  runRestore,
+  runRooms,
+  runSaves
+};

package/dist/simulate.d.ts

@@ -23,6 +23,9 @@ interface SimulateArgs {
     url?: string;
     key?: string;
     trace?: string;
+    mispredictionMax?: number;
+    snapsMax?: number;
+    correctionsMax?: number;
 }
 /** Hand-rolled, like `parseDevArgs`: the CLI has no argument-parsing dependency. */
 declare function parseSimulateArgs(args: readonly string[]): SimulateArgs;
@@ -40,10 +43,43 @@ declare function loadProjectSchema(options: LoadSchemaOptions): Promise<{
     schema: AnySchema;
     file: string;
 } | undefined>;
+/** The shared world-builder's exports, as `joinRoom({ physics })` wants them. */
+interface LoadedWorld {
+    readonly gravity: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    readonly timestep?: number | undefined;
+    readonly setup?: ((world: unknown, rapier: unknown) => void) | undefined;
+    readonly bodies?: Record<string, (...args: never[]) => unknown> | undefined;
+    readonly intents?: Record<string, (...args: never[]) => void> | undefined;
+    readonly file: string;
+}
+/**
+ * Bundles and imports the project's shared world-builder module, so the bots predict physics the
+ * way a browser client would. The engine stays external — it must be the project's own copy,
+ * resolved at import time, exactly as a room bundle resolves it.
+ */
+declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedWorld | undefined>;
+/**
+ * The build-twice determinism check: builds two worlds from the shared `setup` and compares
+ * Rapier's own snapshots byte for byte. A builder that is not pure over synced inputs
+ * (`Math.random()`, a clock, module state) produces different worlds on the two sides, and every
+ * "misprediction" it causes would be blamed on netcode — catch it here instead. Returns an error
+ * description, or `undefined` when the worlds agree.
+ */
+declare function checkWorldDeterminism(world: LoadedWorld): Promise<string | undefined>;
 interface RunSimulationOptions extends Partial<SimulateArgs> {
     /** Project root; defaults to `process.cwd()`. */
     readonly cwd?: string;
     readonly log?: (line: string) => void;
+    /**
+     * Correction-storm threshold override (per bot per second; `@irtio/bots` default 5). A
+     * physics room judges one correction opportunity per tick, so contact-heavy moments on slow
+     * hardware can burst past the cursor-tuned default without anything being wrong.
+     */
+    readonly correctionsPerSecMax?: number;
     /** @internal Test seam, same as `startDev`'s. */
     readonly irtioPackages?: Record<string, string> | undefined;
 }
@@ -52,6 +88,11 @@ interface SimulationRun {
     readonly tracePath: string;
     /** `false` when there was no schema module and the run fell back to a relay simulation. */
     readonly schema: boolean;
+    /** `true` when the bots predicted physics from a shared world-builder module (D22 part 2). */
+    readonly predicted: boolean;
+    /** Result of the build-twice world-builder check: the failure text, or `undefined` if it held
+     *  (or did not apply). A failure also fails the run. */
+    readonly worldError?: string;
     /** Everything that was printed, in order — the same lines `log` received. */
     readonly output: readonly string[];
 }
@@ -59,4 +100,4 @@ interface SimulationRun {
 declare function runSimulation(options?: RunSimulationOptions): Promise<SimulationRun>;
 declare function simulate(args: readonly string[]): Promise<void>;
 
-export { type LoadSchemaOptions, type RunSimulationOptions, type SimulateArgs, type SimulationRun, loadProjectSchema, parseSimulateArgs, runSimulation, simulate };
+export { type LoadSchemaOptions, type RunSimulationOptions, type SimulateArgs, type SimulationRun, checkWorldDeterminism, loadProjectSchema, loadProjectWorld, parseSimulateArgs, runSimulation, simulate };

package/dist/simulate.js

@@ -10,6 +10,7 @@ var DEFAULT_URL = "ws://localhost:7070";
 var DEFAULT_BOTS = 5;
 var DEFAULT_SECONDS = 10;
 var SCHEMA_CANDIDATES = ["irtio/schema.ts", "irtio/schema.js", "schema.ts"];
+var WORLD_CANDIDATES = ["irtio/world.ts", "irtio/world.js", "world.ts"];
 function positive(raw, flag) {
   const value = Number(raw);
   if (!Number.isFinite(value) || value <= 0) {
@@ -17,6 +18,13 @@ function positive(raw, flag) {
   }
   return value;
 }
+function nonNegativeInt(raw, flag) {
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    throw new Error(`irtio simulate: ${flag} must be a non-negative integer`);
+  }
+  return value;
+}
 function parseSimulateArgs(args) {
   const parsed = { bots: DEFAULT_BOTS, seconds: DEFAULT_SECONDS, cheat: false };
   for (let i = 0; i < args.length; i++) {
@@ -55,6 +63,15 @@ function parseSimulateArgs(args) {
       case "--cheat":
         parsed.cheat = true;
         break;
+      case "--misprediction-max":
+        parsed.mispredictionMax = positive(value(), "--misprediction-max");
+        break;
+      case "--snaps-max":
+        parsed.snapsMax = nonNegativeInt(value(), "--snaps-max");
+        break;
+      case "--corrections-max":
+        parsed.correctionsMax = positive(value(), "--corrections-max");
+        break;
       default:
         throw new Error(`irtio simulate: unknown option ${JSON.stringify(arg)}`);
     }
@@ -71,6 +88,7 @@ function monorepoPackages() {
     "@irtio/server": path.join(packagesDir, "server/src/index.ts")
   };
 }
+var importSeq = 0;
 function looksLikeSchema(value) {
   const candidate = value;
   return typeof candidate === "object" && candidate !== null && Array.isArray(candidate.collections) && candidate.hash8 instanceof Uint8Array;
@@ -91,7 +109,7 @@ async function loadProjectSchema(options) {
     outfile,
     ...alias !== void 0 ? { alias } : {}
   });
-  const module = await import(`${pathToFileURL(outfile).href}?v=${Date.now()}`);
+  const module = await import(`${pathToFileURL(outfile).href}?v=${Date.now()}-${importSeq++}`);
   const schema = module.schema ?? module.default;
   if (!looksLikeSchema(schema)) {
     const names = Object.keys(module).join(", ") || "nothing";
@@ -103,6 +121,63 @@ 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");
+  const alias = options.irtioPackages ?? monorepoPackages();
+  await esbuild.build({
+    entryPoints: [entry],
+    bundle: true,
+    format: "esm",
+    platform: "node",
+    outfile,
+    external: ["@dimforge/rapier3d-compat"],
+    ...alias !== void 0 ? { alias } : {}
+  });
+  const module = await import(`${pathToFileURL(outfile).href}?v=${Date.now()}-${importSeq++}`);
+  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.
+  the shared world-builder must export the same gravity the room config uses
+  (this is what \`irtio init --physics\` writes)`
+    );
+  }
+  return {
+    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 } : {},
+    file: entry
+  };
+}
+async function checkWorldDeterminism(world) {
+  if (!world.setup) return void 0;
+  const { initPhysics } = await import("@irtio/runtime");
+  const rapier = await initPhysics();
+  const build2 = () => {
+    const w = new rapier.World({ ...world.gravity });
+    try {
+      world.setup(w, rapier);
+      return w.takeSnapshot();
+    } finally {
+      w.free();
+    }
+  };
+  const first = build2();
+  const second = build2();
+  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.`;
+}
+function everyByteEqual(a, b) {
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+  return true;
+}
 function rate(bytesPerSecond) {
   return bytesPerSecond >= 1e3 ? `${(bytesPerSecond / 1e3).toFixed(1)} kB/s` : `${Math.round(bytesPerSecond)} B/s`;
 }
@@ -114,9 +189,11 @@ function formatReport(report, schemaLoaded, cheating) {
   }
   lines.push("");
   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)}`;
   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 ${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}`
     )
   );
   if (report.tracePath !== void 0) lines.push(pc.dim(`  trace: ${report.tracePath}`));
@@ -161,16 +238,37 @@ async function runSimulation(options = {}) {
     outDir,
     irtioPackages: options.irtioPackages
   });
+  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;
+  let worldError;
+  if (world) {
+    worldError = await checkWorldDeterminism(world);
+  }
   const common = {
     url,
     durationMs: seconds * 1e3,
     ...options.key !== void 0 ? { key: options.key } : {},
-    ...options.room !== void 0 ? { room: options.room } : {}
+    ...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 } : {}
   };
+  const predicted = world !== void 0 && worldError === void 0;
   const runner = loaded ? await spawnBots(bots, {
     ...common,
     schema: loaded.schema,
-    script: randomScript(loaded.schema, { cheat: options.cheat ?? false })
+    script: randomScript(loaded.schema, { cheat: options.cheat ?? false }),
+    ...predicted ? {
+      physics: {
+        gravity: world.gravity,
+        ...world.timestep !== void 0 ? { timestep: world.timestep } : {},
+        ...world.setup !== void 0 ? { setup: world.setup } : {},
+        ...world.bodies !== void 0 ? { bodies: world.bodies } : {},
+        ...world.intents !== void 0 ? { intents: world.intents } : {}
+      }
+    } : {}
   }) : await spawnBots(bots, { ...common, script: relayEchoScript() });
   log("");
   log(
@@ -190,10 +288,33 @@ async function runSimulation(options = {}) {
   for (const line of formatReport(report, loaded !== void 0, options.cheat ?? false)) {
     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)`
+      )
+    );
+  } 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)."
+      )
+    );
+  }
   for (const failure of runner.scriptErrors) {
     log(pc.red(`  bot ${failure.bot} script failed: ${String(failure.error)}`));
   }
-  return { report, tracePath, schema: loaded !== void 0, output };
+  return {
+    report,
+    tracePath,
+    schema: loaded !== void 0,
+    predicted,
+    ...worldError !== void 0 ? { worldError } : {},
+    output
+  };
 }
 async function simulate(args) {
   let parsed;
@@ -206,7 +327,7 @@ async function simulate(args) {
   }
   try {
     const run = await runSimulation(parsed);
-    if (!run.report.ok) process.exitCode = 1;
+    if (!run.report.ok || run.worldError !== void 0) process.exitCode = 1;
   } catch (err) {
     console.error(pc.red(err instanceof Error ? err.message : String(err)));
     console.error(pc.dim("is `irtio dev` running? pass --url to point somewhere else."));
@@ -214,7 +335,9 @@ async function simulate(args) {
   }
 }
 export {
+  checkWorldDeterminism,
   loadProjectSchema,
+  loadProjectWorld,
   parseSimulateArgs,
   runSimulation,
   simulate