@irtio/cli 0.5.1 → 0.6.0

package/dist/{dev-7UZZGE4U.js → dev-QM26ONKS.js}

@@ -1,26 +1,48 @@
+import {
+  profileTick
+} from "./chunk-ZK5JLUD4.js";
 import {
   clientImportsRoom
 } from "./chunk-TQU6345E.js";
-import {
-  BundleError,
-  bundleRoom
-} from "./chunk-KRQUAEN2.js";
 import {
   DEFAULT_SAVE_RETAIN,
   DiskStore,
+  IRT_IDENTITY_ISSUER,
   KV_ERRORS,
+  LEADERBOARD_ERRORS,
   PLAYER_ISSUER_RE,
   PRE_MIGRATION_SAVE_ID,
+  RATING_ERRORS,
   listSaves,
   mintSaveId,
+  parseIdentityKeys,
   pruneSaves,
-  saveKey
-} from "./chunk-BPE452KF.js";
+  ratingPlayerProblem,
+  ratingQueueProblem,
+  ratingResultsProblem,
+  ratingValueProblem,
+  saveKey,
+  verifyAssertion
+} from "./chunk-RQSJZWQC.js";
+import {
+  readProjectConfig
+} from "./chunk-DKWG7MGO.js";
+import {
+  BundleError,
+  bundleRoom
+} from "./chunk-OTSFRVJN.js";
+import {
+  HelpRequested,
+  helpFor,
+  helpRequested
+} from "./chunk-ZD4ND6X6.js";
+import "./chunk-RNAH5T4W.js";
+import "./chunk-UPHQM6NZ.js";
 
 // src/dev.ts
 import { existsSync } from "fs";
 import { watch } from "fs";
-import { mkdir, readFile } from "fs/promises";
+import { mkdir } from "fs/promises";
 import { createRequire } from "module";
 import * as path from "path";
 import { fileURLToPath, pathToFileURL as pathToFileURL3 } from "url";
@@ -40,9 +62,61 @@ var DEFAULT_LIMITS = {
   relayIdleMs: 3e4,
   relayReconnectGraceMs: 3e4,
   relayMaxClients: 64,
+  relayMaxClientsFree: 16,
+  freeMaxAwakeRooms: 10,
   saveRetain: DEFAULT_SAVE_RETAIN
 };
 
+// ../supervisor/src/codes.ts
+import { randomInt } from "crypto";
+import {
+  CODE_ALPHABET,
+  DEFAULT_ROOM_TYPE,
+  ROOM_ID_RE,
+  formatRoomId,
+  parseRoomId
+} from "@irtio/protocol";
+var TENANT_ROOM_ID = "__tenant";
+var CODE_SHAPE_RE = /^[A-Za-z0-9]{4,5}$/;
+function pick(n) {
+  let out = "";
+  for (let i = 0; i < n; i++) out += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
+  return out;
+}
+function newRoomCode(taken) {
+  for (let len = 4; len <= 8; len++) {
+    for (let attempt = 0; attempt < 64; attempt++) {
+      const code = pick(len);
+      if (!taken(code)) return code;
+    }
+  }
+  throw new Error("newRoomCode: exhausted the room code space");
+}
+function newClientId(taken) {
+  for (let attempt = 0; attempt < 128; attempt++) {
+    const id = `c${pick(10)}`;
+    if (!taken(id)) return id;
+  }
+  throw new Error("newClientId: could not allocate a unique client id");
+}
+function looksLikeRoomCode(id) {
+  if (!CODE_SHAPE_RE.test(id)) return false;
+  for (const ch of id.toUpperCase()) {
+    if (!CODE_ALPHABET.includes(ch)) return false;
+  }
+  return true;
+}
+function normalizeRoomId(raw) {
+  const parsed = parseRoomId(raw);
+  if (!parsed) return void 0;
+  if (parsed.id === TENANT_ROOM_ID) return void 0;
+  const id = looksLikeRoomCode(parsed.id) ? parsed.id.toUpperCase() : parsed.id;
+  return formatRoomId(parsed.type, id);
+}
+function roomTypeOf(roomId) {
+  return parseRoomId(roomId)?.type ?? DEFAULT_ROOM_TYPE;
+}
+
 // ../supervisor/src/resilience.ts
 var SNAPSHOT_FLUSH_MAX_RETRIES = 3;
 var SNAPSHOT_FLUSH_RETRY_DELAYS_MS = [100, 200, 400];
