@irtio/runtime 3.1.1 → 4.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @irtio/runtime
+
+Execute irtio room definitions in a custom host or an in-process harness. The runtime applies
+client input, runs handlers, encodes state updates, and saves and restores rooms.
+
+```bash
+npm install @irtio/runtime @irtio/server @irtio/schema
+```
+
+For game development, use [`irtio dev`](https://irt.io/docs/reference/cli#irtio-dev) to run a room
+and [`@irtio/testing`](https://irt.io/docs/reference/testing) to test it with real SDK clients.
+
+## Run a room with the low-level harness
+
+This TypeScript example creates a room and advances one server tick:
+
+```ts
+import { defineSchema, singleton, u32 } from '@irtio/schema';
+import { defineRoom } from '@irtio/server';
+import { createRoomHarness } from '@irtio/runtime/test';
+
+const schema = defineSchema({ counter: singleton({ ticks: u32 }) });
+const definition = defineRoom(schema, {
+  mode: 'tick',
+  tickRate: 20,
+  tick(state) {
+    state.counter.ticks += 1;
+  },
+});
+
+const harness = createRoomHarness(definition);
+try {
+  harness.tick();
+  console.log(harness.state.counter.ticks); // 1
+} finally {
+  harness.stop();
+}
+```
+
+The low-level harness uses a fake clock and protocol clients. Its `tick()` and `run(ms)` methods
+are synchronous. This differs from the async methods in `@irtio/testing`.
+
+## Entry points
+
+| Import | Use |
+| --- | --- |
+| `@irtio/runtime` | `RoomCore`, host contracts, snapshots, migrations, and inspection |
+| `@irtio/runtime/test` | `createRoomHarness`, `FakeClock`, and test-host helpers |
+| `@irtio/runtime/worker` | Node worker host and typed worker messages |
+
+A custom host supplies the `RoomHost` contract, including time, scheduling, frame delivery, and
+room lifecycle operations. Keep credentials and transport admission checks at your host boundary.
+Initialize the appropriate physics engine before constructing a room that uses it.
+
+See the [server room API](https://irt.io/docs/reference/room) for the behavior room handlers expect
+and [hibernation](https://irt.io/docs/concepts/hibernation) for persistence and restoration rules.

package/dist/{chunk-2L3RGWXM.js → chunk-KJN62J37.js}

@@ -397,6 +397,22 @@ function isVisible(c, role) {
   if (c.visibility === "server") return false;
   return c.visibility !== "role" || (c.roles ?? []).includes(role);
 }
+function isPerClient(c) {
+  return c.visibility === "spatial-grid" || c.visibility === "owner";
+}
+var perClientCache = /* @__PURE__ */ new WeakMap();
+function perClientDescs(ext) {
+  let hit = perClientCache.get(ext);
+  if (!hit) {
+    const all = ext.collections;
+    hit = {
+      spatial: all.filter((c) => c.visibility === "spatial-grid"),
+      perClient: all.filter(isPerClient)
+    };
+    perClientCache.set(ext, hit);
+  }
+  return hit;
+}
 function visibleTo(role) {
   return (c) => isVisible(c, role);
 }
@@ -421,20 +437,30 @@ function encodeViewSnapshot(ext, plain, role, tick, memberships) {
     { tick },
     {
       collections: visibleTo(role),
-      entities: (c, id) => c.visibility !== "spatial-grid" || (memberships?.get(c.name)?.has(id) ?? false)
+      entities: (c, id) => !isPerClient(c) || (memberships?.get(c.name)?.has(id) ?? false)
     }
   );
 }
-function spatialMemberships(ext, plain, clientId, role, indexes = buildSpatialIndexes(ext.collections, plain)) {
+function ownedIds(plain, desc, clientId) {
+  const out = /* @__PURE__ */ new Set();
+  if (clientId === "") return out;
+  const coll = plainEntity(plain, desc.name);
+  for (const id of coll.ids()) if (coll.ownerOf(id) === clientId) out.add(id);
+  return out;
+}
+function viewMemberships(ext, plain, clientId, role, indexes = buildSpatialIndexes(ext.collections, plain)) {
   const out = /* @__PURE__ */ new Map();
   for (const [name, index] of indexes) out.set(name, querySpatialIndex(index, clientId, role));
+  for (const c of ext.collections) {
+    if (c.visibility === "owner") out.set(c.name, ownedIds(plain, c, clientId));
+  }
   return out;
 }
 var aoiMemo = /* @__PURE__ */ new WeakMap();
 function inClientView(core, clientId, desc, id) {
   const role = core.clients.get(clientId)?.role ?? "";
   if (!isVisible(desc, role)) return false;
-  if (desc.visibility !== "spatial-grid") return true;
+  if (!isPerClient(desc)) return true;
   let memo = aoiMemo.get(core);
   if (!memo || memo.tick !== core.tick) {
     memo = { tick: core.tick, byClient: /* @__PURE__ */ new Map() };
@@ -443,18 +469,23 @@ function inClientView(core, clientId, desc, id) {
   const key = `${clientId}\0${role}`;
   let mine = memo.byClient.get(key);
   if (!mine) {
-    mine = spatialMemberships(core.ext, core.plain, clientId, role);
+    mine = viewMemberships(core.ext, core.plain, clientId, role);
     memo.byClient.set(key, mine);
   }
   return mine.get(desc.name)?.has(id) ?? false;
 }
 function createVisibilityPolicy(ext, plain, clientId, role) {
-  const memberships = spatialMemberships(ext, plain, clientId, role);
+  const memberships = viewMemberships(ext, plain, clientId, role);
   return {
     memberships,
     maySeeCollection: (desc) => isVisible(desc, role),
-    maySeeEntity: (desc, id) => isVisible(desc, role) && (desc.visibility !== "spatial-grid" || (memberships.get(desc.name)?.has(id) ?? false)),
+    maySeeEntity: (desc, id) => isVisible(desc, role) && (!isPerClient(desc) || (memberships.get(desc.name)?.has(id) ?? false)),
     describeSpatial: (desc, ids) => {
+      if (desc.visibility === "owner") {
+        const coll2 = plainEntity(plain, desc.name);
+        const at2 = (id) => `${id} owned by ${coll2.ownerOf(id) || "<server>"}`;
+        return `viewer ${clientId}, ${desc.name} ${ids.map(at2).join(" ")}`;
+      }
       const grid = desc.grid;
       if (desc.visibility !== "spatial-grid" || !grid) return void 0;
       const coll = plainEntity(plain, desc.name);
@@ -469,13 +500,13 @@ function createVisibilityPolicy(ext, plain, clientId, role) {
 function sharedViewDirty(ext, dirty, role) {
   return filterDirty(dirty, (name) => {
     const desc = ext.collection(name);
-    return desc.visibility !== "spatial-grid" && isVisible(desc, role);
+    return !isPerClient(desc) && isVisible(desc, role);
   });
 }
-function aoiViewDirty(ext, dirty, previous, current) {
+function perClientViewDirty(ext, dirty, previous, current) {
   const out = createDirtySet();
   for (const desc of ext.collections) {
-    if (desc.visibility !== "spatial-grid") continue;
+    if (!isPerClient(desc)) continue;
     const before = previous.get(desc.name) ?? /* @__PURE__ */ new Set();
     const now = current.get(desc.name) ?? /* @__PURE__ */ new Set();
     for (const id of before) if (!now.has(id)) markRemove(out, desc.name, id);
@@ -497,7 +528,7 @@ function membershipSafeDirty(ext, dirty, memberships) {
   const out = createDirtySet();
   for (const [name, changed] of dirty) {
     const desc = ext.collection(name);
-    if (desc.visibility !== "spatial-grid") {
+    if (!isPerClient(desc)) {
       out.set(name, changed);
       continue;
     }
@@ -563,13 +594,16 @@ function catchUpDirty(ext, plain, fromRole, toRole) {
 import {
   ErrorCode as ErrorCode2,
   FrameType as FrameType2,
+  NO_REPLY_REQ_ID_BIT,
   OWNERSHIP_ASK,
+  REQ_ID_MASK,
   clampErrorMessage,
   decodeCall,
   decodeReply,
   encodeCall,
   encodeFrame as encodeFrame2,
   encodeReply,
+  isNoReplyReqId,
   isReservedRpcName,
   rpcByIdOf,
   rpcTable
@@ -578,12 +612,12 @@ import {
   SERVER_OWNER as SERVER_OWNER2,
   decodeFields,
   encodeFields,
-  validateValue
+  validateValue as validateValue2
 } from "@irtio/schema";
 import { DenyError } from "@irtio/server";
 
 // src/core/ownership.ts
-import { SERVER_OWNER, defaultRecord } from "@irtio/schema";
+import { SERVER_OWNER, cloneValue, defaultRecord, validateValue } from "@irtio/schema";
 var HOLD_ACTIONS = /* @__PURE__ */ new Set([
   "release",
   "nearest",
@@ -735,7 +769,7 @@ function nearestConnected(core, collection, id) {
   }
   return best;
 }
-function addPerPlayerRecords(core, clientId) {
+function addPerPlayerRecords(core, clientId, seeds) {
   for (const c of core.ext.collections) {
     if (c.kind !== "entity" || !c.perPlayer) continue;
     const coll = plainEntity(core.plain, c.name);
@@ -746,7 +780,23 @@ function addPerPlayerRecords(core, clientId) {
       continue;
     }
     try {
-      trackedEntity(core, c.name).add(clientId, defaultRecord(c), { owner: clientId });
+      const record = defaultRecord(c);
+      const seed = seeds?.get(c.name);
+      if (seed && c.persist) {
+        for (const field of c.persist) {
+          const value = seed[field];
+          if (value === void 0) continue;
+          const desc = c.fields[c.fieldIndex.get(field) ?? -1];
+          if (!desc) continue;
+          const err = validateValue(desc.type, value, `${c.name}.${field}`);
+          if (err) {
+            core.log("warn", `persisted ${c.name}.${field} for ${clientId} dropped: ${err}`);
+            continue;
+          }
+          record[field] = cloneValue(value);
+        }
+      }
+      trackedEntity(core, c.name).add(clientId, record, { owner: clientId });
     } catch (err) {
       core.log("error", `perPlayer add on ${c.name} failed for ${clientId}:`, err);
     }
@@ -942,7 +992,7 @@ function handleCall(core, clientId, payload) {
     return true;
   }
   for (const f of desc.params) {
-    const problem = validateValue(f.type, params[f.name], f.name);
+    const problem = validateValue2(f.type, params[f.name], f.name);
     if (problem) {
       traceEarly?.(errorText("E_RPC_BAD_PARAMS", problem));
       sendReply(core, clientId, call.reqId, null, errorText("E_RPC_BAD_PARAMS", problem));
@@ -1136,10 +1186,10 @@ function descFor(core, name) {
   }
   return found;
 }
-function sendCall(core, clientId, desc, params) {
+function sendCall(core, clientId, desc, params, noReply = false) {
   const s = stateOf3(core);
-  const reqId = s.nextReqId;
-  s.nextReqId = s.nextReqId + 1 >>> 0 || 1;
+  const reqId = noReply ? (s.nextReqId | NO_REPLY_REQ_ID_BIT) >>> 0 : s.nextReqId;
+  s.nextReqId = s.nextReqId + 1 & REQ_ID_MASK || 1;
   const bytes = encodeFields(desc.params, params);
   core.send(
     clientId,
@@ -1177,13 +1227,20 @@ function createCallProxy(core, clientId) {
         if (typeof prop !== "string") return void 0;
         return (params) => {
           const desc = descFor(core, prop);
-          return new Promise((resolve, reject2) => {
+          const p = new Promise((resolve, reject2) => {
             callClient(core, clientId, desc, params ?? {}, {
               timeoutMs: RPC_TIMEOUT_MS,
               resolve,
               reject: reject2
             });
           });
+          void p.catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            core.stats.rpcClientFailures++;
+            core.log("warn", `rpc ${desc.name} to ${clientId} failed: ${message}`);
+            core.recordEvent("error", clientId, `rpc ${desc.name}: ${message}`);
+          });
+          return p;
         };
       }
     }
@@ -1200,7 +1257,7 @@ function createBroadcastProxy(core, except) {
           for (const entry of core.clients.values()) {
             if (!entry.connected) continue;
             if (except?.has(entry.clientId)) continue;
-            sendCall(core, entry.clientId, desc, params ?? {});
+            sendCall(core, entry.clientId, desc, params ?? {}, true);
           }
         };
       }
@@ -1223,6 +1280,7 @@ function handleReply(core, clientId, payload) {
   const key = pendingKey(clientId, reply.reqId);
   const pending = s.pending.get(key);
   if (!pending) {
+    if (isNoReplyReqId(reply.reqId)) return true;
     core.log("warn", `REPLY from ${clientId} for unknown reqId ${reply.reqId}`);
     return true;
   }
@@ -1353,7 +1411,7 @@ function rejectAllHostCalls(core, reason) {
 // src/core/writes.ts
 import {
   SERVER_OWNER as SERVER_OWNER3,
-  cloneValue,
+  cloneValue as cloneValue2,
   decodeDelta,
   defaultValue,
   encodeDelta as encodeDelta2,
@@ -1407,7 +1465,7 @@ function applyMaskedPatch(fields, target, patch, mask) {
         continue;
       }
     }
-    target[f.name] = cloneValue(value);
+    target[f.name] = cloneValue2(value);
   }
 }
 function assignChanged(desc, target, key, prev, next) {
@@ -1487,7 +1545,7 @@ function applyOp(core, clientId, c, op) {
     );
     return;
   }
-  if (c.kind === "entity" && c.visibility === "spatial-grid") {
+  if (c.kind === "entity" && isPerClient(c)) {
     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`);
@@ -1532,17 +1590,17 @@ function applyOp(core, clientId, c, op) {
   const fields = fieldList(c);
   const growth = updateGrowth(c, leafPaths(fields, op.mask));
   if (growth > 0 && !admitGrowth(core, clientId, growth)) return;
-  const prev = cloneValue(current);
-  const next = cloneValue(current);
+  const prev = cloneValue2(current);
+  const next = cloneValue2(current);
   applyMaskedPatch(fields, next, op.patch, op.mask);
-  const requested = cloneValue(next);
+  const requested = cloneValue2(next);
   if (c.physics || c.serverFields) {
     const refused2 = [];
     for (const leaf of leafPaths(fields, op.mask)) {
       const field = leaf.names[0];
       const why = ownerMayNotWrite(c, field);
       if (why === void 0) continue;
-      next[field] = cloneValue(prev[field]);
+      next[field] = cloneValue2(prev[field]);
       refused2.push(why);
     }
     if (refused2.length > 0) {
@@ -1580,7 +1638,7 @@ function applyOp(core, clientId, c, op) {
       map = /* @__PURE__ */ new Map();
       entry.accepted.set(key, map);
     }
-    for (const leaf of written) map.set(leafKey(leaf), cloneValue(valueAt(result, leaf.names)));
+    for (const leaf of written) map.set(leafKey(leaf), cloneValue2(valueAt(result, leaf.names)));
   }
   const corrected = written.filter(
     (leaf) => !deepEqual(valueAt(result, leaf.names), valueAt(requested, leaf.names))
@@ -3774,7 +3832,7 @@ import {
   withBuiltins as withBuiltins2
 } from "@irtio/protocol";
 import {
-  cloneValue as cloneValue2,
+  cloneValue as cloneValue3,
   createDirtySet as createDirtySet3,
   createState,
   decodeSnapshot as decodeSnapshot3,
@@ -5121,7 +5179,7 @@ function stateOf6(core) {
 function omniscientMemberships(core) {
   const out = /* @__PURE__ */ new Map();
   for (const desc of core.ext.collections) {
-    if (desc.visibility !== "spatial-grid") continue;
+    if (!isPerClient(desc)) continue;
     out.set(desc.name, new Set(plainEntity(core.plain, desc.name).ids()));
   }
   return out;
@@ -5130,9 +5188,7 @@ function hasRoleScoped(core) {
   return core.ext.collections.some((c) => c.visibility === "role");
 }
 function hasSpatial(core) {
-  return core.ext.collections.some(
-    (c) => c.visibility === "spatial-grid"
-  );
+  return core.ext.collections.some(isPerClient);
 }
 function recorderSnapshot(core, state) {
   if (state.view === "") {
@@ -6141,7 +6197,7 @@ function ownJoinCapture(plain, name, added, clientId) {
   for (const id of added) {
     const owner = coll.ownerOf(id);
     if (name === PRESENCE_COLLECTION ? id !== clientId : owner !== clientId) continue;
-    (mine ??= /* @__PURE__ */ new Map()).set(id, { value: cloneValue2(coll.get(id)), owner });
+    (mine ??= /* @__PURE__ */ new Map()).set(id, { value: cloneValue3(coll.get(id)), owner });
   }
   return mine;
 }
@@ -6176,6 +6232,7 @@ var RoomCore = class _RoomCore {
     bytesOut: 0,
     bytesOutByClient: /* @__PURE__ */ new Map(),
     handlerErrors: 0,
+    rpcClientFailures: 0,
     encodesLastFlush: 0,
     aoiEncodesLastFlush: 0,
     gridBuildMs: 0,
@@ -6777,6 +6834,9 @@ var RoomCore = class _RoomCore {
       role: this.resolveRole(options.role, void 0),
       name: options.name ?? "",
       tick: this.tick,
+      // Bug #133: no `ClientEntry` exists yet, so the flag comes straight from the join options —
+      // the same value line 1130 will stamp on the entry a moment later if this admission passes.
+      npc: options.npc === true,
       deny: (reason) => {
         throw new DenyError2(reason);
       },
@@ -6838,7 +6898,7 @@ var RoomCore = class _RoomCore {
           this.plain,
           role2,
           this.tick,
-          spatialMemberships(this.ext, this.plain, clientId, role2)
+          viewMemberships(this.ext, this.plain, clientId, role2)
         )
       };
     }
@@ -6905,7 +6965,7 @@ var RoomCore = class _RoomCore {
     this.clients.set(clientId, entry);
     this.invalidateClients();
     reclaimHolds(this.internals, clientId, entry.playerId);
-    addPerPlayerRecords(this.internals, clientId);
+    addPerPlayerRecords(this.internals, clientId, options.persisted);
     const onJoin = this.definition.config.onJoin;
     if (onJoin) {
       const ctx = this.ctxFor(clientId, reconnecting);
@@ -6913,7 +6973,7 @@ var RoomCore = class _RoomCore {
     }
     if (!entry.npc) this.loop.noteActivity();
     this.recordEvent("join", clientId, reconnecting ? "reconnect" : void 0);
-    const memberships = spatialMemberships(this.ext, this.plain, clientId, entry.role);
+    const memberships = viewMemberships(this.ext, this.plain, clientId, entry.role);
     entry.spatialMembership = memberships;
     const snapshot = encodeViewSnapshot(this.ext, this.plain, entry.role, this.tick, memberships);
     entry.welcomed = true;
@@ -6928,7 +6988,7 @@ var RoomCore = class _RoomCore {
         const captured = mine ?? /* @__PURE__ */ new Map();
         for (const id of cd.added) {
           if (!visible.has(id) || captured.has(id)) continue;
-          captured.set(id, { value: cloneValue2(coll.get(id)), owner: coll.ownerOf(id) });
+          captured.set(id, { value: cloneValue3(coll.get(id)), owner: coll.ownerOf(id) });
         }
         if (captured.size > 0) pending.set(name2, captured);
       } else if (mine) pending.set(name2, mine);
@@ -6969,6 +7029,30 @@ var RoomCore = class _RoomCore {
     this.invalidateClients();
     this.eventFlush();
   }
+  // ---- M8 proposal 13: identity-keyed player persistence ----
+  /**
+   * The current values of every `persist` field this client's `perPlayer` records hold, or
+   * `undefined` when the schema declares none and when the client has no records.
+   *
+   * Read by the relay host just before `leave`, which is the last moment the records exist: the
+   * declared leave rules remove a `perPlayer` record.
+   */
+  persistedFieldsOf(clientId) {
+    let out;
+    for (const c of this.ext.collections) {
+      if (c.kind !== "entity" || !c.perPlayer || !c.persist || c.persist.length === 0) continue;
+      const record = plainEntity(this.plain, c.name).get(clientId);
+      if (!record) continue;
+      const picked = {};
+      for (const field of c.persist) {
+        const value = record[field];
+        if (value !== void 0) picked[field] = cloneValue3(value);
+      }
+      if (Object.keys(picked).length > 0) (out ??= /* @__PURE__ */ new Map()).set(c.name, picked);
+    }
+    return out;
+  }
+  // ---- end M8 proposal 13 ----
   markDisconnected(clientId) {
     const entry = this.clients.get(clientId);
     if (!entry) {
@@ -6995,6 +7079,9 @@ var RoomCore = class _RoomCore {
       // other entry point (join, leave, write, ownership) has no client tick by construction.
       clientTick: void 0,
       reconnecting,
+      // Bug #133: read from the seat, not from anything the session says about itself — only
+      // `room.spawnNPC`'s loopback join sets it, so an RPC ctx reports it honestly too.
+      npc: entry?.npc ?? false,
       room: this.room,
       // M7 pf4 (a): on every ctx rather than only the RPC one, because the type says it is there.
       // `rpc.ts` is what turns the throw into an `ok: false` reply; anywhere else it is a throw.
@@ -7193,7 +7280,7 @@ var RoomCore = class _RoomCore {
     this.ledger?.newFlush();
     this.stats.encodesLastFlush = 0;
     this.stats.aoiEncodesLastFlush = 0;
-    const spatialDescs = this.ext.collections.filter((desc) => desc.visibility === "spatial-grid");
+    const { spatial: spatialDescs, perClient } = perClientDescs(this.ext);
     const buildStarted = performance.now();
     const indexes = buildSpatialIndexes(spatialDescs, this.plain);
     this.stats.gridBuildMs += performance.now() - buildStarted;
@@ -7201,7 +7288,7 @@ var RoomCore = class _RoomCore {
     for (const entry of this.clients.values()) {
       if (entry.connected) {
         const queryStarted = performance.now();
-        const memberships = spatialMemberships(
+        const memberships = viewMemberships(
           this.ext,
           this.plain,
           entry.clientId,
@@ -7244,7 +7331,7 @@ var RoomCore = class _RoomCore {
           }
         }
         let delta;
-        if (spatialDescs.length > 0) {
+        if (perClient.length > 0) {
           const sourceDirty = entry.pendingJoinAdds ? stripAdds(this.plain, dirty, entry.pendingJoinAdds) : dirty;
           let shared;
           if (entry.pendingJoinAdds) {
@@ -7269,7 +7356,7 @@ var RoomCore = class _RoomCore {
               this.ledger ? { shared } : void 0
             );
           }
-          const aoiDirty = aoiViewDirty(
+          const aoiDirty = perClientViewDirty(
             this.ext,
             sourceDirty,
             entry.spatialMembership,
@@ -7310,7 +7397,7 @@ var RoomCore = class _RoomCore {
             encodeFrame5(FrameType6.DELTA, delta),
             this.ledger ? {
               ...churn ? { churn } : {},
-              ...spatialDescs.length > 0 ? {} : { shared: delta }
+              ...perClient.length > 0 ? {} : { shared: delta }
             } : void 0
           );
         }
@@ -7349,6 +7436,7 @@ export {
   summarize,
   RpcTraceRing,
   isVisible,
+  isPerClient,
   visibleTo,
   visibleNames,
   viewKeyFor,

package/dist/{chunk-XPRLQCNF.js → chunk-ZGJY4E3G.js}

@@ -3,7 +3,7 @@ import {
   parseHibernationBlob,
   sameSchemaHash,
   writeHibernationBlob
-} from "./chunk-2L3RGWXM.js";
+} from "./chunk-KJN62J37.js";
 
 // src/migrate.ts
 import { PRESENCE_COLLECTION, withBuiltins } from "@irtio/protocol";

package/dist/{contract-BoCNAPZT.d.ts → contract-DHWlURaq.d.ts}

@@ -552,6 +552,12 @@ interface JoinOptions {
      * therefore the only thing `room.ban` can key a cooldown on honestly.
      */
     readonly subject?: string;
+    /**
+     * Seed values for this client's fresh `perPlayer` records, from the relay host's persistence
+     * blob: collection name → partial field values. Applied only where a new record is created; a
+     * reclaimed or reconnected record keeps what it has.
+     */
+    readonly persisted?: ReadonlyMap<string, Readonly<Record<string, unknown>>>;
 }
 interface JoinResult {
     readonly tick: number;
@@ -598,6 +604,13 @@ interface RoomStats {
     /** Per connected client. */
     bytesOutByClient: Map<string, number>;
     handlerErrors: number;
+    /**
+     * Bug #131: server→client RPCs (`room.call(id).someRpc(...)`) that rejected — the client has no
+     * implementation, disconnected, or did not answer within the 5 s window. Counted whether or not
+     * the room's own code attached a `.catch`, and deliberately *not* a `handlerErrors`: nothing the
+     * room's code did threw.
+     */
+    rpcClientFailures: number;
     encodesLastFlush: number;
     aoiEncodesLastFlush: number;
     gridBuildMs: number;
@@ -657,6 +670,13 @@ interface RoomCoreApi<S extends AnySchema = AnySchema> {
     leave(clientId: string, reason: LeaveReason): void;
     /** Grace window opened by the host: presence `connected = false`; frames are no longer sent. */
     markDisconnected(clientId: string): void;
+    /**
+     * M8 proposal 13: the current values of every `persist` field this client's `perPlayer` records
+     * hold, or `undefined` when the schema declares none and when the client has no records.
+     *
+     * Read by the relay host just before `leave`, to write the player's persistence blob.
+     */
+    persistedFieldsOf(clientId: string): ReadonlyMap<string, Record<string, unknown>> | undefined;
     /** One inbound protocol frame (`WRITE` | `CALL` | `REPLY` | `MSG`). Anything else → host.kick(E_BAD_FRAME). */
     receive(clientId: string, frame: Uint8Array): void;
     /** Full state + tick + rng for hibernation. Runs `onSleep`. Clears timers. */

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-BoCNAPZT.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-CGbiPxi3.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-DHWlURaq.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-Bpo_nqlO.js';
 import { CollectionDesc, AnySchema, PlainState, DirtySet } from '@irtio/schema';
 import '@irtio/protocol';
 import '@irtio/server';
@@ -26,6 +26,12 @@ declare const RPC_TIMEOUT_MS = 5000;
  *
  * A collection with `visibility: 'role'` is visible only to the roles it names — including its
  * adds and removes, so a client never learns such a record exists.
+ *
+ * Two modes filter *entities* rather than collections, and both are handled by the same
+ * per-client membership machinery: `visibility: 'spatial-grid'` (the ids inside the client's AOI)
+ * and `visibility: 'owner'` (the ids the client owns, per the first-class `ownerOf` ownership
+ * every entity record carries). A server-owned record — owner `SERVER_OWNER`, the empty string —
+ * is owned by no client and is therefore visible to none.
  */
 
 /**
@@ -33,6 +39,13 @@ declare const RPC_TIMEOUT_MS = 5000;
  * answer `visibility: 'role'` with an empty `roles` list has always given, said on purpose.
  */
 declare function isVisible(c: CollectionDesc, role: string): boolean;
+/**
+ * Is `c` filtered per client rather than per role? `spatial-grid` by AOI membership, `owner` by
+ * record ownership. Both answer `isVisible` with `true` — from the role's side the collection
+ * genuinely is visible, and it is the entities that come and go — so every path that encodes or
+ * judges entities has to ask this question as well.
+ */
+declare function isPerClient(c: CollectionDesc): boolean;
 /** A `SnapshotOptions.collections` predicate for one role. */
 declare function visibleTo(role: string): (c: CollectionDesc) => boolean;
 /** Names of the collections `role` sees (memoised per schema + role). */
@@ -48,7 +61,10 @@ interface VisibilityPolicy {
     readonly memberships: ReadonlyMap<string, ReadonlySet<string>>;
     maySeeCollection(desc: CollectionDesc): boolean;
     maySeeEntity(desc: CollectionDesc, id: string): boolean;
-    /** Viewer cell, offending cells, and the radius — the diagnostics a leak report needs. */
+    /**
+     * Viewer cell, offending cells, and the radius — the diagnostics a leak report needs. For an
+     * `owner` collection it names the actual owner of each offending id instead.
+     */
     describeSpatial(desc: CollectionDesc, ids: readonly string[]): string | undefined;
 }
 /** Reusable authority-based policy for runtime, harness, and bot leak checks. */
@@ -245,4 +261,4 @@ declare function migrateSnapshot(blob: Uint8Array, chain: readonly MigrationStep
 declare function toMigrationState(schema: AnySchema, plain: PlainState): MigrationState;
 declare function fromMigrationState(schema: AnySchema, state: MigrationState, version: number): PlainState;
 
-export { type DecodedSave, type MigrateOptions, type MigrationEntity, type MigrationHelpers, type MigrationModule, type MigrationOutcome, type MigrationRecord, type MigrationState, type MigrationStep, type ParsedSnapshot, READABLE_SNAPSHOT_VERSIONS, RPC_TIMEOUT_MS, SNAPSHOT_FORMAT_VERSION, type SnapshotHeader, type SnapshotMode, type VisibilityPolicy, catchUpDirty, createVisibilityPolicy, decodeSave, encodeViewDelta, encodeViewSnapshot, fromMigrationState, isVisible, migrateSnapshot, parseHibernationBlob, toMigrationState, viewKeyFor, visibleNames, visibleTo, writeHibernationBlob };
+export { type DecodedSave, type MigrateOptions, type MigrationEntity, type MigrationHelpers, type MigrationModule, type MigrationOutcome, type MigrationRecord, type MigrationState, type MigrationStep, type ParsedSnapshot, READABLE_SNAPSHOT_VERSIONS, RPC_TIMEOUT_MS, SNAPSHOT_FORMAT_VERSION, type SnapshotHeader, type SnapshotMode, type VisibilityPolicy, catchUpDirty, createVisibilityPolicy, decodeSave, encodeViewDelta, encodeViewSnapshot, fromMigrationState, isPerClient, isVisible, migrateSnapshot, parseHibernationBlob, toMigrationState, viewKeyFor, visibleNames, visibleTo, writeHibernationBlob };

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   fromMigrationState,
   migrateSnapshot,
   toMigrationState
-} from "./chunk-XPRLQCNF.js";
+} from "./chunk-ZGJY4E3G.js";
 import {
   AdmissionError,
   CRASH_AFTER_THROWS,
@@ -44,6 +44,7 @@ import {
   initPhysics,
   initRapier2d,
   inspectState,
+  isPerClient,
   isVisible,
   loadedMatter,
   loadedPhysics,
@@ -58,7 +59,7 @@ import {
   visibleNames,
   visibleTo,
   writeHibernationBlob
-} from "./chunk-2L3RGWXM.js";
+} from "./chunk-KJN62J37.js";
 export {
   AdmissionError,
   CRASH_AFTER_THROWS,
@@ -101,6 +102,7 @@ export {
   initPhysics,
   initRapier2d,
   inspectState,
+  isPerClient,
   isVisible,
   loadedMatter,
   loadedPhysics,

package/dist/{room-CGbiPxi3.d.ts → room-Bpo_nqlO.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, 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-BoCNAPZT.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-DHWlURaq.js';
 
 declare class Mulberry32 {
     /** Current internal state (u32). Survives hibernation. */
@@ -83,7 +83,12 @@ interface ClientEntry {
      * Every other client's delta is unaffected.
      */
     pendingJoinAdds: Map<string, ReadonlyMap<string, JoinAddCapture>> | undefined;
-    /** Last AOI membership sent to this client, keyed by spatial collection. */
+    /**
+     * Last per-client entity membership sent to this client, keyed by collection: AOI membership
+     * for a `spatial-grid` collection, the ids it owns for an `owner` one. The diff against this
+     * flush's membership is what synthesises the adds and removes neither the dirty set nor the
+     * shared per-role payload can carry.
+     */
     spatialMembership: Map<string, Set<string>>;
 }
 /** What `join` captured for one of a client's own just-added records, for `flush`'s comparison. */
@@ -1152,6 +1157,14 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     /** Event mode only: presence/lifecycle changes are their own event. No-op in tick mode. */
     private eventFlush;
     leave(clientId: string, reason: LeaveReason): void;
+    /**
+     * The current values of every `persist` field this client's `perPlayer` records hold, or
+     * `undefined` when the schema declares none and when the client has no records.
+     *
+     * Read by the relay host just before `leave`, which is the last moment the records exist: the
+     * declared leave rules remove a `perPlayer` record.
+     */
+    persistedFieldsOf(clientId: string): ReadonlyMap<string, Record<string, unknown>> | undefined;
     markDisconnected(clientId: string): void;
     ctxFor(clientId: string, reconnecting?: boolean): Ctx;
     /**

package/dist/test/index.d.ts

@@ -1,8 +1,8 @@
-import { R as RoomCore } from '../room-CGbiPxi3.js';
-export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-CGbiPxi3.js';
+import { R as RoomCore } from '../room-Bpo_nqlO.js';
+export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-Bpo_nqlO.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-BoCNAPZT.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-DHWlURaq.js';
 import { AnySchema, PlainState, EntityCollection, State } from '@irtio/schema';
 
 /**
@@ -20,6 +20,14 @@ declare class FakeClock {
     clearTimeout(handle: unknown): void;
     /** Number of timers still armed (a room that is ticking always has at least one). */
     get pending(): number;
+    /**
+     * The `at` of the earliest armed timer, or `undefined` when nothing is armed. Read-only: it
+     * changes nothing. It exists for callers that need to advance to the next timer rather than
+     * over it — `testRoom`'s `t.run(ms)` uses it to hop timer by timer, so a script parked on an
+     * `await` (whose continuation only runs once `advance` has returned and microtasks drain) can
+     * arm its next timer and keep going inside a single long run.
+     */
+    nextDueAt(): number | undefined;
     /**
      * Advances to `time + ms`, firing every timer that comes due in order (earliest `at` first,
      * ties broken by creation order). A timer that arms another timer inside the window fires too.
@@ -361,6 +369,11 @@ interface JoinSpec {
      * `onAdmit` that requires identity needs to be tested against.
      */
     readonly subject?: string;
+    /**
+     * The persistence blob this join arrives with: collection name → persisted field values. What
+     * the relay host reads from the store for an identified player, without a store or a socket.
+     */
+    readonly persisted?: ReadonlyMap<string, Readonly<Record<string, unknown>>>;
 }
 interface UntilOptions {
     /** Default 1000. */

package/dist/test/index.js

@@ -4,8 +4,9 @@ import {
   initMatter,
   initPhysics,
   initRapier2d,
+  isPerClient,
   visibleNames
-} from "../chunk-2L3RGWXM.js";
+} from "../chunk-KJN62J37.js";
 
 // src/test/clock.ts
 var FakeClock = class {
@@ -28,6 +29,22 @@ var FakeClock = class {
   get pending() {
     return this.timers.size;
   }
+  /**
+   * The `at` of the earliest armed timer, or `undefined` when nothing is armed. Read-only: it
+   * changes nothing. It exists for callers that need to advance to the next timer rather than
+   * over it — `testRoom`'s `t.run(ms)` uses it to hop timer by timer, so a script parked on an
+   * `await` (whose continuation only runs once `advance` has returned and microtasks drain) can
+   * arm its next timer and keep going inside a single long run.
+   */
+  nextDueAt() {
+    let earliest;
+    for (const t of this.timers.values()) {
+      if (!earliest || t.at < earliest.at || t.at === earliest.at && t.id < earliest.id) {
+        earliest = t;
+      }
+    }
+    return earliest?.at;
+  }
   /**
    * Advances to `time + ms`, firing every timer that comes due in order (earliest `at` first,
    * ties broken by creation order). A timer that arms another timer inside the window fires too.
@@ -336,6 +353,7 @@ import {
   encodeFrame,
   encodeMsg,
   encodeReply,
+  isNoReplyReqId,
   rpcTable
 } from "@irtio/protocol";
 import {
@@ -605,7 +623,7 @@ var FakeClientImpl = class {
   /** Flags any collection the frame named that this client's role may not see. */
   checkFrameVisibility(delta) {
     for (const dc of delta.collections) {
-      const spatial = this.bridge.ext.collection(dc.name).visibility === "spatial-grid";
+      const spatial = isPerClient(this.bridge.ext.collection(dc.name));
       const leaked = dc.ops.filter((op) => {
         if (!this.bridge.visible(this.role, this.id, dc.name)) return true;
         if (!spatial) return false;
@@ -644,20 +662,26 @@ var FakeClientImpl = class {
     this.calls.push({ name: desc.name, params });
     const impl = this.impls.get(desc.name);
     if (!impl) return;
+    const noReply = isNoReplyReqId(call.reqId);
     let result;
     try {
       result = impl(params);
     } catch (err) {
-      this.replyError(call.reqId, err);
+      if (!noReply) this.replyError(call.reqId, err);
       return;
     }
     if (isThenable(result)) {
       Promise.resolve(result).then(
-        (v) => this.replyOk(desc, call.reqId, v),
-        (err) => this.replyError(call.reqId, err)
+        (v) => {
+          if (!noReply) this.replyOk(desc, call.reqId, v);
+        },
+        (err) => {
+          if (!noReply) this.replyError(call.reqId, err);
+        }
       );
       return;
     }
+    if (noReply) return;
     this.replyOk(desc, call.reqId, result);
   }
   replyOk(desc, reqId, result) {
@@ -966,8 +990,11 @@ var Harness = class {
       ...spec.playerId !== void 0 ? { playerId: spec.playerId } : {},
       // ---- end M6 lane K ----
       // ---- M8 lane 5: moderation ----
-      ...spec.subject !== void 0 ? { subject: spec.subject } : {}
+      ...spec.subject !== void 0 ? { subject: spec.subject } : {},
       // ---- end M8 lane 5 ----
+      // ---- M8 proposal 13 ----
+      ...spec.persisted !== void 0 ? { persisted: spec.persisted } : {}
+      // ---- end M8 proposal 13 ----
     };
     const client = new FakeClientImpl(this.bridge, id, options);
     this.byId.set(id, client);
@@ -991,7 +1018,7 @@ var Harness = class {
       const keep = visibleNames(ext, client.role);
       const policy = createVisibilityPolicy(ext, this.coreRef.plain, client.id, client.role);
       for (const c of ext.collections) {
-        if (c.visibility === "spatial-grid") {
+        if (isPerClient(c)) {
           const coll = client.view[c.name];
           const ids = coll ? [...coll.ids()].filter((id) => !policy.maySeeEntity(c, id)) : [];
           if (ids.length > 0) {

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-BoCNAPZT.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-DHWlURaq.js';
 import { ErrorCodeName, ProfileSnapshot, PlatformNotice } from '@irtio/protocol';
 import { NpcConfig, LeaveReason } from '@irtio/server';
 import '@irtio/schema';

package/dist/worker/index.js

@@ -1,6 +1,6 @@
 import {
   migrateSnapshot
-} from "../chunk-XPRLQCNF.js";
+} from "../chunk-ZGJY4E3G.js";
 import {
   AdmissionError,
   RoomCore,
@@ -10,7 +10,7 @@ import {
   initRapier2d,
   onFirstRapierStep,
   rapierHasStepped
-} from "../chunk-2L3RGWXM.js";
+} from "../chunk-KJN62J37.js";
 
 // src/worker/index.ts
 import { getHeapStatistics } from "v8";
@@ -452,6 +452,16 @@ if (!isMainThread && parentPort) {
   const post = (msg, transfer) => {
     port.postMessage(msg, transfer ?? transferList(msg));
   };
+  process.on("unhandledRejection", (reason) => {
+    post({
+      t: "log",
+      level: "error",
+      args: [
+        "worker: unhandled rejection",
+        reason instanceof Error ? reason.stack ?? reason.message : reason
+      ]
+    });
+  });
   const host = createWorkerHost(post);
   const state = { core: void 0 };
   port.on("message", (msg) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/runtime",
-  "version": "3.1.1",
+  "version": "4.1.0",
   "description": "irtio room runtime: RoomCore, worker_threads host, in-process test harness",
   "license": "MIT",
   "repository": {
@@ -36,9 +36,9 @@
     "@dimforge/rapier2d-compat": "0.20.0",
     "@dimforge/rapier3d-compat": "0.20.0",
     "matter-js": "0.20.0",
-    "@irtio/protocol": "3.1.1",
-    "@irtio/schema": "3.1.1",
-    "@irtio/server": "3.1.1"
+    "@irtio/protocol": "^4.1.0",
+    "@irtio/schema": "^4.1.0",
+    "@irtio/server": "^4.1.0"
   },
   "devDependencies": {
     "@types/matter-js": "0.20.2"