@irtio/cli 0.5.2 → 0.6.0

package/dist/ratings-VG32WFDG.js

@@ -0,0 +1,297 @@
+import {
+  readProjectConfig
+} from "./chunk-DKWG7MGO.js";
+import {
+  HelpRequested,
+  helpFor,
+  helpRequested
+} from "./chunk-ZD4ND6X6.js";
+import {
+  createApiClient,
+  isLoginRequired
+} from "./chunk-RNAH5T4W.js";
+import {
+  resolveControlUrlForUser
+} from "./chunk-UPHQM6NZ.js";
+
+// src/ratings.ts
+import pc from "picocolors";
+var USAGE = `usage: irtio ratings <queue> [options]
+       irtio ratings list [options]
+       irtio ratings delete <queue> --player <id> --yes [options]
+
+Prints a project's skill ratings for one queue, best first. Needs your login: a rating is a
+number the matchmaker uses, not a scoreboard for players to read.
+
+There is no submit command. A rating moves only from room code (room.ratings.report), which
+is what makes it mean anything.
+
+list     every queue with ratings on the project, with its row count
+delete   remove one player's rating in one queue. Needs --player, your login and --yes;
+         without --yes it prints what would go and changes nothing.
+
+options:
+  --limit <n>        how many rows (default 20, max 100)
+  --cursor <c>       continue from a previous page's nextCursor
+  --all              page through the whole queue, following cursors
+  --player <id>      with delete: whose rating to remove
+  --yes              with delete: actually delete
+  --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)
+  -h, --help         print this
+`;
+function parseRatingsArgs(args) {
+  if (helpRequested(args)) throw helpFor(USAGE);
+  const parsed = {};
+  if (args[0] === "list" || args[0] === "delete") parsed.action = args[0];
+  for (let i = parsed.action === void 0 ? 0 : 1; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--cursor": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio ratings: --cursor needs a value");
+        }
+        parsed.cursor = value;
+        break;
+      }
+      case "--all":
+        parsed.all = true;
+        break;
+      case "--yes":
+        parsed.yes = true;
+        break;
+      case "--player": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio ratings: --player needs a player id");
+        }
+        parsed.player = value;
+        break;
+      }
+      case "--limit": {
+        const value = Number(args[++i]);
+        if (!Number.isInteger(value) || value < 1) {
+          throw new Error("irtio ratings: --limit needs a whole number of at least 1");
+        }
+        parsed.limit = value;
+        break;
+      }
+      case "--project": {
+        const value = args[++i];
+        if (value === void 0) throw new Error("irtio ratings: --project needs a value");
+        parsed.project = value;
+        break;
+      }
+      case "-c":
+      case "--config": {
+        const value = args[++i];
+        if (value === void 0 || value === "") {
+          throw new Error("irtio ratings: --config needs a value");
+        }
+        parsed.config = value;
+        break;
+      }
+      case "--url": {
+        const value = args[++i];
+        if (value === void 0) throw new Error("irtio ratings: --url needs a value");
+        parsed.url = value;
+        break;
+      }
+      default:
+        if (arg.startsWith("-")) {
+          throw new Error(`irtio ratings: unknown option ${JSON.stringify(arg)}`);
+        }
+        if (parsed.queue !== void 0) {
+          throw new Error("irtio ratings: give exactly one queue name");
+        }
+        parsed.queue = arg;
+    }
+  }
+  return parsed;
+}
+function formatRatings(body) {
+  const out = [pc.dim(`queue ${body.queue}  \xB7  Glicko-2, higher is stronger`), ""];
+  if (body.entries.length === 0) {
+    out.push(pc.dim("no ratings in this queue yet"));
+    out.push(pc.dim("a rating appears when room code calls room.ratings.report"));
+    return out;
+  }
+  const rankWidth = Math.max(4, ...body.entries.map((e) => String(e.rank).length));
+  const idWidth = Math.max(6, ...body.entries.map((e) => e.playerId.length));
+  out.push(pc.dim(`${"RANK".padEnd(rankWidth)}  ${"PLAYER".padEnd(idWidth)}  RATING  \xB1DEV  GAMES`));
+  for (const e of body.entries) {
+    out.push(
+      `${String(e.rank).padEnd(rankWidth)}  ${e.playerId.padEnd(idWidth)}  ${e.rating.toFixed(0).padStart(6)}  ${e.deviation.toFixed(0).padStart(4)}  ${String(e.games).padStart(5)}`
+    );
+  }
+  out.push("");
+  out.push(
+    pc.dim("\xB1DEV is how sure the rating is. 350 means a new player; under 80 means settled.")
+  );
+  return out;
+}
+async function runRatings(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const base = `/v1/projects/${encodeURIComponent(options.project)}/ratings/${encodeURIComponent(
+    options.queue
+  )}`;
+  const pageUrl = (cursor) => {
+    const query = new URLSearchParams();
+    if (options.limit !== void 0) query.set("limit", String(options.limit));
+    if (cursor !== void 0) query.set("cursor", cursor);
+    const q = query.toString();
+    return `${base}${q === "" ? "" : `?${q}`}`;
+  };
+  let body = await client.get(pageUrl(options.cursor));
+  const entries = [...body.entries];
+  if (options.all === true) {
+    let next = body.nextCursor;
+    for (let page = 1; next !== void 0 && page < 100; page++) {
+      body = await client.get(pageUrl(next));
+      for (const entry of body.entries) {
+        entries.push({ ...entry, rank: entries.length + 1 });
+      }
+      next = body.nextCursor;
+    }
+    if (next !== void 0) {
+      throw new Error(
+        "irtio ratings: --all stopped after a hundred pages. Read it in pieces with --cursor"
+      );
+    }
+  }
+  const combined = { ...body, entries };
+  for (const line of formatRatings(combined)) log(line);
+  if (options.all !== true && body.nextCursor !== void 0) {
+    log("");
+    log(pc.dim(`more rows: --cursor ${body.nextCursor}`));
+  }
+  return combined;
+}
+function formatQueueList(queues) {
+  if (queues.length === 0) {
+    return [
+      pc.dim("no ratings on this project yet"),
+      pc.dim("a rating reaches a queue from room code: room.ratings.report")
+    ];
+  }
+  const nameWidth = Math.max(5, ...queues.map((q) => q.queue.length));
+  const out = [pc.dim(`${"QUEUE".padEnd(nameWidth)}  ${"ROWS".padStart(7)}  MATCHING`)];
+  for (const q of queues) {
+    const matching = q.skill ? "skill" : "fifo";
+    const note = q.configured && q.rows === 0 ? pc.dim("  (configured, no ratings yet)") : !q.configured ? pc.dim("  (ratings only; not a configured queue)") : !q.skill ? pc.dim("  (ratings recorded, but this queue fills in arrival order)") : "";
+    out.push(`${q.queue.padEnd(nameWidth)}  ${String(q.rows).padStart(7)}  ${matching}${note}`);
+  }
+  return out;
+}
+async function runQueueList(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const body = await client.get(
+    `/v1/projects/${encodeURIComponent(options.project)}/ratings`
+  );
+  for (const line of formatQueueList(body.queues)) log(line);
+  return body.queues;
+}
+async function runRatingDelete(options) {
+  const log = options.log ?? ((line) => console.log(line));
+  const controlUrl = await resolveControlUrlForUser(options.controlUrl);
+  const client = options.client ?? await createApiClient(controlUrl);
+  const path = `/v1/projects/${encodeURIComponent(options.project)}/ratings/${encodeURIComponent(
+    options.queue
+  )}/${encodeURIComponent(options.player)}`;
+  if (!options.yes) {
+    log(
+      `this would delete ${pc.bold(options.player)}'s rating in queue ${pc.bold(options.queue)} in project ${options.project}`
+    );
+    log(pc.dim("nothing was deleted. This cannot be undone once it runs"));
+    log(`to proceed: irtio ratings delete ${options.queue} --player ${options.player} --yes`);
+    return false;
+  }
+  const body = await client.del(path);
+  log(
+    body.deleted ? pc.green(`deleted ${options.player}'s rating in queue ${options.queue}`) : pc.dim(`${options.player} had no rating in queue ${options.queue}; nothing to delete`)
+  );
+  return true;
+}
+async function ratings(args, deps = {}) {
+  const log = deps.log ?? ((line) => console.log(line));
+  const errorLog = deps.errorLog ?? ((line) => console.error(line));
+  try {
+    const parsed = parseRatingsArgs(args);
+    const config = await readProjectConfig(process.cwd(), "irtio ratings", parsed.config);
+    const project = parsed.project ?? config.project;
+    if (project === void 0) {
+      throw new Error(
+        "irtio ratings: no project id. 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.action === "list") {
+      if (parsed.queue !== void 0) throw new Error("irtio ratings list: takes no queue name");
+      await runQueueList(common);
+      return;
+    }
+    if (parsed.action === "delete") {
+      if (parsed.queue === void 0) {
+        throw new Error(
+          "irtio ratings delete: which queue? e.g. irtio ratings delete ranked --player irt:abc --yes"
+        );
+      }
+      if (parsed.player === void 0) {
+        throw new Error("irtio ratings delete: --player is required; there is no whole-queue wipe");
+      }
+      await runRatingDelete({
+        ...common,
+        queue: parsed.queue,
+        player: parsed.player,
+        yes: parsed.yes === true
+      });
+      return;
+    }
+    if (parsed.queue === void 0) {
+      throw new Error("irtio ratings: which queue? e.g. irtio ratings ranked");
+    }
+    if (parsed.cursor !== void 0 && parsed.all === true) {
+      throw new Error("irtio ratings: --cursor and --all are two ways to do the same thing");
+    }
+    await runRatings({
+      ...common,
+      queue: parsed.queue,
+      ...parsed.limit !== void 0 ? { limit: parsed.limit } : {},
+      ...parsed.cursor !== void 0 ? { cursor: parsed.cursor } : {},
+      ...parsed.all !== void 0 ? { all: parsed.all } : {}
+    });
+  } catch (err) {
+    if (err instanceof HelpRequested) {
+      log(err.usage);
+      return;
+    }
+    if (isLoginRequired(err)) {
+      errorLog("irtio ratings: not logged in. Run `irtio login` first");
+      process.exitCode = 1;
+      return;
+    }
+    errorLog(err instanceof Error ? err.message : String(err));
+    process.exitCode = 1;
+  }
+}
+export {
+  USAGE,
+  formatQueueList,
+  formatRatings,
+  parseRatingsArgs,
+  ratings,
+  runQueueList,
+  runRatingDelete,
+  runRatings
+};

package/dist/{rollback-GA6UY772.js → rollback-SO74MVZV.js}

@@ -1,14 +1,18 @@
 import {
   readProjectConfig
-} from "./chunk-32QTPKVT.js";
+} from "./chunk-DKWG7MGO.js";
 import {
   HelpRequested,
-  createApiClient,
   helpFor,
-  helpRequested,
-  isLoginRequired,
+  helpRequested
+} from "./chunk-ZD4ND6X6.js";
+import {
+  createApiClient,
+  isLoginRequired
+} from "./chunk-RNAH5T4W.js";
+import {
   resolveControlUrlForUser
-} from "./chunk-TV66QHFP.js";
+} from "./chunk-UPHQM6NZ.js";
 
 // src/rollback.ts
 import "fs";

