@irtio/cli 0.6.0 → 0.8.0

package/dist/{rooms-VI33P4RA.js → rooms-52Q5KBUS.js}

@@ -1,15 +1,15 @@
 import {
   readProjectConfig
-} from "./chunk-DKWG7MGO.js";
+} from "./chunk-JL235KIE.js";
 import {
   HelpRequested,
   helpFor,
   helpRequested
-} from "./chunk-ZD4ND6X6.js";
+} from "./chunk-OCVALOGK.js";
 import {
   createApiClient,
   isLoginRequired
-} from "./chunk-RNAH5T4W.js";
+} from "./chunk-IDF46P7R.js";
 import {
   resolveControlUrlForUser
 } from "./chunk-UPHQM6NZ.js";
@@ -19,27 +19,42 @@ import "fs";
 import "fs/promises";
 import "path";
 import pc from "picocolors";
-var USAGE = `usage: irtio rooms [options]
+var USAGE = `usage: irtio rooms [--active|--idle] [--idle-longer-than <d>] [options]
+       irtio rooms get <room> [options]
+       irtio rooms set <room> --retention <d|forever|clear> [options]
        irtio rooms saves <room> [options]
        irtio rooms restore <room> --save <id> [options]
-       irtio rooms delete <room> [options]
+       irtio rooms delete <room> [--force] [options]
 
-Lists a project's rooms, with the retention window each one's type declares. Rows not reported for
-longer than the control plane's row-pruning window (30 days by default) are pruned; that prunes the
-listing only and never a room's stored state.
+Lists a project's rooms, with the retention window in force for each one and when it will be
+deleted. Rows not reported for longer than the control plane's row-pruning window (30 days by
+default) are pruned; that prunes the listing only and never a room's stored state.
 
 subcommands:
+  get <room>                one room in full: its type and size class, how many save generations
+                            it holds, how big its stored state is, and the exact deletion time
+  set <room> --retention <d|forever|clear>
+                            override the retention window for THIS room. A duration like 30m, 6h
+                            or 7d keeps it that long past its last activity; forever keeps it
+                            indefinitely; clear goes back to what its type declares
   saves <room>              list a room's save generations, newest first
   restore <room> --save <id>
                             bring a room back from a save. This DISCARDS its current state, and
                             stops the tenant if it is live
   delete <room>             delete a room's stored state: its snapshot, its saves and its alarms.
-                            This is permanent. Refused while the room is awake
+                            This is permanent. Refused while the room is awake unless --force
+
+list filters:
+  --active           only rooms that are awake in a live tenant
+  --idle             only rooms that are not
+  --idle-longer-than <d>
+                     only rooms whose last report is older than a duration like 30m, 6h or 7d
 
 options:
+  --force            with delete: disconnect the room's clients first, then delete it
   --project <id>     project id (default: the project file)
   -c, --config <f>   the project file to read (default irtio.json)
