@irtio/runtime 0.10.0 → 0.11.0

package/dist/{chunk-KGZEQTJR.js → chunk-GYPUNTQN.js}

@@ -9,6 +9,181 @@ var RoomFullError = class extends Error {
   name = "RoomFullError";
 };
 
+// src/core/caps.ts
+import {
+  ErrorCode,
+  FrameType,
+  encodeErrorPayload,
+  encodeFrame,
+  formatError
+} from "@irtio/protocol";
+import { encodeSnapshot } from "@irtio/schema";
+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 RELAY_WRITE_CAPS = {
+  stateBytes: RELAY_STATE_BYTES,
+  recordsPerCollection: RELAY_RECORDS_PER_COLLECTION,
+  writesPerSecond: RELAY_WRITES_PER_SECOND
+};
+function refuseByName(core, clientId, code, vars) {
+  const message = formatError(code, vars);
+  core.recordEvent("write-rejected", clientId, `${code}: ${message}`);
+  core.send(
+    clientId,
+    encodeFrame(
+      FrameType.ERROR,
+      encodeErrorPayload({ code: ErrorCode[code].code, message, fatal: false })
+    )
+  );
+}
+function maxTypeBytes(t) {
+  const optional = t.opt ? 1 : 0;
+  switch (t.kind) {
+    case "bool":
+    case "u8":
+      return optional + 1;
+    case "u16":
+      return optional + 2;
+    case "u32":
+    case "i32":
+    case "f32":
+      return optional + 4;
+    case "f64":
+      return optional + 8;
+    case "enum":
+      return optional + 2;
+    case "str":
+      return optional + 5 + t.max * 4;
+    case "ref":
+      return optional + 5 + 64 * 4;
+    case "list":
+      return optional + 5 + t.max * maxTypeBytes(t.item);
+    case "struct": {
+      let sum = optional;
+      for (const f of Object.values(t.fields)) sum += maxTypeBytes(f);
+      return sum;
+    }
+    default:
+      return optional + 8;
+  }
+}
+function maxRecordBytes(c) {
+  let sum = 5 + 64 * 4 + 5 + 64 * 4;
+  for (const f of c.fields) sum += maxTypeBytes(f.type);
+  return sum;
+}
+var STALE_MEASURE_TICKS = 300;
+var StateMeter = class {
+  constructor(core, cap) {
+    this.core = core;
+    this.cap = cap;
+    this.figure = this.measure();
+  }
+  core;
+  cap;
+  /** The running figure: the last exact measure plus every accepted write's upper bound since. */
+  figure;
+  measuredAtTick = -1;
+  measure() {
+    const bytes = encodeSnapshot(this.core.ext, this.core.plain, { tick: this.core.tick });
+    this.measuredAtTick = this.core.tick;
+    return bytes.length;
+  }
+  /** Has the figure gone long enough without an exact measure to be worth distrusting? */
+  stale() {
+    return this.core.tick - this.measuredAtTick >= STALE_MEASURE_TICKS;
+  }
+  /**
+   * The truth, if it is worth paying for: over half the cap, or stale, and at most once a tick.
+   * A small room that is being written to steadily encodes once every {@link STALE_MEASURE_TICKS}
+   * ticks and otherwise uses the running figure, which is why it costs next to nothing.
+   */
+  refresh() {
+    if (this.measuredAtTick === this.core.tick) return;
+    if (this.figure * 2 <= this.cap && !this.stale()) return;
+    this.figure = this.measure();
+  }
+  /** `true` when a write that could add `growth` bytes must be refused. */
+  wouldExceed(growth) {
+    if (this.stale()) this.refresh();
+    if (this.figure + growth <= this.cap) return false;
+    this.refresh();
+    return this.figure + growth > this.cap;
+  }
+  /** Records an accepted write's upper bound. */
+  grew(growth) {
+    this.figure += growth;
+  }
+  /** The current figure, for the room row and `irtio rooms`. Exact when it matters. */
+  bytes() {
+    this.refresh();
+    return this.figure;
+  }
+};
+var states = /* @__PURE__ */ new WeakMap();
+function installCaps(core, caps) {
+  states.set(core, {
+    caps,
+    meter: caps.stateBytes !== void 0 ? new StateMeter(core, caps.stateBytes) : void 0,
+    buckets: /* @__PURE__ */ new Map()
+  });
+}
+function stateOf(core) {
+  let s = states.get(core);
+  if (!s) {
+    s = { caps: {}, meter: void 0, buckets: /* @__PURE__ */ new Map() };
+    states.set(core, s);
+  }
+  return s;
+}
+function recordCap(core) {
+  return stateOf(core).caps.recordsPerCollection ?? DEFAULT_RECORDS_PER_COLLECTION;
+}
+function admitGrowth(core, clientId, growth) {
+  const meter = stateOf(core).meter;
+  if (!meter) return true;
+  if (meter.wouldExceed(growth)) {
+    refuseByName(core, clientId, "E_STATE_CAP", { limit: meter.cap });
+    return false;
+  }
+  meter.grew(growth);
+  return true;
+}
+function stateBytesOf(core) {
+  return stateOf(core).meter?.bytes();
+}
+function admitWrite(core, clientId, nowMs, ops = 1) {
+  const s = stateOf(core);
+  const limit = s.caps.writesPerSecond;
+  if (limit === void 0) return true;
+  const cost = Math.max(1, ops);
+  let bucket = s.buckets.get(clientId);
+  if (!bucket) {
+    bucket = { tokens: limit, at: nowMs, told: false };
+    s.buckets.set(clientId, bucket);
+  }
+  const elapsed = nowMs - bucket.at;
+  if (elapsed > 0) {
+    bucket.tokens = Math.min(limit, bucket.tokens + elapsed * limit / 1e3);
+    bucket.at = nowMs;
+  }
+  if (bucket.tokens >= cost) {
+    bucket.tokens -= cost;
+    bucket.told = false;
+    return true;
+  }
+  if (!bucket.told) {
+    bucket.told = true;
+    refuseByName(core, clientId, "E_WRITE_RATE", { limit });
+  }
+  return false;
+}
+function forgetWriter(core, clientId) {
+  states.get(core)?.buckets.delete(clientId);
+}
+
 // src/core/inspect.ts
 import { EntityCollection } from "@irtio/schema";
 var EVENT_RING_SIZE = 100;