@@ -84,27 +158,38 @@ async function putSnapshotWithRetry(store, key, bytes, metrics, log) {
 // ../supervisor/src/server.ts
 import { execFile } from "child_process";
 import { randomBytes, timingSafeEqual as timingSafeEqual2 } from "crypto";
+import { readdirSync } from "fs";
 import { mkdtemp, writeFile } from "fs/promises";
 import { createServer } from "http";
 import { tmpdir } from "os";
 import * as nodePath from "path";
 import { pathToFileURL as pathToFileURL2 } from "url";
 import {
-  ErrorCode as ErrorCode2,
-  FrameType as FrameType2,
+  BUS_MAILBOX_PREFIX as BUS_MAILBOX_PREFIX2,
+  BUS_OUTBOX as BUS_OUTBOX2,
+  CLOSE_EGRESS_WALL,
+  DEFAULT_ROOM_TYPE as DEFAULT_ROOM_TYPE3,
+  ErrorCode as ErrorCode3,
+  FrameType as FrameType3,
   PROTOCOL_VERSION,
+  ROOM_TYPE_RE,
   decodeFrame,
   decodeHello,
-  decodeMsg,
   decodePing,
+  decodeVoiceMessage,
   encodeErrorPayload as encodeErrorPayload2,
-  encodeFrame as encodeFrame2,
-  encodeMsg,
+  encodeFrame as encodeFrame3,
+  encodeMsg as encodeMsg2,
   encodePong,
+  encodeVoiceMessage,
   encodeWelcome,
   formatError,
+  isMailboxAlarm,
+  isOutboxAlarm,
   isRelayHash8,
+  isVoiceMsg,
   relaySchema as relaySchema2,
+  schemaPayload,
   withBuiltins
 } from "@irtio/protocol";
 import { inspectState } from "@irtio/runtime";
@@ -131,6 +216,14 @@ var AlarmSet = class {
   /** `name` -> wall-clock ms the alarm is due at. Wall clock, not monotonic: it has to mean the
    *  same thing to a control plane on another machine and across a tenant restart. */
   due = /* @__PURE__ */ new Map();
+  /**
+   * D59: `name` -> the opaque payload string that entry carries, for the names that have one.
+   *
+   * A separate map rather than a field on a richer value type, so that every alarm which is not a
+   * bus mailbox entry is stored exactly as it was: an alarm is a name and a time, and D26's whole
+   * surface stays that. Only mailbox entries (`BUS_MAILBOX_PREFIX`) ever put anything here.
+   */
+  payloads = /* @__PURE__ */ new Map();
   timer;
   /** Called when one or more alarms come due, with the names in deterministic (name) order. */
   deliver;
@@ -149,13 +242,34 @@ var AlarmSet = class {
     this.deliver = void 0;
     this.clearTimer();
   }
-  /** `atMs === undefined` cancels. Arming a name that is already armed replaces its due time. */
-  set(name, atMs) {
-    if (atMs === void 0) this.due.delete(name);
-    else this.due.set(name, atMs);
+  /**
+   * `atMs === undefined` cancels. Arming a name that is already armed replaces its due time.
+   *
+   * D59: `payload` attaches an opaque string to the entry, which is how a bus mailbox entry rides
+   * this machinery. **Replace-by-name is why mailbox names are minted unique**: two sends of the
+   * same payload to the same room have to deliver twice, and a stable name would have the second
+   * quietly overwrite the first.
+   */
+  set(name, atMs, payload) {
+    if (atMs === void 0) {
+      this.due.delete(name);
+      this.payloads.delete(name);
+    } else {
+      this.due.set(name, atMs);
+      if (payload === void 0) this.payloads.delete(name);
+      else this.payloads.set(name, payload);
+    }
     this.rearm();
     this.onChange?.();
   }
+  /** D59: the payload armed with `name`, or `undefined` for an ordinary alarm. */
+  payloadOf(name) {
+    return this.payloads.get(name);
+  }
+  /** D59: how many armed entries carry a payload, i.e. the depth of this room's mailbox. */
+  get mailboxDepth() {
+    return this.payloads.size;
+  }
   get size() {
     return this.due.size;
   }
@@ -164,12 +278,19 @@ var AlarmSet = class {
   /** Replaces the armed set wholesale — how a room start re-arms from the persisted sidecar. */
   load(entries) {
     this.due.clear();
-    for (const e of entries) this.due.set(e.name, e.dueAt);
+    this.payloads.clear();
+    for (const e of entries) {
+      this.due.set(e.name, e.dueAt);
+      if (e.payload !== void 0) this.payloads.set(e.name, e.payload);
+    }
     this.rearm();
   }
   /** Snapshot for `/admin/rooms` and for tests. */
   entries() {
-    return [...this.due.entries()].map(([name, dueAt]) => ({ name, dueAt })).sort((a, b) => a.dueAt - b.dueAt || (a.name < b.name ? -1 : 1));
+    return [...this.due.entries()].map(([name, dueAt]) => {
+      const payload = this.payloads.get(name);
+      return { name, dueAt, ...payload !== void 0 ? { payload } : {} };
+    }).sort((a, b) => a.dueAt - b.dueAt || (a.name < b.name ? -1 : 1));
   }
   /** The earliest due time, or `undefined` when nothing is armed. What control is told. */
   get earliestDueAt() {
@@ -188,6 +309,7 @@ var AlarmSet = class {
     if (names.length === 0) return names;
     for (const name of names) this.due.delete(name);
     this.deliver?.(names);
+    for (const name of names) if (!this.due.has(name)) this.payloads.delete(name);
     this.rearm();
     this.onChange?.();
     return names;
@@ -248,11 +370,64 @@ function decodeAlarms(bytes) {
     const e = entry;
     if (typeof e.name !== "string" || e.name === "") continue;
     if (typeof e.dueAt !== "number" || !Number.isFinite(e.dueAt)) continue;
-    out.push({ name: e.name, dueAt: e.dueAt });
+    const payload = e.payload;
+    out.push({
+      name: e.name,
+      dueAt: e.dueAt,
+      ...typeof payload === "string" ? { payload } : {}
+    });
   }
   return out;
 }
 
+// ../supervisor/src/relay-host.ts
+import {
+  ErrorCode,
+  FrameType,
+  decodeMsg,
+  encodeFrame,
+  encodeMsg
+} from "@irtio/protocol";
+function relayJoin(room, peer) {
+  const relay = room.relayRoom;
+  if (!relay.has(peer.clientId) && relay.size >= room.maxClients) {
+    return { ok: false, code: "E_ROOM_FULL" };
+  }
+  const delta = relay.add(peer.clientId, peer.role, peer.name);
+  return { ok: true, tick: relay.tick, snapshot: relay.snapshot(), delta };
+}
+function relayForward(room, peer, type, payload) {
+  if (type !== FrameType.MSG) {
+    return { ok: false, reason: "relay rooms accept MSG only (no room code is deployed)" };
+  }
+  let target;
+  let body;
+  try {
+    const msg = decodeMsg(payload);
+    target = msg.target;
+    body = msg.payload;
+  } catch {
+    return { ok: false, reason: "malformed MSG" };
+  }
+  if (target.kind === "server") {
+    return { ok: false, reason: "relay rooms have no server to address" };
+  }
+  if (target.kind === "voice") return { ok: true, dropped: true };
+  const out = encodeFrame(
+    FrameType.MSG,
+    encodeMsg({ target: { kind: "client", clientId: peer.clientId }, payload: body })
+  );
+  for (const other of room.peers()) {
+    if (other === peer || other.state !== "joined") continue;
+    if (target.kind === "client" && other.clientId !== target.clientId) continue;
+    if (target.kind === "role" && other.role !== target.role) continue;
+    const sent = other.send(out);
+    if (sent > 0) room.countEgress(sent);
+  }
+  room.touched(room.relayRoom.advance());
+  return { ok: true };
+}
+
 // ../supervisor/src/auth.ts
 import { createHmac, timingSafeEqual } from "crypto";
 import { isLocalhostOrigin, originAllowed } from "@irtio/protocol";
@@ -324,6 +499,13 @@ function verifyJwt(issuers, token, projectId, now = Date.now()) {
   if (typeof claims.iss !== "string" || !PLAYER_ISSUER_RE.test(claims.iss)) {
     return malformed("iss is required: 1-64 of a-z 0-9 . _ - (never a colon)");
   }
+  if (claims.iss === IRT_IDENTITY_ISSUER) {
+    return {
+      ok: false,
+      code: "E_TOKEN_BAD_ISSUER",
+      reason: `${IRT_IDENTITY_ISSUER} is reserved for platform identities`
+    };
+  }
   if (typeof claims.aud !== "string") {
     return malformed("aud (the project id) is required");
   }
@@ -377,7 +559,7 @@ function mac(secret, payload) {
   return createHmac("sha256", secret).update(payload).digest("base64url");
 }
 function signResume(secret, p) {
-  const payload = `${p.clientId}|${p.roomId}|${encodeURIComponent(p.role)}|${p.expMs}`;
+  const payload = `${p.clientId}|${p.roomId}|${encodeURIComponent(p.role)}|${p.expMs}|${p.iatMs}`;
   return Buffer.from(`${payload}.${mac(secret, payload)}`, "utf8").toString("base64url");
 }
 function verifyResume(secret, token, now = Date.now()) {
@@ -396,55 +578,428 @@ function verifyResume(secret, token, now = Date.now()) {
   const b = Buffer.from(expected, "utf8");
   if (a.length !== b.length || !timingSafeEqual(a, b)) return void 0;
   const parts = payload.split("|");
-  if (parts.length !== 4) return void 0;
-  const [clientId, roomId, encodedRole, expText] = parts;
+  if (parts.length !== 5) return void 0;
+  const [clientId, roomId, encodedRole, expText, iatText] = parts;
   const expMs = Number(expText);
   if (!Number.isFinite(expMs) || expMs <= now) return void 0;
+  const iatMs = Number(iatText);
+  if (!Number.isFinite(iatMs)) return void 0;
   let role;
   try {
     role = decodeURIComponent(encodedRole);
   } catch {
     return void 0;
   }
-  return { clientId, roomId, role, expMs };
+  return { clientId, roomId, role, expMs, iatMs };
 }
 
-// ../supervisor/src/codes.ts
-import { randomInt } from "crypto";
-var CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
-var ROOM_ID_RE = /^[A-Za-z0-9_-]{1,32}$/;
-var CODE_SHAPE_RE = /^[A-Za-z0-9]{4,5}$/;
-function pick(n) {
-  let out = "";
-  for (let i = 0; i < n; i++) out += CODE_ALPHABET[randomInt(CODE_ALPHABET.length)];
-  return out;
+// ../supervisor/src/bandwidth.ts
+var FREE_BANDWIDTH_CEILING_BPS = 25e6;
+var CARD_BANDWIDTH_CEILING_BPS = 1e8;
+var BANDWIDTH_WINDOW_MS = 1e4;
+var BUCKETS = 10;
+var BUCKET_MS = BANDWIDTH_WINDOW_MS / BUCKETS;
+function bandwidthCeilingBps(plan) {
+  return plan === "card" ? CARD_BANDWIDTH_CEILING_BPS : FREE_BANDWIDTH_CEILING_BPS;
 }
-function newRoomCode(taken) {
-  for (let len = 4; len <= 8; len++) {
-    for (let attempt = 0; attempt < 64; attempt++) {
-      const code = pick(len);
-      if (!taken(code)) return code;
+var BandwidthCeiling = class {
+  constructor(now = Date.now) {
+    this.now = now;
+  }
+  now;
+  buckets = new Float64Array(BUCKETS);
+  total = 0;
+  head = 0;
+  headAt = 0;
+  started = false;
+  ceiling = 0;
+  engagedNow = false;
+  /** Rooms already warned during the current engagement. Cleared when the ceiling disengages. */
+  warned = /* @__PURE__ */ new Set();
+  /**
+   * Sets the plan whose ceiling is enforced. `undefined` — a box control has never spoken to —
+   * disables enforcement, which is the documented failure direction.
+   */
+  setPlan(plan) {
+    this.ceiling = plan === void 0 ? 0 : bandwidthCeilingBps(plan);
+    if (this.ceiling === 0) this.disengage();
+  }
+  /** Counts bytes that left the box. Called from the same place the lease is spent. */
+  count(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0) return;
+    this.roll();
+    this.buckets[this.head] = (this.buckets[this.head] ?? 0) + bytes;
+    this.total += bytes;
+  }
+  /**
+   * Whether forwarding must stop right now.
+   *
+   * Reads the clock as well as the counters, so a project that stops sending recovers as the
+   * window empties rather than only when it next sends something.
+   */
+  get engaged() {
+    if (this.ceiling <= 0) return false;
+    this.roll();
+    const over = this.bitsPerSec > this.ceiling;
+    if (over && !this.engagedNow) this.engagedNow = true;
+    else if (!over && this.engagedNow) this.disengage();
+    return this.engagedNow;
+  }
+  /** The measured rate over the whole window, in bits per second. */
+  get bitsPerSec() {
+    this.roll();
+    return this.total * 8 / (BANDWIDTH_WINDOW_MS / 1e3);
+  }
+  /**
+   * Whether this room still owes a warning for the current engagement — true exactly once per room
+   * per engagement, so a developer learns why their messages vanished without the ceiling turning
+   * into a log flood at frame rate.
+   */
+  takeWarning(roomId) {
+    if (!this.engagedNow || this.warned.has(roomId)) return false;
+    this.warned.add(roomId);
+    return true;
+  }
+  state() {
+    return {
+      enforcing: this.ceiling > 0,
+      ceilingBps: this.ceiling,
+      bitsPerSec: this.bitsPerSec,
+      engaged: this.engaged
+    };
+  }
+  disengage() {
+    this.engagedNow = false;
+    this.warned.clear();
+  }
+  /** Advances the ring to now, zeroing the buckets that have aged out of the window. */
+  roll() {
+    const t = this.now();
+    if (!this.started) {
+      this.started = true;
+      this.headAt = t - t % BUCKET_MS;
+      return;
     }
+    let steps = Math.floor((t - this.headAt) / BUCKET_MS);
+    if (steps <= 0) return;
+    if (steps >= BUCKETS) {
+      this.buckets.fill(0);
+      this.total = 0;
+      this.head = 0;
+    } else {
+      while (steps-- > 0) {
+        this.head = (this.head + 1) % BUCKETS;
+        this.total -= this.buckets[this.head] ?? 0;
+        this.buckets[this.head] = 0;
+      }
+      if (this.total < 0) this.total = 0;
+    }
+    this.headAt = t - t % BUCKET_MS;
   }
-  throw new Error("newRoomCode: exhausted the room code space");
+};
+function bandwidthWarning(plan) {
+  const mbit = Math.round(bandwidthCeilingBps(plan) / 1e6);
+  return `sustained data-out is above this project's ${mbit} Mbit/s fair-use ceiling, so some messages are being dropped until the rate falls; ` + (plan === "free" ? "send less per tick, or add a card for the 100 Mbit/s ceiling" : "send less per tick, or ask support to raise the ceiling for this project");
 }
-function newClientId(taken) {
-  for (let attempt = 0; attempt < 128; attempt++) {
-    const id = `c${pick(10)}`;
-    if (!taken(id)) return id;
+
+// ../supervisor/src/bus.ts
+import {
+  BUS_ERRORS,
+  BUS_LIMITS,
+  BUS_MAILBOX_PREFIX,
+  BUS_OUTBOX,
+  BUS_OUTBOX_PREFIX,
+  busChannelProblem,
+  busPayloadProblem
+} from "@irtio/protocol";
+function newBusBucket() {
+  return new TokenBucket(BUS_LIMITS.opsBurst, BUS_LIMITS.opsPerSecond);
+}
+function mintMailboxName(counter) {
+  return `${BUS_MAILBOX_PREFIX}${Date.now().toString(36)}.${counter.toString(36)}`;
+}
+function encodeMailboxEntry(entry) {
+  return JSON.stringify(entry);
+}
+function decodeMailboxEntry(payload) {
+  if (payload === void 0) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return void 0;
   }
-  throw new Error("newClientId: could not allocate a unique client id");
+  const e = parsed;
+  if (!e || typeof e.from !== "string" || typeof e.payload !== "string") return void 0;
+  const attempts = typeof e.attempts === "number" && Number.isFinite(e.attempts) ? e.attempts : 0;
+  return { from: e.from, payload: e.payload, attempts };
 }
-function looksLikeRoomCode(id) {
-  if (!CODE_SHAPE_RE.test(id)) return false;
-  for (const ch of id.toUpperCase()) {
-    if (!CODE_ALPHABET.includes(ch)) return false;
+var BusRegistry = class {
+  channels = /* @__PURE__ */ new Map();
+  /** roomId -> the channels it is in, so dropping a room is one pass rather than a scan. */
+  byRoom = /* @__PURE__ */ new Map();
+  /**
+   * Adds `roomId` to `channel`. Returns a problem when the channel name is illegal or the room is
+   * already holding as many subscriptions as it may.
+   */
+  subscribe(roomId, channel) {
+    const problem = busChannelProblem(channel);
+    if (problem) return problem;
+    const mine = this.byRoom.get(roomId);
+    if (mine !== void 0 && !mine.has(channel) && mine.size >= BUS_LIMITS.subscriptionsPerRoom) {
+      return {
+        code: BUS_ERRORS.tooManySubscriptions,
+        message: `a room may subscribe to at most ${BUS_LIMITS.subscriptionsPerRoom} channels`
+      };
+    }
+    let subs = this.channels.get(channel);
+    if (!subs) this.channels.set(channel, subs = /* @__PURE__ */ new Set());
+    subs.add(roomId);
+    (mine ?? this.byRoom.set(roomId, /* @__PURE__ */ new Set()).get(roomId)).add(channel);
+    return void 0;
   }
-  return true;
+  unsubscribe(roomId, channel) {
+    const subs = this.channels.get(channel);
+    if (subs) {
+      subs.delete(roomId);
+      if (subs.size === 0) this.channels.delete(channel);
+    }
+    const mine = this.byRoom.get(roomId);
+    if (mine) {
+      mine.delete(channel);
+      if (mine.size === 0) this.byRoom.delete(roomId);
+    }
+  }
+  /**
+   * Drops every subscription this room holds. Called when a room is closed for good.
+   *
+   * Deliberately NOT called on hibernation. What makes "publish reaches awake subscribers only"
+   * true is the liveness check in the supervisor's fan-out, which posts to a subscriber only when
+   * it is `running` with a live worker; keeping the bookkeeping in step as well would mean
+   * chasing the eight separate places a worker can go away, and missing one of those would be a
+   * silent correctness bug rather than a leak. A hibernated room's stale entry costs a set member
+   * and is overwritten when its definition re-subscribes on the next wake.
+   */
+  unsubscribeAll(roomId) {
+    const mine = this.byRoom.get(roomId);
+    if (!mine) return;
+    for (const channel of mine) {
+      const subs = this.channels.get(channel);
+      if (!subs) continue;
+      subs.delete(roomId);
+      if (subs.size === 0) this.channels.delete(channel);
+    }
+    this.byRoom.delete(roomId);
+  }
+  /** Every room subscribed to `channel` except `exclude`, which is how a publisher is never told
+   *  its own message. Sorted, so a fan-out is deterministic and a test can assert an order. */
+  subscribers(channel, exclude) {
+    const subs = this.channels.get(channel);
+    if (!subs) return [];
+    return [...subs].filter((id) => id !== exclude).sort();
+  }
+  /** The channels `roomId` currently holds, for `/admin/rooms` and for tests. */
+  subscriptionsOf(roomId) {
+    return [...this.byRoom.get(roomId) ?? []].sort();
+  }
+};
+function mintOutboxName(counter) {
+  return `${BUS_OUTBOX_PREFIX}${Date.now().toString(36)}.${counter.toString(36)}`;
 }
-function normalizeRoomId(raw) {
-  if (!ROOM_ID_RE.test(raw)) return void 0;
-  return looksLikeRoomCode(raw) ? raw.toUpperCase() : raw;
+function encodeOutboxEntry(entry) {
+  return JSON.stringify(entry);
+}
+function decodeOutboxEntry(payload) {
+  if (payload === void 0) return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(payload);
+  } catch {
+    return void 0;
+  }
+  const e = parsed;
+  if (!e || typeof e.to !== "string" || typeof e.from !== "string" || typeof e.payload !== "string" || typeof e.id !== "string") {
+    return void 0;
+  }
+  return {
+    to: e.to,
+    from: e.from,
+    payload: e.payload,
+    id: e.id,
+    firstAt: typeof e.firstAt === "number" && Number.isFinite(e.firstAt) ? e.firstAt : Date.now(),
+    attempts: typeof e.attempts === "number" && Number.isFinite(e.attempts) ? e.attempts : 0
+  };
+}
+function outboxRetryDelayMs(attempts) {
+  return Math.min(BUS_OUTBOX.firstRetryMs * 2 ** Math.max(0, attempts), BUS_OUTBOX.maxRetryMs);
+}
+
+// ../supervisor/src/caps.ts
+function parseCapState(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const raw = value;
+  if (typeof raw.project !== "string" || raw.project === "") return void 0;
+  if (!Array.isArray(raw.meters)) return void 0;
+  const meters = [];
+  for (const entry of raw.meters) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const m = entry;
+    if (typeof m.meter !== "string" || m.meter === "") continue;
+    if (typeof m.used !== "number" || !Number.isFinite(m.used)) continue;
+    const limit = typeof m.limit === "number" && Number.isFinite(m.limit) ? m.limit : null;
+    const mode = m.mode === "hard" || m.mode === "soft" ? m.mode : "none";
+    const status = m.status === "crossed" || m.status === "warn" ? m.status : "under";
+    const lease = typeof m.lease === "number" && Number.isFinite(m.lease) && m.lease >= 0 ? Math.floor(m.lease) : void 0;
+    meters.push({
+      meter: m.meter,
+      used: m.used,
+      limit,
+      mode,
+      status,
+      ...lease !== void 0 ? { lease } : {}
+    });
+  }
+  return {
+    project: raw.project,
+    plan: raw.plan === "card" ? "card" : "free",
+    at: typeof raw.at === "number" && Number.isFinite(raw.at) ? raw.at : Date.now(),
+    periodStart: typeof raw.periodStart === "string" ? raw.periodStart : "",
+    meters
+  };
+}
+var CapGate = class {
+  state;
+  /** Replaces the cached state wholesale. Returns the state it stored, for the admin reply. */
+  apply(state) {
+    this.state = state;
+    return state;
+  }
+  /** What the box currently believes, for `/admin/caps` reads and for tests. */
+  current() {
+    return this.state;
+  }
+  /** The plan the box currently believes this project is on. `undefined` before the first push. */
+  plan() {
+    return this.state?.plan;
+  }
+  /** M5 part 3.5: the leased budget for a meter, or `undefined` when it is not leased. */
+  leaseFor(meter) {
+    return this.state?.meters.find((m) => m.meter === meter)?.lease;
+  }
+  /** How stale the cached state is, in ms, or `undefined` when there is none. */
+  ageMs(nowMs = Date.now()) {
+    return this.state === void 0 ? void 0 : nowMs - this.state.at;
+  }
+  /**
+   * The refusal for a meter whose cap is a crossed HARD cap, or `undefined` when the work may
+   * proceed.
+   *
+   * A `soft` crossing returns nothing. That is D48's card-on-file rule in one line: a soft cap
+   * alerts and keeps serving, and the alerting happens in control where the mailer is.
+   */
+  refusal(meter) {
+    const state = this.state;
+    if (state === void 0) return void 0;
+    const found = state.meters.find((m) => m.meter === meter);
+    if (!found || found.mode !== "hard" || found.status !== "crossed") return void 0;
+    return capRefusalMessage(meter, state.plan);
+  }
+};
+function capRefusalMessage(meter, plan) {
+  const what = meter === "egress_bytes" ? "data out" : meter === "room_hours" ? "room hours" : meter === "storage_bytes" ? "storage" : meter.replace(/_/g, " ");
+  const fix = plan === "free" ? "add a card in the billing page, or wait for the period to reset on the 1st" : "raise or remove the ceiling for this project in the billing page";
+  return `this project is at its ${what} cap for the current billing period; ${fix}`;
+}
+
+// ../supervisor/src/egress-lease.ts
+var EGRESS_LEASE_CHUNK_BYTES = 5 * 1024 * 1024 * 1024;
+var EgressLease = class {
+  remaining = 0;
+  spent = 0;
+  leasedEver = false;
+  period = "";
+  trippedNow = false;
+  /**
+   * Replaces the local budget with a freshly leased one.
+   *
+   * Wholesale, never additive, and that is the load-bearing choice: `remainingBytes` is computed
+   * by control from the project's allowance minus the usage it has actually received, so adding
+   * successive leases together would count the same allowance more than once. A new lease is a new
+   * statement of what is left, not a top-up.
+   *
+   * A lease of zero is a real lease and trips the wall. A lease for a different period untrips it,
+   * because the month rolled and the project's allowance came back.
+   */
+  apply(lease) {
+    const granted = Number.isFinite(lease.remainingBytes) ? Math.max(0, Math.floor(lease.remainingBytes)) : 0;
+    this.remaining = granted;
+    this.spent = 0;
+    this.period = lease.periodStart;
+    this.leasedEver = true;
+    this.trippedNow = granted <= 0;
+  }
+  /**
+   * Counts bytes that left the box, and returns `true` when this call is the one that trips the
+   * wall — so the caller can close sockets exactly once rather than on every subsequent frame.
+   */
+  spend(bytes) {
+    if (!this.leasedEver) return false;
+    if (!Number.isFinite(bytes) || bytes <= 0) return false;
+    this.spent += bytes;
+    this.remaining -= bytes;
+    if (this.remaining > 0 || this.trippedNow) return false;
+    this.trippedNow = true;
+    return true;
+  }
+  /** Whether forwarding must stop. False on a box that has never been leased anything. */
+  get tripped() {
+    return this.leasedEver && this.trippedNow;
+  }
+  /** Whether control has ever leased this box anything. */
+  get leased() {
+    return this.leasedEver;
+  }
+  state() {
+    return {
+      leased: this.leasedEver,
+      remainingBytes: Math.max(0, this.remaining),
+      spentBytes: this.spent,
+      tripped: this.tripped,
+      periodStart: this.period
+    };
+  }
+};
+function egressWallMessage(plan) {
+  const fix = plan === "free" ? "add a card in the billing page, or wait for the period to reset on the 1st" : "raise the monthly overage spend cap for this project in the billing page";
+  return `this project has used its data-out allowance for the current billing period, so ${plan === "free" ? "forwarding has stopped" : "forwarding has stopped at the spend cap"}; ${fix}`;
+}
+
+// ../supervisor/src/heap-caps.ts
+import {
+  DEFAULT_MEMORY_MB,
+  NATIVE_RESERVE_FRACTION as PROTOCOL_NATIVE_RESERVE_FRACTION,
+  SUPERVISOR_BASELINE_MIB as PROTOCOL_SUPERVISOR_BASELINE_MIB,
+  YOUNG_GEN_MB,
+  declarationsFit,
+  vmSizeFor
+} from "@irtio/protocol";
+var SUPERVISOR_BASELINE_MIB = PROTOCOL_SUPERVISOR_BASELINE_MIB;
+var HEAP_WARN_FRACTION = 0.8;
+function checkDeclaredFit(vmMemMib, declared, baselineMib = SUPERVISOR_BASELINE_MIB) {
+  const types = declared.map((d) => ({
+    type: d.type,
+    ...d.memoryMb !== void 0 ? { memoryMb: d.memoryMb } : {},
+    ...d.maxAwake !== void 0 ? { maxAwake: d.maxAwake } : {},
+    ...d.physics === true ? { physics: true } : {}
+  }));
+  const verdict = declarationsFit(vmMemMib, types, { baselineMib });
+  return {
+    fits: verdict.fits,
+    requiredMib: verdict.required.vmMib,
+    budgetMib: vmMemMib,
+    undeclared: declared.filter((d) => d.memoryMb === void 0).map((d) => d.type),
+    detail: `${verdict.required.detail}, against a ${vmMemMib} MiB VM`
+  };
 }
 
 // ../supervisor/src/relay.ts
@@ -550,6 +1105,15 @@ var RelayRoom = class _RelayRoom {
     return this.snapshot();
   }
 };
+function isRelayPresenceSnapshot(bytes) {
+  if (!bytes || bytes.length === 0) return false;
+  try {
+    decodeSnapshot(relaySchema, bytes);
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 // ../supervisor/src/hibernate.ts
 function hibernateRoom(sup, room) {
@@ -627,9 +1191,9 @@ async function afterSleep(sup, room) {
   sup.dropRoomIfIdle(room);
 }
 async function wakeRoom(sup, room) {
-  if (room.state === "waking" || room.state === "starting" || room.state === "hibernating") {
-    await room.transition;
-    return;
+  while (room.state === "waking" || room.state === "starting" || room.state === "hibernating") {
+    await room.transition.catch(() => {
+    });
   }
   if (room.state !== "hibernated") return;
   room.state = "waking";
@@ -693,7 +1257,7 @@ async function migrateRoom(sup, room, toVersion) {
   const oldKey = sup.storeKey(room);
   let chain;
   try {
-    chain = sup.migrationChain(fromVersion, toVersion);
+    chain = sup.migrationChain(fromVersion, toVersion, room.roomType);
   } catch (err) {
     return failed(err instanceof Error ? err.message : String(err));
   }
@@ -769,7 +1333,7 @@ async function migrateRoom(sup, room, toVersion) {
       outcome = failed(`migration to v${toVersion} failed; room restarted on v${fromVersion}`);
       return;
     }
-    sup.failOutdatedSessions(room, toVersion);
+    const swapped = sup.failOutdatedSessions(room, toVersion, fromVersion);
     await sup.rejoinAll(room);
     for (const clientId of room.pendingLeaves) {
       room.worker?.post({ t: "leave", clientId, reason: "timeout" });
@@ -782,7 +1346,11 @@ async function migrateRoom(sup, room, toVersion) {
     const ms = performance.now() - startedAt;
     room.metrics.lastWakeMs = ms;
     if (ms > room.metrics.maxWakeMs) room.metrics.maxWakeMs = ms;
-    sup.roomLog(room, "info", `migrated v${fromVersion} \u2192 v${toVersion}, gap ${ms.toFixed(1)} ms`);
+    sup.roomLog(
+      room,
+      "info",
+      `migrated v${fromVersion} \u2192 v${toVersion}, gap ${ms.toFixed(1)} ms` + (swapped > 0 ? `, ${swapped} client(s) kept their socket and swapped schema` : "")
+    );
     outcome = { roomId: room.id, outcome: "migrated" };
   })();
   room.transition = work.catch((err) => {
@@ -864,7 +1432,8 @@ function newRoomMetrics() {
     lastWakeMs: 0,
     maxWakeMs: 0,
     workerElu: 0,
-    droppedFramesOnRestart: 0
+    droppedFramesOnRestart: 0,
+    npcConnections: 0
   };
 }
 function emptyRoomsByState() {
@@ -888,15 +1457,222 @@ var LogRing = class {
   }
 };
 
+// ../supervisor/src/npc/loopback.ts
+var CONNECTING = 0;
+var OPEN = 1;
+var CLOSING = 2;
+var CLOSED = 3;
+var LoopbackServerSocket = class {
+  CONNECTING = CONNECTING;
+  OPEN = OPEN;
+  CLOSING = CLOSING;
+  CLOSED = CLOSED;
+  readyState = OPEN;
+  /** Always 0: there is no kernel buffer, so an NPC is never a slow consumer. */
+  bufferedAmount = 0;
+  listeners = /* @__PURE__ */ new Map();
+  peer;
+  on(event, listener) {
+    let set = this.listeners.get(event);
+    if (!set) this.listeners.set(event, set = /* @__PURE__ */ new Set());
+    set.add(listener);
+    return this;
+  }
+  once(event, listener) {
+    const wrapper = (...args) => {
+      this.off(event, wrapper);
+      listener(...args);
+    };
+    return this.on(event, wrapper);
+  }
+  off(event, listener) {
+    this.listeners.get(event)?.delete(listener);
+    return this;
+  }
+  emit(event, ...args) {
+    for (const listener of [...this.listeners.get(event) ?? []]) listener(...args);
+  }
+  send(bytes) {
+    if (this.readyState !== OPEN) return;
+    const peer = this.peer;
+    const copy = bytes.slice();
+    setImmediate(() => peer?.onmessage?.(copy));
+  }
+  /** The supervisor pings every session; a loopback peer answers at once so it never times out. */
+  ping() {
+    setImmediate(() => this.emit("pong"));
+  }
+  close(code = 1e3, reason = "") {
+    if (this.readyState === CLOSED || this.readyState === CLOSING) return;
+    this.readyState = CLOSING;
+    const peer = this.peer;
+    setImmediate(() => {
+      this.readyState = CLOSED;
+      peer?.onclose?.({ code, reason });
+      this.emit("close", code, reason);
+    });
+  }
+  terminate() {
+    if (this.readyState === CLOSED) return;
+    this.readyState = CLOSED;
+    const peer = this.peer;
+    setImmediate(() => {
+      peer?.onclose?.({ code: 1006, reason: "terminated" });
+      this.emit("close", 1006, "terminated");
+    });
+  }
+};
+var ClientHalf = class {
+  constructor(server) {
+    this.server = server;
+  }
+  server;
+  onopen = null;
+  onmessage = null;
+  onclose = null;
+  onerror = null;
+  open = true;
+  send(bytes) {
+    if (!this.open || this.server.readyState !== OPEN) return;
+    const copy = bytes.slice();
+    setImmediate(() => this.server.emit("message", copy));
+  }
+  close() {
+    if (!this.open) return;
+    this.open = false;
+    const server = this.server;
+    setImmediate(() => {
+      if (server.readyState === CLOSED) return;
+      server.readyState = CLOSED;
+      server.emit("close", 1e3, "npc closed");
+      this.onclose?.({ code: 1e3 });
+    });
+  }
+};
+function loopbackPair() {
+  const server = new LoopbackServerSocket();
+  const client = new ClientHalf(server);
+  server.peer = client;
+  setImmediate(() => client.onopen?.());
+  return { server, client };
+}
+
+// ../supervisor/src/npc/runtime.ts
+var NPC_TRACE_LIMIT = 16;
+var NPC_JOIN_TIMEOUT_MS = 1e4;
+var NpcManager = class {
+  constructor(host) {
+    this.host = host;
+  }
+  host;
+  live = /* @__PURE__ */ new Map();
+  /** NPC sessions this manager believes are live in a room. Diagnostics and metrics. */
+  countIn(roomId) {
+    let n = 0;
+    for (const entry of this.live.values()) {
+      if (entry.roomId === roomId) n++;
+    }
+    return n;
+  }
+  has(clientId) {
+    return this.live.has(clientId);
+  }
+  spawn(roomId, definition, clientId, config) {
+    if (this.live.has(clientId)) {
+      this.host.log(roomId, "warn", `irtio: npc ${clientId} is already running; spawn ignored`);
+      return;
+    }
+    const npcs = definition.config.npcs;
+    const script = npcs?.[config.brain.script];
+    if (!script) {
+      this.host.log(
+        roomId,
+        "error",
+        `irtio: npc script ${JSON.stringify(config.brain.script)} is not in this deployment's npcs map`
+      );
+      return;
+    }
+    const entry = { roomId, clientId, runner: void 0, stopped: false };
+    this.live.set(clientId, entry);
+    const name = config.name ?? config.brain.script;
+    void import("@irtio/bots").then(
+      async ({ spawnBots }) => spawnBots(1, {
+        schema: definition.schema,
+        room: roomId,
+        url: "loopback:npc",
+        key: this.host.projectId,
+        name,
+        ...config.role !== void 0 ? { role: config.role } : {},
+        ...config.seed !== void 0 ? { seed: config.seed } : {},
+        traceLimit: NPC_TRACE_LIMIT,
+        joinTimeoutMs: NPC_JOIN_TIMEOUT_MS,
+        transport: {
+          connect: () => this.host.openLoopback(roomId, clientId)
+        },
+        script: (bot) => script(bot)
+      })
+    ).then(
+      (runner) => {
+        entry.runner = runner;
+        if (entry.stopped) void this.stopRunner(entry);
+      },
+      (err) => {
+        this.live.delete(clientId);
+        this.host.log(
+          roomId,
+          "error",
+          `irtio: npc ${JSON.stringify(name)} did not join: ${errorText(err)}`
+        );
+      }
+    );
+  }
+  despawn(clientId) {
+    const entry = this.live.get(clientId);
+    if (!entry) return;
+    this.live.delete(clientId);
+    entry.stopped = true;
+    if (entry.runner) void this.stopRunner(entry);
+  }
+  /** Every NPC in a room: the room hibernated, closed, restarted, or the tenant is shutting down. */
+  despawnRoom(roomId) {
+    for (const entry of [...this.live.values()]) {
+      if (entry.roomId === roomId) this.despawn(entry.clientId);
+    }
+  }
+  despawnAll() {
+    for (const entry of [...this.live.values()]) this.despawn(entry.clientId);
+  }
+  async stopRunner(entry) {
+    const runner = entry.runner;
+    entry.runner = void 0;
+    if (!runner) return;
+    try {
+      await runner.stop();
+    } catch (err) {
+      this.host.log(entry.roomId, "warn", `irtio: npc ${entry.clientId} stop: ${errorText(err)}`);
+    }
+  }
+};
+function errorText(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
 // ../supervisor/src/rooms.ts
+import {
+  DEFAULT_ROOM_TYPE as DEFAULT_ROOM_TYPE2,
+  parseRoomId as parseRoomId2,
+  roomClassFor,
+  roomHoursSourceFor
+} from "@irtio/protocol";
 var WAKE_QUEUE_CAP = 256;
-function relayConfig(limits) {
+var SEEN_PLAYERS_CAP = 512;
+function relayConfig(limits, plan) {
   return {
     mode: "event",
     tickRate: 0,
     idleMs: limits.relayIdleMs,
     reconnectGraceMs: limits.relayReconnectGraceMs,
-    maxClients: limits.relayMaxClients
+    maxClients: plan === "free" ? limits.relayMaxClientsFree : limits.relayMaxClients
   };
 }
 var RoomRecord = class {
@@ -913,6 +1689,14 @@ var RoomRecord = class {
   relayRoom;
   lastTick = 0;
   metrics = newRoomMetrics();
+  /**
+   * D65: the room's bandwidth ledger as of the last `stats` round trip, when this supervisor was
+   * started with profiling on. Deliberately *beside* `metrics` and not in it: the host agent
+   * flattens every numeric field of `RoomMetrics` into a rollup row per poll, and a ledger is
+   * tens of rows that change names with the schema. It is a local development surface, not fleet
+   * telemetry. `undefined` means nobody is profiling, never "no bytes".
+   */
+  profile;
   logs = new LogRing();
   createdAt = Date.now();
   /** Frames that arrived while hibernating/waking, replayed in order after the re-joins. */
@@ -921,8 +1705,39 @@ var RoomRecord = class {
   droppedWakeFrames = 0;
   /** Sessions whose grace expired while the room had no worker; `leave` is sent on the next wake. */
   pendingLeaves = /* @__PURE__ */ new Set();
+  /**
+   * Bug #49: client ids the worker sent a frame for that this room has no session under, each
+   * logged once. Cleared with the room; a room that keeps naming unknown clients is one warning
+   * per id, not one per frame.
+   */
+  unknownSendWarned = /* @__PURE__ */ new Set();
   /** Timestamps of worker restarts, pruned to the last minute (plan §3.3 cap). */
   restarts = [];
+  /**
+   * D55: whether the "heap near its cap" warning has already been logged for the current
+   * crossing. Edge-triggered rather than level-triggered, so a room sitting above the line warns
+   * once instead of on every metrics poll; cleared when it drops back under.
+   */
+  heapWarned = false;
+  /**
+   * D63-e: the live half of the backfill flag, as `room.backfill.set` has left it.
+   *
+   * On the record rather than in the worker so it is not in the hibernation blob (the blob format
+   * does not move for this), and **reset to the declaration whenever a worker reports ready** —
+   * a fresh start and a wake alike.
+   *
+   * The reset is the deliberate part, and the alternative was considered. Carrying the value
+   * across a wake would make the supervisor's copy and the room's own `room.backfill.open` say
+   * different things the moment the worker restarted, because the worker's mirror is seeded from
+   * the declaration and nothing pushes the old value back into it. Resetting keeps the two
+   * honest. What it costs is nothing real: a room hibernates because it went idle, and a versus
+   * room in the middle of a round is not idle, so the only rooms this reopens are rooms with
+   * nobody in them.
+   *
+   * Starts `true` so a room that declared `backfill: true` and never touches the toggle is open,
+   * which is the arena case and the common one.
+   */
+  backfillOpen = true;
   /**
    * The deployment version this room was created under. New rooms take the newest; rooms created
    * before a deploy keep theirs until they idle (per-room drain, plan §3.3).
@@ -934,17 +1749,98 @@ var RoomRecord = class {
    * ever serialized into the hibernation blob.
    */
   alarms = new AlarmSet();
+  /**
+   * D67-e: ids of cross-shard bus messages delivered to this room, newest last, bounded by the
+   * supervisor. A message that arrives twice (a lost acknowledgement) is delivered twice, as
+   * at-least-once promises, and its duplicate is logged by name from this set.
+   */
+  busSeen = /* @__PURE__ */ new Set();
+  /**
+   * D59: this room's bus budget.
+   *
+   * On the record rather than in a map keyed by room id, so it lives and dies with the room and
+   * cannot be a leak or a stale entry. This is the per-room rate-limit machinery D59 asks for and
+   * that the supervisor did not have: every limiter before it (`ipBuckets`, `helloBuckets`, the
+   * per-session frame buckets) is scoped to a connection, an IP or a project key, and none of them
+   * metered what a *room* asked the host to do.
+   *
+   * It survives hibernation for the same reason the alarm set does: the record does. A room cannot
+   * reset its budget by sleeping.
+   */
+  busBucket = newBusBucket();
+  /**
+   * D63: every player id this room has held since it was created, newest last.
+   *
+   * `roomHoldsPlayer` is not enough for a rating report and the difference is the whole point: by
+   * the time a room decides who won, the loser has very often already closed the tab. A report
+   * that could only name players still connected would be a report no versus game could make. So
+   * membership for ratings is "has this room ever held you", recorded here at join.
+   *
+   * On the record, not on the worker, so it survives a hibernation the same way the alarm set
+   * does — a room that slept between the last round and the report must still be able to make it.
+   * It is deliberately NOT serialized into the hibernation blob: a room whose tenant restarts
+   * loses it, which costs a report and is the conservative direction to fail in.
+   *
+   * Bounded at `SEEN_PLAYERS_CAP`, oldest evicted first. An arena that has held ten thousand
+   * players over a week must not carry ten thousand strings for the life of the process, and a
+   * room reporting on a player who left five hundred players ago is not a match result.
+   */
+  seenPlayers = /* @__PURE__ */ new Set();
   /**
    * D24: a save generation to start this room from instead of its live snapshot, set from the
    * placement instruction and consumed by the next start. One shot: a restore is an event, not a
    * standing property of the room.
    */
   pendingRestoreSaveId;
+  /**
+   * D47: when this room's alive-time was last banked into the usage ledger, or `undefined` while
+   * the room is not chargeable (hibernated/closed). Owned by `sampleRoomClocks`; deliberately
+   * separate from `createdAt`, which counts wall time a hibernated room keeps accruing.
+   */
+  usageSince;
   /** Serialises room-level async work (start / wake / restart / hibernate). */
   transition = Promise.resolve();
   /** Periodic crash-safety snapshot (event-mode bundle rooms) or the relay idle timer. */
   timer;
   config;
+  /**
+   * D58: the room type this room runs, parsed once from its id. `DEFAULT_ROOM_TYPE` for a plain
+   * id, which is every id a project had before named room types.
+   *
+   * Parsed here and nowhere else downstream. Shard note 2: outside the definition lookup and the
+   * limits derivation, everything keys on the whole opaque roomId, so this getter is the only
+   * place the split leaks into the room's own lifetime.
+   */
+  get roomType() {
+    return parseRoomId2(this.id)?.type ?? DEFAULT_ROOM_TYPE2;
+  }
+  /** D47: the engine dimension room-hours rows carry; `''` for a room with no physics. */
+  get engine() {
+    return this.config.engine ?? "";
+  }
+  /**
+   * D60: the size class this room is billed as, derived from its declared `memoryMb`.
+   *
+   * Derived rather than stored, and derived from the same number that drives the worker's heap
+   * cap, so the bill and the enforcement cannot disagree about a room. A relay room is not a
+   * class: it is served by a different thing entirely and carries its own source.
+   */
+  get sizeClass() {
+    return roomClassFor(this.config.memoryMb);
+  }
+  /**
+   * D60: the room-hours `source` this room's hours are reported under. `room` for Small.
+   *
+   * **A relay room served by this supervisor reports `room`, not `relay`, deliberately.** The
+   * $0.001 relay rate is honest cost accounting for a room served by the shared relay host: no RAM
+   * reservation, no VM slot, just sockets and a presence map. A relay room running inside a tenant
+   * VM has all of those costs — it is a supervisor in a Firecracker guest doing the work — and
+   * billing it at the shared-host rate would price the discount before earning it. The `relay`
+   * source is reserved for the process that actually deserves it. See the part 3 report.
+   */
+  get usageSource() {
+    return roomHoursSourceFor(this.sizeClass);
+  }
   /** Sessions with a live socket that have completed their join. */
   connected() {
     return [...this.clients.values()].filter((s) => s.state === "joined" && s.open);
@@ -963,6 +1859,31 @@ var RoomRecord = class {
   log(level, ...args) {
     this.logs.push(level, args);
   }
+  /** D63: remember that this room held `playerId`. Re-seeing one moves it to the newest slot. */
+  notePlayerSeen(playerId) {
+    this.seenPlayers.delete(playerId);
+    this.seenPlayers.add(playerId);
+    while (this.seenPlayers.size > SEEN_PLAYERS_CAP) {
+      const oldest = this.seenPlayers.values().next().value;
+      if (oldest === void 0) break;
+      this.seenPlayers.delete(oldest);
+    }
+  }
+  /** D63: has this room ever held `playerId`? The rating report's membership check. */
+  hasHeldPlayer(playerId) {
+    return this.seenPlayers.has(playerId);
+  }
+  /**
+   * D63-e: is this room accepting backfill right now?
+   *
+   * The declaration is the ceiling and `backfillOpen` is the live value, so a room that declared
+   * nothing answers false however it toggled. Reported on the room list; never enforced at join —
+   * `maxClients` is what refuses a join, and a lost race for the last seat is a normal outcome
+   * the client retries.
+   */
+  get backfillNow() {
+    return this.config.backfill === true && this.backfillOpen;
+  }
   info() {
     const dueAlarmAt = this.alarms.earliestDueAt;
     return {
@@ -974,7 +1895,13 @@ var RoomRecord = class {
       metrics: { ...this.metrics, workerElu: this.worker?.elu ?? 0 },
       createdAt: this.createdAt,
       ...dueAlarmAt !== void 0 ? { dueAlarmAt } : {},
-      ...this.alarms.size > 0 ? { alarms: this.alarms.size } : {}
+      ...this.alarms.size > 0 ? { alarms: this.alarms.size } : {},
+      ...this.profile !== void 0 ? { profile: this.profile } : {},
+      // D63-d/e. `maxClients` is always reported (it is always known); `backfill` is reported
+      // only when the room type declared it, so "absent" and "not a candidate" stay the same
+      // thing all the way to control's nullable column.
+      maxClients: this.config.maxClients,
+      ...this.config.backfill === true ? { backfill: this.backfillNow } : {}
     };
   }
 };
@@ -1000,15 +1927,52 @@ var RoomRegistry = class {
   }
 };
 
+// ../supervisor/src/schema-swap.ts
+import { diffSchemas, schemaFromCanonical } from "@irtio/schema";
+var verdicts = /* @__PURE__ */ new Map();
+var MAX_MEMO = 64;
+function isAdditiveMigration(fromJson, toJson) {
+  if (fromJson === toJson) return true;
+  const key = `${fromJson.length}|${fromJson}${toJson}`;
+  const cached = verdicts.get(key);
+  if (cached !== void 0) return cached;
+  let verdict = false;
+  try {
+    const oldSchema = schemaFromCanonical(fromJson);
+    const newSchema = schemaFromCanonical(toJson);
+    const changes = diffSchemas(oldSchema, newSchema);
+    verdict = changes.every((c) => c.kind === "additive") && !touchesPhysicsCollection(oldSchema, newSchema);
+  } catch {
+    verdict = false;
+  }
+  if (verdicts.size >= MAX_MEMO) verdicts.clear();
+  verdicts.set(key, verdict);
+  return verdict;
+}
+function touchesPhysicsCollection(oldSchema, newSchema) {
+  const physicsNames = /* @__PURE__ */ new Set();
+  for (const c of oldSchema.collections) if (c.physics !== void 0) physicsNames.add(c.name);
+  for (const c of newSchema.collections) if (c.physics !== void 0) physicsNames.add(c.name);
+  if (physicsNames.size === 0) return false;
+  for (const name of physicsNames) {
+    const before = oldSchema.collections.find((c) => c.name === name);
+    const after = newSchema.collections.find((c) => c.name === name);
+    if (!before || !after) return true;
+    if (JSON.stringify(before) !== JSON.stringify(after)) return true;
+  }
+  return false;
+}
+
 // ../supervisor/src/session.ts
 import {
-  ErrorCode,
-  FrameType,
+  ErrorCode as ErrorCode2,
+  FrameType as FrameType2,
   encodeErrorPayload,
-  encodeFrame
+  encodeFrame as encodeFrame2
 } from "@irtio/protocol";
 var CLOSE_POLICY = 1008;
 var CLOSE_GRACE_MS = 250;
+var HELD_FRAMES_MAX = 16;
 var Session = class {
   constructor(ws, remoteAddress, origin, framesPerSec, maxBufferedBytes, onSlowConsumer) {
     this.ws = ws;
@@ -1024,6 +1988,16 @@ var Session = class {
   maxBufferedBytes;
   onSlowConsumer;
   state = "awaiting-hello";
+  /**
+   * Bug #49: frames the worker sent this session while it was still `'joining'`. The room's
+   * `onJoin` runs inside `RoomCore.join`, so a `room.call(ctx.clientId)` made there reaches the
+   * supervisor before the join outcome does, and the client accepts nothing before its `WELCOME`.
+   * Held here, sent in order right after the welcome (`joinBundle`), discarded when the join is
+   * rejected or the socket closes first. Capped at `HELD_FRAMES_MAX`; `droppedHeld` counts the
+   * overflow so the first drop can be logged once.
+   */
+  pendingOut = [];
+  droppedHeld = 0;
   clientId = "";
   roomId = "";
   /** Set once the HELLO resolved a room. */
@@ -1038,6 +2012,24 @@ var Session = class {
    *  session whose schema is older than the room's new version by name (`E_SCHEMA_MISMATCH`)
    *  rather than send it a resync WELCOME it cannot decode. */
   schemaHash8;
+  /**
+   * D50: this client set `HELLO_SCHEMA_SWAP_BIT`, so it can rebuild its codec from a `SCHEMA`
+   * frame and an additive migrate may swap it in place instead of closing it. Load-bearing in
+   * the negative direction too: `decodeFrame` throws on an unknown type, so a session without
+   * this flag must never be sent frame 13.
+   */
+  schemaSwap = false;
+  /**
+   * D44: this session is a scripted NPC on a loopback socket. It skips the per-IP bucket and the
+   * origin check on the way in (there is no address and no page), is tagged in metrics and in
+   * `SessionInfo`, and is otherwise the ordinary session it looks like.
+   */
+  npc = false;
+  /**
+   * D44: the client id the room already minted for this NPC, so `room.spawnNPC` could hand a
+   * handle back synchronously. Absent for every dialled session, which mints its own.
+   */
+  forcedClientId;
   /** Set when the session was rejected/kicked: no grace window on close. */
   fatal = false;
   /** Slow consumers are closed but keep their grace window (a resume gets a fresh snapshot). */
@@ -1054,6 +2046,14 @@ var Session = class {
   get open() {
     return this.ws.readyState === this.ws.OPEN;
   }
+  /**
+   * D47: the ONE place billable egress is counted. It is here rather than beside the five
+   * `room.metrics.egressBytes += sent` call sites for two reasons the anti-lying tests pin: a
+   * sixth copy of a five-place pattern is a sixth place to forget, and the five call sites are
+   * *observability* — they count NPC loopback bytes, which never leave the box and must never be
+   * billed. Set by the server for every session; the NPC exclusion is below, not in the callback.
+   */
+  onEgress;
   /**
    * Sends one already-framed message. Returns the byte count sent (0 when dropped). A client whose
    * `bufferedAmount` is over the limit is closed with `E_SLOW_CONSUMER` — that's exactly what
@@ -1066,15 +2066,16 @@ var Session = class {
       return 0;
     }
     this.ws.send(bytes, { binary: true });
+    if (!this.npc) this.onEgress?.(bytes.length);
     return bytes.length;
   }
   sendFrame(type, payload) {
-    return this.send(encodeFrame(type, payload));
+    return this.send(encodeFrame2(type, payload));
   }
   sendError(code, message, fatal) {
     this.sendFrame(
-      FrameType.ERROR,
-      encodeErrorPayload({ code: ErrorCode[code].code, message, fatal })
+      FrameType2.ERROR,
+      encodeErrorPayload({ code: ErrorCode2[code].code, message, fatal })
     );
   }
   /** ERROR + close (1008). Fatal rejections skip the grace window on the following `close` event. */
@@ -1083,6 +2084,19 @@ var Session = class {
     this.sendError(code, message, true);
     this.closeSocket(CLOSE_POLICY, code);
   }
+  /**
+   * M5 part 3.5 (Part C): `fail`, but with a chosen WebSocket close code.
+   *
+   * It exists for exactly one caller, the egress wall, and the reason is that the close code is
+   * the only part of a refusal a browser is guaranteed to see. An ERROR frame can lose the race
+   * with the close; `event.code` cannot. Everything else about a fatal rejection is unchanged, so
+   * a wall close still skips the reconnect grace the way a policy close does.
+   */
+  failWith(code, message, closeCode) {
+    this.fatal = true;
+    this.sendError(code, message, true);
+    this.closeSocket(closeCode, code);
+  }
   closeSocket(code = CLOSE_POLICY, reason = "") {
     this.clearHelloTimer();
     if (this.ws.readyState === this.ws.CLOSED) return;
@@ -1118,11 +2132,99 @@ var Session = class {
       name: this.name,
       state: this.state,
       remoteAddress: this.remoteAddress,
-      origin: this.origin
+      origin: this.origin,
+      npc: this.npc
     };
   }
 };
 
+// ../supervisor/src/usage.ts
+var USAGE_WINDOW_MS = 60 * 60 * 1e3;
+var CLOSED_WINDOW_GRACE_MS = 15 * 60 * 1e3;
+var ROOM_SAMPLE_MS = 1e3;
+function windowStartOf(nowMs) {
+  return Math.floor(nowMs / USAGE_WINDOW_MS) * USAGE_WINDOW_MS;
+}
+function keyOf(meter, windowStart, source, engine) {
+  return `${meter}\0${windowStart}\0${source}\0${engine}`;
+}
+var UsageAccumulator = class {
+  cells = /* @__PURE__ */ new Map();
+  cell(meter, source, engine, nowMs) {
+    const windowStart = windowStartOf(nowMs);
+    const key = keyOf(meter, windowStart, source, engine);
+    let cell = this.cells.get(key);
+    if (cell === void 0) {
+      cell = { meter, windowStart, source, engine, value: 0 };
+      this.cells.set(key, cell);
+    }
+    return cell;
+  }
+  /** Bytes that actually left the box on a real socket. NPC loopback bytes never reach here. */
+  addEgressBytes(bytes, nowMs = Date.now()) {
+    if (!Number.isFinite(bytes) || bytes <= 0) return;
+    this.cell("egress_bytes", "room", "", nowMs).value += bytes;
+  }
+  /**
+   * Worker-alive milliseconds for one room, reported as fractional hours. `engine` is the room's
+   * physics engine or `''` — a reported dimension, not a multiplier.
+   */
+  addRoomMs(ms, engine, nowMs = Date.now(), source = "room") {
+    if (!Number.isFinite(ms) || ms <= 0) return;
+    this.cell("room_hours", source, engine, nowMs).value += ms / (60 * 60 * 1e3);
+  }
+  /**
+   * Every window still worth reporting: the current one plus any closed window inside the grace.
+   * Closed windows past the grace are dropped here, so the ledger is bounded without a timer.
+   */
+  windows(nowMs = Date.now()) {
+    const current = windowStartOf(nowMs);
+    const out = [];
+    for (const [key, cell] of this.cells) {
+      if (cell.windowStart < current && nowMs - (cell.windowStart + USAGE_WINDOW_MS) > CLOSED_WINDOW_GRACE_MS) {
+        this.cells.delete(key);
+        continue;
+      }
+      out.push({
+        meter: cell.meter,
+        windowStart: cell.windowStart,
+        source: cell.source,
+        engine: cell.engine,
+        value: cell.value
+      });
+    }
+    out.sort(
+      (a, b) => a.windowStart - b.windowStart || a.meter.localeCompare(b.meter) || a.source.localeCompare(b.source) || a.engine.localeCompare(b.engine)
+    );
+    return out;
+  }
+  /** Test/diagnostic read of one running total. */
+  valueOf(meter, nowMs = Date.now(), source = "room", engine = "") {
+    return this.cells.get(keyOf(meter, windowStartOf(nowMs), source, engine))?.value ?? 0;
+  }
+};
+function chargeableRoomState(state) {
+  return state === "starting" || state === "running" || state === "waking";
+}
+function sampleRoomClocks(rooms, usage, nowMs) {
+  for (const room of rooms) {
+    const chargeable = chargeableRoomState(room.state);
+    if (!chargeable) {
+      if (room.usageSince !== void 0) {
+        usage.addRoomMs(nowMs - room.usageSince, room.engine, nowMs, room.usageSource);
+        room.usageSince = void 0;
+      }
+      continue;
+    }
+    if (room.usageSince === void 0) {
+      room.usageSince = nowMs;
+      continue;
+    }
+    usage.addRoomMs(nowMs - room.usageSince, room.engine, nowMs, room.usageSource);
+    room.usageSince = nowMs;
+  }
+}
+
 // ../supervisor/src/worker-host.ts
 import { pathToFileURL } from "url";
 import { Worker } from "worker_threads";
@@ -1180,7 +2282,7 @@ var WorkerHost = class {
     }
   }
   onMessage(msg) {
-    if ((msg.t === "serialized" || msg.t === "inspected") && this.pending.has(msg.reqId)) {
+    if ((msg.t === "serialized" || msg.t === "inspected" || msg.t === "stats" || msg.t === "recording" || msg.t === "timeline") && msg.reqId !== void 0 && this.pending.has(msg.reqId)) {
       const resolve2 = this.pending.get(msg.reqId);
       this.pending.delete(msg.reqId);
       resolve2?.(msg);
@@ -1251,6 +2353,49 @@ var WorkerHost = class {
     );
     return msg?.t === "inspected" ? msg : void 0;
   }
+  /** D41: arm the room's authoritative timeline recorder. `false` when the worker did not answer. */
+  async startTimeline(options = {}, timeoutMs = 5e3) {
+    const msg = await this.request(
+      (reqId) => ({
+        t: "record",
+        reqId,
+        ...options.maxTicks !== void 0 ? { maxTicks: options.maxTicks } : {},
+        ...options.maxRecords !== void 0 ? { maxRecords: options.maxRecords } : {}
+      }),
+      timeoutMs
+    );
+    return msg?.t === "recording" && msg.ok;
+  }
+  /** D41: the recorded timeline. `undefined` when unarmed, or when the worker did not answer. */
+  async timeline(timeoutMs = 1e4) {
+    const msg = await this.request(
+      (reqId) => ({ t: "timeline", reqId }),
+      timeoutMs
+    );
+    return msg?.t === "timeline" ? msg.dump : void 0;
+  }
+  /**
+   * D36: the room's own tick counters — `overruns` and `maxTickMs` above all. `undefined` when
+   * the worker died or did not answer in time, and the caller must report that as *unavailable*
+   * rather than as zero: a room shedding ticks and a room nobody asked look identical otherwise,
+   * and that is exactly the lie the `tick-health` invariant exists to prevent.
+   */
+  async stats(timeoutMs = 2e3) {
+    return (await this.statsMessage(timeoutMs))?.stats;
+  }
+  /**
+   * The whole `stats` reply, including D55's `heap` ride-along. `stats()` above is the D36 shape
+   * and stays as it was; this is the one callers use when they also want the worker's heap, which
+   * is a fact about the thread rather than one of the room's own counters. Same round trip: the
+   * heap number costs no extra message.
+   */
+  async statsMessage(timeoutMs = 2e3) {
+    const msg = await this.request(
+      (reqId) => ({ t: "stats", reqId }),
+      timeoutMs
+    );
+    return msg?.t === "stats" ? msg : void 0;
+  }
   /** Intentional shutdown: `onDead` is not fired. */
   async terminate() {
     if (this.disposed) return;
@@ -1271,14 +2416,44 @@ var WorkerHost = class {
 };
 
 // ../supervisor/src/server.ts
+function relayHostRoomFor(sup, room) {
+  const relayRoom = room.relayRoom;
+  if (!relayRoom) throw new Error("irtio: relay host adapter on a room with no relay presence");
+  return {
+    id: room.id,
+    relayRoom,
+    peers: () => room.clients.values(),
+    maxClients: room.config.maxClients,
+    countEgress(bytes) {
+      room.metrics.egressBytes += bytes;
+      room.metrics.framesOut++;
+    },
+    touched(tick) {
+      room.lastTick = tick;
+    }
+  };
+}
 var WS_PING_MS = 2e4;
 var WS_PING_MISSES = 2;
 var MAX_STRIKES = 3;
 var JOIN_TIMEOUT_MS = 15e3;
+var IDENTITY_KEY_WAIT_MS = 2e3;
+var MAX_IDENTITY_KEY_WAITERS = 64;
+var RESUME_TOKEN_TTL_MS = 24 * 60 * 60 * 1e3;
+var BUS_SEEN_MAX = 256;
+var SHARD_ASSIGNMENT_RETRY_MS = [1e3, 3e4];
 var KvUnavailable = class extends Error {
   code = KV_ERRORS.unavailable;
   name = "KvUnavailable";
 };
+var LeaderboardUnavailable = class extends Error {
+  code = LEADERBOARD_ERRORS.unavailable;
+  name = "LeaderboardUnavailable";
+};
+var RatingUnavailable = class extends Error {
+  code = RATING_ERRORS.unavailable;
+  name = "RatingUnavailable";
+};
 function codeOf(err) {
   const code = err?.code;
   return typeof code === "string" && code.startsWith("E_") ? code : void 0;
@@ -1322,6 +2497,7 @@ var SupervisorImpl = class {
         `placement carries ${this.pendingRestores.size} pending restore(s): ` + [...this.pendingRestores].map(([r, sv]) => `${r}<-${sv}`).join(", ")
       );
     }
+    this.identityKeys = config.identityKeys ?? [];
     this.resumeSecret = config.resumeSecret ?? randomBytes(32).toString("base64url");
     if (config.resumeSecret === void 0) {
       this.log("warn", "no resumeSecret configured: resume tokens die with this process");
@@ -1332,6 +2508,15 @@ var SupervisorImpl = class {
         this.limits.connectionsPerIpPerMin / 60
       )
     );
+    this.npcs = new NpcManager({
+      projectId: config.projectId,
+      openLoopback: (roomId, clientId) => this.openLoopback(roomId, clientId),
+      log: (roomId, level, message) => {
+        const room = this.registry.get(roomId);
+        if (room) this.roomLog(room, level, message);
+        else this.log(level, message);
+      }
+    });
     this.helloBuckets = new BucketMap(
       () => new TokenBucket(this.limits.hellosPerMin, this.limits.hellosPerMin / 60)
     );
@@ -1353,6 +2538,8 @@ var SupervisorImpl = class {
       res.writeHead(404).end();
     });
     this.wss = new WebSocketServer({ server: this.http });
+    this.wss.on("error", () => {
+    });
     this.wss.on("connection", (ws, req) => {
       this.onConnection(ws, {
         origin: header(req.headers.origin),
@@ -1370,6 +2557,11 @@ var SupervisorImpl = class {
   limits;
   store;
   processMetrics = newProcessMetrics();
+  /**
+   * D38: the ring behind the reserved `__tenant` room id. Same bounded ring every room gets, so
+   * a noisy boot costs the same as a noisy room and nothing here can grow without limit.
+   */
+  tenantLogs = new LogRing();
   /** The newest runnable deployment; every new room is created under it. */
   bundle;
   schemaHash;
@@ -1380,9 +2572,21 @@ var SupervisorImpl = class {
   wss;
   readyPromise;
   ipBuckets;
+  /**
+   * D59: this tenant's channel-to-subscriber map, beside the room registry it already keeps.
+   *
+   * One per supervisor, which is one per tenant, which is what makes a cross-project reach
+   * unrepresentable rather than refused: there is no other registry to look in and no project
+   * argument on any path that reaches this.
+   */
+  bus = new BusRegistry();
+  /** Monotonic within this process; feeds `mintMailboxName` so two sends never share a name. */
+  mailboxCounter = 0;
   helloBuckets;
   resumeSecret;
   clientIds = /* @__PURE__ */ new Set();
+  /** D44: the scripted NPCs this tenant is running, and the bot runtime driving each. */
+  npcs;
   joinWaiters = /* @__PURE__ */ new Map();
   readyWaiters = /* @__PURE__ */ new Map();
   creating = /* @__PURE__ */ new Map();
@@ -1397,8 +2601,116 @@ var SupervisorImpl = class {
    *  reported on `/admin/idle` so the host-agent can escalate instead of reading "not idle yet"
    *  forever. Reset the moment a flush succeeds cleanly, or a client reconnects. */
   flushFailures = 0;
+  /**
+   * D56: `true` once any room worker in this VM generation has reported that a Rapier world
+   * stepped, which is the point V8 tier-compiled the physics WASM and paid its RSS transient.
+   * Reported on `/admin/idle` so the host agent can hold the tenant's *first* VM snapshot until
+   * the compile is inside the image instead of being redone after every wake.
+   *
+   * Sticky for the life of the process, and deliberately not reset by the idle path: the fact is
+   * about this VM's memory, not about the current idle window, and the room that set it has
+   * usually been hibernated away by the time the tenant goes idle.
+   */
+  physicsWarm = false;
+  /**
+   * D56: measure the Rapier tier-up RSS transient where it actually matters — inside a placed
+   * guest. The desktop re-measurement (2026-08-31) showed the transient peaks on V8's background
+   * compile threads *seconds after* the first step returns (~107 MB above baseline on a many-core
+   * machine, settling back), which a before/after sample around the step misses entirely; a
+   * 1-vCPU guest's peak is the number `VM_MEM_MIB_PHYSICS` actually needs, and nobody has it.
+   * So: on the first `physicsStepped`, sample process RSS (workers are threads, so this is the
+   * whole VM's node process) every 250 ms for 12 s and log baseline, peak, and settled values.
+   * One shot per process; timers unref'd so this never holds the tenant open.
+   */
+  notePhysicsWarm() {
+    if (this.physicsWarm) return;
+    this.physicsWarm = true;
+    const mib = (b) => (b / 1024 / 1024).toFixed(1);
+    const baseline = process.memoryUsage().rss;
+    const t0 = Date.now();
+    let peak = baseline;
+    let peakAtMs = 0;
+    const sampler = setInterval(() => {
+      const rss = process.memoryUsage().rss;
+      if (rss > peak) {
+        peak = rss;
+        peakAtMs = Date.now() - t0;
+      }
+    }, 250);
+    sampler.unref?.();
+    const done = setTimeout(() => {
+      clearInterval(sampler);
+      const settled = process.memoryUsage().rss;
+      this.log(
+        "info",
+        `rapier first step: rss ${mib(baseline)} MiB at step, peak +${mib(peak - baseline)} MiB at ${peakAtMs} ms, settled +${mib(settled - baseline)} MiB after 12 s (D56 tier-up transient; VM_MEM_MIB_PHYSICS evidence)`
+      );
+    }, 12e3);
+    done.unref?.();
+  }
   idleTimer;
   pingTimer;
+  /**
+   * D47: this tenant's usage ledger. One supervisor serves one project, so it needs no project
+   * id; the host agent stamps one on the way out. Public so a test can read the running totals
+   * the way `/admin/usage` does.
+   */
+  usage = new UsageAccumulator();
+  usageTimer;
+  /**
+   * D48: this tenant's cap state, pushed from control over `/admin/caps` and held in memory.
+   *
+   * Public for the same reason `usage` is: a test drives the real thing. Note what it is not: a
+   * client of anything. It has no fetch, no database and no timer, so the pin test's claim that a
+   * join touches no billing query is a property of the type rather than of a careful reading.
+   */
+  caps = new CapGate();
+  /**
+   * M5 part 3.5 (Part C): the leased egress budget this box spends locally.
+   *
+   * Beside `caps` rather than inside it, because they answer different questions at different
+   * moments. `caps` answers "may this project start new work", once per join, from a picture
+   * control drew up to ninety seconds ago. This answers "may this byte leave", on every send,
+   * from a budget the box is decrementing itself. Both are needed and neither subsumes the other.
+   */
+  egressLease = new EgressLease();
+  /**
+   * Pricing amendment 1, decision 1: this project's sustained bandwidth ceiling.
+   *
+   * A third question beside the other two, asked at a third moment. `caps` answers "may this
+   * project start new work", `egressLease` answers "may this byte leave at all this month", and
+   * this answers "is this project sending too fast right now". Only the last one is recoverable
+   * without anybody doing anything: it disengages on its own when the rate falls.
+   *
+   * Public for the same reason the other two are: a test drives the real thing.
+   */
+  bandwidth = new BandwidthCeiling();
+  /**
+   * D53: the platform public keys this tenant will accept identity assertions from, pushed from
+   * control over `/admin/identity-keys` exactly the way cap state is.
+   *
+   * What matters about this field is what it is NOT: there is no private key here, and no way to
+   * obtain one. A supervisor — and therefore any hostile room code sharing its process — can
+   * check that an assertion was minted by the platform and can do nothing else with these bytes.
+   * That is the whole reason the assertion is Ed25519 rather than an HMAC like the BYO-JWT path,
+   * where verification key and minting key are the same string.
+   *
+   * Empty (a tenant that has not been handed keys yet) refuses assertion joins by name —
+   * `E_ASSERTION_UNVERIFIABLE`, meaning retry — rather than failing open. Cap state fails open on
+   * purpose; a credential check must not.
+   */
+  identityKeys = [];
+  /**
+   * M5 part 4: assertion HELLOs parked waiting for the first key push, and the cap on how many
+   * may be parked at once.
+   *
+   * The cap is the safety argument. The wait sits AFTER the HELLO rate bucket, so nothing here
+   * lets a caller open more sockets than the bucket already allows — but a parked socket is a
+   * socket held open, and an unbounded list of them would turn a key-delivery gap into a way to
+   * hold every connection a project is allowed. Past the cap the refusal is immediate, and it is
+   * the same refusal, with the same code, that every one of these got before the wait existed.
+   */
+  identityKeyWaiters = [];
   /**
    * D24: `roomId -> saveId` placement instructions that have not been consumed yet. Populated
    * from `SupervisorConfig.restoreRooms` at boot — placement is the only channel into a tenant,
@@ -1416,6 +2728,7 @@ var SupervisorImpl = class {
     }
     this.bundle = this.newestBundle();
     this.schemaHash = this.bundle?.schemaHash;
+    this.checkDeclaredSizing();
     this.workerEntry = this.config.workerEntry ?? resolveWorkerEntry();
     await new Promise((resolve2, reject) => {
       this.http.once("error", reject);
@@ -1427,6 +2740,8 @@ var SupervisorImpl = class {
     });
     this.pingTimer = setInterval(() => this.keepalive(), WS_PING_MS);
     this.pingTimer.unref?.();
+    this.usageTimer = setInterval(() => this.sampleUsage(), ROOM_SAMPLE_MS);
+    this.usageTimer.unref?.();
     const tenantIdleMs = this.config.tenantIdleMs ?? 3e5;
     if (tenantIdleMs > 0) {
       const every = Math.min(1e3, Math.max(50, Math.floor(tenantIdleMs / 4)));
@@ -1437,7 +2752,29 @@ var SupervisorImpl = class {
       "info",
       `supervisor listening on ${this.port} (${this.bundle ? "bundle" : "relay"} tenant)`
     );
-    await this.resumeAlarmedRooms();
+    this.logCompileCacheState();
+    if (this.isSharded()) {
+      void this.resumeAlarmedRooms().catch((err) => {
+        this.log("warn", "the shard-assigned boot scan failed", err);
+      });
+    } else {
+      await this.resumeAlarmedRooms();
+    }
+  }
+  /**
+   * D56 fix 3 verification: say at boot whether this process sees the compile cache baked into
+   * the rootfs, so the first live evidence that the bake reached a guest is a log line instead
+   * of an ssh session into a paused VM. One line, boot only; absent env means dev, and says so.
+   */
+  logCompileCacheState() {
+    const dir = process.env.NODE_COMPILE_CACHE;
+    if (dir === void 0 || dir === "") return;
+    try {
+      const entries = readdirSync(dir, { recursive: true }).length;
+      this.log("info", `compile cache at ${dir}: ${entries} entries`);
+    } catch (err) {
+      this.log("warn", `compile cache at ${dir}: unreadable (${err.message})`);
+    }
   }
   /**
    * D26, and the piece staging caught missing: **start every room that owes an alarm**, at boot.
@@ -1484,11 +2821,16 @@ var SupervisorImpl = class {
       );
       return;
     }
-    this.log(
-      "info",
-      `resuming ${rooms.size} room(s) with pending alarms: ${[...rooms].join(", ")}`
-    );
-    for (const roomId of [...rooms].sort()) {
+    const mine = this.isSharded() ? await this.assignedRooms([...rooms].sort()) : [...rooms].sort();
+    if (mine.length === 0) {
+      this.log(
+        "info",
+        `no rooms to resume on this shard: ${rooms.size} candidate(s) belong elsewhere`
+      );
+      return;
+    }
+    this.log("info", `resuming ${mine.length} room(s) with pending alarms: ${mine.join(", ")}`);
+    for (const roomId of mine) {
       try {
         await this.ensureRoom(roomId);
       } catch (err) {
@@ -1496,6 +2838,42 @@ var SupervisorImpl = class {
       }
     }
   }
+  /** D67-d: true for a shard of a project with more than one; false for every tenant today. */
+  isSharded() {
+    return (this.config.shards ?? 1) > 1;
+  }
+  /**
+   * D67-d: the subset of `candidates` this shard owns, from the control plane through the
+   * gateway's `/shard/filter`. Retries 1, 2, 4 ... 30 s (capped, never giving up) on any failure,
+   * logging "waiting for shard assignment" at warn each time, because a shard that guesses would
+   * either double-start rooms another shard holds or leave alarms undelivered; waiting is the only
+   * honest state. The sleep is injected so the schedule is tested with a recorded fake.
+   */
+  async assignedRooms(candidates) {
+    const shard = this.config.shard ?? 0;
+    const sleep2 = this.config.shardRetrySleep ?? ((ms) => new Promise((resolve2) => {
+      const t = setTimeout(resolve2, ms);
+      t.unref?.();
+    }));
+    let delayMs = SHARD_ASSIGNMENT_RETRY_MS[0];
+    for (let attempt = 1; ; attempt++) {
+      if (this.closing) return [];
+      try {
+        const client = this.config.shardClient;
+        if (!client) throw new Error("no shard client is configured on this tenant");
+        const mine = await client.filter(shard, candidates);
+        const known = new Set(candidates);
+        return mine.filter((r) => known.has(r)).sort();
+      } catch (err) {
+        this.log(
+          "warn",
+          `waiting for shard assignment (shard ${shard} of ${this.config.shards ?? 1}, attempt ${attempt}, ${candidates.length} candidate(s), retry in ${delayMs} ms): ${err instanceof Error ? err.message : String(err)}`
+        );
+        await sleep2(delayMs);
+        delayMs = Math.min(delayMs * 2, SHARD_ASSIGNMENT_RETRY_MS[1]);
+      }
+    }
+  }
   /**
    * Everything a **VM-snapshot restore** owes the alarm clock, run from `/admin/resume` once the
    * guest wall clock has been corrected.
@@ -1554,7 +2932,7 @@ var SupervisorImpl = class {
    * rooms that are still serving the old code.
    */
   async reloadBundle(bundlePath) {
-    const loaded = await loadBundle(bundlePath, this.deploymentVersion);
+    const loaded = await loadBundle(bundlePath, this.deploymentVersion, DEFAULT_ROOM_TYPE3);
     for (const room of this.registry.values()) {
       room.wakeQueue.length = 0;
       room.droppedWakeFrames = 0;
@@ -1564,18 +2942,36 @@ var SupervisorImpl = class {
     this.deployments.set(loaded.version, {
       version: loaded.version,
       schemaJson: loaded.schemaJson,
-      bundle: loaded
+      bundle: loaded,
+      bundles: /* @__PURE__ */ new Map([[DEFAULT_ROOM_TYPE3, loaded]])
     });
     this.bundle = loaded;
     this.schemaHash = loaded.schemaHash;
     this.log("info", `bundle reloaded from ${bundlePath}`);
   }
+  /**
+   * D47: banks every chargeable room's alive-time into the ledger. Called on
+   * {@link ROOM_SAMPLE_MS}, on close, and immediately before `/admin/usage` is read, so what the
+   * host agent ships is never a second stale.
+   */
+  sampleUsage(now = Date.now()) {
+    sampleRoomClocks(this.registry.values(), this.usage, now);
+  }
+  /** The `/admin/usage` body, and the ledger read the host agent ships. */
+  usageWindows(now = Date.now()) {
+    this.sampleUsage(now);
+    return this.usage.windows(now);
+  }
   async close() {
     if (this.closing) return;
     this.closing = true;
     this.quiesceAlarms();
+    this.npcs.despawnAll();
+    this.releaseIdentityKeyWaiters();
     if (this.idleTimer) clearInterval(this.idleTimer);
     if (this.pingTimer) clearInterval(this.pingTimer);
+    this.sampleUsage();
+    if (this.usageTimer) clearInterval(this.usageTimer);
     try {
       await flushAll(this);
     } catch (err) {
@@ -1601,13 +2997,50 @@ var SupervisorImpl = class {
   // -------------------------------------------------------------------------
   // Logging
   // -------------------------------------------------------------------------
+  /**
+   * D38: a tenant-level event now enters the log pipeline instead of only reaching the console.
+   *
+   * `/admin/logs` reads per-room rings, so before this every event that was not about a room —
+   * boot, resume, deploy, placement, alarm recovery, storage failures — was invisible to the host
+   * agent, to the control plane, and to `irtio logs`. Those are precisely the lines somebody
+   * reaches for when a project is not working, and the only way to see them was to be on the box
+   * reading the guest console.
+   *
+   * They go into a ring under the reserved id `__tenant` (D38), so the whole existing pipeline
+   * carries them with no new route and no new frame.
+   */
   log(level, ...args) {
+    this.tenantLogs.push(level, args);
+    this.emit(level, args);
+  }
+  /** The console/config sink, with no ring behind it. */
+  emit(level, args) {
     if (this.config.log) this.config.log(level, ...args);
     else console[level === "info" ? "log" : level]("[irtio]", ...args);
   }
+  /** A room event: it belongs in that room's ring, and nowhere near the `__tenant` one. */
+  /**
+   * D44: opens one NPC session and hands back the client half of its socket. It goes straight
+   * through `onConnection` — the same function the WebSocket server calls — so an NPC and a
+   * browser differ by a flag on the accept, and by nothing at all after it.
+   */
+  openLoopback(roomId, clientId) {
+    const { server, client } = loopbackPair();
+    this.onConnection(server, {
+      loopback: { clientId },
+      origin: void 0,
+      routerOrigin: void 0,
+      forwardedFor: void 0,
+      routerSecret: void 0,
+      // Never a real address, and deliberately not `127.0.0.1`: an operator reading a session
+      // list should be able to tell an NPC from something dialling the loopback interface.
+      remoteAddress: `npc:${roomId}`
+    });
+    return client;
+  }
   roomLog(room, level, ...args) {
     room.log(level, ...args);
-    this.log(level, `[${room.id}]`, ...args);
+    this.emit(level, [`[${room.id}]`, ...args]);
   }
   /**
    * Week-5 snapshot keys carry the deployment version (`@v3`); version `0` keeps the week-3 key
@@ -1647,18 +3080,32 @@ var SupervisorImpl = class {
           // §10.8 escalation: consecutive flush passes that left a room unflushed. The host agent
           // treats >=3 as worth an error-level log (once, deduped) instead of reading the tenant
           // as merely slow to go idle.
-          flushFailures: this.flushFailures
+          flushFailures: this.flushFailures,
+          // D56: has a Rapier world stepped in this VM yet? The agent gates a cold-booted
+          // tenant's first snapshot on it. Additive; an agent that ignores it behaves as before.
+          physicsWarm: this.physicsWarm
         });
         return true;
       case "/admin/rooms":
         json({ rooms: this.rooms(), deploymentVersion: this.deploymentVersion });
         return true;
       case "/admin/metrics":
-        json({
-          at: Date.now(),
-          metrics: this.metrics(),
-          rooms: this.rooms().map((r) => r.metrics)
-        });
+        void this.refreshTickHealth().then(
+          () => json({
+            at: Date.now(),
+            metrics: this.metrics(),
+            rooms: this.rooms().map((r) => ({ id: r.id, metrics: r.metrics })),
+            // D47: the usage ledger rides the poll the agent already makes. A separate route
+            // would be a fourth round trip per tenant per poll for four rows.
+            usage: this.usageWindows()
+          }),
+          () => json({
+            at: Date.now(),
+            metrics: this.metrics(),
+            rooms: this.rooms().map((r) => ({ id: r.id, metrics: r.metrics })),
+            usage: this.usageWindows()
+          })
+        );
         return true;
       // D31 (week 7): the ONE write on this otherwise read-only surface, and a deliberate
       // exception to its "the agent must not be able to change anything" rule: after a
@@ -1768,10 +3215,31 @@ var SupervisorImpl = class {
                   migrationPath = nodePath.join(dir, `m${d.version}.mjs`);
                   await writeFile(migrationPath, Buffer.from(d.migrationB64, "base64"));
                 }
+                let rooms2;
+                if (d.roomsB64 !== void 0) {
+                  if (typeof d.roomsB64 !== "object" || d.roomsB64 === null || Array.isArray(d.roomsB64)) {
+                    throw new Error("roomsB64 must be an object of room type to base64 bundle");
+                  }
+                  rooms2 = {};
+                  for (const [type, b64] of Object.entries(d.roomsB64)) {
+                    if (!ROOM_TYPE_RE.test(type)) {
+                      throw new Error(
+                        `roomsB64 names an illegal room type ${JSON.stringify(type)}`
+                      );
+                    }
+                    if (typeof b64 !== "string") {
+                      throw new Error(`roomsB64.${type} must be a base64 bundle`);
+                    }
+                    const typePath = nodePath.join(dir, `v${d.version}.${type}.mjs`);
+                    await writeFile(typePath, Buffer.from(b64, "base64"));
+                    rooms2[type] = typePath;
+                  }
+                }
                 await this.addBundle({
                   version: d.version,
                   ...typeof d.schemaJson === "string" ? { schemaJson: d.schemaJson } : {},
                   ...bundlePath !== void 0 ? { bundlePath } : {},
+                  ...rooms2 !== void 0 ? { rooms: rooms2 } : {},
                   ...migrationPath !== void 0 ? { migrationPath } : {}
                 });
                 added.push(d.version);
@@ -1796,32 +3264,187 @@ var SupervisorImpl = class {
         });
         return true;
       }
-      case "/admin/logs": {
-        const since = Number(url.searchParams.get("since") ?? 0) || 0;
-        const limit = Math.min(Number(url.searchParams.get("limit") ?? 200) || 200, 1e3);
-        const entries = [];
-        for (const room of this.registry.values()) {
-          for (const entry of this.logs(room.id)) {
-            if (entry.at <= since) continue;
-            entries.push({
-              at: entry.at,
-              level: entry.level,
-              roomId: room.id,
-              message: entry.args.map((x) => typeof x === "string" ? x : String(x)).join(" ")
-            });
-          }
+      // D48: the THIRD write on this otherwise read-only surface, and the reasoning is the same
+      // one that carved out the other two. Cap state changes at runtime by design (a meter
+      // crosses, a card is added, an owner raises a ceiling) and the boot-time env channel is
+      // closed to it: env is hashed into the VM snapshot's identity (D29), so a cap that rode it
+      // would cold-boot the fleet on every cap change. GET answers what this tenant currently
+      // believes, which is the thing an operator wants when a join is being refused and nobody
+      // can see why.
+      // M5 part 7 (D67-e): the FOURTH write on this surface. A bus message another shard sent to
+      // a room on this one, forwarded by the control plane through the host agent. Load-if-exists
+      // then the local park; never a room from nothing. Answers the local `busSend` result so the
+      // sender's promise resolves with the same refusals it would see on one shard.
+      case "/admin/bus/deliver": {
+        if (req.method !== "POST") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end('{"error":"POST only"}');
+          return true;
         }
-        entries.sort((x, y) => x.at - y.at);
-        json({ entries: entries.slice(-limit) });
+        let body = "";
+        req.on("data", (d) => {
+          body += d.toString();
+        });
+        req.on("end", () => {
+          void (async () => {
+            let parsed;
+            try {
+              parsed = JSON.parse(body || "{}");
+            } catch {
+              res.writeHead(400, { "content-type": "application/json" });
+              res.end('{"error":"body is not JSON"}');
+              return;
+            }
+            const { to, from, payload, id } = parsed;
+            if (typeof to !== "string" || typeof from !== "string" || typeof payload !== "string" || typeof id !== "string") {
+              res.writeHead(400, { "content-type": "application/json" });
+              res.end('{"error":"to, from, payload and id must be strings"}');
+              return;
+            }
+            if (busPayloadProblem(payload)) {
+              res.writeHead(400, { "content-type": "application/json" });
+              res.end('{"error":"payload over the bus limit"}');
+              return;
+            }
+            try {
+              json(await this.deliverForwarded({ to, from, payload, id }));
+            } catch (err) {
+              this.log("error", "admin bus deliver failed", err);
+              res.writeHead(500, { "content-type": "application/json" });
+              res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+            }
+          })();
+        });
         return true;
       }
-      default:
-        res.writeHead(404, { "content-type": "application/json" });
-        res.end('{"error":"not found"}');
-        return true;
-    }
-  }
-  storeKey(room, version) {
+      case "/admin/caps": {
+        if (req.method === "GET") {
+          const state = this.caps.current();
+          json({
+            present: state !== void 0,
+            ageMs: this.caps.ageMs() ?? null,
+            state: state ?? null
+          });
+          return true;
+        }
+        if (req.method !== "POST") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end('{"error":"GET or POST"}');
+          return true;
+        }
+        let body = "";
+        req.on("data", (d) => {
+          body += d.toString();
+        });
+        req.on("end", () => {
+          let parsed;
+          try {
+            parsed = JSON.parse(body || "null");
+          } catch {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end('{"error":"body is not JSON"}');
+            return;
+          }
+          const state = parseCapState(parsed);
+          if (!state) {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end('{"error":"body is not a cap state"}');
+            return;
+          }
+          this.caps.apply(state);
+          this.bandwidth.setPlan(state.plan);
+          const leaseBytes = this.caps.leaseFor("egress_bytes");
+          if (leaseBytes !== void 0) {
+            const wasTripped = this.egressLease.tripped;
+            this.egressLease.apply({
+              remainingBytes: leaseBytes,
+              periodStart: state.periodStart
+            });
+            if (this.egressLease.tripped && !wasTripped) this.tripEgressWall();
+            else if (!this.egressLease.tripped && wasTripped) {
+              this.log("info", "egress wall lifted: a fresh budget was leased");
+            }
+          }
+          const crossed = state.meters.filter((m) => m.mode === "hard" && m.status === "crossed").map((m) => m.meter);
+          if (crossed.length > 0) {
+            this.log("warn", `usage caps applied: hard cap reached on ${crossed.join(", ")}`);
+          }
+          json({ ok: true, applied: state.meters.length, crossed });
+        });
+        return true;
+      }
+      /**
+       * D53: the platform identity public keys, pushed the way cap state is and for the same
+       * reason — an env var would be hashed into the VM snapshot's identity (D29) and every key
+       * rotation would cold-boot the fleet.
+       *
+       * GET answers what this tenant currently holds (kids only; the PEMs are public but an
+       * operator debugging a refused join wants the fingerprints, not a wall of base64). POST
+       * replaces the set wholesale: two keys may be active at once, so a rotation is an overlap
+       * rather than a flag day, exactly like `irtio keys jwt-secret`.
+       */
+      case "/admin/identity-keys": {
+        if (req.method === "GET") {
+          json({ kids: this.identityKeys.map((k) => k.kid) });
+          return true;
+        }
+        if (req.method !== "POST") {
+          res.writeHead(405, { "content-type": "application/json" });
+          res.end('{"error":"GET or POST"}');
+          return true;
+        }
+        let body = "";
+        req.on("data", (d) => {
+          body += d.toString();
+        });
+        req.on("end", () => {
+          let parsed;
+          try {
+            parsed = JSON.parse(body || "null");
+          } catch {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end('{"error":"body is not JSON"}');
+            return;
+          }
+          const keys = parseIdentityKeys(parsed);
+          if (!keys) {
+            res.writeHead(400, { "content-type": "application/json" });
+            res.end('{"error":"body is not {keys: [{kid, publicKeyPem}]}"}');
+            return;
+          }
+          this.identityKeys = keys;
+          if (keys.length > 0) this.releaseIdentityKeyWaiters();
+          json({ ok: true, kids: keys.map((k) => k.kid) });
+        });
+        return true;
+      }
+      case "/admin/logs": {
+        const since = Number(url.searchParams.get("since") ?? 0) || 0;
+        const limit = Math.min(Number(url.searchParams.get("limit") ?? 200) || 200, 1e3);
+        const entries = [];
+        const streams = [TENANT_ROOM_ID, ...this.registry.values().map((r) => r.id)];
+        for (const roomId of streams) {
+          for (const entry of this.logs(roomId)) {
+            if (entry.at <= since) continue;
+            entries.push({
+              at: entry.at,
+              level: entry.level,
+              roomId,
+              message: entry.args.map((x) => typeof x === "string" ? x : String(x)).join(" ")
+            });
+          }
+        }
+        entries.sort((x, y) => x.at - y.at);
+        json({ entries: entries.slice(-limit) });
+        return true;
+      }
+      default:
+        res.writeHead(404, { "content-type": "application/json" });
+        res.end('{"error":"not found"}');
+        return true;
+    }
+  }
+  storeKey(room, version) {
     const id = typeof room === "string" ? room : room.id;
     const v = version ?? (typeof room === "string" ? 0 : room.version);
     const base = `${this.config.projectId}/${id}`;
@@ -1843,7 +3466,25 @@ var SupervisorImpl = class {
   }
   async registerDeployment(ref) {
     const migrationUrl = ref.migrationPath !== void 0 ? toFileUrl(ref.migrationPath) : void 0;
-    const bundle = ref.bundlePath !== void 0 ? await loadBundle(ref.bundlePath, ref.version) : void 0;
+    const bundles = /* @__PURE__ */ new Map();
+    if (ref.bundlePath !== void 0) {
+      bundles.set(
+        DEFAULT_ROOM_TYPE3,
+        await loadBundle(ref.bundlePath, ref.version, DEFAULT_ROOM_TYPE3)
+      );
+    }
+    for (const [type, path2] of Object.entries(ref.rooms ?? {})) {
+      if (!ROOM_TYPE_RE.test(type)) {
+        throw new Error(
+          `irtio: deployment v${ref.version} names a room type ${JSON.stringify(type)}, which is not a legal type name (lowercase, starting with a letter or digit, up to 24 characters)`
+        );
+      }
+      if (bundles.has(type)) {
+        throw new Error(`irtio: deployment v${ref.version} defines the room type ${type} twice`);
+      }
+      bundles.set(type, await loadBundle(path2, ref.version, type));
+    }
+    const bundle = bundles.get(DEFAULT_ROOM_TYPE3);
     const schemaJson = bundle?.schemaJson ?? ref.schemaJson;
     if (schemaJson === void 0) {
       throw new Error(
@@ -1853,14 +3494,210 @@ var SupervisorImpl = class {
     this.deployments.set(ref.version, {
       version: ref.version,
       schemaJson,
+      bundles,
       ...migrationUrl !== void 0 ? { migrationUrl } : {},
       ...bundle !== void 0 ? { bundle } : {}
     });
   }
+  /**
+   * The newest loaded bundle for a room type, or `undefined` when the tenant defines no such type.
+   *
+   * Deliberately distinct from "no bundle at all": a tenant with room types that is asked for a
+   * type it does not have has made a naming mistake, and answering that with the relay rung would
+   * silently give the client a schema-less room instead of an error it can read.
+   */
+  bundleFor(type) {
+    let best;
+    for (const d of this.deployments.values()) {
+      const b = d.bundles.get(type);
+      if (b && (!best || b.version > best.version)) best = b;
+    }
+    return best;
+  }
+  /** Every room type this tenant defines, newest deployment first, sorted for stable messages. */
+  roomTypes() {
+    const types = /* @__PURE__ */ new Set();
+    for (const d of this.deployments.values()) for (const type of d.bundles.keys()) types.add(type);
+    return [...types].sort();
+  }
+  /**
+   * M5 part 3.5: does what this project declared fit the VM it was given?
+   *
+   * **This check inverted in part 3.5, and what it does on failure inverted with it.** In part 2
+   * the VM size was a class guess and the declarations were checked against it, so a mismatch was
+   * a real possibility for an ordinary project and logging was the only defensible response:
+   * refusing to boot would have stopped a project that was serving players, over arithmetic that
+   * was deliberately pessimistic.
+   *
+   * Now the declarations *decide* the size, through the same `vmSizeFor` the host agent calls
+   * before it builds the machine. An ordinary project therefore fits by construction and this
+   * check can only fail one way: the project set an explicit `vmMemMib` override smaller than its
+   * own declarations. That is not pessimism meeting reality, it is a project having stated two
+   * incompatible things, and the honest answer to it pre-release is to refuse the room set at
+   * boot rather than to serve rooms inside a machine that cannot hold them.
+   *
+   * No VM budget means a dev box, and dev keeps the generous defaults untouched.
+   */
+  checkDeclaredSizing() {
+    const vmMemMib = this.config.vmMemMib;
+    if (vmMemMib === void 0) return;
+    const types = this.roomTypes();
+    if (types.length === 0) return;
+    const declared = types.map((type) => {
+      const config = this.bundleFor(type)?.config;
+      return {
+        type,
+        memoryMb: config?.memoryMb,
+        ...config?.maxAwake !== void 0 ? { maxAwake: config.maxAwake } : {},
+        ...config?.engine !== void 0 ? { physics: true } : {}
+      };
+    });
+    const fit = checkDeclaredFit(vmMemMib, declared);
+    if (fit.fits) {
+      this.log("info", `room type sizing fits the VM budget: ${fit.detail}`);
+      return;
+    }
+    const message = `this project's room types do not fit its VM: ${fit.detail}. Arithmetic sizing gives a project the VM its declarations ask for, so the only way to reach this is an explicit vmMemMib override smaller than the declarations under it. These types need ${fit.requiredMib} MiB and the override booked ${fit.budgetMib}. Raise or remove the override, or lower a memoryMb or maxAwake declaration.` + (fit.undeclared.length > 0 ? ` Counted at the platform default because they declare no memoryMb: ${fit.undeclared.join(", ")}.` : "");
+    this.log("error", message);
+    throw new Error(`irtio: ${message}`);
+  }
+  /** D58: the worker limits a room of this type runs under: its declaration, or the default. */
+  limitsFor(type) {
+    const declared = this.bundleFor(type)?.config.memoryMb;
+    if (declared === void 0) return this.limits;
+    return {
+      workerMaxOldGenMb: declared,
+      workerMaxYoungGenMb: this.limits.workerMaxYoungGenMb
+    };
+  }
+  /**
+   * M5 part 3.5: how many rooms of a type are holding worker memory right now.
+   *
+   * Awake means "costs the VM its declared heap": starting, running, waking, and hibernating (a
+   * room mid-sleep still has its worker). A hibernated or closed room holds nothing, which is why
+   * `maxAwake` is a bound on this number and not on how many rooms a project may ever have.
+   */
+  awakeOfType(type) {
+    let n = 0;
+    for (const room of this.registry.values()) {
+      if (room.relay) continue;
+      if (roomTypeOf(room.id) !== type) continue;
+      if (room.state === "hibernated" || room.state === "closed") continue;
+      n++;
+    }
+    return n;
+  }
+  /**
+   * The refusal for starting a *new* room of a type that is already at its **declared** `maxAwake`,
+   * or `undefined` when there is room.
+   *
+   * **This is what makes declared sizing honest rather than optimistic.** The tenant's VM was
+   * built with `(memoryMb + youngGen) x maxAwake` MiB for this type, so room N+1 is a room the
+   * machine was never sized to hold; admitting it would recreate exactly the "several under-cap
+   * rooms sum past the VM" caveat part 1 recorded and part 3.5 exists to close.
+   *
+   * Four boundaries, stated rather than left implicit, because each of them narrows the claim.
+   *
+   * - **It applies only to a placed tenant.** No `IRT_VM_MEM_MIB` means a dev box, and a dev box
+   *   has headroom rather than a machine sized to a declaration — which is the same signal, and
+   *   the same reasoning, that leaves `DEFAULT_LIMITS` alone in `heap-caps.ts`. It is also what
+   *   `games/dive`'s end-to-end suite discovered the hard way: enforcing a production-shaped bound
+   *   against a developer's laptop refuses rooms nothing was going to run out of memory over. The
+   *   cost is that a developer meets this refusal in production rather than in dev, which is
+   *   recorded as a debt.
+   *
+   * - **Only a declared `maxAwake` is enforced.** An undeclared type is *sized* at one awake room,
+   *   which is the conservative number for arithmetic, but it is not *capped* at one. Capping it
+   *   would invent a limit no project asked for and would stop every existing multi-room project
+   *   dead at its second room. So for an undeclared type the pre-part-3.5 situation stands
+   *   unchanged: rooms are contained by their heap caps and their sum is not bounded. The bound is
+   *   something a project opts into by saying a number, and the sum is exact for the types that
+   *   did. This is narrower than the plan asked for and it is recorded as such.
+   * - **Relay rooms are exempt.** They have no bundle, so they have no declaration, and their
+   *   client cap is a `SupervisorLimits` knob rather than a room-type one.
+   * - **A wake is not refused, only a create.** Refusing to wake an existing room would leave a
+   *   room its players cannot get back into and its state stranded, which is the "silently dies
+   *   under a cap" failure D48 was built around avoiding. The consequence is that a project which
+   *   accumulates hibernated rooms can exceed its declared concurrency by waking them. Recorded as
+   *   a debt rather than hidden here: the bound bites where rooms are *created*, which is the
+   *   point a project controls.
+   */
+  maxAwakeRefusal(roomId) {
+    if (this.config.vmMemMib === void 0) return void 0;
+    const type = roomTypeOf(roomId);
+    const declared = this.bundleFor(type)?.config.maxAwake;
+    if (declared === void 0) return void 0;
+    if (this.awakeOfType(type) < declared) return void 0;
+    return `room type ${JSON.stringify(type)} already has ${declared} room${declared === 1 ? "" : "s"} awake, which is what it declared. The tenant VM was sized for exactly that many, so starting another would put this project over the memory it asked for. Raise \`maxAwake\` in this type's defineRoom config and deploy; the change takes effect at the next placement.`;
+  }
+  /**
+   * M5 part 3.5 (Part C): how many rooms of any type are holding a worker right now.
+   *
+   * The same "awake" the per-type bound uses: starting, running, waking and hibernating hold a
+   * worker; hibernated and closed do not. Relay rooms count, because a relay room is a real room
+   * in the registry with real sockets attached, and the cap exists to bound exactly the burst a
+   * crowd of relay rooms produces.
+   */
+  awakeRooms() {
+    let n = 0;
+    for (const room of this.registry.values()) {
+      if (room.state === "hibernated" || room.state === "closed") continue;
+      n++;
+    }
+    return n;
+  }
+  /**
+   * The refusal for starting a new room on a free project that is already at the concurrent
+   * awake-rooms cap, or `undefined` when there is room.
+   *
+   * Free only, deliberately. A card project's exposure is bounded by money — the included tier,
+   * then metered overage under a spend cap it controls — and adding a shape cap on top would be
+   * refusing work a customer has agreed to pay for.
+   *
+   * A box with no cap state does not enforce this, for the same reason it enforces no other cap:
+   * the failure direction is "serve", and a fleet socket blinking must not look like a free tier.
+   */
+  freeAwakeRoomsRefusal() {
+    if (this.caps.plan() !== "free") return void 0;
+    const cap = this.limits.freeMaxAwakeRooms;
+    if (this.awakeRooms() < cap) return void 0;
+    return `this project is on the free plan, which allows ${cap} rooms awake at the same time, and ${cap} are awake now. Rooms that go idle free a slot within a minute. Add a card in the billing page to lift the limit.`;
+  }
+  /**
+   * M5 part 3.5 (Part C): the wall trips. Forwarding stops and every session closes.
+   *
+   * Three things are deliberate about what this does and does not do.
+   *
+   * **Sockets close, rooms do not.** Rooms hibernate on their ordinary idle path once their
+   * clients are gone, which means state is snapshotted normally and comes back when the period
+   * rolls or a card is added. A wall that destroyed rooms would turn a billing event into data
+   * loss, which is the "silently dies under a cap" failure this milestone is built around
+   * avoiding.
+   *
+   * **Every socket gets the distinct close code**, not just the ones that were sending. A player
+   * who was idle when the wall tripped needs the same explanation as one who was not.
+   *
+   * **NPCs are closed too, and that is not a contradiction of their exemption.** An NPC's bytes
+   * are loopback and never counted against the lease, so an NPC cannot spend a project into the
+   * wall. But an NPC in a room whose players have all been disconnected is a worker burning
+   * room-hours for an audience of nobody.
+   */
+  tripEgressWall() {
+    const plan = this.caps.plan() ?? "free";
+    const message = egressWallMessage(plan);
+    this.log(
+      "warn",
+      `egress wall tripped: the leased data-out budget is spent. Closing ${this.sessions.size} session${this.sessions.size === 1 ? "" : "s"} with close code ${CLOSE_EGRESS_WALL}. ` + message
+    );
+    for (const session of [...this.sessions]) {
+      if (!session.open) continue;
+      session.failWith("E_EGRESS_WALL", message, CLOSE_EGRESS_WALL);
+    }
+  }
   /** Registers a newer deployment. Rooms already running keep theirs and drain (plan §3.3). */
   async addBundle(ref) {
-    if (ref.bundlePath === void 0 && ref.schemaJson === void 0) {
-      throw new Error("addBundle: a deployment needs a bundlePath or a schemaJson");
+    if (ref.bundlePath === void 0 && ref.schemaJson === void 0 && Object.keys(ref.rooms ?? {}).length === 0) {
+      throw new Error("addBundle: a deployment needs a bundlePath, a rooms map or a schemaJson");
     }
     await this.registerDeployment(ref);
     const newest = this.newestBundle();
@@ -1912,14 +3749,16 @@ var SupervisorImpl = class {
    * `from` up to `to`. `undefined` when there is nothing to do; throws when a version in between
    * is unknown, which would otherwise mean decoding bytes with the wrong schema.
    */
-  migrationChain(from, to) {
+  migrationChain(from, to, type = DEFAULT_ROOM_TYPE3) {
     if (from >= to) return void 0;
     const steps = [];
     for (const d of [...this.deployments.values()].sort((a, b) => a.version - b.version)) {
       if (d.version < from || d.version > to) continue;
       steps.push({
         version: d.version,
-        schemaJson: d.schemaJson,
+        // D58: each type migrates against its own schema. The default type reads `d.schemaJson`,
+        // which is exactly what every project got before types, so nothing single-room shifts.
+        schemaJson: d.bundles.get(type)?.schemaJson ?? d.schemaJson,
         ...d.migrationUrl !== void 0 && d.version > from ? { migrationUrl: d.migrationUrl } : {}
       });
     }
@@ -1948,6 +3787,15 @@ var SupervisorImpl = class {
       this.limits.maxBufferedBytes,
       (s) => this.onSlowConsumer(s)
     );
+    if (meta.loopback) {
+      session.npc = true;
+      session.forcedClientId = meta.loopback.clientId;
+    }
+    session.onEgress = (bytes) => {
+      this.usage.addEgressBytes(bytes);
+      if (this.egressLease.spend(bytes)) this.tripEgressWall();
+      this.bandwidth.count(bytes);
+    };
     this.sessions.add(session);
     this.idleSince = 0;
     this.idleFired = false;
@@ -1960,13 +3808,20 @@ var SupervisorImpl = class {
       session.missedPongs = 0;
     });
     ws.on("message", (data) => this.onSocketMessage(session, data));
-    if (!originAllowed(this.config.origins, this.config.allowNoOrigin !== false, origin)) {
-      session.fail("E_ORIGIN", formatError("E_ORIGIN", { origin: origin ?? "(none)" }));
-      return;
-    }
-    if (!this.ipBuckets.take(remoteAddress)) {
-      session.fail("E_RATE_LIMITED", "too many connections from this address");
-      return;
+    if (!session.npc) {
+      if (!originAllowed(this.config.origins, this.config.allowNoOrigin !== false, origin)) {
+        session.fail("E_ORIGIN", formatError("E_ORIGIN", { origin: origin ?? "(none)" }));
+        return;
+      }
+      if (!this.ipBuckets.take(remoteAddress)) {
+        session.fail("E_RATE_LIMITED", "too many connections from this address");
+        return;
+      }
+      const capRefusal = this.caps.refusal("egress_bytes");
+      if (capRefusal !== void 0) {
+        session.fail("E_USAGE_CAP", capRefusal);
+        return;
+      }
     }
     session.helloTimer = setTimeout(() => {
       session.helloTimer = void 0;
@@ -1983,7 +3838,7 @@ var SupervisorImpl = class {
       let payload;
       try {
         const frame = decodeFrame(bytes);
-        if (frame.type !== FrameType2.HELLO) {
+        if (frame.type !== FrameType3.HELLO) {
           session.fail("E_BAD_FRAME", formatError("E_BAD_FRAME", { frame: frame.type }));
           return;
         }
@@ -2002,10 +3857,10 @@ var SupervisorImpl = class {
     session.slowConsumer = true;
     try {
       session.ws.send(
-        encodeFrame2(
-          FrameType2.ERROR,
+        encodeFrame3(
+          FrameType3.ERROR,
           encodeErrorPayload2({
-            code: ErrorCode2.E_SLOW_CONSUMER.code,
+            code: ErrorCode3.E_SLOW_CONSUMER.code,
             message: formatError("E_SLOW_CONSUMER"),
             fatal: true
           })
@@ -2053,6 +3908,9 @@ var SupervisorImpl = class {
     if (session.state !== "joined") return;
     session.state = "disconnected";
     room.metrics.connections = Math.max(0, room.metrics.connections - 1);
+    if (session.npc) {
+      room.metrics.npcConnections = Math.max(0, room.metrics.npcConnections - 1);
+    }
     if (session.fatal && !session.slowConsumer) {
       this.expireSession(session, "kicked");
       return;
@@ -2064,7 +3922,7 @@ var SupervisorImpl = class {
       const delta = room.relayRoom.setConnected(session.clientId, false);
       if (delta) {
         room.lastTick = room.relayRoom.tick;
-        this.broadcast(room, encodeFrame2(FrameType2.DELTA, delta));
+        this.broadcast(room, encodeFrame3(FrameType3.DELTA, delta));
       }
     }
     session.graceTimer = setTimeout(
@@ -2086,11 +3944,21 @@ var SupervisorImpl = class {
     if (!room) return;
     if (room.clients.get(session.clientId) === session) room.clients.delete(session.clientId);
     this.clientIds.delete(session.clientId);
+    if (this.config.voice) {
+      void this.config.voice.close({
+        projectId: this.config.projectId,
+        roomId: room.id,
+        clientId: session.clientId,
+        npc: session.npc
+      }).catch((err) => {
+        this.log("warn", `voice close failed for ${session.clientId}: ${String(err)}`);
+      });
+    }
     if (room.relay) {
       const delta = room.relayRoom?.remove(session.clientId);
       if (delta && room.relayRoom) {
         room.lastTick = room.relayRoom.tick;
-        this.broadcast(room, encodeFrame2(FrameType2.DELTA, delta));
+        this.broadcast(room, encodeFrame3(FrameType3.DELTA, delta));
       }
     } else if (room.state === "running" && room.worker) {
       room.worker.post({ t: "leave", clientId: session.clientId, reason });
@@ -2102,6 +3970,44 @@ var SupervisorImpl = class {
   // -------------------------------------------------------------------------
   // HELLO
   // -------------------------------------------------------------------------
+  /** Assertion HELLOs parked waiting for the platform keys. See the field for why it is bounded. */
+  get identityKeyWaiterCount() {
+    return this.identityKeyWaiters.length;
+  }
+  /** Wakes every parked assertion HELLO. Called when the first key push lands, and on close. */
+  releaseIdentityKeyWaiters() {
+    const waiters = this.identityKeyWaiters;
+    this.identityKeyWaiters = [];
+    for (const wake of waiters) wake();
+  }
+  /**
+   * Waits, bounded, for this tenant to be handed a platform key.
+   *
+   * Three ways out and all three are the same to the caller: the keys arrive (the common case, in
+   * about one loopback round trip), the deadline passes, or the parking list is already full. In
+   * every one of them the caller goes straight back to `verifyAssertion`, which refuses with
+   * `E_ASSERTION_UNVERIFIABLE` if the keys still are not there. Nothing here can turn a refusal
+   * into an acceptance; the only thing it changes is how long a player waits before finding out.
+   */
+  awaitIdentityKeys() {
+    const waitMs = this.config.identityKeyWaitMs ?? IDENTITY_KEY_WAIT_MS;
+    if (waitMs <= 0) return Promise.resolve();
+    if (this.identityKeyWaiters.length >= MAX_IDENTITY_KEY_WAITERS) return Promise.resolve();
+    return new Promise((resolve2) => {
+      let done = false;
+      const finish = () => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        const at = this.identityKeyWaiters.indexOf(finish);
+        if (at >= 0) this.identityKeyWaiters.splice(at, 1);
+        resolve2();
+      };
+      const timer = setTimeout(finish, waitMs);
+      timer.unref?.();
+      this.identityKeyWaiters.push(finish);
+    });
+  }
   async handleHello(session, payload) {
     session.clearHelloTimer();
     let hello;
@@ -2128,7 +4034,16 @@ var SupervisorImpl = class {
       return;
     }
     let jwt;
-    if (credential.kind === "jwt") {
+    if (credential.kind === "assertion") {
+      if (this.identityKeys.length === 0) await this.awaitIdentityKeys();
+      const verdict = verifyAssertion(this.identityKeys, credential.token, this.config.projectId);
+      if (!verdict.ok) {
+        const vars = verdict.code === "E_TOKEN_MALFORMED" ? { reason: verdict.reason } : verdict.code === "E_TOKEN_BAD_ALG" ? { alg: verdict.reason } : {};
+        session.fail(verdict.code, formatError(verdict.code, vars));
+        return;
+      }
+      jwt = { playerId: verdict.playerId };
+    } else if (credential.kind === "jwt") {
       const issuers = this.config.jwtIssuers;
       if (issuers === void 0 || issuers.length === 0) {
         session.fail("E_AUTH", "this project has no JWT secret \u2014 mint one: irtio keys jwt-secret");
@@ -2142,23 +4057,12 @@ var SupervisorImpl = class {
       }
       jwt = verdict;
     }
-    if (this.bundle) {
-      const known = [...this.deployments.values()].some(
-        (d) => d.bundle !== void 0 && bytesEqual(hello.schemaHash8, d.bundle.hash8)
-      );
-      if (!known) {
-        session.fail("E_SCHEMA_MISMATCH", formatError("E_SCHEMA_MISMATCH"));
-        return;
-      }
-    } else if (!isRelayHash8(hello.schemaHash8)) {
-      session.fail("E_SCHEMA_MISMATCH", "this project has no room code deployed (relay tenant)");
-      return;
-    }
     session.state = "joining";
     session.role = jwt?.role ?? hello.role ?? "";
     session.name = hello.name ?? "";
     session.playerId = jwt?.playerId;
     session.schemaHash8 = hello.schemaHash8;
+    session.schemaSwap = hello.schemaSwap === true;
     let resume;
     if (hello.resumeToken !== void 0 && hello.resumeToken !== "") {
       resume = verifyResume(this.resumeSecret, hello.resumeToken);
@@ -2184,10 +4088,60 @@ var SupervisorImpl = class {
     } else {
       roomId = newRoomCode((code) => this.registry.has(code));
     }
+    const roomType = roomTypeOf(roomId);
+    const typed = this.roomTypes().length > 0;
+    if (typed) {
+      const known = [...this.deployments.values()].some((d) => {
+        const b = d.bundles.get(roomType);
+        return b !== void 0 && bytesEqual(hello.schemaHash8, b.hash8);
+      });
+      if (!known) {
+        if (this.bundleFor(roomType) === void 0) {
+          session.fail(
+            "E_ROOM_NOT_FOUND",
+            `this project has no room type ${JSON.stringify(roomType)}. It defines: ` + this.roomTypes().join(", ")
+          );
+          return;
+        }
+        session.fail(
+          "E_SCHEMA_MISMATCH",
+          `${formatError("E_SCHEMA_MISMATCH")} for room type ${roomType}`
+        );
+        return;
+      }
+    } else if (!isRelayHash8(hello.schemaHash8)) {
+      session.fail("E_SCHEMA_MISMATCH", "this project has no room code deployed (relay tenant)");
+      return;
+    }
     if (jwt?.roomId !== void 0 && jwt.roomId !== roomId) {
       session.fail("E_TOKEN_WRONG_ROOM", formatError("E_TOKEN_WRONG_ROOM"));
       return;
     }
+    if (!session.npc && !this.registry.has(roomId)) {
+      const roomCapRefusal = this.caps.refusal("room_hours");
+      if (roomCapRefusal !== void 0) {
+        session.fail("E_USAGE_CAP", roomCapRefusal);
+        return;
+      }
+      const tierRefusal = this.freeAwakeRoomsRefusal();
+      if (tierRefusal !== void 0) {
+        session.fail("E_TIER_LIMIT", tierRefusal);
+        return;
+      }
+      if (this.egressLease.tripped) {
+        session.failWith(
+          "E_EGRESS_WALL",
+          egressWallMessage(this.caps.plan() ?? "free"),
+          CLOSE_EGRESS_WALL
+        );
+        return;
+      }
+      const awakeRefusal = this.maxAwakeRefusal(roomId);
+      if (awakeRefusal !== void 0) {
+        session.fail("E_TYPE_AT_CAPACITY", awakeRefusal);
+        return;
+      }
+    }
     const room = await this.ensureRoom(roomId);
     if (!room) {
       session.fail("E_INTERNAL", formatError("E_INTERNAL"));
@@ -2202,8 +4156,12 @@ var SupervisorImpl = class {
     session.roomId = roomId;
     let reconnecting = false;
     if (resume) {
-      reconnecting = true;
       const existing = room.clients.get(resume.clientId);
+      if (!existing && resume.iatMs >= room.createdAt) {
+        session.fail("E_RESUME_EXPIRED", formatError("E_RESUME_EXPIRED"));
+        return;
+      }
+      reconnecting = true;
       if (existing && existing !== session) {
         existing.clearGraceTimer();
         existing.state = "gone";
@@ -2216,7 +4174,16 @@ var SupervisorImpl = class {
       session.clientId = resume.clientId;
       if (session.role === "") session.role = resume.role;
     } else {
-      session.clientId = newClientId((id) => this.clientIds.has(id));
+      const forced = session.forcedClientId;
+      if (forced !== void 0) {
+        if (this.clientIds.has(forced)) {
+          session.fail("E_INTERNAL", `npc client id ${forced} is already in use`);
+          return;
+        }
+        session.clientId = forced;
+      } else {
+        session.clientId = newClientId((id) => this.clientIds.has(id));
+      }
     }
     this.clientIds.add(session.clientId);
     room.clients.set(session.clientId, session);
@@ -2232,21 +4199,37 @@ var SupervisorImpl = class {
     if (inFlight) return inFlight;
     const existing = this.registry.get(roomId);
     if (existing) {
-      if (existing.state === "hibernated") await wakeRoom(this, existing);
-      else await existing.transition.catch(() => {
-      });
+      for (; ; ) {
+        if (existing.state === "hibernated" || existing.state === "hibernating") {
+          await wakeRoom(this, existing);
+        } else {
+          await existing.transition.catch(() => {
+          });
+        }
+        const state = existing.state;
+        if (state !== "hibernated" && state !== "hibernating") break;
+      }
       return existing;
     }
     const create = (async () => {
-      const config = this.bundle ? this.bundle.config : relayConfig(this.limits);
-      const room = new RoomRecord(roomId, this.bundle === void 0, config);
+      const relay = this.deployments.size === 0 || this.roomTypes().length === 0;
+      const bundle = relay ? void 0 : this.bundleFor(roomTypeOf(roomId));
+      if (!relay && bundle === void 0) {
+        this.log(
+          "warn",
+          `no room type ${JSON.stringify(roomTypeOf(roomId))} in this project (join of ${roomId}); this project defines: ${this.roomTypes().join(", ")}`
+        );
+        return void 0;
+      }
+      const config = bundle ? bundle.config : relayConfig(this.limits, this.caps.plan());
+      const room = new RoomRecord(roomId, bundle === void 0, config);
       room.version = this.deploymentVersion;
       room.pendingRestoreSaveId = this.pendingRestores.get(roomId);
       this.pendingRestores.delete(roomId);
       this.registry.set(room);
       const restored = await this.loadPendingRestore(room);
-      const found = restored ?? await this.findSnapshot(roomId);
-      const snapshot = found?.bytes;
+      let found = restored ?? await this.findSnapshot(roomId);
+      let snapshot = found?.bytes;
       if (room.relay) {
         room.relayRoom = snapshot ? RelayRoom.restore(snapshot) : RelayRoom.create();
         room.lastTick = room.relayRoom.tick;
@@ -2254,6 +4237,15 @@ var SupervisorImpl = class {
         this.armRelayIdle(room);
         return room;
       }
+      if (found && found.version === 0 && room.version > 0 && isRelayPresenceSnapshot(snapshot)) {
+        this.roomLog(
+          room,
+          "info",
+          `ignoring a relay presence snapshot at v0 for a v${room.version} coded room; a presence list is not room state, so this room starts cold`
+        );
+        snapshot = void 0;
+        found = void 0;
+      }
       if (found && found.version > room.version) {
         this.roomLog(
           room,
@@ -2266,7 +4258,7 @@ var SupervisorImpl = class {
       let migrate;
       if (found && found.version !== room.version) {
         try {
-          migrate = this.migrationChain(found.version, room.version);
+          migrate = this.migrationChain(found.version, room.version, room.roomType);
         } catch (err) {
           this.roomLog(room, "error", "cannot migrate this room", err);
           this.registry.delete(roomId);
@@ -2300,9 +4292,10 @@ var SupervisorImpl = class {
   }
   /** Spawns the worker and waits for `ready`. Leaves the room's state to the caller. */
   async startWorker(room, snapshot, migrate) {
-    const bundle = this.deployments.get(room.version)?.bundle ?? this.bundle;
+    const type = room.roomType;
+    const bundle = this.deployments.get(room.version)?.bundles.get(type) ?? this.bundleFor(type);
     if (!bundle) return false;
-    const worker = new WorkerHost(this.workerEntry, this.limits, {
+    const worker = new WorkerHost(this.workerEntry, this.limitsFor(type), {
       onMessage: (msg) => this.onWorkerMessage(room, msg),
       onDead: (reason) => this.onWorkerDead(room, reason)
     });
@@ -2323,8 +4316,15 @@ var SupervisorImpl = class {
         roomId: room.id,
         bundleUrl: bundle.bundleUrl,
         ...this.config.publicUrl !== void 0 ? { publicUrl: this.config.publicUrl } : {},
-        ...snapshot ? { snapshot } : {},
-        ...migrate ? { migrate } : {}
+        // A copy, because `post` transfers the buffer and the caller may need its bytes again:
+        // `migrateRoom` restarts the old version from the same snapshot when the chain throws,
+        // and posting the detached buffer a second time killed that worker with a
+        // DataCloneError. The crash restart then revived the room from the store, which is how
+        // the containment test passed while an orphaned ready waiter timed out 30 s later.
+        ...snapshot ? { snapshot: new Uint8Array(snapshot) } : {},
+        ...migrate ? { migrate } : {},
+        // D65: `irtio dev --profile` only.
+        ...this.config.profile === true ? { profile: true } : {}
       });
     });
     if (!outcome || outcome.t !== "ready") {
@@ -2338,6 +4338,7 @@ var SupervisorImpl = class {
       return false;
     }
     room.config = outcome.config;
+    room.backfillOpen = true;
     if (outcome.migrated) {
       const m = outcome.migrated;
       this.roomLog(
@@ -2382,6 +4383,8 @@ var SupervisorImpl = class {
         const saveId = await this.saveRoom(room);
         return { ok: true, value: saveId };
       }
+      case "busSend":
+        return this.busSend(room, call.roomId, call.payload);
       case "kvGet": {
         const value = await this.requireKv().get(call.playerId, call.key);
         return value === void 0 ? { ok: true } : { ok: true, value };
@@ -2392,8 +4395,67 @@ var SupervisorImpl = class {
       case "kvDelete":
         await this.requireKv().delete(call.playerId, call.key);
         return { ok: true };
+      case "lbSubmit": {
+        if (!this.roomHoldsPlayer(room, call.playerId)) {
+          return {
+            ok: false,
+            code: LEADERBOARD_ERRORS.notInRoom,
+            message: `${call.playerId} is not a client of room ${room.id}; leaderboard submits are only accepted for players currently in the room`
+          };
+        }
+        await this.requireLeaderboard().submit(call.board, call.playerId, call.score);
+        return { ok: true };
+      }
+      case "ratingReport": {
+        const problem = ratingQueueProblem(call.queue) ?? ratingResultsProblem(call.results);
+        if (problem) return { ok: false, code: problem.code, message: problem.message };
+        for (const r of call.results) {
+          if (!room.hasHeldPlayer(r.playerId)) {
+            return {
+              ok: false,
+              code: RATING_ERRORS.notInRoom,
+              message: `${r.playerId} has never been a client of room ${room.id}; rating reports are only accepted for players this room has actually held`
+            };
+          }
+        }
+        await this.requireRatings().report(call.queue, call.results);
+        return { ok: true };
+      }
+      case "ratingSet": {
+        const problem = ratingQueueProblem(call.queue) ?? ratingPlayerProblem(call.playerId) ?? ratingValueProblem({
+          rating: call.rating,
+          ...call.deviation !== void 0 ? { deviation: call.deviation } : {}
+        });
+        if (problem) return { ok: false, code: problem.code, message: problem.message };
+        if (!room.hasHeldPlayer(call.playerId)) {
+          return {
+            ok: false,
+            code: RATING_ERRORS.notInRoom,
+            message: `${call.playerId} has never been a client of room ${room.id}; a rating may only be set for a player this room has actually held`
+          };
+        }
+        await this.requireRatings().set(call.queue, call.playerId, {
+          rating: call.rating,
+          ...call.deviation !== void 0 ? { deviation: call.deviation } : {}
+        });
+        return { ok: true };
+      }
     }
   }
+  /**
+   * Is `playerId` one of this room's current clients?
+   *
+   * The identity a session answers to is its verified `playerId` when it has one (a JWT or a
+   * platform assertion) and its client id otherwise — the same `ctx.playerId` ladder the room
+   * itself sees, so a room submitting under the id it was handed always passes, and a room
+   * submitting under an id it invented never does.
+   */
+  roomHoldsPlayer(room, playerId) {
+    for (const session of room.clients.values()) {
+      if ((session.playerId ?? session.clientId) === playerId) return true;
+    }
+    return false;
+  }
   requireKv() {
     const kv = this.config.kv;
     if (!kv) {
@@ -2403,6 +4465,24 @@ var SupervisorImpl = class {
     }
     return kv;
   }
+  requireLeaderboard() {
+    const lb = this.config.leaderboard;
+    if (!lb) {
+      throw new LeaderboardUnavailable(
+        "leaderboards are not configured for this tenant (no control plane behind it)"
+      );
+    }
+    return lb;
+  }
+  requireRatings() {
+    const ratings = this.config.ratings;
+    if (!ratings) {
+      throw new RatingUnavailable(
+        "skill ratings are not configured for this tenant (no control plane behind it)"
+      );
+    }
+    return ratings;
+  }
   /**
    * D24: one save generation. Serializes exactly the way hibernation does — same
    * `worker.serialize()`, same bytes, same `putSnapshotWithRetry` durability — writes it under
@@ -2534,54 +4614,382 @@ var SupervisorImpl = class {
     }
   }
   /**
-   * D26: re-arms this room's alarms from the sidecar and starts persisting changes to it.
-   *
-   * Anything already due fires immediately — an alarm is "at or after", never before, and a
-   * tenant that was stopped for an hour owes the room an hour-late alarm rather than nothing.
+   * D26: re-arms this room's alarms from the sidecar and starts persisting changes to it.
+   *
+   * Anything already due fires immediately — an alarm is "at or after", never before, and a
+   * tenant that was stopped for an hour owes the room an hour-late alarm rather than nothing.
+   */
+  async loadAlarms(room) {
+    if (room.relay) return;
+    let persisted = [];
+    try {
+      const bytes = await this.store.get(alarmsKey(this.storeKey(room)));
+      if (bytes) persisted = decodeAlarms(bytes);
+    } catch (err) {
+      this.roomLog(room, "warn", "could not read this room's alarms; starting with none", err);
+    }
+    room.alarms.onChange = () => this.persistAlarms(room);
+    room.alarms.attach((names) => this.deliverAlarms(room, names));
+    if (persisted.length > 0) {
+      room.alarms.load(persisted);
+      const overdue = room.alarms.fireDue();
+      if (overdue.length > 0) {
+        this.roomLog(
+          room,
+          "info",
+          `firing ${overdue.length} overdue alarm(s): ${overdue.join(", ")}`
+        );
+      }
+    }
+  }
+  /**
+   * Delivers due alarms into the room, **waking it first if it is asleep**. This is the whole
+   * hibernated case: the timer kept counting because it lives on the record rather than in the
+   * worker, and the wake is the same one a joining client would have triggered.
+   *
+   * The loop is not defensive padding — it is the fix for a real race that cost an hour to find.
+   * `fireDue` removes an alarm before delivering it, so between the state check and the `await`
+   * the room can slip into hibernation (`hibernateRoom` flips the state synchronously). A single
+   * check-then-await therefore saw `running`, woke up to `hibernated`, and dropped an alarm that
+   * no longer existed anywhere — a round timer that simply never fired, with a warning nobody was
+   * watching. Re-checking after every transition covers the slip, and anything still undeliverable
+   * is **re-armed** rather than discarded: a durable alarm that this process could not deliver is
+   * the next placement's problem, not a lost one.
+   */
+  // -------------------------------------------------------------------------
+  // D59: the bus
+  // -------------------------------------------------------------------------
+  /**
+   * Takes one token from a room's bus budget, or returns the refusal.
+   *
+   * Both verbs draw on the same bucket, on purpose: publish costs a fan-out and send costs a store
+   * write, and a limiter that metered only one of them would be a limiter a room could route
+   * around by choosing the other. This is also the whole of the per-room rate-limit machinery D59
+   * asks for. Every limiter in the supervisor before it was scoped to a connection, an IP or a
+   * project key, and none of them metered what a room asked the host to do.
+   */
+  /**
+   * D59: forget everything a room was subscribed to. Called when a room is gone for good.
+   *
+   * Note what this is NOT called for: hibernation. A hibernated room keeping a subscription entry
+   * is harmless, because `busPublish` posts only to rooms that are `running` with a live worker,
+   * and that liveness check — not this bookkeeping — is what makes "publish reaches awake
+   * subscribers only" true. Doing it here as well would mean chasing eight separate places where a
+   * worker goes away, and getting one wrong would be a silent correctness bug rather than a leak.
+   */
+  busRoomClosed(roomId) {
+    this.bus.unsubscribeAll(roomId);
+  }
+  /** D59: the channels a room currently holds, for `/admin/rooms` and for tests. */
+  busSubscriptionsOf(roomId) {
+    return this.bus.subscriptionsOf(roomId);
+  }
+  busBudget(room, verb) {
+    if (room.busBucket.take()) return void 0;
+    return {
+      code: BUS_ERRORS.rateLimited,
+      message: `room.bus.${verb}: this room is over its bus budget of ${BUS_LIMITS.opsPerSecond} operations per second`
+    };
+  }
+  /**
+   * `room.bus.publish`: fan out to awake subscribers, and nothing else.
+   *
+   * Every refusal here is a log line rather than a value, because the verb is fire-and-forget on
+   * the runtime side and there is nothing to answer. The `from` handed to each subscriber is
+   * `room.id`, the record's own id and not anything the worker supplied, so a room cannot publish
+   * under another room's name.
+   */
+  busPublish(room, channel, payload) {
+    const problem = busChannelProblem(channel) ?? busPayloadProblem(payload) ?? this.busBudget(room, "publish");
+    if (problem) {
+      this.roomLog(room, "warn", `bus.publish: ${problem.code}: ${problem.message}`);
+      return;
+    }
+    for (const id of this.bus.subscribers(channel, room.id)) {
+      const target = this.registry.get(id);
+      if (!target || target.state !== "running" || !target.worker) continue;
+      target.worker.post({ t: "busEvent", channel, from: room.id, payload });
+    }
+  }
+  /**
+   * `room.bus.send`: park a durable, at-least-once message in the target's mailbox.
+   *
+   * The mailbox is the alarm set. Arming for `Date.now()` means `deliverAlarms` picks it up on the
+   * next turn and, the part that makes the feature work at all, wakes the room first if it is
+   * hibernated, because the alarm timer lives on the `RoomRecord` and outlives the worker.
+   *
+   * Refusals are values rather than log lines, unlike publish, because each one is a different
+   * thing for the sender to do: shrink the payload, fix the roomId, back off, or slow down.
+   */
+  async busSend(room, targetId, payload) {
+    const refuse = (p) => ({
+      ok: false,
+      code: p.code,
+      message: p.message
+    });
+    const budget = busPayloadProblem(payload) ?? this.busBudget(room, "send");
+    if (budget) return refuse(budget);
+    const normalized = normalizeRoomId(targetId);
+    const target = normalized === void 0 ? void 0 : this.registry.get(normalized);
+    if (target && target.state !== "closed") {
+      return this.parkLocally(target, room.id, payload, targetId);
+    }
+    if (!this.isSharded() || normalized === void 0) {
+      return refuse({
+        code: BUS_ERRORS.noSuchRoom,
+        message: `no room ${JSON.stringify(targetId)} in this project`
+      });
+    }
+    if (room.alarms.mailboxDepth >= BUS_LIMITS.mailboxDepth) {
+      return refuse({
+        code: BUS_ERRORS.mailboxFull,
+        message: `room ${JSON.stringify(room.id)} has ${BUS_LIMITS.mailboxDepth} undelivered bus messages in its mailbox and outbox; it is not keeping up`
+      });
+    }
+    const name = mintOutboxName(this.mailboxCounter++);
+    const entry = {
+      to: normalized,
+      from: room.id,
+      payload,
+      id: name,
+      firstAt: this.busNow(),
+      attempts: 0
+    };
+    room.alarms.set(name, this.busNow() + this.outboxDelay(0), encodeOutboxEntry(entry));
+    const outcome = await this.forwardOutbox(room, name, entry);
+    switch (outcome) {
+      case "delivered":
+        return { ok: true };
+      case "no-such-room":
+        return refuse({
+          code: BUS_ERRORS.noSuchRoom,
+          message: `no room ${JSON.stringify(targetId)} in this project, on any shard`
+        });
+      case "mailbox-full":
+        room.alarms.set(name, void 0);
+        return refuse({
+          code: BUS_ERRORS.mailboxFull,
+          message: `room ${JSON.stringify(targetId)} has ${BUS_LIMITS.mailboxDepth} undelivered bus messages; it is not keeping up`
+        });
+      default:
+        return { ok: true };
+    }
+  }
+  /** Today's local park-and-wake, factored out so the cross-shard target side can share it. */
+  parkLocally(target, from, payload, targetId) {
+    if (target.relay) {
+      return {
+        ok: false,
+        code: BUS_ERRORS.noSuchRoom,
+        message: `room ${JSON.stringify(targetId)} is a relay room and runs no bus handlers`
+      };
+    }
+    if (target.alarms.mailboxDepth >= BUS_LIMITS.mailboxDepth) {
+      return {
+        ok: false,
+        code: BUS_ERRORS.mailboxFull,
+        message: `room ${JSON.stringify(targetId)} has ${BUS_LIMITS.mailboxDepth} undelivered bus messages; it is not keeping up`
+      };
+    }
+    const entry = { from, payload, attempts: 0 };
+    target.alarms.set(
+      mintMailboxName(this.mailboxCounter++),
+      Date.now(),
+      encodeMailboxEntry(entry)
+    );
+    return { ok: true };
+  }
+  /** D67-e: the clock the outbox stamps and ages by; injected so the hour is tested, not waited. */
+  busNow() {
+    return this.config.busClock?.() ?? Date.now();
+  }
+  /** D67-e: the retry schedule, injectable for the same reason the clock is. */
+  outboxDelay(attempts) {
+    return this.config.busRetryDelayMs?.(attempts) ?? outboxRetryDelayMs(attempts);
+  }
+  /**
+   * Whether the store holds anything for `roomId`: its live key, an `@v<N>` key, or anything
+   * under `<key>/` (the alarm sidecar, saves). The listing is by prefix, so `abc` would match
+   * `abcd`'s keys without the filter, which is the same filter control's directory applies.
+   */
+  async roomExistsInStore(roomId) {
+    const base = `${this.config.projectId}/${roomId}`;
+    try {
+      const keys = await this.store.list(base);
+      return keys.some((k) => k === base || k.startsWith(`${base}@v`) || k.startsWith(`${base}/`));
+    } catch {
+      return false;
+    }
+  }
+  /**
+   * One forward of an outbox entry through the control plane. Answers what the sender should
+   * conclude: `delivered` and `no-such-room` drop the entry, `mailbox-full` is the target's
+   * answer, and `retry` (the target's shard is starting, the hop failed) leaves the entry armed.
+   */
+  async forwardOutbox(room, name, entry) {
+    const client = this.config.shardClient;
+    if (!client) {
+      this.roomLog(
+        room,
+        "warn",
+        `bus.send to ${entry.to}: no shard client on this tenant; will retry`
+      );
+      return "retry";
+    }
+    try {
+      const result = await client.send({
+        shard: this.config.shard ?? 0,
+        to: entry.to,
+        from: entry.from,
+        payload: entry.payload,
+        id: entry.id
+      });
+      if (result.ok) {
+        room.alarms.set(name, void 0);
+        return "delivered";
+      }
+      if (result.code === BUS_ERRORS.noSuchRoom) {
+        room.alarms.set(name, void 0);
+        return "no-such-room";
+      }
+      if (result.code === BUS_ERRORS.mailboxFull) return "mailbox-full";
+      return "retry";
+    } catch (err) {
+      this.roomLog(
+        room,
+        "warn",
+        `bus.send to ${entry.to} could not be forwarded (attempt ${entry.attempts + 1}); will retry`,
+        err
+      );
+      return "retry";
+    }
+  }
+  /**
+   * An outbox entry's alarm came due: forward it again, or dead-letter it. Runs on the record,
+   * whatever the room's state, and never wakes the room: a retry is a host call, not room code,
+   * so a hibernated sender stays asleep and is not billed for its own outbox.
    */
-  async loadAlarms(room) {
-    if (room.relay) return;
-    let persisted = [];
-    try {
-      const bytes = await this.store.get(alarmsKey(this.storeKey(room)));
-      if (bytes) persisted = decodeAlarms(bytes);
-    } catch (err) {
-      this.roomLog(room, "warn", "could not read this room's alarms; starting with none", err);
+  retryOutbox(room, name, raw) {
+    const entry = decodeOutboxEntry(raw);
+    if (!entry) {
+      this.roomLog(room, "warn", `dropping an unreadable bus outbox entry (${name})`);
+      return;
     }
-    room.alarms.onChange = () => this.persistAlarms(room);
-    room.alarms.attach((names) => this.deliverAlarms(room, names));
-    if (persisted.length > 0) {
-      room.alarms.load(persisted);
-      const overdue = room.alarms.fireDue();
-      if (overdue.length > 0) {
+    const now = this.busNow();
+    if (now - entry.firstAt >= BUS_OUTBOX2.ttlMs) {
+      this.roomLog(
+        room,
+        "warn",
+        `a bus message to ${JSON.stringify(entry.to)} could not be delivered across shards in ${entry.attempts} attempt(s) over an hour and has been dropped (${entry.id})`
+      );
+      return;
+    }
+    const next = { ...entry, attempts: entry.attempts + 1 };
+    room.alarms.set(name, now + this.outboxDelay(next.attempts), encodeOutboxEntry(next));
+    void this.forwardOutbox(room, name, next).then((outcome) => {
+      if (outcome === "mailbox-full") {
         this.roomLog(
           room,
           "info",
-          `firing ${overdue.length} overdue alarm(s): ${overdue.join(", ")}`
+          `bus.send to ${entry.to}: the target's mailbox is full; will retry`
         );
       }
+    });
+  }
+  /**
+   * D67-e, the target side: `POST /admin/bus/deliver` from the host agent, carrying a message
+   * the control plane forwarded from another shard. Load-if-exists, then today's local park; never
+   * `ensureRoom` from nothing, because a room the directory did not place here is not this
+   * shard's to create. A message whose `id` this room has seen before is delivered again (a lost
+   * acknowledgement, at-least-once) and the duplicate is logged by name.
+   */
+  async deliverForwarded(message) {
+    const normalized = normalizeRoomId(message.to);
+    if (normalized === void 0) {
+      return {
+        ok: false,
+        code: BUS_ERRORS.noSuchRoom,
+        message: `no room ${JSON.stringify(message.to)}`
+      };
+    }
+    let target = this.registry.get(normalized);
+    if ((!target || target.state === "closed") && await this.roomExistsInStore(normalized)) {
+      target = await this.ensureRoom(normalized);
+    }
+    if (!target || target.state === "closed") {
+      return {
+        ok: false,
+        code: BUS_ERRORS.noSuchRoom,
+        message: `no room ${JSON.stringify(message.to)} on this shard`
+      };
+    }
+    if (target.busSeen.has(message.id)) {
+      this.roomLog(
+        target,
+        "warn",
+        `duplicate bus delivery ${message.id} from ${message.from}; delivering again`
+      );
+    } else {
+      target.busSeen.add(message.id);
+      if (target.busSeen.size > BUS_SEEN_MAX) {
+        const oldest = target.busSeen.values().next().value;
+        if (oldest !== void 0) target.busSeen.delete(oldest);
+      }
     }
+    return this.parkLocally(target, message.from, message.payload, message.to);
   }
   /**
-   * Delivers due alarms into the room, **waking it first if it is asleep**. This is the whole
-   * hibernated case: the timer kept counting because it lives on the record rather than in the
-   * worker, and the wake is the same one a joining client would have triggered.
+   * Delivers one mailbox entry, or bounds and drops it.
    *
-   * The loop is not defensive padding — it is the fix for a real race that cost an hour to find.
-   * `fireDue` removes an alarm before delivering it, so between the state check and the `await`
-   * the room can slip into hibernation (`hibernateRoom` flips the state synchronously). A single
-   * check-then-await therefore saw `running`, woke up to `hibernated`, and dropped an alarm that
-   * no longer existed anywhere — a round timer that simply never fired, with a warning nobody was
-   * watching. Re-checking after every transition covers the slip, and anything still undeliverable
-   * is **re-armed** rather than discarded: a durable alarm that this process could not deliver is
-   * the next placement's problem, not a lost one.
+   * The attempt counter is incremented *before* delivery and persisted with the entry, so a
+   * message whose handler kills the room still counts the attempt. Counting after a successful
+   * delivery would count nothing at all in exactly the case the bound exists for.
    */
-  deliverAlarms(room, names) {
+  deliverMailbox(room, name, raw) {
+    const entry = decodeMailboxEntry(raw);
+    if (!entry) {
+      this.roomLog(room, "warn", `dropping an unreadable bus mailbox entry (${name})`);
+      return;
+    }
+    const attempts = entry.attempts + 1;
+    if (attempts > BUS_LIMITS.maxDeliveryAttempts) {
+      this.roomLog(
+        room,
+        "error",
+        `a bus message from ${JSON.stringify(entry.from)} could not be delivered in ${BUS_LIMITS.maxDeliveryAttempts} attempts and has been dropped`
+      );
+      return;
+    }
+    if (room.state === "running" && room.worker) {
+      room.alarms.set(
+        name,
+        Date.now() + BUS_LIMITS.redeliveryDelayMs,
+        encodeMailboxEntry({ ...entry, attempts })
+      );
+      room.worker.post({ t: "busMessage", name, from: entry.from, payload: entry.payload });
+      return;
+    }
+    room.alarms.set(name, Date.now(), encodeMailboxEntry({ ...entry, attempts }));
+  }
+  deliverAlarms(room, allNames) {
+    const names = [];
+    for (const name of allNames) {
+      if (isOutboxAlarm(name)) this.retryOutbox(room, name, room.alarms.payloadOf(name));
+      else names.push(name);
+    }
+    if (names.length === 0) return;
+    const mailboxPayloads = /* @__PURE__ */ new Map();
+    for (const name of names) {
+      if (isMailboxAlarm(name)) mailboxPayloads.set(name, room.alarms.payloadOf(name));
+    }
     void (async () => {
       for (let attempt = 0; attempt < 4; attempt++) {
         if (room.state === "closed") return;
         if (room.state === "running" && room.worker) {
-          for (const name of names) room.worker.post({ t: "alarm", name });
+          for (const name of names) {
+            if (isMailboxAlarm(name)) this.deliverMailbox(room, name, mailboxPayloads.get(name));
+            else room.worker.post({ t: "alarm", name });
+          }
           return;
         }
         if (room.state === "hibernated") {
@@ -2597,7 +5005,10 @@ var SupervisorImpl = class {
         `alarm(s) ${names.join(", ")} came due while the room was ${room.state}; re-armed for the next start rather than dropped`
       );
       const now = Date.now();
-      for (const name of names) room.alarms.set(name, now);
+      for (const name of names) {
+        if (isMailboxAlarm(name)) this.deliverMailbox(room, name, mailboxPayloads.get(name));
+        else room.alarms.set(name, now);
+      }
     })();
   }
   /**
@@ -2672,9 +5083,11 @@ var SupervisorImpl = class {
   closeRoom(room, code, message) {
     if (room.state === "closed") return;
     room.state = "closed";
+    this.npcs.despawnRoom(room.id);
     this.clearRoomTimer(room);
     room.alarms.detach();
     room.alarms.onChange = void 0;
+    this.busRoomClosed(room.id);
     for (const session of [...room.clients.values()]) {
       session.fatal = true;
       session.sendError(code, message, true);
@@ -2699,22 +5112,45 @@ var SupervisorImpl = class {
   async joinBundle(room, session, reconnecting) {
     const outcome = await this.requestJoin(room, session, reconnecting);
     if (!outcome) {
+      session.pendingOut.length = 0;
       session.fail("E_INTERNAL", "the room did not answer the join");
       return;
     }
     if (outcome.t === "joinRejected") {
+      session.pendingOut.length = 0;
       room.clients.delete(session.clientId);
       this.clientIds.delete(session.clientId);
       session.fail(outcome.code, outcome.reason ?? formatError(outcome.code, { roomId: room.id }));
       return;
     }
-    if (!session.open) return;
+    if (!session.open) {
+      session.pendingOut.length = 0;
+      session.state = "gone";
+      if (room.clients.get(session.clientId) === session) room.clients.delete(session.clientId);
+      this.clientIds.delete(session.clientId);
+      const reason = session.fatal ? "kicked" : "timeout";
+      if (room.state === "running" && room.worker) {
+        room.worker.post({ t: "leave", clientId: session.clientId, reason });
+      } else if (room.state !== "closed") {
+        room.pendingLeaves.add(session.clientId);
+      }
+      return;
+    }
     session.role = outcome.role;
     session.state = "joined";
+    room.notePlayerSeen(session.playerId ?? session.clientId);
     if (outcome.tick > room.lastTick) room.lastTick = outcome.tick;
     room.metrics.connections++;
     room.metrics.totalConnections++;
+    if (session.npc) room.metrics.npcConnections++;
     this.sendWelcome(session, outcome.tick, outcome.snapshot);
+    for (const bytes of session.pendingOut.splice(0)) {
+      const sent = session.send(bytes);
+      if (sent > 0) {
+        room.metrics.egressBytes += sent;
+        room.metrics.framesOut++;
+      }
+    }
   }
   requestJoin(room, session, reconnecting) {
     const worker = room.worker;
@@ -2737,43 +5173,53 @@ var SupervisorImpl = class {
         ...session.name !== "" ? { name: session.name } : {},
         // D27: the verified JWT subject; absent for key joins (playerId stays the client id).
         ...session.playerId !== void 0 ? { playerId: session.playerId } : {},
-        ...reconnecting ? { reconnecting: true } : {}
+        ...reconnecting ? { reconnecting: true } : {},
+        ...session.npc ? { npc: true } : {}
       });
     });
   }
+  /**
+   * D66: the admission decision now lives in `relay-host.ts`, so the process that will serve
+   * relay-only tenants without a VM runs the same code. What stays here is what is the
+   * *supervisor's* and not a relay's: the session registries, the welcome frame, and the idle
+   * timer that leads to hibernation.
+   */
   joinRelay(room, session, _reconnecting) {
     const relay = room.relayRoom;
     if (!relay) {
       session.fail("E_INTERNAL", formatError("E_INTERNAL"));
       return;
     }
-    if (!relay.has(session.clientId) && relay.size >= room.config.maxClients) {
+    const outcome = relayJoin(relayHostRoomFor(this, room), session);
+    if (!outcome.ok) {
       room.clients.delete(session.clientId);
       this.clientIds.delete(session.clientId);
-      session.fail("E_ROOM_FULL", formatError("E_ROOM_FULL", { roomId: room.id }));
+      session.fail(outcome.code, formatError(outcome.code, { roomId: room.id }));
       return;
     }
-    const delta = relay.add(session.clientId, session.role, session.name);
-    room.lastTick = relay.tick;
+    room.lastTick = outcome.tick;
     session.state = "joined";
+    room.notePlayerSeen(session.playerId ?? session.clientId);
     room.metrics.connections++;
     room.metrics.totalConnections++;
-    this.sendWelcome(session, relay.tick, relay.snapshot());
-    this.broadcast(room, encodeFrame2(FrameType2.DELTA, delta), session.clientId);
+    this.sendWelcome(session, outcome.tick, outcome.snapshot);
+    this.broadcast(room, encodeFrame3(FrameType3.DELTA, outcome.delta), session.clientId);
     this.armRelayIdle(room);
   }
   /** `WELCOME` with a fresh resume token — also used as the resync after a wake/restart. */
   sendWelcome(session, tick, snapshot) {
     const room = session.room;
     if (!room) return;
+    const now = Date.now();
     const resumeToken = signResume(this.resumeSecret, {
       clientId: session.clientId,
       roomId: room.id,
       role: session.role,
-      expMs: Date.now() + room.config.reconnectGraceMs
+      expMs: now + RESUME_TOKEN_TTL_MS,
+      iatMs: now
     });
-    const bytes = encodeFrame2(
-      FrameType2.WELCOME,
+    const bytes = encodeFrame3(
+      FrameType3.WELCOME,
       encodeWelcome({
         clientId: session.clientId,
         role: session.role,
@@ -2781,8 +5227,11 @@ var SupervisorImpl = class {
         snapshot,
         resumeToken,
         roomId: room.id,
-        // 0 for a relay room (tickRate 0): "unknown" — the client falls back to its 50 ms floor.
-        tickIntervalMs: room.config.tickRate > 0 ? Math.round(1e3 / room.config.tickRate) : 0
+        // 0 for a relay room: "unknown" — the client falls back to its 50 ms floor.
+        tickRate: room.config.tickRate,
+        // Always meaningful: bundle rooms default to 64 (@irtio/server DEFAULTS) and relay rooms
+        // come from SupervisorLimits.relayMaxClients, so unlike tickRate this is never 0/unset.
+        maxClients: room.config.maxClients
       })
     );
     const sent = session.send(bytes);
@@ -2798,17 +5247,31 @@ var SupervisorImpl = class {
    * the new client, instead of feeding it bytes it will mis-decode. Clients already on the new
    * schema (the page reloaded after the client shipped) rejoin normally.
    */
-  failOutdatedSessions(room, version) {
-    const hash8 = this.deployments.get(version)?.bundle?.hash8;
-    if (!hash8) return;
+  failOutdatedSessions(room, version, fromVersion) {
+    const type = room.roomType;
+    const target = this.deployments.get(version);
+    const targetBundle = target?.bundles.get(type);
+    const hash8 = targetBundle?.hash8;
+    if (!hash8 || !target) return 0;
+    const from = fromVersion !== void 0 ? this.deployments.get(fromVersion) : void 0;
+    const fromSchemaJson = from?.bundles.get(type)?.schemaJson;
+    const targetSchemaJson = targetBundle.schemaJson;
+    const swappable = fromSchemaJson !== void 0 && isAdditiveMigration(fromSchemaJson, targetSchemaJson);
+    let swapped = 0;
     for (const session of room.connected()) {
-      if (session.schemaHash8 !== void 0 && !bytesEqual(session.schemaHash8, hash8)) {
-        session.fail(
-          "E_SCHEMA_MISMATCH",
-          "the room migrated to a newer deployment; reconnect with an updated client"
-        );
+      if (session.schemaHash8 === void 0 || bytesEqual(session.schemaHash8, hash8)) continue;
+      if (swappable && session.schemaSwap) {
+        session.sendFrame(FrameType3.SCHEMA, schemaPayload(targetSchemaJson));
+        session.schemaHash8 = hash8;
+        swapped++;
+        continue;
       }
+      session.fail(
+        "E_SCHEMA_MISMATCH",
+        "the room migrated to a newer deployment; reconnect with an updated client"
+      );
     }
+    return swapped;
   }
   /** Re-joins every still-connected socket after a wake or a crash restart, with a resync WELCOME. */
   async rejoinAll(room) {
@@ -2861,23 +5324,33 @@ var SupervisorImpl = class {
       this.badFrame(session, "unknown frame type");
       return;
     }
-    if (type === FrameType2.PING) {
+    if (type === FrameType3.PING) {
       let t = 0;
       try {
         t = decodePing(payload).t;
       } catch {
       }
-      const sent = session.sendFrame(FrameType2.PONG, encodePong({ t, serverTick: room.lastTick }));
+      const sent = session.sendFrame(FrameType3.PONG, encodePong({ t, serverTick: room.lastTick }));
       if (sent > 0) {
         room.metrics.egressBytes += sent;
         room.metrics.framesOut++;
       }
       return;
     }
-    if (type === FrameType2.LEAVE) {
+    if (type === FrameType3.LEAVE) {
       this.handleLeaveFrame(session);
       return;
     }
+    if (type === FrameType3.MSG && this.bandwidth.engaged) {
+      if (this.bandwidth.takeWarning(room.id)) {
+        this.roomLog(room, "warn", bandwidthWarning(this.caps.plan() ?? "free"));
+      }
+      return;
+    }
+    if (type === FrameType3.MSG && isVoiceMsg(payload)) {
+      this.handleVoiceFrame(room, session, payload.subarray(1));
+      return;
+    }
     if (room.relay) {
       this.relayFrame(room, session, type, payload);
       return;
@@ -2916,43 +5389,81 @@ var SupervisorImpl = class {
     } catch {
     }
   }
+  /**
+   * D66: the forwarding rules now live in `relay-host.ts` — see that module for why. What stays
+   * here is the supervisor's half of a refusal (`badFrame` closes the connection its own way) and
+   * the idle timer.
+   */
   relayFrame(room, session, type, payload) {
-    const relay = room.relayRoom;
-    if (!relay) return;
-    if (type !== FrameType2.MSG) {
-      this.badFrame(session, "relay rooms accept MSG only (no room code is deployed)");
+    if (!room.relayRoom) return;
+    const outcome = relayForward(relayHostRoomFor(this, room), session, type, payload);
+    if (!outcome.ok) {
+      this.badFrame(session, outcome.reason);
       return;
     }
-    let target;
-    let body;
-    try {
-      const msg = decodeMsg(payload);
-      target = msg.target;
-      body = msg.payload;
-    } catch {
-      this.badFrame(session, "malformed MSG");
+    this.armRelayIdle(room);
+  }
+  /**
+   * D51: one intercepted voice-signaling message. Never reaches room code — see the interception
+   * in `routeFrame` and the module note on `VoiceRelay`.
+   *
+   * The supervisor's contribution here is deliberately thin: identity (which project, room and
+   * client this is, and whether it is an NPC) and a way back to the socket. It does not parse the
+   * message, so no signaling shape is pinned inside the tenant boundary.
+   */
+  handleVoiceFrame(room, session, message) {
+    const relay = this.config.voice;
+    if (!relay) {
+      this.sendVoice(
+        session,
+        encodeVoiceMessage({
+          t: "error",
+          code: "E_VOICE_UNAVAILABLE",
+          message: "voice is not configured for this tenant"
+        })
+      );
       return;
     }
-    if (target.kind === "server") {
-      this.badFrame(session, "relay rooms have no server to address");
-      return;
+    if (!session.npc) {
+      const voiceCapRefusal = this.caps.refusal("voice_minutes");
+      if (voiceCapRefusal !== void 0 && decodeVoiceMessage(message)?.t === "join") {
+        this.sendVoice(
+          session,
+          encodeVoiceMessage({ t: "error", code: "E_USAGE_CAP", message: voiceCapRefusal })
+        );
+        return;
+      }
     }
-    const out = encodeFrame2(
-      FrameType2.MSG,
-      encodeMsg({ target: { kind: "client", clientId: session.clientId }, payload: body })
+    const ctx = {
+      projectId: this.config.projectId,
+      roomId: room.id,
+      clientId: session.clientId,
+      npc: session.npc
+    };
+    void relay.signal(ctx, message, (reply) => this.sendVoice(session, reply)).catch((err) => {
+      this.log("warn", `voice relay failed for ${session.clientId}: ${String(err)}`);
+      this.sendVoice(
+        session,
+        encodeVoiceMessage({
+          t: "error",
+          code: "E_VOICE_FAILED",
+          message: "voice signaling failed"
+        })
+      );
+    });
+  }
+  /** Writes one voice message back to a single client, inside its `{ kind: 'voice' }` envelope. */
+  sendVoice(session, message) {
+    if (session.state !== "joined") return;
+    const sent = session.sendFrame(
+      FrameType3.MSG,
+      encodeMsg2({ target: { kind: "voice" }, payload: message })
     );
-    for (const peer of room.clients.values()) {
-      if (peer === session || peer.state !== "joined") continue;
-      if (target.kind === "client" && peer.clientId !== target.clientId) continue;
-      if (target.kind === "role" && peer.role !== target.role) continue;
-      const sent = peer.send(out);
-      if (sent > 0) {
-        room.metrics.egressBytes += sent;
-        room.metrics.framesOut++;
-      }
+    const room = session.room;
+    if (sent > 0 && room) {
+      room.metrics.egressBytes += sent;
+      room.metrics.framesOut++;
     }
-    room.lastTick = relay.advance();
-    this.armRelayIdle(room);
   }
   badFrame(session, message) {
     session.badFrameStrikes++;
@@ -2986,7 +5497,30 @@ var SupervisorImpl = class {
       case "send": {
         noteTick(room, msg.bytes);
         const session = room.clients.get(msg.clientId);
-        if (!session || session.state !== "joined") return;
+        if (!session) {
+          if (!room.unknownSendWarned.has(msg.clientId)) {
+            room.unknownSendWarned.add(msg.clientId);
+            this.roomLog(
+              room,
+              "warn",
+              `dropped a ${frameName(msg.bytes)} frame for unknown client ${msg.clientId}`
+            );
+          }
+          return;
+        }
+        if (session.state === "joining") {
+          if (session.pendingOut.length < HELD_FRAMES_MAX) {
+            session.pendingOut.push(msg.bytes);
+          } else if (session.droppedHeld++ === 0) {
+            this.roomLog(
+              room,
+              "warn",
+              `dropped a ${frameName(msg.bytes)} frame for ${msg.clientId}: more than ${HELD_FRAMES_MAX} frames sent while it was still joining`
+            );
+          }
+          return;
+        }
+        if (session.state !== "joined") return;
         const sent = session.send(msg.bytes);
         if (sent > 0) {
           room.metrics.egressBytes += sent;
@@ -3008,14 +5542,58 @@ var SupervisorImpl = class {
         );
         return;
       case "sleep":
+        this.npcs.despawnRoom(room.id);
         void hibernateRoom(this, room);
         return;
       case "hostCall":
         void this.runHostCall(room, msg.reqId, msg.call);
         return;
+      case "setBackfill":
+        room.backfillOpen = msg.open;
+        return;
       case "setAlarm":
+        if (isMailboxAlarm(msg.name)) {
+          this.roomLog(
+            room,
+            "warn",
+            `refusing to arm ${JSON.stringify(msg.name)}: names beginning with ${JSON.stringify(BUS_MAILBOX_PREFIX2)} belong to the bus`
+          );
+          return;
+        }
         room.alarms.set(msg.name, msg.atMs);
         return;
+      case "busPublish":
+        this.busPublish(room, msg.channel, msg.payload);
+        return;
+      case "busSubscribe": {
+        if (!msg.subscribed) {
+          this.bus.unsubscribe(room.id, msg.channel);
+          return;
+        }
+        const problem = this.busBudget(room, "subscribe") ?? this.bus.subscribe(room.id, msg.channel);
+        if (problem) {
+          this.roomLog(room, "warn", `bus.subscribe: ${problem.code}: ${problem.message}`);
+        }
+        return;
+      }
+      case "spawnNpc": {
+        const definition = this.deployments.get(room.version)?.bundle?.definition;
+        if (!definition) {
+          this.roomLog(room, "error", "irtio: spawnNPC needs a room bundle; none is loaded");
+          return;
+        }
+        this.npcs.spawn(room.id, definition, msg.clientId, msg.config);
+        return;
+      }
+      case "despawnNpc":
+        this.npcs.despawn(msg.clientId);
+        return;
+      case "busAck":
+        room.alarms.set(msg.name, void 0);
+        return;
+      case "stats":
+        if (msg.physicsStepped === true) this.notePhysicsWarm();
+        return;
       case "log":
         room.log(msg.level, ...msg.args);
         return;
@@ -3029,6 +5607,11 @@ var SupervisorImpl = class {
   /** Worker died: restart from the latest snapshot and resync everyone (plan §3.3). */
   onWorkerDead(room, reason) {
     if (room.state === "closed" || this.closing) return;
+    const initializing = this.readyWaiters.get(room);
+    if (initializing) {
+      initializing({ t: "initFailed", reason });
+      return;
+    }
     this.roomLog(room, "error", `worker died (${reason}); restarting`);
     room.worker = void 0;
     room.metrics.restarts++;
@@ -3127,8 +5710,72 @@ var SupervisorImpl = class {
     };
   }
   logs(roomId) {
+    if (roomId === TENANT_ROOM_ID) return this.tenantLogs.list();
     return this.registry.get(roomId)?.logs.list() ?? [];
   }
+  /**
+   * D36: pull every live room's tick counters out of its worker and into `RoomMetrics`.
+   *
+   * The counters exist already — `RoomCore.stats.overruns` has been incremented next to the
+   * `tick overrun` log line since week 2 — but they never left the worker thread, so the one
+   * signal that says "this room is shedding work" reached nothing a client, a CLI or an operator
+   * could read. Every `overruns` a report shows now came through here.
+   *
+   * A room that does not answer is left exactly as it was, with `overruns` still `undefined` if
+   * it has never answered. That is the whole point of the field being optional: `tick-health`
+   * reports `unavailable` for it, rather than a zero nobody measured.
+   */
+  async refreshTickHealth(timeoutMs = 2e3) {
+    const live = this.registry.values().filter((r) => r.worker?.alive === true);
+    const answered = await Promise.all(
+      live.map(async (room) => {
+        const msg = await room.worker?.statsMessage(timeoutMs);
+        if (!msg) return void 0;
+        const stats = msg.stats;
+        room.metrics.ticks = stats.ticks;
+        room.metrics.maxTickMs = stats.maxTickMs;
+        room.metrics.overruns = stats.overruns;
+        if (msg.heap !== void 0) {
+          this.recordHeap(room, msg.heap.usedBytes, msg.heap.limitBytes);
+        }
+        if (msg.profile !== void 0) room.profile = msg.profile;
+        if (msg.physicsStepped === true) this.notePhysicsWarm();
+        return room.id;
+      })
+    );
+    return answered.filter((id) => id !== void 0);
+  }
+  /**
+   * D55 step 2: the per-room heap reading, plus the warning that is the whole point of taking it.
+   *
+   * Before this, the first signal a developer got that a room was too big for its VM was the
+   * tenant dying. The warning fires once per crossing of `HEAP_WARN_FRACTION` rather than on
+   * every poll, and re-arms when the room drops back under the line, so a room that sits at 85%
+   * says so once instead of filling the ring the operator would read it from. Room-scoped
+   * (`roomLog`), because "which room" is the actionable half.
+   */
+  recordHeap(room, usedBytes, limitBytes) {
+    room.metrics.heapUsedBytes = usedBytes;
+    room.metrics.heapLimitBytes = limitBytes;
+    const capBytes = this.limits.workerMaxOldGenMb * 1024 * 1024;
+    if (capBytes <= 0) return;
+    const fraction = usedBytes / capBytes;
+    if (fraction >= HEAP_WARN_FRACTION) {
+      if (!room.heapWarned) {
+        room.heapWarned = true;
+        const usedMb = Math.round(usedBytes / (1024 * 1024));
+        const limitMb = this.limits.workerMaxOldGenMb;
+        const pct = Math.round(fraction * 100);
+        this.roomLog(
+          room,
+          "warn",
+          `room heap at ${pct}% of its worker cap (${usedMb} MB of ${limitMb} MB); past the cap the worker is killed and the room restarts, and three restarts in a minute close it`
+        );
+      }
+      return;
+    }
+    room.heapWarned = false;
+  }
   async inspect(roomId) {
     const room = this.registry.get(roomId);
     if (!room) return void 0;
@@ -3152,6 +5799,34 @@ var SupervisorImpl = class {
       rss: inspected.rss
     };
   }
+  /**
+   * D41: arm a room's timeline recorder. Bundle rooms only: a relay room has no schema and no
+   * authority over its state, so there is nothing authoritative to record, and answering `false`
+   * is more honest than handing back an empty recording that would read as "nothing happened".
+   */
+  async startTimeline(roomId, options = {}) {
+    const room = this.registry.get(roomId);
+    if (!room?.worker || room.state !== "running") return false;
+    return room.worker.startTimeline(options);
+  }
+  async readTimeline(roomId) {
+    const room = this.registry.get(roomId);
+    if (!room?.worker || room.state !== "running") return void 0;
+    return room.worker.timeline();
+  }
+  /**
+   * D43: a save generation, and its bytes. `saveRoom` writes it (same serialization, same
+   * retention, same durability as `room.save()`), and the object is then read straight back out
+   * of the store, so what a truth-seam diff decodes is the stored artifact rather than a copy of
+   * it made on the way past.
+   */
+  async saveNow(roomId) {
+    const room = this.registry.get(roomId);
+    if (!room?.worker || room.state !== "running") return void 0;
+    const saveId = await this.saveRoom(room);
+    const bytes = await this.store.get(saveKey(this.storeKey(room), saveId));
+    return bytes ? { saveId, bytes } : void 0;
+  }
   /**
    * Ops/test hook: hard-kill a room's worker. The room takes the normal §3.3 crash path (restore
    * from the latest snapshot, resync everyone, restart cap). `false` when the room has no worker.
@@ -3167,14 +5842,19 @@ function header(v) {
   if (v === void 0) return void 0;
   return Array.isArray(v) ? v[0] : v;
 }
+function frameName(bytes) {
+  const type = bytes[0];
+  for (const [name, value] of Object.entries(FrameType3)) if (value === type) return name;
+  return `type ${String(type)}`;
+}
 function noteTick(room, bytes) {
   if (bytes.length < 5) return;
   const type = bytes[0];
-  if (type !== FrameType2.DELTA && type !== FrameType2.CORRECT) return;
+  if (type !== FrameType3.DELTA && type !== FrameType3.CORRECT) return;
   const tick = new DataView(bytes.buffer, bytes.byteOffset + 1, 4).getUint32(0, true);
   if (tick > room.lastTick) room.lastTick = tick;
 }
-async function loadBundle(bundlePath, version) {
+async function loadBundle(bundlePath, version, type) {
   const bundleUrl = bundlePath.startsWith("file:") ? bundlePath : pathToFileURL2(bundlePath).href;
   let mod;
   try {
@@ -3191,6 +5871,7 @@ async function loadBundle(bundlePath, version) {
   const config = definition.config;
   return {
     version,
+    type,
     definition,
     schemaHash: definition.schema.hash,
     hash8: definition.schema.hash8,
@@ -3200,7 +5881,17 @@ async function loadBundle(bundlePath, version) {
       tickRate: config.tickRate,
       idleMs: config.idleMs,
       reconnectGraceMs: config.reconnectGraceMs,
-      maxClients: config.maxClients
+      maxClients: config.maxClients,
+      // D47: the engine dimension for room-hours. Additive and read-only — the supervisor never
+      // acts on it, it only reports it so part 3 can price the physics multiplier.
+      ...typeof config.physics?.engine === "string" ? { engine: config.physics.engine } : {},
+      // D58: the declared worker heap for this type. Absent means the tenant's derived default,
+      // which is what every room got before types existed.
+      ...typeof config.memoryMb === "number" ? { memoryMb: config.memoryMb } : {},
+      // M5 part 3.5: the declared concurrency. Enforced (`startRoom` refuses room N+1), not
+      // reported — the VM was sized on the strength of this number, so a room past it is a room
+      // the machine was never built to hold.
+      ...typeof config.maxAwake === "number" ? { maxAwake: config.maxAwake } : {}
     },
     bundleUrl,
     schemaJson: definition.schema.canonical
@@ -3402,40 +6093,8 @@ function resolveEntry(cwd, room) {
   create one (export default defineRoom(schema, {...})) or pass --room <file>`
   );
 }
-async function readProjectId(cwd) {
-  const file = path.join(cwd, "irtio.json");
-  if (!existsSync(file)) return "dev";
-  let parsed;
-  try {
-    parsed = JSON.parse(await readFile(file, "utf8"));
-  } catch (err) {
-    throw new Error(`irtio dev: ${file} is not valid JSON: ${String(err)}`);
-  }
-  const project = parsed?.project;
-  if (project === void 0) return "dev";
-  if (typeof project !== "string" || project.length === 0) {
-    throw new Error(`irtio dev: ${file} has a "project" that is not a non-empty string`);
-  }
-  return project;
-}
-async function readClientEntry(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 (err) {
-    throw new Error(`irtio dev: ${file} is not valid JSON: ${String(err)}`);
-  }
-  const client = parsed?.client;
-  if (client === void 0) return void 0;
-  if (typeof client !== "string" || client.length === 0) {
-    throw new Error(`irtio dev: ${file} has a "client" that is not a non-empty string`);
-  }
-  return client;
-}
-async function warnIfClientImportsRoom(cwd, entry, log) {
-  const client = await readClientEntry(cwd);
+async function warnIfClientImportsRoom(cwd, entry, config, log) {
+  const client = config.client;
   if (client === void 0) return;
   const clientFile = path.resolve(cwd, client);
   if (await clientImportsRoom(clientFile, entry)) {
@@ -3446,20 +6105,18 @@ async function warnIfClientImportsRoom(cwd, entry, log) {
     );
   }
 }
-function rapierAbsolutePlugin(fromPackageDir) {
+function engineAbsolutePlugin(fromPackageDir, pkg) {
   let resolved;
   try {
-    resolved = createRequire(path.join(fromPackageDir, "package.json")).resolve(
-      "@dimforge/rapier3d-compat"
-    );
+    resolved = createRequire(path.join(fromPackageDir, "package.json")).resolve(pkg);
   } catch {
     return void 0;
   }
   const specifier = pathToFileURL3(resolved).href;
   return {
-    name: "irtio-dev-rapier-absolute",
+    name: `irtio-dev-${pkg.replace(/[^a-z0-9]+/g, "-")}-absolute`,
     setup(build2) {
-      build2.onResolve({ filter: /^@dimforge\/rapier3d-compat$/ }, () => ({
+      build2.onResolve({ filter: new RegExp(`^${pkg.replace(/[/\-]/g, "$&")}$`) }, () => ({
         path: specifier,
         external: true
       }));
@@ -3484,7 +6141,8 @@ async function resolveWorkerEntry2(outDir) {
     );
   }
   const outfile = path.join(outDir, "worker.mjs");
-  const rapierPlugin = rapierAbsolutePlugin(path.join(packagesDir, "runtime"));
+  const runtimeDir = path.join(packagesDir, "runtime");
+  const enginePlugins = ["@dimforge/rapier3d-compat", "matter-js"].map((pkg) => engineAbsolutePlugin(runtimeDir, pkg)).filter((p) => p !== void 0);
   await esbuild.build({
     entryPoints: [source],
     bundle: true,
@@ -3496,29 +6154,35 @@ async function resolveWorkerEntry2(outDir) {
       "@irtio/server": path.join(packagesDir, "server/src/index.ts"),
       "@irtio/protocol": path.join(packagesDir, "protocol/src/index.ts")
     },
-    ...rapierPlugin !== void 0 ? { plugins: [rapierPlugin] } : {},
+    ...enginePlugins.length > 0 ? { plugins: enginePlugins } : {},
     // Rapier stays external for the same reason it does in packages/supervisor/test/support.ts:
     // it is a dependency of `@irtio/runtime`, resolved once at load time. Bundling a second copy
     // here would give the dev worker its own WASM instance, separate from the one the room
     // bundle resolves via node_modules. `rapierPlugin` (above) already externalizes it at an
     // absolute path when `@irtio/runtime`'s own copy can be found; this string entry is the
     // fallback for a published install where that resolution comes for free from node_modules.
-    external: ["node:worker_threads", "node:url", "@dimforge/rapier3d-compat"]
+    external: ["node:worker_threads", "node:url", "@dimforge/rapier3d-compat", "matter-js"]
   });
   return outfile;
 }
-async function buildState(supervisor, projectId, bundle) {
+async function buildState(supervisor, projectId, bundle, startedAt) {
+  await supervisor.refreshTickHealth().catch(() => []);
   const infos = supervisor.rooms();
   const inspects = await Promise.all(
     infos.map((room) => supervisor.inspect(room.id).catch(() => void 0))
   );
   const logs = [];
-  for (const room of infos) {
-    for (const entry of supervisor.logs(room.id)) logs.push({ ...entry, roomId: room.id });
+  for (const roomId of [TENANT_ROOM_ID, ...infos.map((r) => r.id)]) {
+    for (const entry of supervisor.logs(roomId)) logs.push({ ...entry, roomId });
   }
   logs.sort((a, b) => a.at - b.at);
   return {
     project: projectId,
+    // bugs.md #16: which build of the room is this server actually serving, and since when.
+    // The bundle hash alone is not enough to catch the failure that motivated it: a forgotten
+    // `dev` from an earlier session serves an old bundle from an old process, and a reader
+    // comparing two runs needs to see that the *process* did not restart either.
+    startedAt,
     bundle: {
       file: bundle.file,
       hash: bundle.hash,
@@ -3548,13 +6212,15 @@ function send(res, status, type, body) {
 }
 async function startDev(options = {}) {
   const cwd = path.resolve(options.cwd ?? process.cwd());
+  const startedAt = Date.now();
   const log = options.log ?? ((line) => console.log(line));
   const entry = resolveEntry(cwd, options.room);
-  const projectId = await readProjectId(cwd);
+  const config = await readProjectConfig(cwd, "irtio dev", options.config);
+  const projectId = config.project ?? "dev";
   const outDir = path.join(cwd, ".irtio", "dev");
   const port = options.port ?? DEFAULT_PORT;
   await mkdir(outDir, { recursive: true });
-  await warnIfClientImportsRoom(cwd, entry, log);
+  await warnIfClientImportsRoom(cwd, entry, config, log);
   const bundleOptions = {
     entry,
     outDir,
@@ -3576,6 +6242,69 @@ async function startDev(options = {}) {
       send(res, 200, "text/html; charset=utf-8", DEV_PAGE);
       return true;
     }
+    if (route === "/__irt/record.json" || route === "/__irt/timeline.json") {
+      const query = new URL(req.url ?? "", "http://localhost");
+      const roomId = query.searchParams.get("room") ?? "";
+      void (async () => {
+        try {
+          if (route === "/__irt/record.json") {
+            const maxTicks = Number(query.searchParams.get("maxTicks"));
+            const maxRecords = Number(query.searchParams.get("maxRecords"));
+            const started = await supervisor.startTimeline(roomId, {
+              ...Number.isInteger(maxTicks) && maxTicks > 0 ? { maxTicks } : {},
+              ...Number.isInteger(maxRecords) && maxRecords > 0 ? { maxRecords } : {}
+            });
+            send(
+              res,
+              started ? 200 : 404,
+              "application/json; charset=utf-8",
+              JSON.stringify({
+                recording: started,
+                room: roomId,
+                ...started ? {} : { error: `no running room ${roomId} with a worker to record` }
+              })
+            );
+            return;
+          }
+          const dump = await supervisor.readTimeline(roomId);
+          send(
+            res,
+            dump === void 0 ? 404 : 200,
+            "application/json; charset=utf-8",
+            JSON.stringify(
+              dump ?? { error: `room ${roomId} has no recorded timeline`, room: roomId }
+            )
+          );
+        } catch (err) {
+          send(res, 500, "application/json; charset=utf-8", JSON.stringify({ error: String(err) }));
+        }
+      })();
+      return true;
+    }
+    if (route === "/__irt/save.json") {
+      const query = new URL(req.url ?? "", "http://localhost");
+      const roomId = query.searchParams.get("room") ?? "";
+      void (async () => {
+        try {
+          const saved = await supervisor.saveNow(roomId);
+          send(
+            res,
+            saved === void 0 ? 404 : 200,
+            "application/json; charset=utf-8",
+            JSON.stringify(
+              saved === void 0 ? { error: `no running room ${roomId} to save`, room: roomId } : {
+                room: roomId,
+                saveId: saved.saveId,
+                bytes: Buffer.from(saved.bytes).toString("base64")
+              }
+            )
+          );
+        } catch (err) {
+          send(res, 500, "application/json; charset=utf-8", JSON.stringify({ error: String(err) }));
+        }
+      })();
+      return true;
+    }
     if (route === "/__irt/state.json") {
       void (async () => {
         try {
@@ -3583,7 +6312,7 @@ async function startDev(options = {}) {
             res,
             200,
             "application/json; charset=utf-8",
-            JSON.stringify(await buildState(supervisor, projectId, bundle))
+            JSON.stringify(await buildState(supervisor, projectId, bundle, startedAt))
           );
         } catch (err) {
           send(res, 500, "application/json; charset=utf-8", JSON.stringify({ error: String(err) }));
@@ -3604,6 +6333,7 @@ async function startDev(options = {}) {
     store: new DiskStore(path.join(cwd, ".irtio", "snapshots")),
     publicUrl: `http://localhost:${port}`,
     httpHandler,
+    ...options.profile === true ? { profile: true } : {},
     log: (level, ...args) => {
       const line = args.map((a) => typeof a === "string" ? a : safeJson(a)).join(" ");
       log(level === "error" ? pc.red(line) : level === "warn" ? pc.yellow(line) : pc.dim(line));
@@ -3685,8 +6415,23 @@ async function startDev(options = {}) {
     }
   };
 }
+var USAGE = `usage: irtio dev [options]
+
+Bundles the room file, runs a real supervisor on it locally, and serves the inspector on the same
+port. Rebuilds and resets the rooms whenever the room code changes.
+
+options:
+  --room <file>      the room entry (default: irtio/room.ts, irtio/room.js, room.ts)
+  --port <n>         port to listen on (default 7070; 0 picks a free one)
+  --no-watch         do not rebuild on change
+  -c, --config <f>   the project file to read (default irtio.json)
+  --profile          print a bandwidth breakdown per room once a second
+  --profile-top <n>  rows per table (default 12; implies --profile)
+  -h, --help         print this
+`;
 function parseDevArgs(args) {
-  const parsed = { watch: true };
+  if (helpRequested(args)) throw helpFor(USAGE);
+  const parsed = { watch: true, profile: false };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     const eq = arg.indexOf("=");
@@ -3712,6 +6457,22 @@ function parseDevArgs(args) {
       case "--no-watch":
         parsed.watch = false;
         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 dev: --profile-top must be a row count between 1 and 200");
+        }
+        parsed.profile = true;
+        parsed.profileTop = n;
+        break;
+      }
+      case "-c":
+      case "--config":
+        parsed.config = value();
+        break;
       default:
         throw new Error(`irtio dev: unknown option ${JSON.stringify(arg)}`);
     }
@@ -3719,15 +6480,22 @@ function parseDevArgs(args) {
   return parsed;
 }
 async function dev(args) {
-  const parsed = parseDevArgs(args);
+  let parsed;
   let server;
   try {
+    parsed = parseDevArgs(args);
     server = await startDev({
       watch: parsed.watch,
       ...parsed.room !== void 0 ? { room: parsed.room } : {},
-      ...parsed.port !== void 0 ? { port: parsed.port } : {}
+      ...parsed.port !== void 0 ? { port: parsed.port } : {},
+      ...parsed.config !== void 0 ? { config: parsed.config } : {},
+      ...parsed.profile ? { profile: true } : {}
     });
   } catch (err) {
+    if (err instanceof HelpRequested) {
+      console.log(err.usage);
+      return;
+    }
     console.error(pc.red(err instanceof Error ? err.message : String(err)));
     process.exitCode = 1;
     return;
@@ -3739,10 +6507,42 @@ async function dev(args) {
       `share links: http://localhost:${server.port}/?room=CODE (codes appear when a client joins)`
     )
   );
+  let profileTimer;
+  if (parsed.profile) {
+    let history = /* @__PURE__ */ new Map();
+    let busy = false;
+    profileTimer = setInterval(() => {
+      if (busy) return;
+      busy = true;
+      void (async () => {
+        try {
+          await server.supervisor.refreshTickHealth();
+          const at = Date.now();
+          const readings = server.supervisor.rooms().map((room) => ({
+            id: room.id,
+            profile: room.profile,
+            egressBytes: room.metrics.egressBytes,
+            ingressBytes: room.metrics.ingressBytes,
+            at
+          }));
+          const tick = profileTick(readings, history, {
+            ...parsed.profileTop !== void 0 ? { top: parsed.profileTop } : {}
+          });
+          history = tick.history;
+          for (const line of tick.lines) console.log(line);
+        } catch {
+        } finally {
+          busy = false;
+        }
+      })();
+    }, 1e3);
+    profileTimer.unref?.();
+  }
   let stopping = false;
   const shutdown = () => {
     if (stopping) return;
     stopping = true;
+    if (profileTimer) clearInterval(profileTimer);
     void (async () => {
       await server.stop();
       process.exit(0);
@@ -3754,6 +6554,7 @@ async function dev(args) {
   });
 }
 export {
+  USAGE,
   dev,
   parseDevArgs,
   startDev