@irtio/runtime 0.11.0 → 1.0.0

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

@@ -214,12 +214,15 @@ function inspectState(schema, plain) {
 
 // src/core/rpc.ts
 import {
+  ErrorCode as ErrorCode2,
   FrameType as FrameType2,
+  OWNERSHIP_ASK,
   decodeCall,
   decodeReply,
   encodeCall,
   encodeFrame as encodeFrame2,
   encodeReply,
+  isReservedRpcName,
   rpcByIdOf,
   rpcTable
 } from "@irtio/protocol";
@@ -258,11 +261,12 @@ function deepEqual(a, b) {
 
 // src/core/ownership.ts
 import { SERVER_OWNER, defaultRecord } from "@irtio/schema";
+var ASK_WINDOW_MS = 5e3;
 var states2 = /* @__PURE__ */ new WeakMap();
 function stateOf2(core) {
   let s = states2.get(core);
   if (!s) {
-    s = { holds: /* @__PURE__ */ new Map(), askWarned: false };
+    s = { holds: /* @__PURE__ */ new Map(), asks: /* @__PURE__ */ new Map(), askUnknownWarned: false };
     states2.set(core, s);
   }
   return s;
@@ -419,6 +423,31 @@ function addPerPlayerRecords(core, clientId) {
     }
   }
 }
+function askOn(core, collection, id) {
+  return states2.get(core)?.asks.get(keyOf(collection, id));
+}
+function trackAsk(core, ask) {
+  stateOf2(core).asks.set(keyOf(ask.collection, ask.id), ask);
+}
+function clearAsk(core, collection, id) {
+  states2.get(core)?.asks.delete(keyOf(collection, id));
+}
+function asksInFlight(core) {
+  const s = states2.get(core);
+  return s ? [...s.asks.values()] : [];
+}
+function askCount(core) {
+  return states2.get(core)?.asks.size ?? 0;
+}
+function warnSdkPredatesAsk(core, clientId) {
+  const s = stateOf2(core);
+  if (s.askUnknownWarned) return;
+  s.askUnknownWarned = true;
+  core.log("warn", `client ${clientId}'s SDK predates $ownership.ask; ask auto-declined`);
+}
+function grantOwnership(core, collection, id, clientId) {
+  trackedEntity(core, collection).setOwner(id, clientId);
+}
 function resolveTransfer(core, clientId, c, id) {
   const policy = c.ownership;
   const coll = plainEntity(core.plain, c.name);
@@ -435,36 +464,35 @@ function resolveTransfer(core, clientId, c, id) {
     case "never":
       return "refused";
     case "free":
-      trackedEntity(core, c.name).setOwner(id, clientId);
+      grantOwnership(core, c.name, id, clientId);
       return "granted";
     case "closer": {
       if (owner === void 0 || owner === SERVER_OWNER) {
-        trackedEntity(core, c.name).setOwner(id, clientId);
+        grantOwnership(core, c.name, 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);
+        grantOwnership(core, c.name, 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);
+      grantOwnership(core, c.name, id, clientId);
       return "granted";
     }
+    // ---- M6 ask packet ----
     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.`
-        );
+      if (owner === void 0 || owner === SERVER_OWNER) {
+        grantOwnership(core, c.name, id, clientId);
+        return "granted";
       }
-      return "refused";
+      if (core.clients.get(owner)?.connected !== true) return "gone";
+      return "pending";
     }
+    // ---- end M6 ask packet ----
     default:
       return "refused";
   }
@@ -495,6 +523,9 @@ function restoreHolds(core, bytes) {
 // src/core/rpc.ts
 var RPC_TIMEOUT_MS = 5e3;
 var REQUEST_OWNERSHIP = "requestOwnership";
+var RpcTimeoutError = class extends Error {
+};
+var DEFERRED = /* @__PURE__ */ Symbol("deferred reply");
 var states3 = /* @__PURE__ */ new WeakMap();
 function stateOf3(core) {
   let s = states3.get(core);
@@ -530,6 +561,16 @@ function handleCall(core, clientId, payload) {
     sendReply(core, clientId, call.reqId, null, errorText("E_RPC_UNKNOWN", `rpcId ${call.rpcId}`));
     return true;
   }
+  if (isReservedRpcName(desc.name)) {
+    sendReply(
+      core,
+      clientId,
+      call.reqId,
+      null,
+      errorText("E_RPC_REJECTED", `${desc.name} is reserved by irtio`)
+    );
+    return true;
+  }
   if (desc.direction !== "server") {
     sendReply(
       core,
@@ -557,7 +598,8 @@ function handleCall(core, clientId, payload) {
   const ctx = { ...core.ctxFor(clientId), clientTick: call.clientTick || void 0 };
   let result;
   if (desc.name === REQUEST_OWNERSHIP) {
-    result = runRequestOwnership(core, clientId, ctx, params);
+    result = runRequestOwnership(core, clientId, ctx, params, call.reqId, desc);
+    if (result === DEFERRED) return true;
   } else {
     const impl = core.definition.config.rpc?.[desc.name];
     if (!impl) {
@@ -586,32 +628,126 @@ function handleCall(core, clientId, payload) {
   }
   return true;
 }
-function runRequestOwnership(core, clientId, ctx, params) {
+function runRequestOwnership(core, clientId, ctx, params, reqId, desc) {
   const name = String(params.entity ?? "");
   const id = String(params.id ?? "");
   const c = collectionDescOf(core.ext, name);
-  if (!c || c.kind !== "entity" || c.serverOwned) return { granted: false };
+  if (!c || c.kind !== "entity" || c.serverOwned) return refused("gone");
   const plain = plainEntity(core.plain, name);
-  if (!plain.has(id)) return { granted: false };
+  if (!plain.has(id)) return refused("gone");
   const handler = core.definition.config.onOwnershipRequest;
   const tracked = trackedEntity(core, name);
   if (!handler && c.ownership) {
-    return { granted: resolveTransfer(core, clientId, c, id) === "granted" };
+    if (askOn(core, name, id)) return refused("pending");
+    const verdict = resolveTransfer(core, clientId, c, id);
+    if (verdict === "pending") return beginAsk(core, clientId, name, id, reqId, desc);
+    if (verdict === "gone") return refused("gone");
+    return verdict === "granted" ? granted() : refused("");
   }
   if (handler) {
     const ran = core.tryRun("onOwnershipRequest", () => handler(core.anyState, name, id, ctx));
     if (ran.ok && ran.value === true && plain.ownerOf(id) !== clientId) {
       tracked.setOwner(id, clientId);
     }
-    return { granted: plain.ownerOf(id) === clientId };
+    return plain.ownerOf(id) === clientId ? granted() : refused("");
   }
   const owner = plain.ownerOf(id);
-  if (owner === clientId) return { granted: true };
-  if (owner !== SERVER_OWNER2) return { granted: false };
+  if (owner === clientId) return granted();
+  if (owner !== SERVER_OWNER2) return refused("");
   tracked.setOwner(id, clientId);
-  return { granted: true };
+  return granted();
+}
+function granted() {
+  return { granted: true, reason: "" };
+}
+function refused(reason) {
+  return { granted: false, reason };
+}
+var UNKNOWN_RPC_PREFIX = ErrorCode2.E_RPC_UNKNOWN.message.split("{")[0] ?? "";
+function isUnknownRpcReply(err) {
+  return err.message.startsWith(UNKNOWN_RPC_PREFIX) || err.message.startsWith("E_RPC_UNKNOWN");
+}
+function replyToAsker(core, clientId, reqId, desc, result) {
+  if (!desc.returns) {
+    sendReply(core, clientId, reqId, new Uint8Array(0));
+    return;
+  }
+  sendReply(core, clientId, reqId, encodeFields(desc.returns, result));
+}
+function beginAsk(core, asker, collection, id, askerReqId, askerDesc) {
+  const owner = plainEntity(core.plain, collection).ownerOf(id);
+  if (owner === void 0 || owner === SERVER_OWNER2) return refused("gone");
+  const askDesc = rpcTable(core.definition.schema).find((r) => r.name === OWNERSHIP_ASK);
+  if (!askDesc) {
+    core.log("error", `${OWNERSHIP_ASK} is missing from the rpc table; the ask cannot be sent`);
+    return refused("declined");
+  }
+  let settled = false;
+  const answer = (grant, reason) => {
+    if (settled) return;
+    settled = true;
+    clearAsk(core, collection, id);
+    if (grant) grantOwnership(core, collection, id, asker);
+    replyToAsker(core, asker, askerReqId, askerDesc, grant ? granted() : refused(reason));
+  };
+  const ownerReqId = callClient(
+    core,
+    owner,
+    askDesc,
+    { entity: collection, id, from: asker },
+    {
+      timeoutMs: ASK_WINDOW_MS,
+      resolve: (value) => {
+        const say = value?.granted === true;
+        if (!say) {
+          answer(false, "declined");
+          return;
+        }
+        const coll = plainEntity(core.plain, collection);
+        const stillTheirs = coll.has(id) && coll.ownerOf(id) === owner;
+        const askerHere = core.clients.get(asker)?.connected === true;
+        if (!stillTheirs || !askerHere) {
+          answer(false, "gone");
+          return;
+        }
+        answer(true, "");
+      },
+      reject: (err) => {
+        if (isUnknownRpcReply(err)) warnSdkPredatesAsk(core, owner);
+        answer(false, err instanceof RpcTimeoutError ? "timeout" : "declined");
+      }
+    }
+  );
+  if (settled) return DEFERRED;
+  const ask = {
+    collection,
+    id,
+    asker,
+    owner,
+    ownerReqId,
+    deadlineMs: core.host.now() + ASK_WINDOW_MS,
+    answer
+  };
+  trackAsk(core, ask);
+  return DEFERRED;
+}
+function cancelAsksFor(core, clientId) {
+  for (const ask of asksInFlight(core)) {
+    if (ask.asker !== clientId && ask.owner !== clientId) continue;
+    stateOf3(core).pending.delete(pendingKey(ask.owner, ask.ownerReqId));
+    ask.answer(false, "declined");
+  }
+}
+function cancelAllAsks(core) {
+  for (const ask of asksInFlight(core)) {
+    stateOf3(core).pending.delete(pendingKey(ask.owner, ask.ownerReqId));
+    ask.answer(false, "declined");
+  }
 }
 function descFor(core, name) {
+  if (isReservedRpcName(name)) {
+    throw new Error(`room.call: ${name} is reserved by irtio and cannot be called from room code`);
+  }
   const found = rpcTable(core.definition.schema).find((r) => r.name === name);
   if (!found) throw new Error(`room.call: unknown rpc ${JSON.stringify(name)}`);
   if (found.direction !== "client") {
@@ -630,6 +766,28 @@ function sendCall(core, clientId, desc, params) {
   );
   return reqId;
 }
+function callClient(core, clientId, desc, params, settle) {
+  const entry = core.clients.get(clientId);
+  if (!entry || !entry.connected) {
+    core.scheduleContinuationFlush();
+    settle.reject(new Error(`room.call: ${clientId} is not connected`));
+    return 0;
+  }
+  const reqId = sendCall(core, clientId, desc, params);
+  const s = stateOf3(core);
+  s.pending.set(pendingKey(clientId, reqId), {
+    clientId,
+    name: desc.name,
+    returns: desc.returns,
+    deadline: core.host.now() + settle.timeoutMs,
+    resolve: settle.resolve,
+    reject: settle.reject
+  });
+  if (core.mode === "event") {
+    core.loop.after(settle.timeoutMs, () => checkTimeouts(core));
+  }
+  return reqId;
+}
 function createCallProxy(core, clientId) {
   return new Proxy(
     {},
@@ -639,25 +797,11 @@ function createCallProxy(core, clientId) {
         return (params) => {
           const desc = descFor(core, prop);
           return new Promise((resolve, reject2) => {
-            const entry = core.clients.get(clientId);
-            if (!entry || !entry.connected) {
-              core.scheduleContinuationFlush();
-              reject2(new Error(`room.call: ${clientId} is not connected`));
-              return;
-            }
-            const reqId = sendCall(core, clientId, desc, params ?? {});
-            const s = stateOf3(core);
-            s.pending.set(pendingKey(clientId, reqId), {
-              clientId,
-              name: desc.name,
-              returns: desc.returns,
-              deadline: core.host.now() + RPC_TIMEOUT_MS,
+            callClient(core, clientId, desc, params ?? {}, {
+              timeoutMs: RPC_TIMEOUT_MS,
               resolve,
               reject: reject2
             });
-            if (core.mode === "event") {
-              core.loop.after(RPC_TIMEOUT_MS, () => checkTimeouts(core));
-            }
           });
         };
       }
@@ -732,7 +876,7 @@ function checkTimeouts(core) {
   for (const [key, p] of [...s.pending]) {
     if (p.deadline > now) continue;
     s.pending.delete(key);
-    p.reject(new Error(errorText("E_RPC_TIMEOUT", `rpc ${p.name} timed out`)));
+    p.reject(new RpcTimeoutError(errorText("E_RPC_TIMEOUT", `rpc ${p.name} timed out`)));
   }
 }
 function rejectAllPending(core, reason) {
@@ -760,6 +904,10 @@ function rejectAsEvent(core, err) {
   core.scheduleContinuationFlush();
   return Promise.reject(err);
 }
+function resolveAsEvent(core, value) {
+  core.scheduleContinuationFlush();
+  return Promise.resolve(value);
+}
 function startHostCall(core, call, map) {
   if (core.stopped) {
     return rejectAsEvent(core, new Error(`room.${call.kind}: the room is stopped`));
@@ -973,20 +1121,20 @@ function applyOp(core, clientId, c, op) {
   const requested = cloneValue(next);
   const simulated = c.physics;
   if (simulated) {
-    const refused = [];
+    const refused2 = [];
     for (const leaf of leafPaths(fields, op.mask)) {
       const field = leaf.names[0];
       if (simulated.intents.includes(field)) continue;
       next[field] = cloneValue(prev[field]);
-      refused.push(
+      refused2.push(
         simulated.bodyFields.has(field) ? `${field} (simulated)` : `${field} (not an intent)`
       );
     }
-    if (refused.length > 0) {
-      core.recordEvent("write-rejected", clientId, `${c.name}: ${refused.join(", ")}`);
+    if (refused2.length > 0) {
+      core.recordEvent("write-rejected", clientId, `${c.name}: ${refused2.join(", ")}`);
       core.log(
         "warn",
-        `WRITE to ${c.name}.${op.id} from ${clientId} touched fields the owner does not write: ${refused.join(", ")}`
+        `WRITE to ${c.name}.${op.id} from ${clientId} touched fields the owner does not write: ${refused2.join(", ")}`
       );
     }
   }
@@ -2943,7 +3091,7 @@ import {
   cloneValue as cloneValue2,
   createDirtySet as createDirtySet2,
   createState,
-  decodeSnapshot as decodeSnapshot2,
+  decodeSnapshot as decodeSnapshot3,
   encodeDelta as encodeDelta5,
   encodeSnapshot as encodeSnapshot4,
   isDirtyEmpty as isDirtyEmpty4,
@@ -3051,7 +3199,7 @@ var PoseHistory = class {
         const scratch = spec.scratch;
         scratch.fill(0);
         try {
-          spec.read(instance, scratch);
+          spec.read(instance, scratch, id);
           entry.channels.set(scratch, o2);
         } catch (err) {
           if (!this.hookFailed.has(collection)) {
@@ -3826,7 +3974,15 @@ function setLobbyPublic(core, value) {
 }
 
 // src/core/messages.ts
-import { FrameType as FrameType4, decodeMsg, encodeFrame as encodeFrame3, encodeMsg } from "@irtio/protocol";
+import {
+  FrameType as FrameType4,
+  decodeChatMsg,
+  decodeMsg,
+  encodeChatMsg,
+  encodeFrame as encodeFrame3,
+  encodeMsg,
+  isChatMsg
+} from "@irtio/protocol";
 import { decodeFields as decodeFields2 } from "@irtio/schema";
 function toRoomTarget(target) {
   switch (target.kind) {
@@ -3874,6 +4030,7 @@ function decodeTyped(core, clientId, index, payload) {
 }
 function handleMsg(core, clientId, payload) {
   core.recordEvent("msg", clientId);
+  if (isChatMsg(payload)) return handleChat(core, clientId, payload);
   let msg;
   try {
     msg = decodeMsg(payload);
@@ -3917,6 +4074,35 @@ function handleMsg(core, clientId, payload) {
   deliver(core, msg.target, frame, clientId);
   return true;
 }
+function handleChat(core, clientId, payload) {
+  let chat;
+  try {
+    chat = decodeChatMsg(payload);
+  } catch (err) {
+    core.log("warn", `chat from ${clientId} failed to decode:`, err);
+    return false;
+  }
+  if (chat.target.kind !== "all" && chat.target.kind !== "client") {
+    core.stats.messagesDropped++;
+    return true;
+  }
+  const onChat = core.definition.config.onChat;
+  if (onChat) {
+    const line = {
+      from: clientId,
+      text: chat.text,
+      target: chat.target.kind === "all" ? "all" : chat.target.clientId
+    };
+    const ran = core.tryRun("onChat", () => onChat(core.anyState, line, core.ctxFor(clientId)));
+    if (!ran.ok || ran.value === false) return true;
+  }
+  const frame = encodeFrame3(
+    FrameType4.MSG,
+    encodeChatMsg({ target: { kind: "client", clientId }, text: chat.text })
+  );
+  deliver(core, chat.target, frame, clientId);
+  return true;
+}
 function wireTargetOf(target) {
   return target === "all" ? { kind: "all" } : typeof target === "string" ? { kind: "client", clientId: target } : { kind: "role", role: target.role };
 }
@@ -3938,23 +4124,175 @@ function sendTypedMessage(core, index, target, payload) {
 // src/core/replay.ts
 import {
   CLIP_MAX_BYTES,
-  encodeClip
+  CLIP_TTL_DEFAULT_MS,
+  RECORDING_MAX_BYTES,
+  clipExpiryEpochS,
+  encodeClip,
+  encodeRecordingChunk,
+  parseRetention
 } from "@irtio/protocol";
 import {
   encodeDelta as encodeDelta3,
   encodeSnapshot as encodeSnapshot3,
   isDirtyEmpty as isDirtyEmpty2
 } from "@irtio/schema";
+
+// src/core/replay-excerpt.ts
+import {
+  applyDelta,
+  decodeDelta as decodeDelta2,
+  decodeSnapshot as decodeSnapshot2
+} from "@irtio/schema";
+var EXCERPT_MAX_SECONDS = 30;
+var EXCERPT_BURST = 4;
+var EXCERPT_COOLDOWN_MS = 1e3;
+var EXCERPT_MAX_BYTES = 4 * 1024 * 1024;
+var ExcerptTooLargeError = class extends Error {
+  constructor(bytes) {
+    super(`excerpt output passed ${EXCERPT_MAX_BYTES} bytes`);
+    this.bytes = bytes;
+    this.name = "ExcerptTooLargeError";
+  }
+  bytes;
+};
+function estimateValue(value) {
+  if (typeof value === "string") return value.length + 2;
+  if (Array.isArray(value)) {
+    let n = 2;
+    for (const v of value) n += estimateValue(v) + 1;
+    return n;
+  }
+  if (typeof value === "object" && value !== null) {
+    let n = 2;
+    for (const [k, v] of Object.entries(value)) {
+      n += k.length + 3 + estimateValue(v);
+    }
+    return n;
+  }
+  return 8;
+}
+function copyValue(value) {
+  if (Array.isArray(value)) return value.map(copyValue);
+  if (typeof value === "object" && value !== null) {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) out[k] = copyValue(v);
+    return out;
+  }
+  return value;
+}
+function projectTick(state, wanted, ids) {
+  const entities = {};
+  let bytes = 0;
+  for (const desc of wanted) {
+    const coll = state[desc.name];
+    if (coll === void 0) continue;
+    const rows = {};
+    let any = false;
+    for (const id of [...coll.ids()]) {
+      if (ids !== void 0 && !ids.has(id)) continue;
+      const record = coll.get(id);
+      if (record === void 0) continue;
+      const row = {};
+      for (const field of desc.fields) {
+        const v = record[field.name];
+        if (v === void 0) continue;
+        row[field.name] = copyValue(v);
+        bytes += field.name.length + 3 + estimateValue(v);
+      }
+      bytes += id.length + 4;
+      rows[id] = row;
+      any = true;
+    }
+    if (any) {
+      bytes += desc.name.length + 4;
+      entities[desc.name] = rows;
+    }
+  }
+  return { entities, bytes };
+}
+function wantedCollections(ext, names) {
+  const all = ext.collections.filter((c) => c.kind === "entity");
+  if (names === void 0) return [...all];
+  const wanted = new Set(names);
+  return all.filter((c) => wanted.has(c.name));
+}
+function unknownCollection(ext, options) {
+  const names = options?.collections;
+  if (names === void 0) return void 0;
+  const known = new Set(
+    ext.collections.filter((c) => c.kind === "entity").map((c) => c.name)
+  );
+  for (const name of names) {
+    if (!known.has(name)) return String(name);
+  }
+  return void 0;
+}
+function walkExcerpt(ext, ring, tickRate, seconds, options) {
+  const ringFrames = ring.frames;
+  const last = ringFrames[ringFrames.length - 1];
+  if (last === void 0) return { startTick: 0, endTick: 0, tickRate, frames: [] };
+  const from = last.tick - Math.ceil(seconds * tickRate);
+  const window = ring.tail(from);
+  const head = window[0];
+  if (head === void 0 || !head.keyframe) {
+    return { startTick: 0, endTick: 0, tickRate, frames: [] };
+  }
+  const wanted = wantedCollections(ext, options?.collections);
+  const ids = options?.ids === void 0 ? void 0 : new Set(options.ids);
+  const state = decodeSnapshot2(ext, head.bytes).state;
+  const frames = [];
+  let bytes = 0;
+  const emit = (tick) => {
+    if (tick < from) return;
+    const { entities, bytes: n } = projectTick(state, wanted, ids);
+    bytes += n;
+    if (bytes > EXCERPT_MAX_BYTES) throw new ExcerptTooLargeError(bytes);
+    frames.push({ tick, entities });
+  };
+  if (window[1]?.tick !== head.tick) emit(head.tick);
+  for (let i = 1; i < window.length; i++) {
+    const f = window[i];
+    if (f.keyframe) continue;
+    applyDelta(ext, state, decodeDelta2(ext, f.bytes));
+    emit(f.tick);
+  }
+  const first = frames[0];
+  return {
+    startTick: first?.tick ?? head.tick,
+    endTick: frames[frames.length - 1]?.tick ?? head.tick,
+    tickRate,
+    frames
+  };
+}
+
+// src/core/replay.ts
 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 CLIP_BURST = 8;
 var ReplayRing = class {
-  constructor(bounds) {
+  /**
+   * M6 record packet: `onEvict` is handed every segment the ring drops, oldest first, at the
+   * moment it drops it — which is the whole of what a recording is. It is optional and unset in
+   * every room that did not ask to record, so the ring a clip-only room runs is the ring it ran
+   * before this packet, allocation for allocation.
+   *
+   * A *wipe* deliberately does not call it. A wipe is one segment that outgrew the entire ring, so
+   * emitting it would mean writing a chunk bigger than the bound the ring exists to keep. For a
+   * clip that is "holds less footage than it asked for"; for a recording it is not, because the
+   * frames after the wipe are deltas whose keyframe was never written, and playback skips
+   * mid-stream keyframes rather than re-basing on them. So a wipe is not silently less footage: it
+   * ENDS the recording (`append` returns `true` and the flush tap stops it), which turns wrong
+   * footage into short footage.
+   */
+  constructor(bounds, onEvict) {
     this.bounds = bounds;
+    this.onEvict = onEvict;
   }
   bounds;
+  onEvict;
   items = [];
   total = 0;
   /** How many times an oversized segment has emptied the ring. Read through `append`'s return. */
@@ -4025,10 +4363,13 @@ var ReplayRing = class {
         return;
       }
       for (let i = 0; i < next; i++) this.total -= this.items[i].bytes.length;
+      const evicted = this.items.slice(0, next);
       this.items = this.items.slice(next);
+      this.onEvict?.(evicted);
     }
   }
 };
+var RECORD_QUEUE_MAX = 2;
 var states5 = /* @__PURE__ */ new WeakMap();
 function configOf(core) {
   const config = core.definition.config;
@@ -4047,17 +4388,43 @@ function stateOf6(core) {
       REPLAY_MAX_SECONDS,
       Math.max(1, Math.floor(declared.seconds ?? REPLAY_DEFAULT_SECONDS))
     );
+    const record = declared.record === true;
+    const outbox = [];
+    const ttlMs = parseRetention(declared.ttl) ?? CLIP_TTL_DEFAULT_MS;
     s = {
       seconds,
+      ttlMs,
+      recExpiresAtEpochS: void 0,
       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,
+      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
+        },
+        record ? (frames) => outbox.push(...frames) : void 0
+      ),
+      clipTokens: CLIP_BURST,
+      lastRefillAt: Number.NEGATIVE_INFINITY,
       clipsTaken: 0,
-      disarmed: false
+      excerptTokens: EXCERPT_BURST,
+      lastExcerptRefillAt: Number.NEGATIVE_INFINITY,
+      excerptsTaken: 0,
+      disarmed: false,
+      record,
+      outbox,
+      queued: [],
+      recId: void 0,
+      nextSeq: 0,
+      encoded: 0,
+      recBytes: 0,
+      inFlight: false,
+      recStopped: false,
+      recWarned: false,
+      recExpiryWarned: false,
+      finalDrained: false,
+      dropInFlight: false,
+      chunksOut: 0
     };
     states5.set(core, s);
   }
@@ -4106,27 +4473,39 @@ function cacheKeyFor(core, state) {
 function recordFlush(core, dirty, byView) {
   const state = stateOf6(core);
   if (!state || state.disarmed) return;
+  appendFlush(core, state, dirty, byView);
+  if (state.record) pumpDrain(core, state);
+}
+function appendFlush(core, state, dirty, byView) {
   const ring = state.ring;
   if (!ring.empty && isDirtyEmpty2(dirty)) return;
   if (ring.keyframeDue(core.tick)) {
-    const wiped = ring.append({
+    const wiped2 = ring.append({
       tick: core.tick,
       keyframe: true,
       bytes: recorderSnapshot(core, state)
     });
-    if (wiped) {
+    if (wiped2) {
       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);
+  const delta = cached ?? recorderDelta(core, state, dirty);
   if (!delta) return;
-  ring.append({ tick: core.tick, keyframe: false, bytes: delta });
+  const wiped = ring.append({ tick: core.tick, keyframe: false, bytes: delta });
+  if (wiped && state.record) {
+    stopRecording(
+      core,
+      state,
+      `one replay segment was larger than the whole ${REPLAY_RING_MAX_BYTES}-byte ring, so the ring was emptied and the footage after it could not be re-based`
+    );
+  }
 }
 function disarm(core, state) {
   state.disarmed = true;
+  if (state.record) stopRecording(core, state, "the replay ring disarmed");
   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.`
   ]);
@@ -4169,11 +4548,17 @@ function takeClip(core, seconds) {
   }
   const state = stateOf6(core);
   const now = core.host.now();
-  if (now - state.lastClipAt < CLIP_COOLDOWN_MS) {
+  if (state.lastRefillAt === Number.NEGATIVE_INFINITY) state.lastRefillAt = now;
+  const refilled = Math.floor((now - state.lastRefillAt) / CLIP_COOLDOWN_MS);
+  if (refilled > 0) {
+    state.clipTokens = Math.min(CLIP_BURST, state.clipTokens + refilled);
+    state.lastRefillAt += refilled * CLIP_COOLDOWN_MS;
+  }
+  if (state.clipTokens <= 0) {
     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`
+        `E_CLIP_COOLDOWN: room.replay.clip allows bursts of ${CLIP_BURST}, refilled one every ${CLIP_COOLDOWN_MS}ms per room; this room is out of clip tokens right now`
       )
     );
   }
@@ -4208,9 +4593,256 @@ function takeClip(core, seconds) {
       )
     );
   }
-  state.lastClipAt = now;
+  state.clipTokens--;
   state.clipsTaken++;
-  return startHostCall(core, { kind: "clip", bytes }, (value) => ({ id: value ?? "" }));
+  return startHostCall(
+    core,
+    { kind: "clip", bytes, expiresAtEpochS: clipExpiryEpochS(core.wallNow(), state.ttlMs) },
+    (value) => ({ id: value ?? "" })
+  );
+}
+function takeExcerpt(core, options) {
+  if (!replayArmed(core)) {
+    return rejectAsEvent(
+      core,
+      new Error(
+        "E_REPLAY_UNARMED: room.replay.excerpt: 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 seconds = options?.seconds;
+  if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds <= 0) {
+    return rejectAsEvent(
+      core,
+      new Error(
+        "E_EXCERPT_BAD_ARGS: room.replay.excerpt needs { seconds } as a positive number, got " + JSON.stringify(seconds)
+      )
+    );
+  }
+  if (seconds > EXCERPT_MAX_SECONDS) {
+    return rejectAsEvent(
+      core,
+      new Error(
+        `E_EXCERPT_TOO_LONG: room.replay.excerpt decodes at most ${EXCERPT_MAX_SECONDS} seconds at a time and was asked for ${seconds}. An excerpt is a killcam, not a match; for a whole match use \`replay: { record: true }\`.`
+      )
+    );
+  }
+  const badName = unknownCollection(core.ext, options);
+  if (badName !== void 0) {
+    return rejectAsEvent(
+      core,
+      new Error(
+        `E_EXCERPT_BAD_ARGS: room.replay.excerpt was asked for the collection ${JSON.stringify(
+          badName
+        )}, which is not an entity collection in this room's schema. Singleton collections are not excerptable.`
+      )
+    );
+  }
+  const state = stateOf6(core);
+  if (state.disarmed) {
+    return rejectAsEvent(
+      core,
+      new Error(
+        `E_EXCERPT_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`
+      )
+    );
+  }
+  const now = core.host.now();
+  if (state.lastExcerptRefillAt === Number.NEGATIVE_INFINITY) state.lastExcerptRefillAt = now;
+  const refilled = Math.floor((now - state.lastExcerptRefillAt) / EXCERPT_COOLDOWN_MS);
+  if (refilled > 0) {
+    state.excerptTokens = Math.min(EXCERPT_BURST, state.excerptTokens + refilled);
+    state.lastExcerptRefillAt += refilled * EXCERPT_COOLDOWN_MS;
+  }
+  if (state.excerptTokens <= 0) {
+    return rejectAsEvent(
+      core,
+      new Error(
+        `E_EXCERPT_COOLDOWN: room.replay.excerpt allows bursts of ${EXCERPT_BURST}, refilled one every ${EXCERPT_COOLDOWN_MS}ms per room; this room is out of excerpt tokens right now`
+      )
+    );
+  }
+  state.excerptTokens--;
+  const tickRate = core.definition.config.tickRate ?? 20;
+  let out;
+  try {
+    out = walkExcerpt(core.ext, state.ring, tickRate, seconds, options);
+  } catch (err) {
+    if (err instanceof ExcerptTooLargeError) {
+      return rejectAsEvent(
+        core,
+        new Error(
+          `E_EXCERPT_TOO_LARGE: this excerpt would materialize about ${err.bytes} bytes of frames and the limit is ${EXCERPT_MAX_BYTES}. Ask for fewer seconds, or name the collections (and ids) you actually need in \`collections\`/\`ids\`.`
+        )
+      );
+    }
+    return rejectAsEvent(
+      core,
+      new Error(`E_EXCERPT_DECODE: the replay ring could not be decoded: ${String(err)}`)
+    );
+  }
+  state.excerptsTaken++;
+  return resolveAsEvent(core, out);
+}
+var recordingCap = RECORDING_MAX_BYTES;
+function stopRecording(core, state, why) {
+  if (state.recStopped) return;
+  state.recStopped = true;
+  state.outbox.length = 0;
+  state.queued.length = 0;
+  if (state.recWarned) return;
+  state.recWarned = true;
+  core.host.log("warn", [
+    `irtio: room ${core.roomId}: full-match recording stopped (${why}). The chunks already written stay playable and room.replay.clip() still works; nothing further is recorded for the life of this room.`
+  ]);
+}
+function pumpDrain(core, state) {
+  if (state.recStopped) {
+    state.outbox.length = 0;
+    return;
+  }
+  if (state.outbox.length > 0) {
+    const frames = state.outbox.splice(0, state.outbox.length);
+    encodeAndQueue(core, state, frames);
+  }
+  sendNext(core, state);
+}
+function encodeAndQueue(core, state, frames) {
+  if (frames.length === 0) return;
+  if (state.recExpiresAtEpochS === void 0) {
+    state.recExpiresAtEpochS = clipExpiryEpochS(core.wallNow(), state.ttlMs);
+  }
+  const first = frames[0];
+  const header = state.encoded === 0 ? {
+    // The GAME schema's hash, for `assembleClip`'s reason: it is what a client's HELLO
+    // carries and what a deploy changes.
+    schemaHash8: core.definition.schema.hash8,
+    tickRate: core.definition.config.tickRate ?? 20,
+    startTick: first.tick,
+    view: state.view
+  } : void 0;
+  if (header !== void 0 && first.keyframe !== true) {
+    stopRecording(core, state, "the first chunk would not have begun with a keyframe");
+    return;
+  }
+  let bytes;
+  try {
+    bytes = encodeRecordingChunk(
+      frames.map((f) => ({
+        tick: f.tick,
+        kind: f.keyframe ? "keyframe" : "delta",
+        bytes: f.bytes
+      })),
+      header
+    );
+  } catch (err) {
+    stopRecording(core, state, `the chunk could not be encoded: ${String(err)}`);
+    return;
+  }
+  if (bytes.length === 0) return;
+  if (state.recBytes + bytes.length > recordingCap) {
+    stopRecording(
+      core,
+      state,
+      `it reached the ${recordingCap}-byte per-recording limit after ${state.chunksOut} chunk(s)`
+    );
+    return;
+  }
+  state.encoded++;
+  state.queued.push(bytes);
+  if (state.queued.length > RECORD_QUEUE_MAX) {
+    stopRecording(
+      core,
+      state,
+      `the store is answering slower than the ring evicts: ${RECORD_QUEUE_MAX} chunk(s) were already waiting behind the one in flight, and dropping one would have left a gap nothing downstream could re-base on`
+    );
+  }
+}
+function sendNext(core, state, all = false) {
+  if (state.recStopped && !state.finalDrained) return;
+  const parallel = all && state.recId !== void 0;
+  for (; ; ) {
+    if (state.inFlight && !parallel) return;
+    const bytes = state.queued.shift();
+    if (bytes === void 0) return;
+    sendChunk(core, state, bytes);
+    if (!parallel) return;
+  }
+}
+function warnRecordingOutlivedTtl(core, state) {
+  if (state.recExpiryWarned) return;
+  const expiresAtEpochS = state.recExpiresAtEpochS;
+  if (expiresAtEpochS === void 0 || expiresAtEpochS * 1e3 > core.wallNow()) return;
+  state.recExpiryWarned = true;
+  core.host.log("warn", [
+    `irtio: room ${core.roomId}: this full-match recording expired at ${expiresAtEpochS} (unix seconds) while it was still being written. A recording is kept for replay.ttl from its first stored chunk, so a ttl shorter than the match deletes the recording while the match is still running and its link answers 404. Set replay.ttl to at least the length of a match.`
+  ]);
+}
+function sendChunk(core, state, bytes) {
+  warnRecordingOutlivedTtl(core, state);
+  const seq = state.nextSeq;
+  state.nextSeq++;
+  state.chunksOut++;
+  state.recBytes += bytes.length;
+  state.inFlight = true;
+  startHostCall(
+    core,
+    {
+      kind: "record-chunk",
+      recId: state.recId,
+      seq,
+      bytes,
+      // The first chunk's expiry, on every chunk. `encodeAndQueue` set it before anything could
+      // reach here; the fallback is a value, not a second policy.
+      expiresAtEpochS: state.recExpiresAtEpochS ?? clipExpiryEpochS(core.wallNow(), state.ttlMs)
+    },
+    (value) => value ?? ""
+  ).then((id) => {
+    state.inFlight = false;
+    state.dropInFlight = false;
+    if (state.recId === void 0 && id !== "") state.recId = id;
+    sendNext(core, state, state.finalDrained);
+  }).catch((err) => {
+    state.inFlight = false;
+    if (state.dropInFlight) {
+      state.dropInFlight = false;
+      if (state.recId === void 0) {
+        stopRecording(
+          core,
+          state,
+          "the reply carrying the recording's id was dropped before it arrived, and a second chunk would have been stored as a second recording"
+        );
+        return;
+      }
+      sendNext(core, state, state.finalDrained);
+      return;
+    }
+    if (state.queued.length > 0) {
+      const bytes2 = state.queued.reduce((n, b) => n + b.length, 0);
+      core.host.log("warn", [
+        `irtio: room ${core.roomId}: the full-match recording lost its last ${state.queued.length} chunk(s) (${bytes2} bytes). The room ended before the store answered the first chunk, so the recording's id was never known here and the tail had nowhere to go. Everything already stored plays.`
+      ]);
+      state.queued.length = 0;
+    }
+    stopRecording(core, state, `a chunk was not stored: ${String(err)}`);
+  });
+}
+function drainRecordingFinal(core) {
+  const state = states5.get(core);
+  if (!state || !state.record || state.recStopped || state.finalDrained) return;
+  state.finalDrained = true;
+  const remaining = state.ring.frames;
+  const frames = [...state.outbox.splice(0, state.outbox.length), ...remaining];
+  if (frames.length > 0) encodeAndQueue(core, state, frames);
+  sendNext(core, state, true);
+  state.recStopped = true;
+}
+function recordingId(core) {
+  return states5.get(core)?.recId;
+}
+function noteRecordingRepliesDropped(core) {
+  const state = states5.get(core);
+  if (state?.inFlight === true) state.dropInFlight = true;
 }
 
 // src/core/room-api.ts