package/dist/{rooms-B66LQIIF.js → rooms-VI33P4RA.js}

@@ -1,14 +1,18 @@
 import {
   readProjectConfig
-} from "./chunk-32QTPKVT.js";
+} from "./chunk-DKWG7MGO.js";
 import {
   HelpRequested,
-  createApiClient,
   helpFor,
-  helpRequested,
-  isLoginRequired,
+  helpRequested
+} from "./chunk-ZD4ND6X6.js";
+import {
+  createApiClient,
+  isLoginRequired
+} from "./chunk-RNAH5T4W.js";
+import {
   resolveControlUrlForUser
-} from "./chunk-TV66QHFP.js";
+} from "./chunk-UPHQM6NZ.js";
 
 // src/rooms.ts
 import "fs";
@@ -18,15 +22,19 @@ import pc from "picocolors";
 var USAGE = `usage: irtio rooms [options]
        irtio rooms saves <room> [options]
        irtio rooms restore <room> --save <id> [options]
+       irtio rooms delete <room> [options]
 
-Lists a project's rooms. Rows not reported for longer than the control plane's retention window
-(30 days by default) are pruned.
+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.
 
 subcommands:
   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
 
 options:
   --project <id>     project id (default: the project file)
@@ -39,7 +47,7 @@ function parseRoomsArgs(args) {
   const parsed = { sub: "list" };
   let rest = args;
   const first = args[0];
-  if (first === "saves" || first === "restore") {
+  if (first === "saves" || first === "restore" || first === "delete") {
     parsed.sub = first;
     const room = args[1];
     if (room === void 0 || room.startsWith("-")) {
@@ -109,10 +117,11 @@ function statusColor(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`)];
+  const out = [pc.dim(`${"ROOM".padEnd(idWidth)}  STATUS      RETAIN  LAST SEEN`)];
   for (const r of rows) {
+    const retention = r.retention ?? "forever";
     out.push(
-      `${r.roomId.padEnd(idWidth)}  ${statusColor(r.status).padEnd(10)}  ${pc.dim(r.lastSeen)}`
+      `${r.roomId.padEnd(idWidth)}  ${statusColor(r.status).padEnd(10)}  ${retention.padEnd(6)}  ${pc.dim(r.lastSeen)}`
     );
   }
   return out;