@@ -39,17 +214,17 @@ function inspectState(schema, plain) {
 
 // src/core/rpc.ts
 import {
-  FrameType,
+  FrameType as FrameType2,
   decodeCall,
   decodeReply,
   encodeCall,
-  encodeFrame,
+  encodeFrame as encodeFrame2,
   encodeReply,
   rpcByIdOf,
   rpcTable
 } from "@irtio/protocol";
 import {
-  SERVER_OWNER,
+  SERVER_OWNER as SERVER_OWNER2,
   decodeFields,
   encodeFields,
   validateValue
@@ -81,15 +256,251 @@ function deepEqual(a, b) {
   return true;
 }
 
+// src/core/ownership.ts
+import { SERVER_OWNER, defaultRecord } from "@irtio/schema";
+var states2 = /* @__PURE__ */ new WeakMap();
+function stateOf2(core) {
+  let s = states2.get(core);
+  if (!s) {
+    s = { holds: /* @__PURE__ */ new Map(), askWarned: false };
+    states2.set(core, s);
+  }
+  return s;
+}
+function keyOf(collection, id) {
+  return `${collection} ${id}`;
+}
+function policyCollections(core) {
+  return core.ext.collections.filter(
+    (c) => c.kind === "entity" && c.ownership !== void 0
+  );
+}
+function wallNow(core) {
+  return core.wallNow();
+}
+function holdOn(core, collection, id) {
+  return states2.get(core)?.holds.get(keyOf(collection, id));
+}
+function holdCount(core) {
+  return states2.get(core)?.holds.size ?? 0;
+}
+function placeHolds(core, clientId, playerId) {
+  const s = stateOf2(core);
+  const now = wallNow(core);
+  for (const c of policyCollections(core)) {
+    const policy = c.ownership;
+    const coll = plainEntity(core.plain, c.name);
+    for (const id of [...coll.ids()]) {
+      if (coll.ownerOf(id) !== clientId) continue;
+      const hold = {
+        collection: c.name,
+        id,
+        holder: playerId,
+        deadlineMs: now + policy.holdMs,
+        // `then` is the D77 spec's own name for the leave action; a hold is plain data nothing
+        // ever awaits.
+        // biome-ignore lint/suspicious/noThenProperty: see above
+        then: policy.then
+      };
+      if (policy.holdMs <= 0) {
+        act(core, hold);
+        continue;
+      }
+      s.holds.set(keyOf(c.name, id), hold);
+    }
+  }
+}
+function reclaimHolds(core, clientId, playerId) {
+  const s = states2.get(core);
+  if (!s || s.holds.size === 0) return 0;
+  let reclaimed = 0;
+  for (const [key, hold] of [...s.holds]) {
+    if (hold.holder !== playerId) continue;
+    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);
+    reclaimed++;
+  }
+  return reclaimed;
+}
+function expireHolds(core) {
+  const s = states2.get(core);
+  if (!s || s.holds.size === 0) return;
+  const now = wallNow(core);
+  for (const [key, hold] of [...s.holds]) {
+    if (hold.deadlineMs > now) continue;
+    s.holds.delete(key);
+    act(core, hold);
+  }
+}
+function act(core, hold) {
+  const coll = plainEntity(core.plain, hold.collection);
+  if (!coll.has(hold.id)) return;
+  const tracked = trackedEntity(core, hold.collection);
+  switch (hold.then) {
+    case "remove":
+      tracked.remove(hold.id);
+      return;
+    case "release":
+      tracked.setOwner(hold.id, SERVER_OWNER);
+      return;
+    case "nearest": {
+      const to = nearestConnected(core, hold.collection, hold.id);
+      tracked.setOwner(hold.id, to ?? SERVER_OWNER);
+      return;
+    }
+    case "random": {
+      const candidates = connectedClients(core);
+      if (candidates.length === 0) {
+        tracked.setOwner(hold.id, SERVER_OWNER);
+        return;
+      }
+      const pick = candidates[Math.floor(core.rng.next() * candidates.length)];
+      tracked.setOwner(hold.id, pick);
+      return;
+    }
+    default:
+      return;
+  }
+}
+function connectedClients(core) {
+  const out = [];
+  for (const entry of core.clients.values()) if (entry.connected) out.push(entry.clientId);
+  return out;
+}
+function numberAt(record, field) {
+  if (!record) return void 0;
+  const v = record[field];
+  return typeof v === "number" && Number.isFinite(v) ? v : void 0;
+}
+function distanceTo(core, policy, object, clientId) {
+  const position = policy.position;
+  if (!position || !object) return void 0;
+  const players = plainEntity(core.plain, position.players);
+  const player = players.get(clientId);
+  const px = numberAt(player, position.x);
+  const py = numberAt(player, position.y);
+  const ox = numberAt(object, position.x);
+  const oy = numberAt(object, position.y);
+  if (px === void 0 || py === void 0 || ox === void 0 || oy === void 0)
+    return void 0;
+  return Math.hypot(px - ox, py - oy);
+}
+function nearestConnected(core, collection, id) {
+  const c = core.ext.collections.find((x) => x.name === collection);
+  const policy = c?.ownership;
+  if (!policy?.position) return void 0;
+  const object = plainEntity(core.plain, collection).get(id);
+  let best;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const clientId of connectedClients(core)) {
+    const d = distanceTo(core, policy, object, clientId);
+    if (d === void 0 || d >= bestDistance) continue;
+    bestDistance = d;
+    best = clientId;
+  }
+  return best;
+}
+function addPerPlayerRecords(core, clientId) {
+  for (const c of core.ext.collections) {
+    if (c.kind !== "entity" || !c.perPlayer) continue;
+    const coll = plainEntity(core.plain, c.name);
+    if (coll.has(clientId)) {
+      if (coll.ownerOf(clientId) !== clientId) {
+        trackedEntity(core, c.name).setOwner(clientId, clientId);
+      }
+      continue;
+    }
+    try {
+      trackedEntity(core, c.name).add(clientId, defaultRecord(c), { owner: clientId });
+    } catch (err) {
+      core.log("error", `perPlayer add on ${c.name} failed for ${clientId}:`, err);
+    }
+  }
+}
+function resolveTransfer(core, clientId, c, id) {
+  const policy = c.ownership;
+  const coll = plainEntity(core.plain, c.name);
+  const owner = coll.ownerOf(id);
+  if (owner === clientId) return "granted";
+  const hold = holdOn(core, c.name, id);
+  if (hold) {
+    const playerId = core.clients.get(clientId)?.playerId ?? clientId;
+    if (hold.holder !== playerId) return "refused";
+    reclaimHolds(core, clientId, playerId);
+    return coll.ownerOf(id) === clientId ? "granted" : "refused";
+  }
+  switch (policy.transfer) {
+    case "never":
+      return "refused";
+    case "free":
+      trackedEntity(core, c.name).setOwner(id, clientId);
+      return "granted";
+    case "closer": {
+      if (owner === void 0 || owner === SERVER_OWNER) {
+        trackedEntity(core, c.name).setOwner(id, clientId);
+        return "granted";
+      }
+      const object = coll.get(id);
+      const ownerDistance = distanceTo(core, policy, object, owner);
+      if (ownerDistance === void 0) {
+        trackedEntity(core, c.name).setOwner(id, clientId);
+        return "granted";
+      }
+      const mine = distanceTo(core, policy, object, clientId);
+      if (mine === void 0) return "refused";
+      if (mine + policy.by >= ownerDistance) return "refused";
+      trackedEntity(core, c.name).setOwner(id, clientId);
+      return "granted";
+    }
+    case "ask": {
+      const s = stateOf2(core);
+      if (!s.askWarned) {
+        s.askWarned = true;
+        core.log(
+          "warn",
+          `${c.name}: ownership transfer 'ask' is not yet forwarded to owners; requests are refused (the same answer an owner who does not reply gives). Use 'closer' or 'free' for now.`
+        );
+      }
+      return "refused";
+    }
+    default:
+      return "refused";
+  }
+}
+function serializeHolds(core) {
+  const s = states2.get(core);
+  if (!s || s.holds.size === 0) return void 0;
+  const json = JSON.stringify([...s.holds.values()]);
+  return new TextEncoder().encode(json);
+}
+function restoreHolds(core, bytes) {
+  const s = stateOf2(core);
+  s.holds.clear();
+  if (!bytes || bytes.length === 0) return;
+  try {
+    const parsed = JSON.parse(new TextDecoder().decode(bytes));
+    for (const h of parsed) {
+      if (typeof h?.collection !== "string" || typeof h.id !== "string" || typeof h.holder !== "string" || typeof h.deadlineMs !== "number") {
+        continue;
+      }
+      s.holds.set(keyOf(h.collection, h.id), h);
+    }
+  } catch (err) {
+    core.log("warn", "hold deadlines did not decode; the room wakes holding nothing:", err);
+  }
+}
+
 // src/core/rpc.ts
 var RPC_TIMEOUT_MS = 5e3;
 var REQUEST_OWNERSHIP = "requestOwnership";