@@ -4580,7 +5212,17 @@ function createRoomApi(core, publicUrl) {
         get armed() {
           return replayArmed(core);
         },
-        clip: (seconds) => takeClip(core, seconds)
+        clip: (seconds) => takeClip(core, seconds),
+        // M7 planned feature 5: the ring read back as plain frames. Same read-through shape as
+        // `clip` — the walk, the projection and the whole budget live in `core/replay-excerpt.ts`
+        // and `core/replay.ts`.
+        excerpt: (options) => takeExcerpt(core, options),
+        // M6 record packet: the id of the recording being written, once the first chunk has been
+        // stored. A getter, like `armed`, so a game reading it late in a match sees the id rather
+        // than the `undefined` it would have captured at the start of one.
+        get recording() {
+          return recordingId(core);
+        }
       };
     },
     // ---- end M6 lane N ----
@@ -4827,7 +5469,7 @@ var RoomCore = class _RoomCore {
       restored = candidate;
     }
     if (restored) {
-      plain = decodeSnapshot2(this.ext, restored.snapshot).state;
+      plain = decodeSnapshot3(this.ext, restored.snapshot).state;
       const presence = plainEntity(plain, PRESENCE_COLLECTION);
       for (const id of [...presence.ids()]) presence.remove(id);
       if (restored.mode !== this.mode) {
@@ -4878,6 +5520,37 @@ var RoomCore = class _RoomCore {
   get busConfig() {
     return this.definition.config.bus;
   }
+  /**
+   * M7 D-P2: the platform notice, and the room's veto.
+   *
+   * Answers whether the supervisor should broadcast. `false` — the veto — comes back for exactly
+   * one input: a handler that ran and returned `false`. Every other path answers `true`, and each
+   * one is a different way of the room having said nothing:
+   *
+   * - **No handler.** A room that never wrote this hook. The design's whole point is that its
+   *   players still hear the warning; a code-less room does not even reach this file.
+   * - **A handler that threw.** `tryRun` and not `guard`, so the throw counts toward the crash
+   *   threshold like any other, and it still does not become a veto. This is the one place the
+   *   convention differs from `onChat`, where a throw refuses, and the reason is the asymmetry of
+   *   the two losses: a chat line nobody sees is small; a save-loss warning nobody sees is the
+   *   feature not existing.
+   * - **A stopped room.** Nobody to ask, and for `closing` nobody left to veto for.
+   *
+   * The handler may also have written state, posted chat or started an end sequence. All of that
+   * is ordinary handler work and is flushed here the way an alarm's is.
+   */
+  deliverPlatformNotice(notice) {
+    if (this.stopped) return true;
+    const handler = this.definition.config.onPlatformNotice;
+    if (!handler) return true;
+    this.recordEvent("notice", void 0, notice.phase);
+    const ran = this.tryRun(
+      "onPlatformNotice",
+      () => handler(this.anyState, notice, this.room)
+    );
+    this.eventFlush();
+    return !(ran.ok && ran.value === false);
+  }
   /**
    * D59: one published message arriving on a channel this room is subscribed to.
    *
@@ -5166,6 +5839,8 @@ var RoomCore = class _RoomCore {
   }
   stop() {
     if (this.stopped) return;
+    drainRecordingFinal(this.internals);
+    cancelAllAsks(this.internals);
     this.stopped = true;
     this.started = false;
     this.loop.stop();
@@ -5208,7 +5883,9 @@ var RoomCore = class _RoomCore {
     const onSleep = this.definition.config.onSleep;
     if (onSleep) this.guard("onSleep", () => onSleep(this.state, this.room));
     this.loop.clearAllTimers();
+    cancelAllAsks(this.internals);
     rejectAllPending(this.internals, "room is hibernating");
+    noteRecordingRepliesDropped(this.internals);
     rejectAllHostCalls(this.internals, "room is hibernating");
     return this.snapshot();
   }
@@ -5356,6 +6033,7 @@ var RoomCore = class _RoomCore {
       const ctx = this.ctxFor(clientId);
       this.guard("onLeave", () => onLeave(this.state, ctx, reason));
     }
+    cancelAsksFor(this.internals, clientId);
     placeHolds(this.internals, clientId, entry.playerId);
     forgetWriter(this.internals, clientId);
     this.presence.remove(clientId);
@@ -5375,6 +6053,7 @@ var RoomCore = class _RoomCore {
     }
     entry.connected = false;
     entry.correction = void 0;
+    cancelAsksFor(this.internals, clientId);
     const record = this.presence.get(clientId);
     if (record && record.connected !== false) record.connected = false;
     this.invalidateClients();
@@ -5501,6 +6180,12 @@ var RoomCore = class _RoomCore {
     return holdCount(this.internals);
   }
   // ---- end M6 lane K ----
+  // ---- M6 ask packet ----
+  /** How many `transfer: 'ask'` requests are waiting on an owner's answer right now. */
+  askCount() {
+    return askCount(this.internals);
+  }
+  // ---- end M6 ask packet ----
   profile() {
     return this.ledger?.snapshot();
   }