@@ -164,6 +173,20 @@ async function runRestore(options) {
   }
   return result;
 }
+async function runDeleteRoom(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("deleting")} room ${pc.bold(options.room)}: its snapshot, its saves and its alarms`
+  );
+  const result = await client.del(
+    `/v1/projects/${options.project}/rooms/${encodeURIComponent(options.room)}`
+  );
+  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"));
+  return result;
+}
 async function runRooms(options) {
   const log = options.log ?? ((line) => console.log(line));
   const controlUrl = await resolveControlUrlForUser(options.controlUrl);
@@ -192,6 +215,8 @@ 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 });
     } else if (parsed.sub === "restore") {
       await runRestore({
         ...common,
@@ -220,6 +245,7 @@ export {
   USAGE,
   parseRoomsArgs,
   rooms,
+  runDeleteRoom,
   runRestore,
   runRooms,
   runSaves

package/dist/simulate.d.ts

@@ -1,6 +1,46 @@
-import { RunEnd, SimulationReport, TickHealthReading } from '@irtio/bots';
+import { ScenarioDefinition, BotConditions, NetworkConditions, AssertionResult, RunEnd, SimulationReport, HitRow, TruthDiff, TickHealthReading } from '@irtio/bots';
 import { AnySchema } from '@irtio/schema';
 
+/**
+ * D41: loading a scenario file, and reading the recorded authoritative timeline back off the dev
+ * server.
+ *
+ * Loading follows `loadProjectSchema`'s pattern exactly: esbuild the user's TypeScript to ESM,
+ * dynamic-import it with a cache-busting query, and shape-check the export. `bundleRoom` is the
+ * wrong tool here for the same reason it is wrong for a schema module, only more so: it enforces
+ * the room sandbox's fixed import menu, and a scenario's whole point is that it imports
+ * `@irtio/bots`.
+ *
+ * Reading follows the tick counters' pattern exactly: the dev server's own inspector routes, on
+ * the socket's port. A deployed tenant has no authoritative tap, so it has no timeline either,
+ * and this module says so rather than inventing one from what a client received.
+ */
+
+/**
+ * A scenario that could not be loaded, or a timeline that could not be recorded. Both are "the
+ * run was not performed" rather than "the room failed": nothing was measured either way, and
+ * reporting a scenario as passing because its assertions never ran would be the worst outcome
+ * this command can produce.
+ */
+declare class ScenarioNotRunError extends Error {
+    readonly cause?: unknown | undefined;
+    readonly name = "ScenarioNotRunError";
+    constructor(message: string, cause?: unknown | undefined);
+}
+interface LoadScenarioOptions {
+    readonly cwd: string;
+    readonly outDir: string;
+    /** The scenario file, absolute or relative to `cwd`. */
+    readonly file: string;
+    /** Redirects `@irtio/*` for the bundle; the monorepo's own `src/` by default. */
+    readonly irtioPackages?: Record<string, string> | undefined;
+}
+/** Bundles the scenario module and returns its default export. */
+declare function loadScenario(options: LoadScenarioOptions): Promise<{
+    scenario: ScenarioDefinition;
+    file: string;
+}>;
+
 /**
  * `irtio simulate`: point N real clients at a running room, play it randomly for a few
  * seconds, and print a pass/fail line per built-in invariant.
@@ -19,16 +59,29 @@ interface SimulateArgs {
     bots: number;
     seconds: number;
     cheat: boolean;
+    /** D42: bots named by `--cheat-bot`. Empty means "whatever `cheat` says". */
+    cheatBots?: number[];
+    /** D42: `--conditions`, applied to every bot. */
+    conditions?: NetworkConditions;
+    /** D42: `--conditions-bot <index>:<json>`, overriding `conditions` for those indices. */
+    conditionsPerBot?: Record<number, NetworkConditions>;
+    /** D43: `--truth`, take a save at the end of the run and diff it against the clients. */
+    truth?: boolean;
     room?: string;
     url?: string;
     key?: string;
     trace?: string;
