@irtio/runtime 4.7.1 → 4.8.0

package/dist/{chunk-RLY4VAMM.js → chunk-53X6AWQZ.js}

@@ -31,6 +31,7 @@ var RELAY_STATE_BYTES = 512 * 1024;
 var RELAY_RECORDS_PER_COLLECTION = 1024;
 var RELAY_WRITES_PER_SECOND = 35;
 var DEFAULT_RECORDS_PER_COLLECTION = RELAY_RECORDS_PER_COLLECTION;
+var MAX_WRITE_OPS = 4 * DEFAULT_RECORDS_PER_COLLECTION;
 var RELAY_WRITE_CAPS = {
   stateBytes: RELAY_STATE_BYTES,
   recordsPerCollection: RELAY_RECORDS_PER_COLLECTION,
@@ -67,6 +68,8 @@ function maxTypeBytes(t) {
       return optional + 5 + t.max * 4;
     case "ref":
       return optional + 5 + 64 * 4;
+    case "bytes":
+      return optional + t.n;
     case "list":
       return optional + 5 + t.max * maxTypeBytes(t.item);
     case "struct": {
@@ -197,6 +200,7 @@ function forgetWriter(core, clientId) {
 import { ByteReader, ByteWriter } from "@irtio/schema";
 
 // src/core/internals.ts
+import { bytesEqual } from "@irtio/schema";
 function collectionDescOf(ext, name) {
   return ext.collections.find((c) => c.name === name);
 }
@@ -211,6 +215,9 @@ function isPlainObject(v) {
 }
 function deepEqual(a, b) {
   if (Object.is(a, b)) return true;
+  if (a instanceof Uint8Array || b instanceof Uint8Array) {
+    return a instanceof Uint8Array && b instanceof Uint8Array && bytesEqual(a, b);
+  }
   if (Array.isArray(a) || Array.isArray(b)) {
     if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
     for (let i = 0; i < a.length; i++) if (!deepEqual(a[i], b[i])) return false;
@@ -624,7 +631,7 @@ var PhysicsRuntime = class {
   // Bodies
   // -------------------------------------------------------------------------
   /**
-   * bugs.md #99: every teardown path goes through here rather than calling `removeRigidBody`
+   * Every teardown path goes through here rather than calling `removeRigidBody`
    * directly.
    *
    * A sleeping body is parked in an island wired through the contact graph. Pulling a body out
@@ -1053,7 +1060,11 @@ function channelValue(channel, t, r, v, w) {
 }
 
 // src/core/inspect.ts
-import { EntityCollection } from "@irtio/schema";
+import {
+  EntityCollection,
+  bytesToBase64,
+  containsBytes
+} from "@irtio/schema";
 var EVENT_RING_SIZE = 100;
 var EventRing = class {
   items = [];
@@ -1069,16 +1080,35 @@ function inspectState(schema, plain) {
   const out = {};
   for (const c of schema.collections) {
     const v = plain[c.name];
+    const hasBytes = c.fields.some((f) => containsBytes(f.type));
+    const show = (value) => hasBytes ? inspectRecord(c, value) : value;
     if (v instanceof EntityCollection) {
       const recs = {};
-      for (const [id, value] of v) recs[id] = { owner: v.ownerOf(id), value };
+      for (const [id, value] of v) recs[id] = { owner: v.ownerOf(id), value: show(value) };
       out[c.name] = recs;
     } else {
-      out[c.name] = v;
+      out[c.name] = show(v);
     }
   }
   return out;
 }
+function inspectRecord(c, value) {
+  if (value === null || typeof value !== "object") return value;
+  const rec = value;
+  const out = {};
+  for (const f of c.fields) out[f.name] = inspectValue(f.type, rec[f.name]);
+  return out;
+}
+function inspectValue(t, value) {
+  if (value instanceof Uint8Array) return bytesToBase64(value);
+  if (t.kind === "struct" && value !== null && typeof value === "object") {
+    const rec = value;
+    const out = {};
+    for (const [k, ft] of Object.entries(t.fields)) out[k] = inspectValue(ft, rec[k]);
+    return out;
+  }
+  return value;
+}
 
 // src/core/rpc-trace.ts
 var RPC_TRACE_SIZE = 200;
@@ -1156,7 +1186,10 @@ function cellFor(grid, value) {
   const x = record[grid.x];
   const y = record[grid.y];
   if (typeof x !== "number" || typeof y !== "number") return void 0;
-  return { x: Math.floor(x / grid.cell), y: Math.floor(y / grid.cell) };
+  const cx = Math.floor(x / grid.cell);
+  const cy = Math.floor(y / grid.cell);
+  if (!Number.isSafeInteger(cx) || !Number.isSafeInteger(cy)) return void 0;
+  return { x: cx, y: cy };
 }
 function cellKey(cell) {
   return `${cell.x},${cell.y}`;
@@ -1189,11 +1222,27 @@ function querySpatialIndex(index, clientId, role) {
   const anchor = index.collection.get(clientId);
   const anchorCell = cellFor(grid, anchor);
   if (!anchor || !anchorCell) return /* @__PURE__ */ new Set();
+  const r = grid.radius;
+  const ax = anchorCell.x;
+  const ay = anchorCell.y;
+  if (!Number.isSafeInteger(ax - r) || !Number.isSafeInteger(ax + r)) return /* @__PURE__ */ new Set();
+  if (!Number.isSafeInteger(ay - r) || !Number.isSafeInteger(ay + r)) return /* @__PURE__ */ new Set();
   const candidates = /* @__PURE__ */ new Set();
-  for (let x = anchorCell.x - grid.radius; x <= anchorCell.x + grid.radius; x++) {
-    for (let y = anchorCell.y - grid.radius; y <= anchorCell.y + grid.radius; y++) {
-      const ids = index.buckets.get(cellKey({ x, y }));
-      if (ids) for (const id of ids) candidates.add(id);
+  const span = 2 * r + 1;
+  if (span * span > index.buckets.size) {
+    for (const [key, ids] of index.buckets) {
+      const comma = key.indexOf(",");
+      const bx = Number(key.slice(0, comma));
+      const by = Number(key.slice(comma + 1));
+      if (Math.abs(bx - ax) <= r && Math.abs(by - ay) <= r)
+        for (const id of ids) candidates.add(id);
+    }
+  } else {
+    for (let i = 0; i < span; i++) {
+      for (let j = 0; j < span; j++) {
+        const ids = index.buckets.get(cellKey({ x: ax - r + i, y: ay - r + j }));
+        if (ids) for (const id of ids) candidates.add(id);
+      }
     }
   }
   candidates.add(clientId);
@@ -1519,11 +1568,22 @@ function reclaimHolds(core, clientId, playerId) {
     s.holds.delete(key);
     const coll = plainEntity(core.plain, hold.collection);
     if (!coll.has(hold.id)) continue;
-    trackedEntity(core, hold.collection).setOwner(hold.id, clientId);
+    const tracked = trackedEntity(core, hold.collection);
+    if (hold.id !== clientId && !coll.has(clientId) && isPerPlayer(core, hold.collection)) {
+      const record = cloneValue(coll.get(hold.id));
+      tracked.remove(hold.id);
+      tracked.add(clientId, record, { owner: clientId });
+    } else {
+      tracked.setOwner(hold.id, clientId);
+    }
     reclaimed++;
   }
   return reclaimed;
 }
+function isPerPlayer(core, collection) {
+  const c = core.ext.collections.find((x) => x.name === collection);
+  return c?.kind === "entity" && c.perPlayer === true;
+}
 function expireHolds(core) {
   const s = states2.get(core);
   if (!s || s.holds.size === 0) return;
@@ -2251,6 +2311,7 @@ import {
   SERVER_OWNER as SERVER_OWNER3,
   cloneValue as cloneValue2,
   decodeDelta,
+  defaultRecord as defaultRecord2,
   defaultValue,
   encodeDelta as encodeDelta2,
   markField,
@@ -2337,29 +2398,60 @@ function recordOf(plain, c, id) {
 function applyWrite(core, clientId, payload) {
   let delta;
   try {
-    delta = decodeDelta(core.ext, payload);
+    delta = decodeDelta(core.ext, payload, { maxOps: MAX_WRITE_OPS });
   } catch (err) {
-    core.log("warn", `WRITE from ${clientId} failed to decode:`, err);
+    core.log(
+      "warn",
+      `WRITE from ${clientId} failed to decode: ${err instanceof Error ? err.message : String(err)}`
+    );
     return { ok: false };
   }
   let ops = 0;
   for (const dc of delta.collections) ops += dc.ops.length;
-  if (!admitWrite(core, clientId, core.host.now(), ops)) return { ok: true };
+  const admitted = admitWrite(core, clientId, core.host.now(), ops);
   const judged = core.clients.get(clientId);
   if (judged && delta.tick > judged.lastClientTick) {
     judged.lastClientTick = delta.tick;
     judged.lastAppliedTick = core.tick;
   }
-  for (const dc of delta.collections) {
-    const c = collectionDescOf(core.ext, dc.name);
-    if (!c) continue;
-    for (const op of dc.ops) applyOp(core, clientId, c, op);
+  if (!admitted) {
+    for (const dc of delta.collections) {
+      const c = collectionDescOf(core.ext, dc.name);
+      if (!c) continue;
+      for (const op of dc.ops) {
+        if (op.op !== "update" || !recordOf(core.plain, c, op.id)) continue;
+        correctLeaves(core, clientId, c.name, op.id, leafPaths(fieldList(c), op.mask));
+      }
+    }
+    return { ok: true };
+  }
+  const tally = { n: 0 };
+  frameTally = tally;
+  try {
+    for (const dc of delta.collections) {
+      const c = collectionDescOf(core.ext, dc.name);
+      if (!c) continue;
+      for (const op of dc.ops) applyOp(core, clientId, c, op);
+    }
+  } finally {
+    frameTally = void 0;
+    if (tally.n > REJECT_LOGS_PER_FRAME)
+      core.log(
+        "warn",
+        `WRITE from ${clientId}: ${tally.n - REJECT_LOGS_PER_FRAME} more rejection lines suppressed (${tally.n} in this frame)`
+      );
   }
   return { ok: true };
 }
+var REJECT_LOGS_PER_FRAME = 8;
+var frameTally;
+function logRejected(core, level, ...args) {
+  if (frameTally && ++frameTally.n > REJECT_LOGS_PER_FRAME) return;
+  core.log(level, ...args);
+}
 function reject(core, clientId, c, op, reason) {
   core.recordEvent("write-rejected", clientId, `${c.name}: ${reason}`);
-  core.log("warn", `WRITE rejected (${reason}) from ${clientId} on ${c.name}`);
+  logRejected(core, "warn", `WRITE rejected (${reason}) from ${clientId} on ${c.name}`);
   if (op.op !== "update") return;
   if (!recordOf(core.plain, c, op.id)) return;
   correctLeaves(core, clientId, c.name, op.id, leafPaths(fieldList(c), op.mask));
@@ -2377,7 +2469,8 @@ function applyOp(core, clientId, c, op) {
   const senderRole = core.clients.get(clientId)?.role ?? "";
   if (!isVisible(c, senderRole)) {
     core.recordEvent("write-rejected", clientId, `${c.name}: not visible to role`);
-    core.log(
+    logRejected(
+      core,
       "warn",
       `WRITE rejected (collection not visible to role ${JSON.stringify(senderRole)}) from ${clientId} on ${c.name}`
     );
@@ -2387,7 +2480,7 @@ function applyOp(core, clientId, c, op) {
     const coll = plainEntity(core.plain, c.name);
     if (coll.has(op.id) && coll.ownerOf(op.id) !== clientId && !inClientView(core, clientId, c, op.id)) {
       core.recordEvent("write-rejected", clientId, `${c.name}: ${op.id} is not in view`);
-      core.log("warn", `WRITE rejected (id not in view) from ${clientId} on ${c.name}`);
+      logRejected(core, "warn", `WRITE rejected (id not in view) from ${clientId} on ${c.name}`);
       return;
     }
   }
@@ -2425,6 +2518,10 @@ function applyOp(core, clientId, c, op) {
     reject(core, clientId, c, op, "not the owner");
     return;
   }
+  if (maskHasRanges(op.mask)) {
+    reject(core, clientId, c, op, "byte-range patches are not allowed in a WRITE");
+    return;
+  }
   const fields = fieldList(c);
   const growth = updateGrowth(c, leafPaths(fields, op.mask));
   if (growth > 0 && !admitGrowth(core, clientId, growth)) return;
@@ -2443,7 +2540,8 @@ function applyOp(core, clientId, c, op) {
     }
     if (refused2.length > 0) {
       core.recordEvent("write-rejected", clientId, `${c.name}: ${refused2.join(", ")}`);
-      core.log(
+      logRejected(
+        core,
         "warn",
         `WRITE to ${c.name}.${op.id} from ${clientId} touched fields the owner does not write: ${refused2.join(", ")}`
       );
@@ -2460,7 +2558,12 @@ function applyOp(core, clientId, c, op) {
       try {
         result = normalizeRecord(c, returned ?? next);
       } catch (err) {
-        core.log("error", `validate.${c.name} returned an invalid record; write rejected:`, err);
+        logRejected(
+          core,
+          "error",
+          `validate.${c.name} returned an invalid record; write rejected:`,
+          err
+        );
         result = prev;
       }
     }
@@ -2496,31 +2599,58 @@ function applyAdd(core, clientId, c, op) {
   }
   if (!admitGrowth(core, clientId, maxRecordBytes(c))) return;
   let value = op.value;
-  if (c.serverFields) {
-    const stripped = [];
+  if (c.physics || c.serverFields) {
+    const refused2 = [];
     const copy = { ...value };
     for (const f of c.fields) {
-      if (!c.serverFields.has(f.name)) continue;
+      const why = ownerMayNotWrite(c, f.name);
+      if (why === void 0) continue;
       const reset = defaultValue(f.type);
-      if (deepEqual(copy[f.name], reset)) continue;
+      if (copy[f.name] === void 0 || deepEqual(copy[f.name], reset)) continue;
       copy[f.name] = reset;
-      stripped.push(f.name);
+      refused2.push(why);
     }
-    if (stripped.length > 0) {
-      core.recordEvent(
-        "write-rejected",
-        clientId,
-        `${c.name}: ${stripped.join(", ")} (serverField)`
-      );
-      core.log(
+    if (refused2.length > 0) {
+      core.recordEvent("write-rejected", clientId, `${c.name}: ${refused2.join(", ")}`);
+      logRejected(
+        core,
         "warn",
-        `add to ${c.name}.${op.id} from ${clientId} set server-only fields; reset to their defaults: ${stripped.join(", ")}`
+        `add to ${c.name}.${op.id} from ${clientId} set server-only fields; reset to their defaults: ${refused2.join(", ")}`
       );
     }
     value = copy;
   }
+  let record;
+  try {
+    record = normalizeRecord(c, value);
+  } catch (err) {
+    reject(core, clientId, c, op, `add rejected: ${String(err)}`);
+    return;
+  }
+  const validator = core.definition.config.validate?.[c.name];
+  if (validator) {
+    const prev = defaultRecord2(c);
+    const ctx = core.ctxFor(clientId);
+    const ran = core.tryRun(`validate.${c.name}`, () => validator(prev, record, ctx));
+    if (!ran.ok) {
+      reject(core, clientId, c, op, `add rejected by validate.${c.name}`);
+      return;
+    }
+    try {
+      record = normalizeRecord(c, ran.value ?? record);
+    } catch (err) {
+      reject(
+        core,
+        clientId,
+        c,
+        op,
+        `validate.${c.name} returned an invalid record: ${String(err)}`
+      );
+      return;
+    }
+  }
   try {
-    trackedEntity(core, c.name).add(op.id, value, { owner: clientId });
+    trackedEntity(core, c.name).add(op.id, record, { owner: clientId });
   } catch (err) {
     reject(core, clientId, c, op, `add rejected: ${String(err)}`);
     return;
@@ -2550,6 +2680,11 @@ function updateGrowth(c, leaves) {
   }
   return growth;
 }
+function maskHasRanges(mask) {
+  if (mask.ranges && mask.ranges.size > 0) return true;
+  for (const n of mask.nested.values()) if (maskHasRanges(n)) return true;
+  return false;
+}
 function isFixedWidth(t) {
   switch (t.kind) {
     case "bool":
@@ -2560,6 +2695,7 @@ function isFixedWidth(t) {
     case "f32":
     case "f64":
     case "enum":
+    case "bytes":
       return t.opt !== true;
     case "struct":
       return Object.values(t.fields).every(isFixedWidth) && t.opt !== true;
@@ -2611,6 +2747,7 @@ function encodeCorrection(core, dirty) {
 var MAX_CATCHUP = 5;
 var CRASH_AFTER_THROWS = 3;
 var TIMER_SLEEP_GUARD_MS = 250;
+var MAX_HOST_TIMER_MS = 2 ** 31 - 1;
 var Loop = class {
   constructor(core) {
     this.core = core;
@@ -2635,7 +2772,7 @@ var Loop = class {
    * Once, deliberately. A `setInterval(100)` in an otherwise silent room must not be able to pin
    * the room resident forever — pending timers are explicitly *not* a reason to stay awake. A
    * one-shot deadline is handed to the supervisor, which wakes the room at it; an interval is
-   * simply dropped, with a warning (bugs.md #142). Reset by real activity.
+   * simply dropped, with a warning. Reset by real activity.
    */
   timerDeferred = false;
   get intervalMs() {
@@ -2869,15 +3006,24 @@ var Loop = class {
   // -------------------------------------------------------------------------
   setTimer(ms, fn, repeat) {
     const id = this.nextTimerId++;
-    const periodTicks = Math.max(1, Math.ceil(ms * this.core.definition.config.tickRate / 1e3));
+    if (!Number.isFinite(ms)) {
+      const where = repeat ? "room.setInterval" : "room.setTimeout";
+      this.core.log("warn", `${where}: ${ms} is not a finite delay; the timer was not armed`);
+      return id;
+    }
+    const periodMs = Math.max(0, ms);
+    const periodTicks = Math.max(
+      1,
+      Math.ceil(periodMs * this.core.definition.config.tickRate / 1e3)
+    );
     const timer = {
       id,
       fn,
       repeat,
       periodTicks,
-      periodMs: Math.max(0, ms),
+      periodMs,
       dueTick: this.core.tick + periodTicks,
-      dueAtMs: this.core.host.now() + Math.max(0, ms),
+      dueAtMs: this.core.host.now() + periodMs,
       handle: void 0
     };
     this.timers.set(id, timer);
@@ -2885,18 +3031,27 @@ var Loop = class {
     return id;
   }
   armHostTimer(timer) {
-    timer.handle = this.core.host.setTimeout(() => {
-      timer.handle = void 0;
-      if (this.core.stopped) return;
-      if (!this.timers.has(timer.id)) return;
-      if (timer.repeat) {
-        timer.dueAtMs = this.core.host.now() + timer.periodMs;
-        this.armHostTimer(timer);
-      } else this.timers.delete(timer.id);
-      this.core.tick++;
-      this.core.guard("room timer", timer.fn);
-      this.core.flush();
-    }, timer.periodMs);
+    const remaining = Math.max(0, timer.dueAtMs - this.core.host.now());
+    const capped = remaining > MAX_HOST_TIMER_MS;
+    timer.handle = this.core.host.setTimeout(
+      () => {
+        timer.handle = void 0;
+        if (this.core.stopped) return;
+        if (!this.timers.has(timer.id)) return;
+        if (capped) {
+          this.armHostTimer(timer);
+          return;
+        }
+        if (timer.repeat) {
+          timer.dueAtMs = this.core.host.now() + timer.periodMs;
+          this.armHostTimer(timer);
+        } else this.timers.delete(timer.id);
+        this.core.tick++;
+        this.core.guard("room timer", timer.fn);
+        this.core.flush();
+      },
+      capped ? MAX_HOST_TIMER_MS : remaining
+    );
   }
   clearTimer(handle) {
     const t = this.timers.get(handle);
@@ -2929,7 +3084,7 @@ var Loop = class {
    * gone" into "your room is awake again by then", which is a contract room code can actually
    * catch up against in `onWake`.
    *
-   * bugs.md #142: that contract is a statement about a **deadline**, and only a `setTimeout` has
+   * That contract is a statement about a **deadline**, and only a `setTimeout` has
    * one. A `setInterval` has a cadence, so its next due time is one period away no matter when
    * you ask — including one period after the room hibernates. Arming the wake for it made an
    * interval mean "never let this room stay asleep": the room slept, the wake brought it back
@@ -3203,7 +3358,7 @@ var MatterRuntime = class {
   // Bodies
   // -------------------------------------------------------------------------
   /**
-   * bugs.md #100, the matter2d half. Rapier's bindings wake a contact island themselves when a
+   * The matter2d half of waking a contact island on removal. Rapier's bindings wake a contact island themselves when a
    * member is removed (`PhysicsRuntime.destroyBody` / `Rapier2dRuntime.destroyBody`); matter.js
    * does not, so a body sleeping against a victim about to be removed is left sleeping and
    * motionless in mid-air once the victim is gone.
@@ -3680,7 +3835,7 @@ var Rapier2dRuntime = class {
   // Bodies
   // -------------------------------------------------------------------------
   /**
-   * bugs.md #99, planar half: the teardown door every removal goes through. See
+   * The planar teardown door every removal goes through. See
    * `PhysicsRuntime.destroyBody` for the argument — one narrow-phase walk of the victim's own
    * contact pairs, so a body resting on what is about to vanish is awake when it does.
    */
@@ -4121,7 +4276,7 @@ import {
   decodeSnapshot as decodeSnapshot3,
   encodeDelta as encodeDelta5,
   encodeSnapshot as encodeSnapshot4,
-  filterDirty as filterDirty2,
+  filterDirty as filterDirty3,
   isDirtyEmpty as isDirtyEmpty4,
   track,
   validateForDeploy
@@ -5204,6 +5359,9 @@ function lobbyConfigOf(core) {
   if (!schemaHasLobby(core.definition.schema)) return void 0;
   return declared;
 }
+function countsAsPlayer(config, role) {
+  return config.roles === void 0 || config.roles.includes(role);
+}
 function stateOf5(core) {
   return core.anyState[LOBBY_STATE];
 }
@@ -5216,7 +5374,7 @@ function evaluateLobby(core) {
   const policy = config.start ?? "when-full";
   const present = [];
   for (const [clientId, entry] of core.clients) {
-    if (!entry.connected) continue;
+    if (!entry.connected || !countsAsPlayer(config, entry.role)) continue;
     present.push(clientId);
     if (!members.has(clientId)) members.add(clientId, { ready: false }, { owner: clientId });
     else if (members.ownerOf(clientId) !== clientId) members.setOwner(clientId, clientId);
@@ -5281,7 +5439,7 @@ function makeLobby(core) {
     get ready() {
       const out = [];
       for (const [clientId, entry] of core.clients) {
-        if (!entry.connected) continue;
+        if (!entry.connected || !countsAsPlayer(config, entry.role)) continue;
         out.push({
           clientId,
           ready: members.get(clientId)?.ready === true
@@ -5336,7 +5494,8 @@ import {
   encodeChatMsg,
   encodeFrame as encodeFrame3,
   encodeMsg,
-  isChatMsg
+  isChatMsg,
+  toWireTarget
 } from "@irtio/protocol";
 import { decodeFields as decodeFields2 } from "@irtio/schema";
 function toRoomTarget(target) {
@@ -5458,22 +5617,20 @@ function handleChat(core, clientId, payload) {
   deliver(core, chat.target, frame, clientId);
   return true;
 }
-function wireTargetOf(target) {
-  return target === "all" ? { kind: "all" } : typeof target === "string" ? { kind: "client", clientId: target } : { kind: "role", role: target.role };
-}
 function sendMessage(core, target, bytes) {
   const frame = encodeFrame3(
     FrameType4.MSG,
     encodeMsg({ target: { kind: "server" }, payload: bytes })
   );
-  deliver(core, wireTargetOf(target), frame);
+  deliver(core, toWireTarget(target, "room.send"), frame);
 }
-function sendTypedMessage(core, index, target, payload) {
+function sendTypedMessage(core, index, target, payload, name = "message") {
+  const wire = toWireTarget(target, `room.messages.${name}.send`);
   const frame = encodeFrame3(
     FrameType4.MSG,
     encodeMsg({ target: { kind: "server" }, payload, typed: { index } })
   );
-  deliver(core, wireTargetOf(target), frame);
+  deliver(core, wire, frame);
 }
 
 // src/core/replay.ts
@@ -5489,12 +5646,14 @@ import {
 import {
   encodeDelta as encodeDelta3,
   encodeSnapshot as encodeSnapshot3,
+  filterDirty as filterDirty2,
   isDirtyEmpty as isDirtyEmpty2
 } from "@irtio/schema";
 
 // src/core/replay-excerpt.ts
 import {
   applyDelta,
+  copyBytes,
   decodeDelta as decodeDelta2,
   decodeSnapshot as decodeSnapshot2
 } from "@irtio/schema";
@@ -5512,6 +5671,7 @@ var ExcerptTooLargeError = class extends Error {
 };
 function estimateValue(value) {
   if (typeof value === "string") return value.length + 2;
+  if (value instanceof Uint8Array) return value.length + 2;
   if (Array.isArray(value)) {
     let n = 2;
     for (const v of value) n += estimateValue(v) + 1;
@@ -5527,6 +5687,7 @@ function estimateValue(value) {
   return 8;
 }
 function copyValue(value) {
+  if (value instanceof Uint8Array) return copyBytes(value);
   if (Array.isArray(value)) return value.map(copyValue);
   if (typeof value === "object" && value !== null) {
     const out = {};
@@ -5571,14 +5732,15 @@ function wantedCollections(ext, names) {
   const wanted = new Set(names);
   return all.filter((c) => wanted.has(c.name));
 }
-function unknownCollection(ext, options) {
+function unknownCollection(ext, options, recorded) {
   const names = options?.collections;
   if (names === void 0) return void 0;
   const known = new Set(
     ext.collections.filter((c) => c.kind === "entity").map((c) => c.name)
   );
   for (const name of names) {
-    if (!known.has(name)) return String(name);
+    if (!known.has(name)) return { kind: "unknown", name: String(name) };
+    if (recorded !== void 0 && !recorded.has(name)) return { kind: "unrecorded", name };
   }
   return void 0;
 }
@@ -5751,6 +5913,8 @@ function stateOf6(core) {
       ttlMs,
       recExpiresAtEpochS: void 0,
       view: declared.view ?? "",
+      mode: declared.omniscient === true ? "omniscient" : declared.view !== void 0 ? "role" : "public",
+      recorded: void 0,
       ring: new ReplayRing(
         {
           windowTicks: Math.max(1, Math.ceil(seconds * tickRate)),
@@ -5785,13 +5949,23 @@ function stateOf6(core) {
   }
   return s;
 }
-function omniscientMemberships(core) {
-  const out = /* @__PURE__ */ new Map();
-  for (const desc of core.ext.collections) {
-    if (!isPerClient(desc)) continue;
-    out.set(desc.name, new Set(plainEntity(core.plain, desc.name).ids()));
-  }
-  return out;
+function recorderCollections(core, state) {
+  if (state.recorded !== void 0) return state.recorded;
+  const keep = (c) => {
+    if (c.visibility === "server") return false;
+    switch (state.mode) {
+      case "omniscient":
+        return true;
+      case "role":
+        return isVisible(c, state.view) && c.visibility !== "owner";
+      default:
+        return c.visibility !== "role" && c.visibility !== "owner";
+    }
+  };
+  state.recorded = new Set(
+    core.ext.collections.filter(keep).map((c) => c.name)
+  );
+  return state.recorded;
 }
 function hasRoleScoped(core) {
   return core.ext.collections.some((c) => c.visibility === "role");
@@ -5800,28 +5974,30 @@ function hasSpatial(core) {
   return core.ext.collections.some(isPerClient);
 }
 function recorderSnapshot(core, state) {
-  if (state.view === "") {
-    return encodeSnapshot3(core.ext, core.plain, { tick: core.tick });
-  }
-  return encodeViewSnapshot(
+  const names = recorderCollections(core, state);
+  return encodeSnapshot3(
     core.ext,
     core.plain,
-    state.view,
-    core.tick,
-    omniscientMemberships(core)
+    { tick: core.tick },
+    { collections: (c) => names.has(c.name) }
   );
 }
 function recorderDelta(core, state, dirty) {
-  if (state.view === "") {
-    if (isDirtyEmpty2(dirty)) return null;
-    return encodeDelta3(core.ext, core.plain, dirty, { tick: core.tick });
-  }
-  return encodeViewDelta(core.ext, core.plain, dirty, state.view, core.tick);
+  const names = recorderCollections(core, state);
+  const filtered = filterDirty2(dirty, (n) => names.has(n));
+  if (isDirtyEmpty2(filtered)) return null;
+  return encodeDelta3(core.ext, core.plain, filtered, { tick: core.tick });
 }
 function cacheKeyFor(core, state) {
   if (hasSpatial(core)) return void 0;
-  if (state.view === "") return hasRoleScoped(core) ? void 0 : "all";
-  return viewKeyFor(core.ext, state.view);
+  switch (state.mode) {
+    case "public":
+      return "all";
+    case "role":
+      return viewKeyFor(core.ext, state.view);
+    default:
+      return hasRoleScoped(core) ? void 0 : "all";
+  }
 }
 function recordFlush(core, dirty, byView) {
   const state = stateOf6(core);
@@ -5979,16 +6155,19 @@ function takeExcerpt(core, options) {
       )
     );
   }
-  const badName = unknownCollection(core.ext, options);
-  if (badName !== void 0) {
+  const state = stateOf6(core);
+  const bad = unknownCollection(core.ext, options, recorderCollections(core, state));
+  if (bad !== void 0) {
     return rejectAsEvent(
       core,
       new Error(
-        `E_EXCERPT_BAD_ARGS: ${JSON.stringify(badName)} is not an entity collection here; singletons are not excerptable`
+        bad.kind === "unknown" ? `E_EXCERPT_BAD_ARGS: ${JSON.stringify(bad.name)} is not an entity collection here; singletons are not excerptable` : (
+          // Short on purpose: `rejectAsEvent` clamps to 96 bytes, and the fix is the second half.
+          `E_EXCERPT_BAD_ARGS: ${JSON.stringify(bad.name)} is not recorded (replay.view / replay.omniscient)`
+        )
       )
     );
   }
-  const state = stateOf6(core);
   if (state.disarmed) {
     return rejectAsEvent(
       core,
@@ -6429,7 +6608,7 @@ function createRoomApi(core, publicUrl) {
   for (const desc of core.definition.schema.messages ?? []) {
     messages[desc.name] = {
       send(target, value) {
-        sendTypedMessage(core, desc.index, target, encodeFields2(desc.fields, value));
+        sendTypedMessage(core, desc.index, target, encodeFields2(desc.fields, value), desc.name);
       }
     };
   }
@@ -6784,6 +6963,7 @@ function setRole(core, clientId, role) {
   entry.role = role;
   if (catchUp) core.send(clientId, catchUp);
   core.invalidateClients();
+  core.host.roleChanged?.(clientId, role);
 }
 function checkNpcConfig(core, config) {
   if (typeof config !== "object" || config === null) {
@@ -7424,7 +7604,7 @@ var RoomCore = class _RoomCore {
    * after the time it would have fired — so keep the deadline in state and catch up in `onWake`.
    *
    * A repeating timer is deliberately not in here: it has a cadence rather than a deadline, and a
-   * wake armed for it can only ever hand the room back its own next period (bugs.md #142, and
+   * wake armed for it can only ever hand the room back its own next period (see
    * `Loop.departureTimers` for the whole argument). The warning below is what a room holding one
    * gets instead.
    *
@@ -7604,7 +7784,7 @@ var RoomCore = class _RoomCore {
     }
     const presence = this.presence;
     const maxClients = this.definition.config.maxClients;
-    const resuming = options.reconnecting === true || presence.has(clientId);
+    const resuming = presence.has(clientId);
     if (!resuming) this.admit(clientId, options);
     if (!presence.has(clientId) && presence.size >= maxClients) {
       throw new RoomFullError(maxClients);
@@ -7723,6 +7903,7 @@ var RoomCore = class _RoomCore {
       this.guard("onLeave", () => onLeave(this.state, ctx, reason));
     }
     cancelAsksFor(this.internals, clientId);
+    entry.connected = false;
     placeHolds(this.internals, clientId, entry.playerId);
     forgetWriter(this.internals, clientId);
     this.presence.remove(clientId);
@@ -7804,7 +7985,7 @@ var RoomCore = class _RoomCore {
     };
   }
   /**
-   * Week 12: the host answering a `room.save()` / `room.kv.*`. The continuation runs here — its
+   * The host answering a `room.save()` / `room.kv.*`. The continuation runs here — its
    * own event, between ticks, off the back of a host turn — and the flush afterwards is what
    * makes "state mutated in a continuation is tracked normally" true rather than aspirational.
    */
@@ -8028,7 +8209,7 @@ var RoomCore = class _RoomCore {
           const keep = visibleNames(this.ext, entry.role);
           const payload = encodeCorrection(
             this.internals,
-            filterDirty2(
+            filterDirty3(
               membershipSafeDirty(this.ext, entry.correction, memberships),
               (name) => keep.has(name)
             )

package/dist/{chunk-NSUQKWYO.js → chunk-GDXHCAD6.js}

@@ -3,7 +3,7 @@ import {
   parseHibernationBlob,
   sameSchemaHash,
   writeHibernationBlob
-} from "./chunk-RLY4VAMM.js";
+} from "./chunk-53X6AWQZ.js";
 
 // src/migrate.ts
 import { PRESENCE_COLLECTION, withBuiltins } from "@irtio/protocol";
@@ -146,12 +146,12 @@ function migrateHolds(bytes, target, options) {
   return new TextEncoder().encode(JSON.stringify(kept));
 }
 function toMigrationState(schema, plain) {
-  const out = {};
+  const out = /* @__PURE__ */ Object.create(null);
   for (const c of schema.collections) {
     const held = plain[c.name];
     if (c.kind === "entity") {
       const coll = held;
-      const map = {};
+      const map = /* @__PURE__ */ Object.create(null);
       for (const [id, rec] of coll.records) {
         map[id] = { owner: rec.owner, value: { ...rec.value } };
       }

package/dist/{contract-CcZadpC6.d.ts → contract-BQDN3oje.d.ts}

@@ -168,7 +168,13 @@ interface RoomEvent {
     readonly detail?: string;
 }
 declare const EVENT_RING_SIZE = 100;
-/** JSON-able view of a plain state: entities as `{id: {owner, value}}`, singletons as values. */
+/**
+ * JSON-able view of a plain state: entities as `{id: {owner, value}}`, singletons as values.
+ *
+ * A `bytes(n)` value is shown as its base64 string rather than as the `{"0": .., "1": ..}` object
+ * JSON makes of a `Uint8Array`. Only collections that declare a bytes field are copied to do that;
+ * every other value is handed back as it is (callers that keep it clone it, see `timeline.ts`).
+ */
 declare function inspectState(schema: AnySchema, plain: PlainState): Record<string, unknown>;
 interface RoomInspection {
     readonly tick: number;
@@ -177,7 +183,7 @@ interface RoomInspection {
 }
 
 /**
- * M6 lane K (D77 / O28): the write core's caps, and the named refusals that enforce them.
+ * The write core's caps, and the named refusals that enforce them.
  *
  * ## Why these are here and not in the relay host
  *
@@ -221,7 +227,7 @@ interface RoomInspection {
  * costs. A room under half the cap pays one measure per stale window and nothing else.
  */
 
-/** O28's numbers, as the relay host sets them. One place, so lane J can move them once. */
+/** The relay host's cap values. Kept in one place so they move together. */
 declare const RELAY_STATE_BYTES: number;
 declare const RELAY_RECORDS_PER_COLLECTION = 1024;
 declare const RELAY_WRITES_PER_SECOND = 35;
@@ -240,8 +246,7 @@ declare const RELAY_WRITE_CAPS: WriteCaps;
 
 type LogLevel = 'info' | 'warn' | 'error';
 /**
- * Week 12: host-side async work a room asked for — a save generation (D24) or a player-KV
- * operation (D25). Room handlers are synchronous and there is no way to block one on I/O, so
+ * Host-side async work a room asked for — a save generation or a player-KV operation. Room handlers are synchronous and there is no way to block one on I/O, so
  * every one of these is started by `RoomHost.hostCall` and *finished* by the host calling
  * `RoomCoreApi.completeHostCall` — the same way an inbound frame arrives. That is what makes
  * "the continuation runs as its own event between ticks" a structural property of the seam
@@ -274,7 +279,7 @@ type HostCall = {
     readonly board: string;
     readonly playerId: string;
     readonly score: number;
-    /** M6 lane B (D69-c): the cohort of a bucketed board. Absent on every board that declares
+    /** The cohort of a bucketed board. Absent on every board that declares
      *  no buckets, which is every board that existed before M6. There is deliberately no
      *  `period` beside it: rotation is control's clock, never the room's. */
     readonly bucket?: string;
@@ -413,7 +418,7 @@ interface RoomHost {
     /** N consecutive tick throws; the runtime does not recover itself. */
     crashed(reason: string): void;
     /**
-     * Week 12: start host-side async work (D24 save, D25 KV). The host **must** deliver the
+     * Start host-side async work (a save or a KV operation). The host **must** deliver the
      * outcome by calling `RoomCoreApi.completeHostCall(reqId, result)` from its own event loop
      * turn, never synchronously from inside this call — a handler is on the stack.
      */
@@ -435,6 +440,16 @@ interface RoomHost {
      * A host with no room list (the in-process test harness) records it and does nothing else.
      */
     setBackfill(open: boolean): void;
+    /**
+     * #217: `room.setRole` committed `role` for `clientId`. Fire-and-forget host state, in the
+     * style of `setBackfill`: the supervisor mirrors it onto the session so a rejoin (reconnect,
+     * wake, crash restart, migration) re-asserts the room's latest grant, not the join-time one.
+     * Only called after the role is actually applied, and never for a no-op or refused call.
+     *
+     * Optional: a host with no sessions to mirror onto (the in-process harness, the relay host)
+     * need not implement it.
+     */
+    roleChanged?(clientId: string, role: string): void;
     /**
      * D75: `room.lobby.setPublic(v)`, and the terminal deregistration a game start performs.
      *
@@ -512,7 +527,7 @@ interface RoomCoreOptions {
      */
     readonly traceRpc?: boolean;
     /**
-     * D77 / O28: the write core's caps — encoded state bytes, records per collection, writes per
+     * The write core's caps — encoded state bytes, records per collection, writes per
      * client per second. A host that sets none gets the record cap and nothing else, which is what
      * every coded room in its own VM wants: it already has a memory ceiling and a tick budget. The
      * relay host sets all three, because it serves many tenants from one process.
@@ -553,8 +568,8 @@ interface JoinOptions {
     /**
      * D25: the identity `ctx.playerId` reports and `room.kv` is meant to be keyed by. Defaults to
      * `clientId`, which — because a resume token carries the client id across a reconnect — is
-     * exactly the resume-token identity, and no more stable than that token. Week 13 (D27) passes
-     * a JWT subject here instead without anything else changing.
+     * exactly the resume-token identity, and no more stable than that token. A JWT join passes
+     * the verified subject here instead without anything else changing.
      */
     readonly playerId?: string;
     /** D44: this join is a scripted NPC's loopback session. */
@@ -588,7 +603,7 @@ declare class RoomFullError extends Error {
     constructor(maxClients: number);
 }
 /**
- * M8 lane 5: this join was refused before it had a seat.
+ * This join was refused before it had a seat.
  *
  * Thrown by `RoomCore.join` for all four of the room's own refusals — a subject inside a
  * `room.ban` cooldown, an `onAdmit` that called `ctx.deny`, an `onAdmit` that never answered
@@ -703,7 +718,7 @@ interface RoomCoreApi<S extends AnySchema = AnySchema> {
      * `host.now()`'s clock, or `undefined` if there was none. The worker translates it to wall
      * clock and hands it to the supervisor, which wakes the room at it — a `room.setTimeout` loses
      * its callback to a hibernation but no longer loses the room's chance to act on the deadline.
-     * A `room.setInterval` is not a deadline and is deliberately not reported (bugs.md #142); the
+     * A `room.setInterval` is not a deadline and is deliberately not reported; the
      * departure logs a warning for one instead. `undefined` until the first `serialize()`, and
      * never touched by `snapshot()`.
      */
@@ -738,7 +753,7 @@ interface RoomCoreApi<S extends AnySchema = AnySchema> {
      */
     rpcTrace(): RpcTraceDump | undefined;
     /**
-     * Week 12: settles the promise `hostCall(reqId, …)` returned. The host calls this from its own
+     * Settles the promise `hostCall(reqId, …)` returned. The host calls this from its own
      * turn; the runtime runs the continuation as a discrete event and flushes afterwards, so state
      * a continuation mutated goes out exactly like state a handler mutated.
      */

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { A as AdmissionError, D as DEFAULT_RECORDS_PER_COLLECTION, a as DEFAULT_TIMELINE_MAX_RECORDS, b as DEFAULT_TIMELINE_MAX_TICKS, E as EVENT_RING_SIZE, H as HOST_CALL_TIMEOUT_MS, c as HostCall, d as HostCallResult, J as JoinOptions, e as JoinResult, L as LogLevel, P as PHYSICS_STEP_EMA_ALPHA, R as RELAY_RECORDS_PER_COLLECTION, f as RELAY_STATE_BYTES, g as RELAY_WRITES_PER_SECOND, h as RELAY_WRITE_CAPS, i as RPC_TRACE_SIZE, j as RPC_TRACE_SUMMARY_MAX, k as RoomCoreApi, l as RoomCoreOptions, m as RoomEvent, n as RoomEventKind, o as RoomFullError, p as RoomHost, q as RoomInspection, r as RoomStats, s as RpcOutcome, t as RpcTraceDump, u as RpcTraceEntry, v as RpcTraceRing, S as StampLag, T as TimelineDump, w as TimelineFrame, x as TimelineRecorder, y as TimelineRecorderOptions, W as WriteCaps, z as inspectState, B as summarizeRpcResult } from './contract-CcZadpC6.js';
-export { C as CRASH_AFTER_THROWS, M as MAX_CATCHUP, a as MatterBodyRecord, b as MatterSection, c as Mulberry32, P as PhysicsEngineTag, d as PhysicsSection, R as RoomCore, e as decodeMatterBodies, f as decodeMatterSectionEnvelope, g as decodePhysicsSection, h as decodeRapier2dSectionEnvelope, i as encodeMatterBodies, j as encodeMatterSectionEnvelope, k as encodePhysicsSection, l as encodeRapier2dSectionEnvelope, m as initMatter, n as initPhysics, o as initRapier2d, p as loadedMatter, q as loadedPhysics, r as loadedRapier2d, s as physicsSectionEngine, t as resetMatterForTests, u as resetPhysicsForTests, v as resetRapier2dForTests } from './room-BW2ZSX_k.js';
+export { A as AdmissionError, D as DEFAULT_RECORDS_PER_COLLECTION, a as DEFAULT_TIMELINE_MAX_RECORDS, b as DEFAULT_TIMELINE_MAX_TICKS, E as EVENT_RING_SIZE, H as HOST_CALL_TIMEOUT_MS, c as HostCall, d as HostCallResult, J as JoinOptions, e as JoinResult, L as LogLevel, P as PHYSICS_STEP_EMA_ALPHA, R as RELAY_RECORDS_PER_COLLECTION, f as RELAY_STATE_BYTES, g as RELAY_WRITES_PER_SECOND, h as RELAY_WRITE_CAPS, i as RPC_TRACE_SIZE, j as RPC_TRACE_SUMMARY_MAX, k as RoomCoreApi, l as RoomCoreOptions, m as RoomEvent, n as RoomEventKind, o as RoomFullError, p as RoomHost, q as RoomInspection, r as RoomStats, s as RpcOutcome, t as RpcTraceDump, u as RpcTraceEntry, v as RpcTraceRing, S as StampLag, T as TimelineDump, w as TimelineFrame, x as TimelineRecorder, y as TimelineRecorderOptions, W as WriteCaps, z as inspectState, B as summarizeRpcResult } from './contract-BQDN3oje.js';
+export { C as CRASH_AFTER_THROWS, M as MAX_CATCHUP, a as MatterBodyRecord, b as MatterSection, c as Mulberry32, P as PhysicsEngineTag, d as PhysicsSection, R as RoomCore, e as decodeMatterBodies, f as decodeMatterSectionEnvelope, g as decodePhysicsSection, h as decodeRapier2dSectionEnvelope, i as encodeMatterBodies, j as encodeMatterSectionEnvelope, k as encodePhysicsSection, l as encodeRapier2dSectionEnvelope, m as initMatter, n as initPhysics, o as initRapier2d, p as loadedMatter, q as loadedPhysics, r as loadedRapier2d, s as physicsSectionEngine, t as resetMatterForTests, u as resetPhysicsForTests, v as resetRapier2dForTests } from './room-BVZiPb6s.js';
 import { CollectionDesc, AnySchema, PlainState, DirtySet } from '@irtio/schema';
 import '@irtio/protocol';
 import '@irtio/server';
@@ -137,7 +137,7 @@ interface ParsedSnapshot extends SnapshotHeader {
     readonly version: number;
     /** The encoded physics section, or `undefined` for a v1 blob / a room with no world. */
     readonly physics: Uint8Array | undefined;
-    /** M6 lane K (D77): the hold deadlines section, or `undefined` when the room held nothing. */
+    /** The hold deadlines section, or `undefined` when the room held nothing. */
     readonly holds: Uint8Array | undefined;
     /** The codec snapshot, encoded under `withBuiltins(schema)`. */
     readonly snapshot: Uint8Array;

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   fromMigrationState,
   migrateSnapshot,
   toMigrationState
-} from "./chunk-NSUQKWYO.js";
+} from "./chunk-GDXHCAD6.js";
 import {
   AdmissionError,
   CRASH_AFTER_THROWS,
@@ -59,7 +59,7 @@ import {
   visibleNames,
   visibleTo,
   writeHibernationBlob
-} from "./chunk-RLY4VAMM.js";
+} from "./chunk-53X6AWQZ.js";
 export {
   AdmissionError,
   CRASH_AFTER_THROWS,

package/dist/{room-BW2ZSX_k.d.ts → room-BVZiPb6s.d.ts}

@@ -1,7 +1,7 @@
 import { PlatformNotice, AttributeOptions, ProfileSnapshot } from '@irtio/protocol';
 import { DirtySet, AnySchema, PlainState, Tracked, State } from '@irtio/schema';
 import { RoomDefinition, RoomMode, Room, RewindView, Ctx, CustomStepper, CustomPose, MatterModule, MatterEngine, MatterBody, RapierModule, RapierWorld, RapierRigidBody, Rapier2dModule, Rapier2dWorld, Rapier2dRigidBody, ResolvedRoomConfig, LeaveReason } from '@irtio/server';
-import { p as RoomHost, r as RoomStats, u as RpcTraceEntry, L as LogLevel, k as RoomCoreApi, l as RoomCoreOptions, n as RoomEventKind, y as TimelineRecorderOptions, T as TimelineDump, t as RpcTraceDump, q as RoomInspection, J as JoinOptions, e as JoinResult, d as HostCallResult } from './contract-CcZadpC6.js';
+import { p as RoomHost, r as RoomStats, u as RpcTraceEntry, L as LogLevel, k as RoomCoreApi, l as RoomCoreOptions, n as RoomEventKind, y as TimelineRecorderOptions, T as TimelineDump, t as RpcTraceDump, q as RoomInspection, J as JoinOptions, e as JoinResult, d as HostCallResult } from './contract-BQDN3oje.js';
 
 declare class Mulberry32 {
     /** Current internal state (u32). Survives hibernation. */
@@ -30,7 +30,7 @@ interface ClientEntry {
      */
     readonly playerId: string;
     /**
-     * M8 lane 5: the verified identity subject behind this session, or `undefined` for a key join.
+     * The verified identity subject behind this session, or `undefined` for a key join.
      * Set once at the first join beside `playerId` and kept for the same reason: what a later HELLO
      * on the same seat claims must not be able to change who the seat belongs to. `room.ban` reads
      * it, and reading `undefined` is what makes "a key join cannot be banned durably" a fact of the
@@ -201,7 +201,7 @@ interface LoopApi {
     /**
      * The departure's read, taken at `serialize()` before the timers are cleared: the earliest
      * **one-shot** deadline, which the supervisor guarantees the room is awake again by, and the
-     * number of repeating timers dropped with no such guarantee (bugs.md #142). See
+     * number of repeating timers dropped with no such guarantee. See
      * `Loop.departureTimers`.
      */
     departureTimers(): {
@@ -442,7 +442,7 @@ declare class Loop implements LoopApi {
      * Once, deliberately. A `setInterval(100)` in an otherwise silent room must not be able to pin
      * the room resident forever — pending timers are explicitly *not* a reason to stay awake. A
      * one-shot deadline is handed to the supervisor, which wakes the room at it; an interval is
-     * simply dropped, with a warning (bugs.md #142). Reset by real activity.
+     * simply dropped, with a warning. Reset by real activity.
      */
     private timerDeferred;
     constructor(core: RoomInternals);
@@ -510,7 +510,7 @@ declare class Loop implements LoopApi {
      * gone" into "your room is awake again by then", which is a contract room code can actually
      * catch up against in `onWake`.
      *
-     * bugs.md #142: that contract is a statement about a **deadline**, and only a `setTimeout` has
+     * That contract is a statement about a **deadline**, and only a `setTimeout` has
      * one. A `setInterval` has a cadence, so its next due time is one period away no matter when
      * you ask — including one period after the room hibernates. Arming the wake for it made an
      * interval mean "never let this room stay asleep": the room slept, the wake brought it back
@@ -665,7 +665,7 @@ declare class MatterRuntime {
     runSetup(room: Room): void;
     free(): void;
     /**
-     * bugs.md #100, the matter2d half. Rapier's bindings wake a contact island themselves when a
+     * The matter2d half of waking a contact island on removal. Rapier's bindings wake a contact island themselves when a
      * member is removed (`PhysicsRuntime.destroyBody` / `Rapier2dRuntime.destroyBody`); matter.js
      * does not, so a body sleeping against a victim about to be removed is left sleeping and
      * motionless in mid-air once the victim is gone.
@@ -884,7 +884,7 @@ declare class PhysicsRuntime {
     runSetup(room: Room): void;
     free(): void;
     /**
-     * bugs.md #99: every teardown path goes through here rather than calling `removeRigidBody`
+     * Every teardown path goes through here rather than calling `removeRigidBody`
      * directly.
      *
      * A sleeping body is parked in an island wired through the contact graph. Pulling a body out
@@ -1054,7 +1054,7 @@ declare class Rapier2dRuntime {
     runSetup(room: Room): void;
     free(): void;
     /**
-     * bugs.md #99, planar half: the teardown door every removal goes through. See
+     * The planar teardown door every removal goes through. See
      * `PhysicsRuntime.destroyBody` for the argument — one narrow-phase walk of the victim's own
      * contact pairs, so a body resting on what is about to vanish is awake when it does.
      */
@@ -1318,7 +1318,7 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
      * after the time it would have fired — so keep the deadline in state and catch up in `onWake`.
      *
      * A repeating timer is deliberately not in here: it has a cadence rather than a deadline, and a
-     * wake armed for it can only ever hand the room back its own next period (bugs.md #142, and
+     * wake armed for it can only ever hand the room back its own next period (see
      * `Loop.departureTimers` for the whole argument). The warning below is what a room holding one
      * gets instead.
      *
@@ -1372,7 +1372,7 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     markDisconnected(clientId: string): void;
     ctxFor(clientId: string, reconnecting?: boolean): Ctx;
     /**
-     * Week 12: the host answering a `room.save()` / `room.kv.*`. The continuation runs here — its
+     * The host answering a `room.save()` / `room.kv.*`. The continuation runs here — its
      * own event, between ticks, off the back of a host turn — and the flush afterwards is what
      * makes "state mutated in a continuation is tracked normally" true rather than aspirational.
      */

package/dist/test/index.d.ts

@@ -1,8 +1,8 @@
-import { R as RoomCore } from '../room-BW2ZSX_k.js';
-export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-BW2ZSX_k.js';
+import { R as RoomCore } from '../room-BVZiPb6s.js';
+export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-BVZiPb6s.js';
 import { ErrorCodeName, FrameType } from '@irtio/protocol';
 import { NpcConfig, LeaveReason, Room, RoomDefinition } from '@irtio/server';
-import { p as RoomHost, L as LogLevel, k as RoomCoreApi, c as HostCall, d as HostCallResult, W as WriteCaps, r as RoomStats } from '../contract-CcZadpC6.js';
+import { p as RoomHost, L as LogLevel, k as RoomCoreApi, c as HostCall, d as HostCallResult, W as WriteCaps, r as RoomStats } from '../contract-BQDN3oje.js';
 import { AnySchema, PlainState, EntityCollection, State } from '@irtio/schema';
 
 /**
@@ -40,7 +40,7 @@ declare class FakeClock {
  * recorded so a test can assert on it: logs, kicks, `close()`, `sleep()`, `crashed()`, and how
  * many frames/bytes went out (per client and in total).
  *
- * Week 12 adds the two host capabilities a room can now reach for, both modelled the way the
+ * It also models the two host capabilities a room can now reach for, both modelled the way the
  * real supervisor models them:
  *
  * - **Host calls** (`room.save()`, `room.kv.*`) are answered on a fake-clock timer, never
@@ -347,7 +347,7 @@ interface HarnessOptions {
      * default, exactly as a deployed room is.
      */
     readonly traceRpc?: boolean;
-    /** D77 / O28: the write-core caps this room runs under. Default: the record cap only. */
+    /** The write-core caps this room runs under. Default: the record cap only. */
     readonly caps?: WriteCaps;
     /** D77: the wall clock hold deadlines are measured against. Default `Date.now`. */
     readonly wallNow?: () => number;

package/dist/test/index.js

@@ -6,7 +6,7 @@ import {
   initRapier2d,
   isPerClient,
   visibleNames
-} from "../chunk-RLY4VAMM.js";
+} from "../chunk-53X6AWQZ.js";
 
 // src/test/clock.ts
 var FakeClock = class {
@@ -389,7 +389,7 @@ function fieldPath(c, names) {
   return path;
 }
 function isPlainObject(v) {
-  return typeof v === "object" && v !== null && !Array.isArray(v);
+  return typeof v === "object" && v !== null && !Array.isArray(v) && !(v instanceof Uint8Array);
 }
 function mergePatch(target, patch) {
   for (const [k, v] of Object.entries(patch)) {

package/dist/worker/index.d.ts

@@ -1,4 +1,4 @@
-import { L as LogLevel, t as RpcTraceDump, T as TimelineDump, r as RoomStats, c as HostCall, d as HostCallResult, k as RoomCoreApi, p as RoomHost } from '../contract-CcZadpC6.js';
+import { L as LogLevel, t as RpcTraceDump, T as TimelineDump, r as RoomStats, c as HostCall, d as HostCallResult, k as RoomCoreApi, p as RoomHost } from '../contract-BQDN3oje.js';
 import { ErrorCodeName, ProfileSnapshot, PlatformNotice } from '@irtio/protocol';
 import { NpcConfig, LeaveReason } from '@irtio/server';
 import '@irtio/schema';
@@ -45,13 +45,13 @@ type ToWorker = {
     clientId: string;
     role?: string;
     name?: string;
-    /** Week 13 (D27): the verified JWT subject — becomes `JoinOptions.playerId` and therefore
+    /** The verified JWT subject — becomes `JoinOptions.playerId` and therefore
      *  `ctx.playerId`. Absent for key joins, whose playerId stays the client id. */
     playerId?: string;
     reconnecting?: boolean;
     /** D44: this join is a scripted NPC's loopback session. */
     npc?: boolean;
-    /** M8 lane 5: the verified subject, absent for a key join. See `JoinOptions.subject` — it is
+    /** The verified subject, absent for a key join. See `JoinOptions.subject` — it is
      *  deliberately narrower than `playerId`, which always has a value. */
     subject?: string;
     /** Issue #123: `JoinOptions.auth`, the credential kind. Absent means `'key'`. */
@@ -75,7 +75,7 @@ type ToWorker = {
  * the room keeps running. `false` is the departure: `onSleep` runs, timers are cleared, pending
  * work is rejected, and the worker is about to be terminated.
  *
- * **Required, deliberately** (bugs.md #82). It was optional, defaulting to the departure, and
+ * **Required, deliberately.** It was optional, defaulting to the departure, and
  * the periodic `snapshotEveryMs` snapshot of a *running* event-mode room simply omitted it — so
  * every such room ran `onSleep` and lost its armed timers every thirty seconds while it kept
  * running. Only the caller knows which of the two it meant, so the protocol makes it say. Host
@@ -115,7 +115,7 @@ type ToWorker = {
     reqId?: number;
 }
 /**
- * Week 12: the supervisor answering a `hostCall` (a D24 save, a D25 KV operation). It arrives
+ * The supervisor answering a `hostCall` (a save or a KV operation). It arrives
  * as an ordinary worker message, which is precisely what makes the room's continuation "its
  * own event between ticks" rather than something that ran inside the handler that asked.
  */
@@ -243,10 +243,22 @@ type FromWorker = {
      * clears nothing and therefore loses nothing. A `room.setInterval` never reports here: it
      * is a cadence rather than a deadline, and a wake armed for one only ever hands the room
      * its own next period, which is how an interval came to mean "this room never stays
-     * asleep" (bugs.md #142). The supervisor arms an internal wake for what does report, so the
+     * asleep". The supervisor arms an internal wake for what does report, so the
      * room is up again by the time its timer would have fired.
      */
     nextTimerAt?: number;
+}
+/**
+ * The `serialize` reply when there is nothing to send: the room has no core yet, or taking the
+ * bytes threw (an encoder error on a bad state value). Answered rather than swallowed so the
+ * supervisor learns it at once instead of timing out, and can tell it apart from success: a
+ * room whose state could not be captured must be left running, never terminated.
+ */
+ | {
+    t: 'serialized';
+    reqId: number;
+    bytes?: undefined;
+    error: string;
 } | {
     t: 'inspected';
     reqId: number;
@@ -309,7 +321,7 @@ type FromWorker = {
      * V8 could not be sampled, which the supervisor must report as unread rather than as
      * zero, for the same reason `ticks`/`overruns` are optional.
      *
-     * bugs.md #146: `externalBytes` is the off-heap half — `ArrayBuffer` backing stores, WASM
+     * `externalBytes` is the off-heap half — `ArrayBuffer` backing stores, WASM
      * memory, `Buffer`s — which neither `usedBytes` nor the old-generation cap above it covers,
      * and which is therefore the half a room can overshoot its whole budget with while every
      * number the platform was reading stays small. Optional on the wire because an older worker
@@ -336,7 +348,7 @@ type FromWorker = {
      */
     profile?: ProfileSnapshot;
 }
-/** Week 12: the room asked for host-side async work; the supervisor answers `hostResult`. */
+/** The room asked for host-side async work; the supervisor answers `hostResult`. */
  | {
     t: 'hostCall';
     reqId: number;
@@ -360,6 +372,15 @@ type FromWorker = {
  | {
     t: 'setBackfill';
     open: boolean;
+}
+/**
+ * #217: `room.setRole` committed a new role. The supervisor mirrors it onto the session so a
+ * later rejoin re-asserts the room's current grant rather than the join-time one.
+ */
+ | {
+    t: 'role';
+    clientId: string;
+    role: string;
 } | {
     t: 'setLobby';
     public?: boolean;

package/dist/worker/index.js

@@ -1,6 +1,6 @@
 import {
   migrateSnapshot
-} from "../chunk-NSUQKWYO.js";
+} from "../chunk-GDXHCAD6.js";
 import {
   AdmissionError,
   RoomCore,
@@ -10,7 +10,7 @@ import {
   initRapier2d,
   onFirstRapierStep,
   rapierHasStepped
-} from "../chunk-RLY4VAMM.js";
+} from "../chunk-53X6AWQZ.js";
 
 // src/worker/index.ts
 import { getHeapStatistics } from "v8";
@@ -81,6 +81,9 @@ function createWorkerHost(post) {
     setBackfill(open) {
       post({ t: "setBackfill", open });
     },
+    roleChanged(clientId, role) {
+      post({ t: "role", clientId, role });
+    },
     // ---- M6 lane H: lobby front door ----
     setLobby(update) {
       post({ t: "setLobby", ...update });
@@ -322,8 +325,19 @@ async function handleMessage(state, host, post, msg) {
       }
       case "serialize": {
         const core = state.core;
-        if (!core) return;
-        const bytes = ownBuffer(msg.forSave ? core.snapshot() : core.serialize());
+        if (!core) {
+          post({ t: "serialized", reqId: msg.reqId, error: "room is not initialized" });
+          return;
+        }
+        let bytes;
+        try {
+          bytes = ownBuffer(msg.forSave ? core.snapshot() : core.serialize());
+        } catch (err) {
+          const detail = err instanceof Error ? err.stack ?? err.message : String(err);
+          post({ t: "log", level: "error", args: ["worker: handling 'serialize' threw", detail] });
+          post({ t: "serialized", reqId: msg.reqId, error: detail });
+          return;
+        }
         const timerAt = msg.forSave ? void 0 : core.lastSerializeTimerAt;
         post(
           {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/runtime",
-  "version": "4.7.1",
+  "version": "4.8.0",
   "description": "irtio room runtime: RoomCore, worker_threads host, in-process test harness",
   "license": "MIT",
   "repository": {
@@ -12,6 +12,9 @@
     "access": "public"
   },
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "sideEffects": false,
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -36,9 +39,9 @@
     "@dimforge/rapier2d-compat": "0.20.0",
     "@dimforge/rapier3d-compat": "0.20.0",
     "matter-js": "0.20.0",
-    "@irtio/protocol": "^4.7.1",
-    "@irtio/schema": "^4.7.1",
-    "@irtio/server": "^4.7.1"
+    "@irtio/protocol": "^4.8.0",
+    "@irtio/schema": "^4.8.0",
+    "@irtio/server": "^4.8.0"
   },
   "devDependencies": {
     "@types/matter-js": "0.20.2"