-var states = /* @__PURE__ */ new WeakMap();
-function stateOf(core) {
-  let s = states.get(core);
+var states3 = /* @__PURE__ */ new WeakMap();
+function stateOf3(core) {
+  let s = states3.get(core);
   if (!s) {
     s = { nextReqId: 1, pending: /* @__PURE__ */ new Map() };
-    states.set(core, s);
+    states3.set(core, s);
   }
   return s;
 }
@@ -101,7 +512,7 @@ function errorText(code, detail) {
 }
 function sendReply(core, clientId, reqId, result, error) {
   const payload = result === null ? encodeReply({ reqId, ok: false, error: error ?? errorText("E_INTERNAL") }) : encodeReply({ reqId, ok: true, result });
-  core.send(clientId, encodeFrame(FrameType.REPLY, payload));
+  core.send(clientId, encodeFrame2(FrameType2.REPLY, payload));
 }
 function handleCall(core, clientId, payload) {
   let call;
@@ -184,6 +595,9 @@ function runRequestOwnership(core, clientId, ctx, params) {
   if (!plain.has(id)) return { granted: false };
   const handler = core.definition.config.onOwnershipRequest;
   const tracked = trackedEntity(core, name);
+  if (!handler && c.ownership) {
+    return { granted: resolveTransfer(core, clientId, c, id) === "granted" };
+  }
   if (handler) {
     const ran = core.tryRun("onOwnershipRequest", () => handler(core.anyState, name, id, ctx));
     if (ran.ok && ran.value === true && plain.ownerOf(id) !== clientId) {
@@ -193,7 +607,7 @@ function runRequestOwnership(core, clientId, ctx, params) {
   }
   const owner = plain.ownerOf(id);
   if (owner === clientId) return { granted: true };
-  if (owner !== SERVER_OWNER) return { granted: false };
+  if (owner !== SERVER_OWNER2) return { granted: false };
   tracked.setOwner(id, clientId);
   return { granted: true };
 }
@@ -206,13 +620,13 @@ function descFor(core, name) {
   return found;
 }
 function sendCall(core, clientId, desc, params) {
-  const s = stateOf(core);
+  const s = stateOf3(core);
   const reqId = s.nextReqId;
   s.nextReqId = s.nextReqId + 1 >>> 0 || 1;
   const bytes = encodeFields(desc.params, params);
   core.send(
     clientId,
-    encodeFrame(FrameType.CALL, encodeCall({ reqId, rpcId: desc.index, params: bytes }))
+    encodeFrame2(FrameType2.CALL, encodeCall({ reqId, rpcId: desc.index, params: bytes }))
   );
   return reqId;
 }
@@ -232,7 +646,7 @@ function createCallProxy(core, clientId) {
               return;
             }
             const reqId = sendCall(core, clientId, desc, params ?? {});
-            const s = stateOf(core);
+            const s = stateOf3(core);
             s.pending.set(pendingKey(clientId, reqId), {
               clientId,
               name: desc.name,
@@ -280,7 +694,7 @@ function handleReply(core, clientId, payload) {
     core.log("warn", `REPLY from ${clientId} failed to decode:`, err);
     return false;
   }
-  const s = stateOf(core);
+  const s = stateOf3(core);
   const key = pendingKey(clientId, reply.reqId);
   const pending = s.pending.get(key);
   if (!pending) {
@@ -304,7 +718,7 @@ function handleReply(core, clientId, payload) {
   return true;
 }
 function rejectPendingFor(core, clientId, reason) {
-  const s = stateOf(core);
+  const s = stateOf3(core);
   for (const [key, p] of [...s.pending]) {
     if (p.clientId !== clientId) continue;
     s.pending.delete(key);
@@ -312,7 +726,7 @@ function rejectPendingFor(core, clientId, reason) {
   }
 }
 function checkTimeouts(core) {
-  const s = stateOf(core);
+  const s = stateOf3(core);
   if (s.pending.size === 0) return;
   const now = core.host.now();
   for (const [key, p] of [...s.pending]) {
@@ -322,7 +736,7 @@ function checkTimeouts(core) {
   }
 }
 function rejectAllPending(core, reason) {
-  const s = stateOf(core);
+  const s = stateOf3(core);
   for (const [key, p] of [...s.pending]) {
     s.pending.delete(key);
     p.reject(new Error(reason));
@@ -330,15 +744,15 @@ function rejectAllPending(core, reason) {
 }
 
 // src/core/loop.ts
-import { FrameType as FrameType2 } from "@irtio/protocol";
+import { FrameType as FrameType3 } from "@irtio/protocol";
 
 // src/core/host-calls.ts
-var states2 = /* @__PURE__ */ new WeakMap();
-function stateOf2(core) {
-  let s = states2.get(core);
+var states4 = /* @__PURE__ */ new WeakMap();
+function stateOf4(core) {
+  let s = states4.get(core);
   if (!s) {
     s = { nextReqId: 1, pending: /* @__PURE__ */ new Map() };
-    states2.set(core, s);
+    states4.set(core, s);
   }
   return s;
 }
@@ -351,7 +765,7 @@ function startHostCall(core, call, map) {
     return rejectAsEvent(core, new Error(`room.${call.kind}: the room is stopped`));
   }
   return new Promise((resolve, reject2) => {
-    const s = stateOf2(core);
+    const s = stateOf4(core);
     const reqId = s.nextReqId;
     s.nextReqId = s.nextReqId + 1 >>> 0 || 1;
     s.pending.set(reqId, {
@@ -375,7 +789,7 @@ function startHostCall(core, call, map) {
   });
 }
 function completeHostCall(core, reqId, result) {
-  const s = stateOf2(core);
+  const s = stateOf4(core);
   const pending = s.pending.get(reqId);
   if (!pending) return false;
   s.pending.delete(reqId);
@@ -384,7 +798,7 @@ function completeHostCall(core, reqId, result) {
   return true;
 }
 function checkHostCallTimeouts(core) {
-  const s = stateOf2(core);
+  const s = stateOf4(core);
   if (s.pending.size === 0) return;
   const now = core.host.now();
   for (const [reqId, p] of [...s.pending]) {
@@ -394,7 +808,7 @@ function checkHostCallTimeouts(core) {
   }
 }
 function rejectAllHostCalls(core, reason) {
-  const s = stateOf2(core);
+  const s = stateOf4(core);
   for (const [reqId, p] of [...s.pending]) {
     s.pending.delete(reqId);
     p.reject(new Error(reason));
@@ -403,7 +817,7 @@ function rejectAllHostCalls(core, reason) {
 
 // src/core/writes.ts
 import {
-  SERVER_OWNER as SERVER_OWNER2,
+  SERVER_OWNER as SERVER_OWNER3,
   cloneValue,
   decodeDelta,
   encodeDelta,
@@ -493,6 +907,9 @@ function applyWrite(core, clientId, payload) {
     core.log("warn", `WRITE from ${clientId} failed to decode:`, 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 judged = core.clients.get(clientId);
   if (judged && delta.tick > judged.lastClientTick) {
     judged.lastClientTick = delta.tick;
@@ -513,8 +930,19 @@ function reject(core, clientId, c, op, reason) {
   correctLeaves(core, clientId, c.name, op.id, leafPaths(fieldList(c), op.mask));
 }
 function applyOp(core, clientId, c, op) {
-  if (op.op !== "update") {
-    reject(core, clientId, c, op, `op '${op.op}' is not allowed in a WRITE`);
+  if (op.op === "add" || op.op === "remove") {
+    if (c.kind !== "entity" || c.serverOwned || !c.clientCreate) {
+      reject(
+        core,
+        clientId,
+        c,
+        op,
+        `op '${op.op}' is not allowed in a WRITE (${c.name} does not declare clientCreate)`
+      );
+      return;
+    }
+    if (op.op === "add") applyAdd(core, clientId, c, op);
+    else applyRemove(core, clientId, c, op);
     return;
   }
   if (c.kind !== "entity") {
@@ -537,6 +965,8 @@ function applyOp(core, clientId, c, op) {
     return;
   }
   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);
   applyMaskedPatch(fields, next, op.patch, op.mask);
@@ -594,6 +1024,66 @@ function applyOp(core, clientId, c, op) {
   );
   correctLeaves(core, clientId, c.name, op.id, corrected);
 }
+function applyAdd(core, clientId, c, op) {
+  const plainColl = plainEntity(core.plain, c.name);
+  if (plainColl.has(op.id)) {
+    reject(core, clientId, c, op, `id ${JSON.stringify(op.id)} already exists`);
+    return;
+  }
+  const cap = recordCap(core);
+  if (plainColl.size >= cap) {
+    refuseByName(core, clientId, "E_RECORD_CAP", { entity: c.name, limit: cap });
+    return;
+  }
+  if (!admitGrowth(core, clientId, maxRecordBytes(c))) return;
+  try {
+    trackedEntity(core, c.name).add(op.id, op.value, { owner: clientId });
+  } catch (err) {
+    reject(core, clientId, c, op, `add rejected: ${String(err)}`);
+    return;
+  }
+  core.recordEvent("write", clientId, `${c.name}: added ${op.id}`);
+}
+function applyRemove(core, clientId, c, op) {
+  const plainColl = plainEntity(core.plain, c.name);
+  if (!plainColl.has(op.id)) return;
+  if (plainColl.ownerOf(op.id) !== clientId) {
+    reject(core, clientId, c, op, "not the owner");
+    return;
+  }
+  trackedEntity(core, c.name).remove(op.id);
+  core.recordEvent("write", clientId, `${c.name}: removed ${op.id}`);
+}
+function updateGrowth(c, leaves) {
+  let growth = 0;
+  for (const leaf of leaves) {
+    const first = leaf.path[0];
+    if (first === void 0) continue;
+    const field = c.fields[first];
+    if (!field) continue;
+    const bound = maxTypeBytes(field.type);
+    if (isFixedWidth(field.type)) continue;
+    growth += bound;
+  }
+  return growth;
+}
+function isFixedWidth(t) {
+  switch (t.kind) {
+    case "bool":
+    case "u8":
+    case "u16":
+    case "u32":
+    case "i32":
+    case "f32":
+    case "f64":
+    case "enum":
+      return t.opt !== true;
+    case "struct":
+      return Object.values(t.fields).every(isFixedWidth) && t.opt !== true;
+    default:
+      return false;
+  }
+}
 function serverWinsCorrections(core, dirty) {
   const ext = core.ext;
   for (const [name, cd] of dirty) {
@@ -604,7 +1094,7 @@ function serverWinsCorrections(core, dirty) {
     const fields = fieldList(c);
     for (const [id, rd] of cd.updated) {
       const owner = coll.ownerOf(id);
-      if (owner === void 0 || owner === SERVER_OWNER2) continue;
+      if (owner === void 0 || owner === SERVER_OWNER3) continue;
       const entry = core.clients.get(owner);
       if (!entry || !entry.connected) continue;
       const value = coll.get(id);
@@ -700,8 +1190,8 @@ var Loop = class {
   }
   /** Applies one queued/immediate frame. Returns `false` on a malformed payload. */
   applyFrame(f) {
-    if (f.type === FrameType2.WRITE) return applyWrite(this.core, f.clientId, f.payload).ok;
-    if (f.type === FrameType2.CALL) return handleCall(this.core, f.clientId, f.payload);
+    if (f.type === FrameType3.WRITE) return applyWrite(this.core, f.clientId, f.payload).ok;
+    if (f.type === FrameType3.CALL) return handleCall(this.core, f.clientId, f.payload);
     return true;
   }
   // -------------------------------------------------------------------------
@@ -2088,7 +2578,7 @@ import {
   createDirtySet,
   createFieldMask,
   encodeDelta as encodeDelta2,
-  encodeSnapshot,
+  encodeSnapshot as encodeSnapshot2,
   filterDirty,
   isDirtyEmpty,
   markAdd,
@@ -2195,7 +2685,7 @@ function viewKeyFor(ext, role) {
   return infoOf(ext).scoped.has(role) ? role : "all";
 }
 function encodeViewSnapshot(ext, plain, role, tick, memberships) {
-  return encodeSnapshot(
+  return encodeSnapshot2(
     ext,
     plain,
     { tick },
@@ -2325,7 +2815,7 @@ function catchUpDirty(ext, plain, fromRole, toRole) {
 import { withBuiltins } from "@irtio/protocol";
 import { ByteReader as ByteReader3, ByteWriter as ByteWriter3, decodeSnapshot } from "@irtio/schema";
 var SNAPSHOT_FORMAT_VERSION = 3;
-var READABLE_SNAPSHOT_VERSIONS = [1, 2, 3];
+var READABLE_SNAPSHOT_VERSIONS = [1, 2, 3, 4];
 function parseHibernationBlob(bytes) {
   const r = new ByteReader3(bytes);
   const version = r.u8();
@@ -2342,7 +2832,12 @@ function parseHibernationBlob(bytes) {
     const section = r.blob();
     if (section.length > 0) physics = section;
   }
-  return { version, seed, rngState, tick, mode, schemaHash8, physics, snapshot: r.rest() };
+  let holds;
+  if (version >= 4) {
+    const section = r.blob();
+    if (section.length > 0) holds = section;
+  }
+  return { version, seed, rngState, tick, mode, schemaHash8, physics, holds, snapshot: r.rest() };
 }
 function sameSchemaHash(a, b) {
   if (!a || !b) return true;
@@ -2350,10 +2845,10 @@ function sameSchemaHash(a, b) {
   for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
   return true;
 }
-function writeHibernationBlob(header, snapshot, physics) {
+function writeHibernationBlob(header, snapshot, physics, holds) {
   const hash = header.schemaHash8;
-  const version = hash ? 3 : physics ? 2 : 1;
-  const w = new ByteWriter3(snapshot.length + (physics?.length ?? 0) + 32);
+  const version = holds && holds.length > 0 ? 4 : hash ? 3 : physics ? 2 : 1;
+  const w = new ByteWriter3(snapshot.length + (physics?.length ?? 0) + (holds?.length ?? 0) + 40);
   w.u8(version);
   w.u32(header.seed >>> 0);
   w.u32(header.rngState >>> 0);
@@ -2361,6 +2856,7 @@ function writeHibernationBlob(header, snapshot, physics) {
   w.u8(header.mode === "event" ? 1 : 0);
   if (hash) w.bytes(hash);
   if (version >= 2) w.blob(physics ?? new Uint8Array(0));
+  if (version >= 4) w.blob(holds ?? new Uint8Array(0));
   w.bytes(snapshot);
   return w.finish();
 }
@@ -2434,13 +2930,13 @@ var TimelineRecorder = class {
 
 // src/core/room.ts
 import {
-  FrameType as FrameType5,
+  FrameType as FrameType6,
   PRESENCE_COLLECTION,
   ProfileLedger,
   busChannelProblem as busChannelProblem2,
   decodeFrame,
   encodeCorrectFrame,
-  encodeFrame as encodeFrame4,
+  encodeFrame as encodeFrame5,
   withBuiltins as withBuiltins2
 } from "@irtio/protocol";
 import {
@@ -2448,9 +2944,9 @@ import {
   createDirtySet as createDirtySet2,
   createState,
   decodeSnapshot as decodeSnapshot2,
-  encodeDelta as encodeDelta4,
-  encodeSnapshot as encodeSnapshot2,
-  isDirtyEmpty as isDirtyEmpty3,
+  encodeDelta as encodeDelta5,
+  encodeSnapshot as encodeSnapshot4,
+  isDirtyEmpty as isDirtyEmpty4,
   track,
   validateForDeploy
 } from "@irtio/schema";
@@ -2709,12 +3205,15 @@ function historyOf(config) {
   }
   return { depth, channels };
 }
-function keyOf(collection, id) {
+function keyOf2(collection, id) {
   return `${collection} ${id}`;
 }
 function angleOf(qz, qw) {
   return 2 * Math.atan2(qz, qw);
 }
+function mixSignature(h, v) {
+  return Math.imul(h ^ (Math.round(v * 1024) | 0), 2654435761);
+}
 var BaseScratch = class {
   constructor(physics, depth, tickNow) {
     this.physics = physics;
@@ -2731,7 +3230,7 @@ var BaseScratch = class {
     this.sync();
     this.present.clear();
     for (let i = 0; i < entry.count; i++) {
-      const key = keyOf(entry.collections[i], entry.ids[i]);
+      const key = keyOf2(entry.collections[i], entry.ids[i]);
       const e = this.bodies.get(key);
       if (!e) continue;
       poseAt(entry, i, this.pose);
@@ -2745,7 +3244,8 @@ var BaseScratch = class {
   }
   /**
    * Brings the scratch's body set in step with the live world: a double for every live body that
-   * has none, a rebuild for one whose collider (or part) count changed, and a prune for one that
+   * has none, a rebuild for one whose collider layout changed (count, handles, body-local
+   * offsets, shape type or extents, sensor flags — see `signatureOf`), and a prune for one that
    * has been gone longer than the history is deep and so can no longer appear in any entry.
    *
    * The prune is conservative rather than exact: `lastLive` only advances when a rewind happens,
@@ -2756,11 +3256,11 @@ var BaseScratch = class {
     const now = this.tickNow();
     const seen = /* @__PURE__ */ new Set();
     this.physics.eachTrackedBody((collection, id, body) => {
-      const key = keyOf(collection, id);
+      const key = keyOf2(collection, id);
       seen.add(key);
-      const parts = this.partsOf(body);
+      const signature = this.signatureOf(body);
       const existing = this.bodies.get(key);
-      if (existing && existing.parts === parts) {
+      if (existing && existing.signature === signature) {
         existing.lastLive = now;
         return;
       }
@@ -2768,7 +3268,7 @@ var BaseScratch = class {
         this.bodies.delete(key);
         this.destroy(existing);
       }
-      const made = this.clone(collection, id, body, parts);
+      const made = this.clone(collection, id, body, signature);
       if (!made) return;
       made.lastLive = now;
       this.bodies.set(key, made);
@@ -2809,16 +3309,46 @@ var RapierScratch = class extends BaseScratch {
     this.world = new this.rapier.World({ x: 0, y: 0, z: 0 });
     this.world.timestep = 0;
   }
-  partsOf(body) {
-    return body.numColliders();
+  signatureOf(body) {
+    const live = body;
+    const n = live.numColliders();
+    const origin = live.translation();
+    const inv = qConj(live.rotation());
+    let h = mixSignature(0, n);
+    for (let i = 0; i < n; i++) {
+      const c = live.collider(i);
+      h = mixSignature(h, c.handle);
+      h = mixSignature(h, c.isSensor() ? 1 : 0);
+      const w = c.translation();
+      const local = qRotate(inv, { x: w.x - origin.x, y: w.y - origin.y, z: w.z - origin.z });
+      h = mixSignature(h, local.x);
+      h = mixSignature(h, local.y);
+      h = mixSignature(h, local.z);
+      const r = qMul(inv, c.rotation());
+      h = mixSignature(h, r.x);
+      h = mixSignature(h, r.y);
+      h = mixSignature(h, r.z);
+      h = mixSignature(h, r.w);
+      const s = c.shape;
+      h = mixSignature(h, s.type);
+      h = mixSignature(h, s.radius ?? 0);
+      h = mixSignature(h, s.halfHeight ?? 0);
+      if (s.halfExtents) {
+        h = mixSignature(h, s.halfExtents.x);
+        h = mixSignature(h, s.halfExtents.y);
+        h = mixSignature(h, s.halfExtents.z);
+      }
+    }
+    return h;
   }
-  clone(collection, id, body, parts) {
+  clone(collection, id, body, signature) {
     const live = body;
     this.trackedLive.add(live.handle);
     const made = this.world.createRigidBody(this.rapier.RigidBodyDesc.fixed());
     const origin = live.translation();
     const rot = live.rotation();
     const inv = qConj(rot);
+    const parts = live.numColliders();
     for (let i = 0; i < parts; i++) {
       const c = live.collider(i);
       const desc = new this.rapier.ColliderDesc(c.shape);
@@ -2830,7 +3360,7 @@ var RapierScratch = class extends BaseScratch {
       this.world.createCollider(desc, made);
     }
     this.owners.set(made.handle, { collection, id });
-    return { collection, id, body: made, parts, lastLive: -1 };
+    return { collection, id, body: made, signature, lastLive: -1 };
   }
   place(entry, pose) {
     const b = entry.body;
@@ -2906,10 +3436,36 @@ var Rapier2dScratch = class extends BaseScratch {
     this.world = new this.rapier.World({ x: 0, y: 0 });
     this.world.timestep = 0;
   }
-  partsOf(body) {
-    return body.numColliders();
+  signatureOf(body) {
+    const live = body;
+    const n = live.numColliders();
+    const origin = live.translation();
+    const angle = live.rotation();
+    const cos = Math.cos(-angle);
+    const sin = Math.sin(-angle);
+    let h = mixSignature(0, n);
+    for (let i = 0; i < n; i++) {
+      const c = live.collider(i);
+      h = mixSignature(h, c.handle);
+      h = mixSignature(h, c.isSensor() ? 1 : 0);
+      const w = c.translation();
+      const dx = w.x - origin.x;
+      const dy = w.y - origin.y;
+      h = mixSignature(h, dx * cos - dy * sin);
+      h = mixSignature(h, dx * sin + dy * cos);
+      h = mixSignature(h, c.rotation() - angle);
+      const s = c.shape;
+      h = mixSignature(h, s.type);
+      h = mixSignature(h, s.radius ?? 0);
+      h = mixSignature(h, s.halfHeight ?? 0);
+      if (s.halfExtents) {
+        h = mixSignature(h, s.halfExtents.x);
+        h = mixSignature(h, s.halfExtents.y);
+      }
+    }
+    return h;
   }
-  clone(collection, id, body, parts) {
+  clone(collection, id, body, signature) {
     const live = body;
     this.trackedLive.add(live.handle);
     const made = this.world.createRigidBody(this.rapier.RigidBodyDesc.fixed());
@@ -2917,6 +3473,7 @@ var Rapier2dScratch = class extends BaseScratch {
     const angle = live.rotation();
     const cos = Math.cos(-angle);
     const sin = Math.sin(-angle);
+    const parts = live.numColliders();
     for (let i = 0; i < parts; i++) {
       const c = live.collider(i);
       const desc = new this.rapier.ColliderDesc(c.shape);
@@ -2929,7 +3486,7 @@ var Rapier2dScratch = class extends BaseScratch {
       this.world.createCollider(desc, made);
     }
     this.owners.set(made.handle, { collection, id });
-    return { collection, id, body: made, parts, lastLive: -1 };
+    return { collection, id, body: made, signature, lastLive: -1 };
   }
   place(entry, pose) {
     const b = entry.body;
@@ -2991,10 +3548,23 @@ var MatterScratch = class extends BaseScratch {
     super(physics, depth, tickNow);
     this.matter = physics.matter;
   }
-  partsOf(body) {
-    return body.parts.length;
-  }
-  clone(collection, id, body, parts) {
+  signatureOf(body) {
+    const live = body;
+    const cos = Math.cos(-live.angle);
+    const sin = Math.sin(-live.angle);
+    let h = mixSignature(0, live.parts.length);
+    for (const p of live.parts) {
+      h = mixSignature(h, p.area);
+      h = mixSignature(h, p.vertices.length);
+      h = mixSignature(h, p.isSensor ? 1 : 0);
+      const dx = p.position.x - live.position.x;
+      const dy = p.position.y - live.position.y;
+      h = mixSignature(h, dx * cos - dy * sin);
+      h = mixSignature(h, dx * sin + dy * cos);
+    }
+    return h;
+  }
+  clone(collection, id, body, signature) {
     const M = this.matter;
     const live = body;
     const made = live.parts.length > 1 ? M.Body.create({ parts: live.parts.slice(1).map((p) => this.clonePart(p, live.angle)) }) : this.clonePart(live, live.angle);
@@ -3002,7 +3572,7 @@ var MatterScratch = class extends BaseScratch {
     made.angle = 0;
     for (const p of made.parts) p.angle = 0;
     this.owners.set(made, { collection, id });
-    return { collection, id, body: made, parts, lastLive: -1 };
+    return { collection, id, body: made, signature, lastLive: -1 };
   }
   /** One part, un-rotated by the parent's angle so the double starts at angle 0. */
   clonePart(part, parentAngle) {
@@ -3131,13 +3701,13 @@ function lobbyConfigOf(core) {
   if (!schemaHasLobby(core.definition.schema)) return void 0;
   return declared;
 }
-function stateOf3(core) {
+function stateOf5(core) {
   return core.anyState[LOBBY_STATE];
 }
 function evaluateLobby(core) {
   const config = lobbyConfigOf(core);
   if (config === void 0) return;
-  const state = stateOf3(core);
+  const state = stateOf5(core);
   if (state === void 0) return;
   const members = trackedEntity(core, LOBBY_MEMBERS);
   const policy = config.start ?? "when-full";
@@ -3176,7 +3746,7 @@ function evaluateLobby(core) {
 function startLobby(core, why) {
   const runtime = runtimeOf(core);
   if (runtime.started) return;
-  const state = stateOf3(core);
+  const state = stateOf5(core);
   if (state === void 0 || state.phase === "started") {
     runtime.started = true;
     return;
@@ -3199,7 +3769,7 @@ function makeLobby(core) {
       "room.lobby: this room has no lobby. Spread lobbyCollections into the schema and declare lobby: {} in defineRoom \u2014 both are needed, and defineRoom refuses either one alone"
     );
   }
-  const state = stateOf3(core);
+  const state = stateOf5(core);
   const members = trackedEntity(core, LOBBY_MEMBERS);
   return {
     get phase() {
@@ -3237,7 +3807,7 @@ function makeLobby(core) {
 function setLobbyPublic(core, value) {
   const config = lobbyConfigOf(core);
   if (config === void 0) return;
-  const state = stateOf3(core);
+  const state = stateOf5(core);
   if (state === void 0) return;
   if (state.phase === "started") {
     core.log(
@@ -3256,7 +3826,7 @@ function setLobbyPublic(core, value) {
 }
 
 // src/core/messages.ts
-import { FrameType as FrameType3, decodeMsg, encodeFrame as encodeFrame2, encodeMsg } from "@irtio/protocol";
+import { FrameType as FrameType4, decodeMsg, encodeFrame as encodeFrame3, encodeMsg } from "@irtio/protocol";
 import { decodeFields as decodeFields2 } from "@irtio/schema";
 function toRoomTarget(target) {
   switch (target.kind) {
@@ -3336,8 +3906,8 @@ function handleMsg(core, clientId, payload) {
     if (!ran.ok || ran.value === false) return true;
   }
   if (msg.target.kind === "server") return true;
-  const frame = encodeFrame2(
-    FrameType3.MSG,
+  const frame = encodeFrame3(
+    FrameType4.MSG,
     encodeMsg({
       target: { kind: "client", clientId },
       payload: msg.payload,
@@ -3351,28 +3921,306 @@ 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 = encodeFrame2(
-    FrameType3.MSG,
+  const frame = encodeFrame3(
+    FrameType4.MSG,
     encodeMsg({ target: { kind: "server" }, payload: bytes })
   );
   deliver(core, wireTargetOf(target), frame);
 }
 function sendTypedMessage(core, index, target, payload) {
-  const frame = encodeFrame2(
-    FrameType3.MSG,
+  const frame = encodeFrame3(
+    FrameType4.MSG,
     encodeMsg({ target: { kind: "server" }, payload, typed: { index } })
   );
   deliver(core, wireTargetOf(target), frame);
 }
 
+// src/core/replay.ts
+import {
+  CLIP_MAX_BYTES,
+  encodeClip
+} from "@irtio/protocol";
+import {
+  encodeDelta as encodeDelta3,
+  encodeSnapshot as encodeSnapshot3,
+  isDirtyEmpty as isDirtyEmpty2
+} from "@irtio/schema";
+var REPLAY_DEFAULT_SECONDS = 60;
+var REPLAY_MAX_SECONDS = 300;
+var REPLAY_RING_MAX_BYTES = 8 * 1024 * 1024;
+var REPLAY_KEYFRAME_SECONDS = 2;
+var CLIP_COOLDOWN_MS = 1e3;
+var ReplayRing = class {
+  constructor(bounds) {
+    this.bounds = bounds;
+  }
+  bounds;
+  items = [];
+  total = 0;
+  /** How many times an oversized segment has emptied the ring. Read through `append`'s return. */
+  wipes = 0;
+  /** The tick the newest keyframe went in at; `-1` while the ring is empty. */
+  lastKeyframeTick = -1;
+  get frames() {
+    return this.items;
+  }
+  get bytes() {
+    return this.total;
+  }
+  get empty() {
+    return this.items.length === 0;
+  }
+  /** How many oversized segments have emptied the ring. A test's handle on the degenerate case. */
+  get wipeCount() {
+    return this.wipes;
+  }
+  /**
+   * Appends a frame and trims. Returns `true` when the trim had to throw the *whole* ring away
+   * (an oversized segment with nowhere to cut), which the caller has to know about: the ring is
+   * now empty, so anything it was about to append next would head the ring without a keyframe.
+   */
+  append(frame) {
+    this.items.push(frame);
+    this.total += frame.bytes.length;
+    if (frame.keyframe) this.lastKeyframeTick = frame.tick;
+    const before = this.wipes;
+    this.trim();
+    return this.wipes !== before;
+  }
+  /** Is a keyframe due at `tick`? Always true while the ring is empty. */
+  keyframeDue(tick) {
+    return this.empty || tick - this.lastKeyframeTick >= this.bounds.keyframeEvery;
+  }
+  /** The frames from the newest keyframe at or before `fromTick` to the end. */
+  tail(fromTick) {
+    let start = 0;
+    for (let i = 0; i < this.items.length; i++) {
+      const f = this.items[i];
+      if (f.keyframe && f.tick <= fromTick) start = i;
+    }
+    return this.items.slice(start);
+  }
+  trim() {
+    const last = this.items[this.items.length - 1];
+    if (!last) return;
+    for (; ; ) {
+      const head = this.items[0];
+      if (!head) return;
+      const overBytes = this.total > this.bounds.maxBytes;
+      const overWindow = last.tick - head.tick > this.bounds.windowTicks;
+      if (!overBytes && !overWindow) return;
+      let next = -1;
+      for (let i = 1; i < this.items.length; i++) {
+        if (this.items[i]?.keyframe === true) {
+          next = i;
+          break;
+        }
+      }
+      if (next === -1) {
+        if (!overBytes) return;
+        this.items = [];
+        this.total = 0;
+        this.lastKeyframeTick = -1;
+        this.wipes++;
+        return;
+      }
+      for (let i = 0; i < next; i++) this.total -= this.items[i].bytes.length;
+      this.items = this.items.slice(next);
+    }
+  }
+};
+var states5 = /* @__PURE__ */ new WeakMap();
+function configOf(core) {
+  const config = core.definition.config;
+  return config.replay;
+}
+function replayArmed(core) {
+  return configOf(core) !== void 0;
+}
+function stateOf6(core) {
+  const declared = configOf(core);
+  if (declared === void 0) return void 0;
+  let s = states5.get(core);
+  if (!s) {
+    const tickRate = core.definition.config.tickRate ?? 20;
+    const seconds = Math.min(
+      REPLAY_MAX_SECONDS,
+      Math.max(1, Math.floor(declared.seconds ?? REPLAY_DEFAULT_SECONDS))
+    );
+    s = {
+      seconds,
+      view: declared.view ?? "",
+      ring: new ReplayRing({
+        windowTicks: Math.max(1, Math.ceil(seconds * tickRate)),
+        keyframeEvery: Math.max(1, Math.round(REPLAY_KEYFRAME_SECONDS * tickRate)),
+        maxBytes: REPLAY_RING_MAX_BYTES
+      }),
+      lastClipAt: Number.NEGATIVE_INFINITY,
+      clipsTaken: 0,
+      disarmed: false
+    };
+    states5.set(core, s);
+  }
+  return s;
+}
+function omniscientMemberships(core) {
+  const out = /* @__PURE__ */ new Map();
+  for (const desc of core.ext.collections) {
+    if (desc.visibility !== "spatial-grid") continue;
+    out.set(desc.name, new Set(plainEntity(core.plain, desc.name).ids()));
+  }
+  return out;
+}
+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"
+  );
+}
+function recorderSnapshot(core, state) {
+  if (state.view === "") {
+    return encodeSnapshot3(core.ext, core.plain, { tick: core.tick });
+  }
+  return encodeViewSnapshot(
+    core.ext,
+    core.plain,
+    state.view,
+    core.tick,
+    omniscientMemberships(core)
+  );
+}
+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);
+}
+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);
+}
+function recordFlush(core, dirty, byView) {
+  const state = stateOf6(core);
+  if (!state || state.disarmed) return;
+  const ring = state.ring;
+  if (!ring.empty && isDirtyEmpty2(dirty)) return;
+  if (ring.keyframeDue(core.tick)) {
+    const wiped = ring.append({
+      tick: core.tick,
+      keyframe: true,
+      bytes: recorderSnapshot(core, state)
+    });
+    if (wiped) {
+      disarm(core, state);
+      return;
+    }
+  }
+  const key = cacheKeyFor(core, state);
+  const cached = key === void 0 ? void 0 : byView.get(key);
+  const delta = cached !== void 0 ? cached : recorderDelta(core, state, dirty);
+  if (!delta) return;
+  ring.append({ tick: core.tick, keyframe: false, bytes: delta });
+}
+function disarm(core, state) {
+  state.disarmed = true;
+  core.host.log("warn", [
+    `irtio: room ${core.roomId}: a single replay keyframe is larger than the replay ring's ${REPLAY_RING_MAX_BYTES}-byte bound, so nothing could ever be held. Recording is off for the life of this room and room.replay.clip() will refuse. Record a narrower view (\`replay: { view: <role> }\`) or hold less state in the recorded collections.`
+  ]);
+}
+function assembleClip(core, seconds) {
+  const state = stateOf6(core);
+  if (!state || state.disarmed || state.ring.empty) return void 0;
+  const tickRate = core.definition.config.tickRate ?? 20;
+  const want = Math.min(state.seconds, Math.max(1, Math.floor(seconds ?? state.seconds)));
+  const ringFrames = state.ring.frames;
+  const last = ringFrames[ringFrames.length - 1];
+  const frames = state.ring.tail(last.tick - Math.ceil(want * tickRate)).map((f) => ({
+    tick: f.tick,
+    kind: f.keyframe ? "keyframe" : "delta",
+    bytes: f.bytes
+  }));
+  const head = frames[0];
+  if (head === void 0 || head.kind !== "keyframe") return void 0;
+  const clip = {
+    // The GAME schema's hash, not the extended one's. That is what a client puts in its HELLO,
+    // so it is the value playback can actually compare against — and it is the hash a deploy
+    // changes, which is the whole thing the pin exists to catch.
+    schemaHash8: core.definition.schema.hash8,
+    tickRate,
+    startTick: head.tick,
+    durationTicks: last.tick - head.tick,
+    view: state.view,
+    frames
+  };
+  return encodeClip(clip);
+}
+function takeClip(core, seconds) {
+  if (!replayArmed(core)) {
+    return rejectAsEvent(
+      core,
+      new Error(
+        "room.replay.clip: this room type did not declare `replay:`, so nothing is being recorded. Add `replay: { seconds: 60 }` to the room config to arm the ring."
+      )
+    );
+  }
+  const state = stateOf6(core);
+  const now = core.host.now();
+  if (now - state.lastClipAt < CLIP_COOLDOWN_MS) {
+    return rejectAsEvent(
+      core,
+      new Error(
+        `E_CLIP_COOLDOWN: room.replay.clip may be called once every ${CLIP_COOLDOWN_MS}ms per room; this call came too soon after the last one`
+      )
+    );
+  }
+  if (state.disarmed) {
+    return rejectAsEvent(
+      core,
+      new Error(
+        `E_CLIP_DISARMED: recording stopped in this room because a single replay keyframe was larger than the ${REPLAY_RING_MAX_BYTES}-byte replay ring; see the warning on this room's log`
+      )
+    );
+  }
+  let bytes;
+  try {
+    bytes = assembleClip(core, seconds);
+  } catch (err) {
+    return rejectAsEvent(
+      core,
+      new Error(`E_CLIP_ENCODE: the replay ring could not be encoded: ${String(err)}`)
+    );
+  }
+  if (bytes === void 0) {
+    return rejectAsEvent(
+      core,
+      new Error("E_CLIP_EMPTY: the replay ring is empty \u2014 this room has not flushed a change yet")
+    );
+  }
+  if (bytes.length > CLIP_MAX_BYTES) {
+    return rejectAsEvent(
+      core,
+      new Error(
+        `E_CLIP_TOO_LARGE: this clip is ${bytes.length} bytes and the limit is ${CLIP_MAX_BYTES}`
+      )
+    );
+  }
+  state.lastClipAt = now;
+  state.clipsTaken++;
+  return startHostCall(core, { kind: "clip", bytes }, (value) => ({ id: value ?? "" }));
+}
+
 // src/core/room-api.ts
 import {
-  FrameType as FrameType4,
+  FrameType as FrameType5,
   busChannelProblem,
   busPayloadProblem,
-  encodeFrame as encodeFrame3
+  encodeFrame as encodeFrame4
 } from "@irtio/protocol";
-import { encodeDelta as encodeDelta3, encodeFields as encodeFields2, isDirtyEmpty as isDirtyEmpty2 } from "@irtio/schema";
+import { encodeDelta as encodeDelta4, encodeFields as encodeFields2, isDirtyEmpty as isDirtyEmpty3 } from "@irtio/schema";
 function makePhysicsApi(p) {
   return {
     get rapier() {
@@ -3722,6 +4570,20 @@ function createRoomApi(core, publicUrl) {
     get lobby() {
       return makeLobby(core);
     },
+    // ---- M6 lane N: replays ----
+    // D81: one getter, and deliberately only one. Everything replays do — the ring, the
+    // eviction invariant, the recorder view, the clip assembly, the cooldown — lives in
+    // `core/replay.ts` behind these two calls, so this file stays what it says it is: a facade
+    // that reads through.
+    get replay() {
+      return {
+        get armed() {
+          return replayArmed(core);
+        },
+        clip: (seconds) => takeClip(core, seconds)
+      };
+    },
+    // ---- end M6 lane N ----
     alarm(name, atMs) {
       if (!isAlarmName(core, name, "room.alarm")) return;
       if (!Number.isFinite(atMs)) {
@@ -3804,10 +4666,10 @@ function setRole(core, clientId, role) {
   }
   if (entry.role === role) return;
   const dirty = catchUpDirty(core.ext, core.plain, entry.role, role);
-  if (!isDirtyEmpty2(dirty)) {
+  if (!isDirtyEmpty3(dirty)) {
     core.send(
       clientId,
-      encodeFrame3(FrameType4.DELTA, encodeDelta3(core.ext, core.plain, dirty, { tick: core.tick }))
+      encodeFrame4(FrameType5.DELTA, encodeDelta4(core.ext, core.plain, dirty, { tick: core.tick }))
     );
   }
   entry.role = role;
@@ -3910,6 +4772,10 @@ var RoomCore = class _RoomCore {
   };
   tick = 0;
   stopped = false;
+  // ---- M6 lane K: stateful relay ----
+  /** D77: the wall clock hold deadlines are measured against. See `RoomCoreOptions.wallNow`. */
+  wallNow;
+  // ---- end M6 lane K ----
   /**
    * Called for every handler throw `tryRun` swallows, before it is logged. A test harness sets
    * this so a room that breaks fails the test that broke it (bug 2): the runtime's job is to
@@ -3986,6 +4852,9 @@ var RoomCore = class _RoomCore {
     const historySetup = this.physics ? historyOf(definition.config.physics) : void 0;
     this.rewindState = historySetup === void 0 ? void 0 : new RewindState(historySetup);
     this.subscribeDeclaredChannels();
+    installCaps(self, options.caps ?? {});
+    this.wallNow = options.wallNow ?? (() => Date.now());
+    restoreHolds(self, restored?.holds);
     if (restored) {
       const onWake = definition.config.onWake;
       if (onWake) this.guard("onWake", () => onWake(this.state, this.room));
@@ -4326,8 +5195,13 @@ var RoomCore = class _RoomCore {
         mode: this.mode,
         schemaHash8: this.ext.hash8
       },
-      encodeSnapshot2(this.ext, this.plain, { tick: this.tick }),
-      physics
+      encodeSnapshot4(this.ext, this.plain, { tick: this.tick }),
+      physics,
+      // ---- M6 lane K: stateful relay ----
+      // D77: hold deadlines are state, so they go where the state goes. `undefined` for a room
+      // holding nothing, which keeps its blob byte-identical to the one it wrote before D77.
+      serializeHolds(this.internals)
+      // ---- end M6 lane K ----
     );
   }
   serialize() {
@@ -4402,6 +5276,18 @@ var RoomCore = class _RoomCore {
       // a key join `ctx.playerId` is exactly as durable as the resume token and no more. A JWT
       // join (D27, week 13) passes the verified `<iss>:<sub>` in `JoinOptions.playerId` instead,
       // and nothing else here changes.
+      //
+      // ---- M6 lane K: stateful relay ----
+      // An existing entry keeps the `playerId` it was created with: this is `existing ?? {...}`,
+      // so a rejoin never overwrites it. That is deliberate and it is the safe direction — a
+      // session's identity cannot be changed by anything a later HELLO on the same seat says. It
+      // has one visible consequence, and D77's holds are where it shows: a client that joins
+      // anonymously and presents an assertion later in the same session keeps the resume token's
+      // client id as its `playerId`, so its holds stay bound to the token rather than moving to
+      // the verified subject. Its next fresh join binds them to the subject. Said in
+      // `authority-models.md` too, because a developer meets it as "my holds did not follow me to
+      // the other tab" rather than as a line in this file.
+      // ---- end M6 lane K ----
       playerId: options.playerId ?? clientId,
       npc: options.npc === true,
       role,
@@ -4419,6 +5305,8 @@ var RoomCore = class _RoomCore {
     entry.connected = true;
     this.clients.set(clientId, entry);
     this.invalidateClients();
+    reclaimHolds(this.internals, clientId, entry.playerId);
+    addPerPlayerRecords(this.internals, clientId);
     const onJoin = this.definition.config.onJoin;
     if (onJoin) {
       const ctx = this.ctxFor(clientId, reconnecting);
@@ -4452,7 +5340,7 @@ var RoomCore = class _RoomCore {
   /** Event mode only: presence/lifecycle changes are their own event. No-op in tick mode. */
   eventFlush() {
     if (this.mode !== "event" || this.stopped) return;
-    if (isDirtyEmpty3(this.tracked.dirty)) return;
+    if (isDirtyEmpty4(this.tracked.dirty)) return;
     this.tick++;
     this.flush();
     this.captureTimeline();
@@ -4468,6 +5356,8 @@ var RoomCore = class _RoomCore {
       const ctx = this.ctxFor(clientId);
       this.guard("onLeave", () => onLeave(this.state, ctx, reason));
     }
+    placeHolds(this.internals, clientId, entry.playerId);
+    forgetWriter(this.internals, clientId);
     this.presence.remove(clientId);
     this.recordEvent("leave", clientId, reason);
     rejectPendingFor(this.internals, clientId, "client disconnected");
@@ -4601,6 +5491,16 @@ var RoomCore = class _RoomCore {
    * `receive()` accepted, plus the join snapshots this room handed the host to wrap in a
    * `WELCOME` (the host builds that frame, so the room never sees it — see the docs page).
    */
+  // ---- M6 lane K: stateful relay ----
+  /** D77: the encoded state size, when a host set the state cap. See `caps.ts`. */
+  stateBytes() {
+    return stateBytesOf(this.internals);
+  }
+  /** D77: how many records are held for players who have left. */
+  holdCount() {
+    return holdCount(this.internals);
+  }
+  // ---- end M6 lane K ----
   profile() {
     return this.ledger?.snapshot();
   }
@@ -4631,20 +5531,20 @@ var RoomCore = class _RoomCore {
       return;
     }
     switch (type) {
-      case FrameType5.WRITE:
-      case FrameType5.CALL: {
-        if (type === FrameType5.WRITE) this.recordEvent("write", clientId);
+      case FrameType6.WRITE:
+      case FrameType6.CALL: {
+        if (type === FrameType6.WRITE) this.recordEvent("write", clientId);
         if (this.mode === "tick") {
           this.loop.enqueue({ clientId, type, payload: payload.slice() });
         } else if (!this.loop.applyEvent({ clientId, type, payload })) {
           this.badFrame(
             clientId,
-            `malformed ${type === FrameType5.WRITE ? "WRITE" : "CALL"} payload`
+            `malformed ${type === FrameType6.WRITE ? "WRITE" : "CALL"} payload`
           );
         }
         return;
       }
-      case FrameType5.REPLY: {
+      case FrameType6.REPLY: {
         if (!handleReply(this.internals, clientId, payload)) {
           this.badFrame(clientId, "malformed REPLY payload");
         } else {
@@ -4652,7 +5552,7 @@ var RoomCore = class _RoomCore {
         }
         return;
       }
-      case FrameType5.MSG: {
+      case FrameType6.MSG: {
         if (this.mode === "event") this.tick++;
         const ok = handleMsg(this.internals, clientId, payload);
         if (this.mode === "event") this.flush();
@@ -4670,6 +5570,7 @@ var RoomCore = class _RoomCore {
    */
   flush() {
     evaluateLobby(this.internals);
+    expireHolds(this.internals);
     const dirty = this.tracked.flush();
     serverWinsCorrections(this.internals, dirty);
     this.ledger?.newFlush();
@@ -4727,14 +5628,14 @@ var RoomCore = class _RoomCore {
           let shared;
           if (entry.pendingJoinAdds) {
             const sharedDirty = sharedViewDirty(this.ext, sourceDirty, entry.role);
-            shared = isDirtyEmpty3(sharedDirty) ? null : encodeDelta4(this.ext, this.plain, sharedDirty, { tick: this.tick });
+            shared = isDirtyEmpty4(sharedDirty) ? null : encodeDelta5(this.ext, this.plain, sharedDirty, { tick: this.tick });
             if (shared) this.stats.encodesLastFlush++;
           } else {
             const key = viewKeyFor(this.ext, entry.role);
             let cached = byView.get(key);
             if (cached === void 0) {
               const sharedDirty = sharedViewDirty(this.ext, dirty, entry.role);
-              cached = isDirtyEmpty3(sharedDirty) ? null : encodeDelta4(this.ext, this.plain, sharedDirty, { tick: this.tick });
+              cached = isDirtyEmpty4(sharedDirty) ? null : encodeDelta5(this.ext, this.plain, sharedDirty, { tick: this.tick });
               if (cached) this.stats.encodesLastFlush++;
               byView.set(key, cached);
             }
@@ -4743,7 +5644,7 @@ var RoomCore = class _RoomCore {
           if (shared) {
             this.send(
               entry.clientId,
-              encodeFrame4(FrameType5.DELTA, shared),
+              encodeFrame5(FrameType6.DELTA, shared),
               this.ledger ? { shared } : void 0
             );
           }
@@ -4754,7 +5655,7 @@ var RoomCore = class _RoomCore {
             memberships
           );
           const encodeStarted = performance.now();
-          delta = isDirtyEmpty3(aoiDirty) ? null : encodeDelta4(this.ext, this.plain, aoiDirty, { tick: this.tick });
+          delta = isDirtyEmpty4(aoiDirty) ? null : encodeDelta5(this.ext, this.plain, aoiDirty, { tick: this.tick });
           this.stats.aoiEncodeMs += performance.now() - encodeStarted;
           if (delta) {
             this.stats.encodesLastFlush++;
@@ -4785,7 +5686,7 @@ var RoomCore = class _RoomCore {
         if (delta) {
           this.send(
             entry.clientId,
-            encodeFrame4(FrameType5.DELTA, delta),
+            encodeFrame5(FrameType6.DELTA, delta),
             this.ledger ? {
               ...churn ? { churn } : {},
               ...spatialDescs.length > 0 ? {} : { shared: delta }
@@ -4796,6 +5697,7 @@ var RoomCore = class _RoomCore {
       entry.correction = void 0;
       entry.accepted.clear();
     }
+    recordFlush(this.internals, dirty, byView);
   }
 };
 function encodeSection(physics) {
@@ -4811,6 +5713,11 @@ function encodeSection(physics) {
 export {
   HOST_CALL_TIMEOUT_MS,
   RoomFullError,
+  RELAY_STATE_BYTES,
+  RELAY_RECORDS_PER_COLLECTION,
+  RELAY_WRITES_PER_SECOND,
+  DEFAULT_RECORDS_PER_COLLECTION,
+  RELAY_WRITE_CAPS,
   EVENT_RING_SIZE,
   inspectState,
   RPC_TIMEOUT_MS,