+    scenario?: string;
     mispredictionMax?: number;
     snapsMax?: number;
     correctionsMax?: number;
     overrunsMax?: number;
+    /** D65: give every bot a bandwidth ledger and print the run's breakdown. */
+    profile?: boolean;
+    /** D65: rows in that table. Implies `profile`. */
+    profileTop?: 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  --cheat                     send illegal writes and expect corrections\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  -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  --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 {
@@ -63,7 +116,14 @@ interface LoadedWorld {
  * 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>;
+/** `bugs.md` #21: a 2D world module, recognised rather than refused. There is nothing to predict
+ *  from it in this release, so the caller drops the predicted-world path and runs anyway. */
+interface UnpredictedWorld {
+    readonly unpredicted: 'matter2d';
+    readonly file: string;
+}
+declare function isUnpredictedWorld(world: LoadedWorld | UnpredictedWorld | undefined): world is UnpredictedWorld;
+declare function loadProjectWorld(options: LoadSchemaOptions): Promise<LoadedWorld | UnpredictedWorld | 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
@@ -82,6 +142,41 @@ interface RoomTickCounters {
     readonly overruns?: number;
     readonly maxTickMs?: number;
 }
+/**
+ * `bugs.md` #16: which build of the room a run tested.
+ *
+ * A `simulate` report used to name the room code, the bot count and the URL, and nothing that
+ * identified the code under test. That is a false-green generator: edit `irtio/room.ts`, forget
+ * that an older `dev` is still holding the port, and the run measures the bundle you replaced.
+ * The information already existed on the inspector; nothing read it.
+ *
+ * Both fields matter and neither is redundant. The bundle hash catches an edit the server never
+ * picked up; the start time catches the case the hash cannot see, which is a *different process*
+ * that happens to be serving an identical bundle, and it is the field that tells a reader the
+ * server they thought they had restarted did not restart.
+ */
+interface BuildIdentity {
+    /** The bundle hash the server is serving, as `irtio dev` prints it at startup. */
+    readonly bundleHash?: string;
+    /** The schema hash behind that bundle, when the server knows one. */
+    readonly schemaHash?: string;
+    /** Epoch ms when the serving process booted. */
+    readonly startedAt?: number;
+    /** Where it was read from. */
+    readonly source?: string;
+    /** Why there is no identity, when there is none. Never both this and the fields above. */
+    readonly unavailable?: string;
+}
+/**
+ * Reads the serving build's identity off the dev inspector, or says why it could not.
+ *
+ * Deliberately shaped like `readTickCounters`: a deployed tenant does not serve `state.json`, so
+ * against staging this returns an `unavailable` sentence rather than a wrong answer. An unknown
+ * build is a fact worth printing, and printing nothing is what caused the bug.
+ */
+declare function readBuildIdentity(wsUrl: string): Promise<BuildIdentity>;
+/** The one line `bugs.md` #16 asked for, beside the URL in the report header. */
+declare function formatBuildIdentity(build: BuildIdentity): string;
 /**
  * Reads one room's tick counters off the dev server, or explains why it could not. Every failure
  * path returns a sentence rather than a zero: the `tick-health` invariant has an `unavailable`
@@ -146,9 +241,57 @@ declare class RunNotPerformedError extends Error {
  * are the two fatal run conditions, and both still print the report and write the trace.
  */
 type SimulationEnd = RunEnd | 'ceiling';
+/** D42: the adversarial section. Present whenever anything was injected or anyone cheated. */
+interface AdversarialRun {
+    /** Per bot: what was injected and what the wrapper counted. */
+    readonly conditions: readonly BotConditions[];
+    /** Bot indices that cheated. */
+    readonly cheated: readonly number[];
+    /** Corrections drawn per cheating bot, in the same order as `cheated`. */
+    readonly correctionsPerCheater: readonly number[];
+}
+/** D41: what a scenario run adds to the report. Absent when no `--scenario` ran. */
+interface ScenarioRun {
+    readonly file: string;
+    /** Every assertion the scenario ran, in order. */
+    readonly assertions: readonly AssertionResult[];
+    readonly ok: boolean;
+    /** Recorded ticks the assertions could read. */
+    readonly ticks: number;
+    /** Ticks the recorder's caps evicted. Non-zero means the recording is a tail. */
+    readonly dropped: number;
+    /** Where the recording was written, so a failed run can be re-read without re-running it. */
+    readonly timelinePath: string;
+}
+/** D43: the truth-seam section, when a run asked for one. */
+interface TruthRun {
+    /** The diff, when a save was taken and decoded. */
+    readonly diff?: TruthDiff;
+    /** The save generation the diff read. */
+    readonly saveId?: string;
+    /**
+     * The decoded save's state, in `inspectState` shape. Carried because it is the only place a
+     * caller can read what the server actually held without starting a room, which is the whole
+     * point of the decoder, and because a test asserting "the illegal write was accepted" has to
+     * read authoritative state rather than infer it from a correction that did not arrive.
+     */
+    readonly saveState?: Record<string, unknown>;
+    /** Why there is no diff, when there is none. Never both this and `diff`. */
+    readonly error?: string;
+}
 interface SimulationRun {
     readonly report: SimulationReport;
     readonly tracePath: string;
+    /** `bugs.md` #16: which build of the room this run tested, or why that is not knowable. */
+    readonly build: BuildIdentity;
+    /** D41: the scenario section, when `--scenario` ran one. */
+    readonly scenario?: ScenarioRun;
+    /** D42: what was injected per bot, and which bots cheated. */
+    readonly adversarial?: AdversarialRun;
+    /** D42: one row per `bot.shot(...)`. Absent when nothing fired. */
+    readonly hits?: readonly HitRow[];
+    /** D43: the truth-seam verdict. Absent unless the run asked for it. */
+    readonly truth?: TruthRun;
     /** `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). */
@@ -169,4 +312,4 @@ interface SimulationRun {
 declare function runSimulation(options?: RunSimulationOptions): Promise<SimulationRun>;
 declare function simulate(args: readonly string[]): Promise<void>;
 
-export { type LoadSchemaOptions, RunNotPerformedError, type RunSimulationOptions, type SimulateArgs, type SimulationEnd, type SimulationRun, USAGE, ceilingFor, checkWorldDeterminism, loadProjectSchema, loadProjectWorld, parseSimulateArgs, readTickCounters, runSimulation, simulate, stateUrlFor, tickHealthFrom };
+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 };