-  --url <control>    control plane (default: your stored login)
+  --url <control>    control plane (default: your stored login, or IRT_API_KEY)
   -h, --help         print this
 `;
 function parseRoomsArgs(args) {
@@ -47,7 +62,7 @@ function parseRoomsArgs(args) {
   const parsed = { sub: "list" };
   let rest = args;
   const first = args[0];
-  if (first === "saves" || first === "restore" || first === "delete") {
+  if (first === "saves" || first === "restore" || first === "delete" || first === "get" || first === "set") {
     parsed.sub = first;
     const room = args[1];
     if (room === void 0 || room.startsWith("-")) {
@@ -65,6 +80,33 @@ function parseRoomsArgs(args) {
         parsed.save = value;
         break;
       }
+      // ---- M6 lane A: rooms API ----
+      case "--active":
+        parsed.active = true;
+        break;
+      case "--idle":
+        parsed.active = false;
+        break;
+      case "--idle-longer-than": {
+        const value = rest[++i];
+        if (value === void 0) {
+          throw new Error("irtio rooms: --idle-longer-than needs a duration like 30m, 6h or 7d");
+        }
+        parsed.idleLongerThan = value;
+        break;
+      }
+      case "--retention": {
+        const value = rest[++i];
+        if (value === void 0) {
+          throw new Error("irtio rooms: --retention needs a duration, forever, or clear");
+        }
+        parsed.retention = value;
+        break;
+      }
+      case "--force":
+        parsed.force = true;
+        break;
+      // ---- end M6 lane A ----
       case "--project": {
         const value = rest[++i];
         if (value === void 0) throw new Error("irtio rooms: --project needs a value");
@@ -94,6 +136,23 @@ function parseRoomsArgs(args) {
       "irtio rooms restore: --save <id> is required \u2014 run `irtio rooms saves <room>` to see them"
     );
   }
+  if (parsed.sub === "set" && parsed.retention === void 0) {
+    throw new Error(
+      "irtio rooms set: --retention <d|forever|clear> is required. A duration like 7d keeps this room that long past its last activity, forever keeps it indefinitely, and clear goes back to what its type declares"
+    );
+  }
+  if (parsed.active !== void 0 && parsed.sub !== "list") {
+    throw new Error("irtio rooms: --active and --idle are filters for the listing");
+  }
+  if (parsed.idleLongerThan !== void 0 && parsed.sub !== "list") {
+    throw new Error("irtio rooms: --idle-longer-than is a filter for the listing");
+  }
+  if (parsed.force === true && parsed.sub !== "delete") {
+    throw new Error("irtio rooms: --force belongs to `irtio rooms delete`");
+  }
+  if (parsed.retention !== void 0 && parsed.sub !== "set") {
+    throw new Error("irtio rooms: --retention belongs to `irtio rooms set`");
+  }
   return parsed;
 }
 function formatBytes(bytes) {
@@ -114,16 +173,60 @@ function formatAge(iso, now) {
 function statusColor(status) {
   return status === "active" || status === "running" ? pc.green(status) : status === "draining" ? pc.yellow(status) : pc.dim(status);
 }
-function formatTable(rows) {
+function formatTable(rows, now) {
   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      RETAIN  LAST SEEN`)];
+  const sharded = rows.some((r) => (r.shard ?? 0) > 0);
+  const head = `${"ROOM".padEnd(idWidth)}  STATUS      RETAIN  DELETES        LAST SEEN` + (sharded ? "  SHARD" : "");
+  const out = [pc.dim(head)];
   for (const r of rows) {
     const retention = r.retention ?? "forever";
+    const mark = r.retentionOverride ? "*" : "";
     out.push(
-      `${r.roomId.padEnd(idWidth)}  ${statusColor(r.status).padEnd(10)}  ${retention.padEnd(6)}  ${pc.dim(r.lastSeen)}`
+      `${r.roomId.padEnd(idWidth)}  ${statusColor(r.status).padEnd(10)}  ${`${retention}${mark}`.padEnd(6)}  ${formatDeadline(r.deletesAt, now).padEnd(13)}  ${pc.dim(r.lastSeen)}` + (sharded ? `  ${String(r.shard ?? 0)}` : "")
     );
   }
+  if (rows.some((r) => r.retentionOverride)) {
+    out.push(pc.dim("* set on this room, not declared by its type"));
+  }
+  return out;
+}
+function formatDeadline(deletesAt, now) {
+  if (!deletesAt) return pc.dim("never");
+  const ms = Date.parse(deletesAt) - now;
+  if (!Number.isFinite(ms)) return pc.dim("never");
+  if (ms <= 0) return pc.yellow("next sweep");
+  const mins = Math.floor(ms / 6e4);
+  if (mins < 60) return `in ${mins}m`;
+  const hours = Math.floor(mins / 60);
+  if (hours < 48) return `in ${hours}h`;
+  return `in ${Math.floor(hours / 24)}d`;
+}
+function formatDetail(room, now) {
+  const line = (label, value) => `${pc.dim(label.padEnd(12))}${value}`;
+  const out = [
+    line("room", pc.bold(room.roomId)),
+    line("status", statusColor(room.status)),
+    line("type", room.type ?? pc.dim("not a room id"))
+  ];
+  out.push(line("class", room.class ?? pc.dim("not declared (billed as small)")));
+  if (room.clients !== null && room.clients !== void 0) {
+    const max = room.maxClients ? `/${room.maxClients}` : "";
+    out.push(line("clients", `${room.clients}${max}`));
+  }
+  out.push(line("retention", room.retention ?? "forever"));
+  if (room.retentionOverride) {
+    out.push(line("", pc.dim(`set on this room (${room.retentionOverride}), not by its type`)));
+  }
+  out.push(line("deletes", formatDeadline(room.deletesAt, now)));
+  out.push(line("saves", String(room.saves)));
+  out.push(
+    line(
+      "state",
+      room.stateBytes === void 0 ? pc.dim("unknown while the room is awake; read it after it sleeps") : formatBytes(room.stateBytes)
+    )
+  );
+  out.push(line("last seen", pc.dim(room.lastSeen)));
   return out;
 }
 function formatSaves(rows, now) {
@@ -180,8 +283,16 @@ async function runDeleteRoom(options) {
   log(
     `${pc.yellow("deleting")} room ${pc.bold(options.room)}: its snapshot, its saves and its alarms`
   );
+  if (options.force === true) {
+    log(
+      pc.yellow(
+        "forced: if the room is awake, every client in it is disconnected first and sees E_ROOM_DELETED. They cannot rejoin the same room; a fresh one starts empty"
+      )
+    );
+  }
   const result = await client.del(
-    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`,
+    options.force === true ? { force: "true" } : {}
   );
   log(pc.green(`deleted ${options.room}: ${result.objects} stored object(s) removed`));
   log(pc.dim("player data and leaderboard scores are keyed to the player and are untouched"));
@@ -191,10 +302,40 @@ 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);
+  const rows = await client.get(`/v1/projects/${options.project}/rooms`, {
+    ...options.active !== void 0 ? { active: String(options.active) } : {},
+    ...options.idleLongerThan !== void 0 ? { "idle-longer-than": options.idleLongerThan } : {}
+  });
+  for (const line of formatTable(rows, options.now ?? Date.now())) log(line);
   return rows;
 }
+async function runGetRoom(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const room = await client.get(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`
+  );
+  for (const line of formatDetail(room, options.now ?? Date.now())) log(line);
+  return room;
+}
+async function runSetRoom(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const retention = options.retention === "clear" ? null : options.retention;
+  const room = await client.patch(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`,
+    { retention }
+  );
+  log(
+    retention === null ? pc.green(
+      `${options.room}: override cleared, back to its type's window (${room.retention ?? "forever"})`
+    ) : pc.green(`${options.room}: retention set to ${retention}`)
+  );
+  for (const line of formatDetail(room, options.now ?? Date.now())) log(line);
+  return room;
+}
 async function rooms(args, deps = {}) {
   const log = deps.log ?? ((line) => console.log(line));
   const errorLog = deps.errorLog ?? ((line) => console.error(line));
@@ -216,15 +357,31 @@ async function rooms(args, deps = {}) {
     if (parsed.sub === "saves") {
       await runSaves({ ...common, room: parsed.room });
     } else if (parsed.sub === "delete") {
-      await runDeleteRoom({ ...common, room: parsed.room });
+      await runDeleteRoom({
+        ...common,
+        room: parsed.room,
+        ...parsed.force === true ? { force: true } : {}
+      });
     } else if (parsed.sub === "restore") {
       await runRestore({
         ...common,
         room: parsed.room,
         saveId: parsed.save
       });
+    } else if (parsed.sub === "get") {
+      await runGetRoom({ ...common, room: parsed.room });
+    } else if (parsed.sub === "set") {
+      await runSetRoom({
+        ...common,
+        room: parsed.room,
+        retention: parsed.retention
+      });
     } else {
-      await runRooms(common);
+      await runRooms({
+        ...common,
+        ...parsed.active !== void 0 ? { active: parsed.active } : {},
+        ...parsed.idleLongerThan !== void 0 ? { idleLongerThan: parsed.idleLongerThan } : {}
+      });
     }
   } catch (err) {
     if (err instanceof HelpRequested) {
@@ -246,7 +403,9 @@ export {
   parseRoomsArgs,
   rooms,
   runDeleteRoom,
+  runGetRoom,
   runRestore,
   runRooms,
-  runSaves
+  runSaves,
+  runSetRoom
 };

package/dist/simulate.d.ts

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