@irtio/protocol 0.5.1 → 0.6.0

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/frame.ts
-var PROTOCOL_VERSION = 1;
+var PROTOCOL_VERSION = 2;
 var FrameType = {
   HELLO: 1,
   WELCOME: 2,
@@ -18,7 +18,19 @@ var FrameType = {
    * reconnect grace window and the room's `onLeave` sees `reason: 'left'` instead of waiting for
    * the close to time out into `'timeout'`. Additive — protocol version stays 1.
    */
-  LEAVE: 12
+  LEAVE: 12,
+  /**
+   * Server → client, payload the new schema's canonical JSON as UTF-8 (D50, gap-and-resync).
+   * Sent during a `migrate`-strategy deploy whose schema change is purely additive, after the old
+   * worker stops sending and before the resync WELCOME, to a session that asked for it. The
+   * client rebuilds its codec from the descriptor and keeps its socket; before this, any schema
+   * change closed it with `E_SCHEMA_MISMATCH`.
+   *
+   * Gated, not versioned. `decodeFrame` throws on an unknown type, so a client that predates this
+   * frame must never receive one: the server sends it only to a session whose HELLO set
+   * `HELLO_SCHEMA_SWAP_BIT`. Additive — protocol version stays 1, the same way LEAVE=12 did.
+   */
+  SCHEMA: 13
 };
 var FRAME_TYPE_VALUES = new Set(Object.values(FrameType));
 function isFrameType(v) {
@@ -45,7 +57,7 @@ var ErrorCode = {
   E_SCHEMA_MISMATCH: { code: 4, message: "schema hash mismatch" },
   E_ROOM_NOT_FOUND: {
     code: 5,
-    message: "room {roomId} not found \u2014 room ids are 1-32 of A-Z a-z 0-9 - _"
+    message: "room {roomId} not found. Room ids are 1-32 of A-Z a-z 0-9 - _, optionally behind a lowercase <type>: prefix"
   },
   E_ROOM_FULL: { code: 6, message: "room {roomId} is full" },
   E_ROOM_CLOSED: { code: 7, message: "room {roomId} is closed" },
@@ -74,8 +86,72 @@ var ErrorCode = {
   E_TOKEN_WRONG_ROOM: { code: 24, message: "auth token is for another room" },
   E_TOKEN_MALFORMED: { code: 25, message: "auth token is malformed: {reason}" },
   E_TOKEN_BAD_ISSUER: { code: 26, message: "auth token issuer {issuer} is not accepted" },
-  E_TOKEN_BAD_ALG: { code: 27, message: "auth token algorithm {alg} is not allowed" }
+  E_TOKEN_BAD_ALG: { code: 27, message: "auth token algorithm {alg} is not allowed" },
+  /**
+   * M4 (D48): the project is at a usage cap and this join is new work.
+   *
+   * The template carries `{detail}` rather than a fixed sentence because the actionable half
+   * differs by tier and by meter, and a refusal that does not say what to do next is the thing
+   * `errors.md`'s fix-line convention exists to prevent. Control composes the detail; the box
+   * relays it. Non-protocol surfaces (the store gateway's write refusal, control's HTTP refusals
+   * for deploys and uploads) reuse the same `E_USAGE_CAP` string code in their own shapes, so one
+   * grep finds every place a cap can be met.
+   */
+  E_USAGE_CAP: { code: 28, message: "{detail}" },
+  /**
+   * M4 part 5 (D53): the tenant cannot verify platform identity assertions because it holds no
+   * platform public key yet.
+   *
+   * Deliberately not `E_AUTH` and not `E_TOKEN_INVALID`. Those say "your credential is bad", and
+   * this is the opposite — the credential may be perfect and the box is not yet in a position to
+   * say so. Keys are delivered to a tenant the way cap state is (a push from control right after
+   * the VM comes up), so the honest reading of this code is "retry in a moment", which is what
+   * the fix line in the errors reference says.
+   */
+  E_ASSERTION_UNVERIFIABLE: {
+    code: 29,
+    message: "this server cannot verify identity assertions yet"
+  },
+  /**
+   * M5 part 3.5: a room type is already running as many rooms as it declared it would.
+   *
+   * Deliberately its own code rather than `E_ROOM_FULL`, which is about clients in a room, and
+   * emphatically not `E_INTERNAL`. This refusal is what makes declared sizing honest: the tenant's
+   * VM memory was computed as the declared per-room heap times this number, so room N+1 is a room
+   * the machine was never built to hold. The message names the type, the limit and the field to
+   * change, because all three are things the developer controls.
+   */
+  E_TYPE_AT_CAPACITY: { code: 30, message: "{detail}" },
+  /**
+   * M5 part 3.5 (Part C): the project has used its egress allowance and forwarding has stopped.
+   *
+   * Its own code, and its own WebSocket close code ({@link CLOSE_EGRESS_WALL}), for one reason: a
+   * developer watching sockets close has to be able to tell a wall from a bug. `E_USAGE_CAP` is
+   * the polite refusal of *new* work at a cap control evaluated up to a minute ago; this is the
+   * box stopping traffic on its own, locally, the moment its leased budget ran out.
+   */
+  E_EGRESS_WALL: { code: 31, message: "{detail}" },
+  /**
+   * M5 part 3.5 (Part C): a free-tier shape limit — the relay client cap, or the concurrent
+   * awake-rooms cap. The message names the limit and the tier, because the fix is a card.
+   */
+  E_TIER_LIMIT: { code: 32, message: "{detail}" },
+  /**
+   * M5 part 7 (D67-i): the project's region has no server with room for another tenant VM.
+   *
+   * Sent by the router, fatal, with close code 1013 (RFC 6455 "try again later"). Before this
+   * code a full region looked like a slow start: the control plane re-ran placement on every
+   * lookup poll for thirty seconds and the client then saw `E_STARTING` followed by `E_INTERNAL`.
+   * The message names the region and the two fixes because both are an operator's, never the
+   * player's: the client does not retry this join on its own.
+   */
+  E_PLACEMENT: {
+    code: 33,
+    message: "no capacity in region {region}; add a server or raise maxVms"
+  }
 };
+var CLOSE_TRY_AGAIN_LATER = 1013;
+var CLOSE_EGRESS_WALL = 4290;
 var ERROR_CATALOGUE = Object.keys(ErrorCode).map((name) => ({ name, code: ErrorCode[name].code, message: ErrorCode[name].message }));
 var BY_CODE = new Map(
   ERROR_CATALOGUE.map((e) => [e.code, e])
@@ -101,6 +177,7 @@ function assertEof(r, what) {
 var HELLO_RESUME_BIT = 1 << 0;
 var HELLO_ROLE_BIT = 1 << 1;
 var HELLO_NAME_BIT = 1 << 2;
+var HELLO_SCHEMA_SWAP_BIT = 1 << 3;
 function encodeHello(h) {
   if (h.schemaHash8.length !== 8) {
     throw new Error(`encodeHello: schemaHash8 must be 8 bytes, got ${h.schemaHash8.length}`);
@@ -114,7 +191,7 @@ function encodeHello(h) {
     w.u8(1);
     w.str(h.credential.token);
   } else {
-    w.u8(2);
+    w.u8(h.credential.kind === "assertion" ? 3 : 2);
     w.str(h.credential.key);
     w.str(h.credential.token);
   }
@@ -124,6 +201,7 @@ function encodeHello(h) {
   if (h.resumeToken !== void 0) mask |= HELLO_RESUME_BIT;
   if (h.role !== void 0) mask |= HELLO_ROLE_BIT;
   if (h.name !== void 0) mask |= HELLO_NAME_BIT;
+  if (h.schemaSwap === true) mask |= HELLO_SCHEMA_SWAP_BIT;
   w.u8(mask);
   if (h.resumeToken !== void 0) w.str(h.resumeToken);
   if (h.role !== void 0) w.str(h.role);
@@ -138,6 +216,7 @@ function decodeHello(bytes) {
   if (credKind === 0) credential = { kind: "key", key: r.str() };
   else if (credKind === 1) credential = { kind: "token", token: r.str() };
   else if (credKind === 2) credential = { kind: "jwt", key: r.str(), token: r.str() };
+  else if (credKind === 3) credential = { kind: "assertion", key: r.str(), token: r.str() };
   else throw new Error(`decodeHello: unknown credential kind ${credKind}`);
   const roomId = r.str();
   const schemaHash8 = r.bytes(8);
@@ -145,13 +224,15 @@ function decodeHello(bytes) {
   const resumeToken = (mask & HELLO_RESUME_BIT) !== 0 ? r.str() : void 0;
   const role = (mask & HELLO_ROLE_BIT) !== 0 ? r.str() : void 0;
   const name = (mask & HELLO_NAME_BIT) !== 0 ? r.str() : void 0;
+  const schemaSwap = (mask & HELLO_SCHEMA_SWAP_BIT) !== 0;
   assertEof(r, "decodeHello");
   const hello = { protocolVersion, credential, roomId, schemaHash8 };
   return {
     ...hello,
     ...resumeToken !== void 0 ? { resumeToken } : {},
     ...role !== void 0 ? { role } : {},
-    ...name !== void 0 ? { name } : {}
+    ...name !== void 0 ? { name } : {},
+    ...schemaSwap ? { schemaSwap: true } : {}
   };
 }
 function encodeWelcome(w0) {
@@ -162,7 +243,8 @@ function encodeWelcome(w0) {
   w.blob(w0.snapshot);
   w.str(w0.resumeToken);
   w.str(w0.roomId);
-  w.u16(w0.tickIntervalMs);
+  w.u16(w0.tickRate);
+  w.u16(w0.maxClients);
   return w.finish();
 }
 function decodeWelcome(bytes) {
@@ -173,9 +255,10 @@ function decodeWelcome(bytes) {
   const snapshot = r.blob();
   const resumeToken = r.str();
   const roomId = r.str();
-  const tickIntervalMs = r.eof ? 0 : r.u16();
+  const tickRate = r.eof ? 0 : r.u16();
+  const maxClients = r.eof ? 0 : r.u16();
   assertEof(r, "decodeWelcome");
-  return { clientId, role, tick, snapshot, resumeToken, roomId, tickIntervalMs };
+  return { clientId, role, tick, snapshot, resumeToken, roomId, tickRate, maxClients };
 }
 function encodeErrorPayload(e) {
   const w = new ByteWriter();
@@ -245,6 +328,15 @@ function encodeWriteFrame(codecBytes) {
 function encodeCorrectFrame(codecBytes, clientTick, appliedTick) {
   return encodeFrame(FrameType.CORRECT, correctPayload(codecBytes, clientTick, appliedTick));
 }
+function schemaPayload(canonical) {
+  return new TextEncoder().encode(canonical);
+}
+function readSchemaPayload(payload) {
+  return new TextDecoder("utf-8", { fatal: true }).decode(payload);
+}
+function encodeSchemaFrame(canonical) {
+  return encodeFrame(FrameType.SCHEMA, schemaPayload(canonical));
+}
 
 // src/rpc.ts
 import { ByteReader as ByteReader2, ByteWriter as ByteWriter2, bool, server, str } from "@irtio/schema";
@@ -323,12 +415,422 @@ function rpcByIdOf(schema, id) {
   return found;
 }
 
+// src/profile.ts
+import { ByteReader as ByteReader3, walkDelta, walkSnapshot } from "@irtio/schema";
+
+// src/presence.ts
+import { bool as bool2, defineSchema, entity, str as str2 } from "@irtio/schema";
+var presenceEntity = entity(
+  { clientId: str2(32), role: str2(32), name: str2(32), connected: bool2 },
+  { serverOwned: true }
+);
+var PRESENCE_COLLECTION = "clients";
+var extended = /* @__PURE__ */ new WeakMap();
+function withBuiltins(schema) {
+  let ext = extended.get(schema);
+  if (!ext) {
+    ext = defineSchema(
+      { ...schema.defs, [PRESENCE_COLLECTION]: presenceEntity },
+      {
+        rpc: schema.rpc,
+        roles: schema.roles,
+        ...schema.project !== void 0 ? { project: schema.project } : {},
+        allowReservedNames: true
+      }
+    );
+    extended.set(schema, ext);
+  }
+  return ext;
+}
+var relaySchema = withBuiltins(defineSchema({}));
+var RELAY_HASH8 = new Uint8Array(8);
+function isRelayHash8(hash8) {
+  if (hash8.length !== 8) return false;
+  for (const b of hash8) if (b !== 0) return false;
+  return true;
+}
+
+// src/profile.ts
+var PROFILE_KINDS = [
+  "field",
+  "presence",
+  "correction",
+  "write",
+  "churn",
+  "rpc",
+  "message",
+  "voice",
+  "join",
+  "overhead",
+  "control"
+];
+var EMPTY_PROFILE = {
+  rows: [],
+  bytesIn: 0,
+  bytesOut: 0,
+  framesIn: 0,
+  framesOut: 0,
+  walks: 0
+};
+var CONTROL_KEYS = {
+  [FrameType.HELLO]: "hello",
+  [FrameType.WELCOME]: "welcome",
+  [FrameType.ERROR]: "error",
+  [FrameType.PING]: "ping",
+  [FrameType.PONG]: "pong",
+  [FrameType.LEAVE]: "leave",
+  [FrameType.SCHEMA]: "schema"
+};
+var MSG_KEYS = ["all", "client", "role", "server"];
+var PENDING_CALLS_MAX = 512;
+var ProfileLedger = class {
+  rows = /* @__PURE__ */ new Map();
+  memo = /* @__PURE__ */ new Map();
+  /** Peer and reqId to the rpc name its CALL carried, so the matching REPLY can be named too. */
+  pending = /* @__PURE__ */ new Map();
+  scratch = [];
+  bytesIn = 0;
+  bytesOut = 0;
+  framesIn = 0;
+  framesOut = 0;
+  walkCount = 0;
+  rpcSchema;
+  /**
+   * `schema` is the runtime-extended schema (`withBuiltins`), which is what delta and snapshot
+   * bodies are encoded against. `rpcSchema` is the one whose `rpcTable` the `rpcId` on the wire
+   * indexes; the two tables agree today (extending adds a collection, not an rpc), but the
+   * senders name them separately and so does this.
+   */
+  schema;
+  constructor(schema, rpcSchema) {
+    this.schema = schema;
+    this.rpcSchema = rpcSchema ?? schema;
+  }
+  /**
+   * D50: a session whose schema was swapped mid-flight keeps its ledger and its accumulated rows.
+   * Rows named after a field the new schema dropped simply stop growing, which is the honest
+   * reading — those bytes really were spent.
+   */
+  swapSchema(schema, rpcSchema) {
+    this.schema = schema;
+    this.rpcSchema = rpcSchema ?? schema;
+    this.memo.clear();
+  }
+  get walks() {
+    return this.walkCount;
+  }
+  /** Drops the shared-payload memo. Call at the top of each flush. */
+  newFlush() {
+    if (this.memo.size > 0) this.memo.clear();
+  }
+  reset() {
+    this.rows.clear();
+    this.memo.clear();
+    this.pending.clear();
+    this.bytesIn = 0;
+    this.bytesOut = 0;
+    this.framesIn = 0;
+    this.framesOut = 0;
+    this.walkCount = 0;
+  }
+  snapshot() {
+    const rows = [];
+    for (const kind of PROFILE_KINDS) {
+      const byKey = this.rows.get(kind);
+      if (!byKey) continue;
+      for (const [key, v] of byKey) rows.push({ kind, key, out: v.out, in: v.in });
+    }
+    rows.sort((a, b) => b.out + b.in - (a.out + a.in) || (a.key < b.key ? -1 : 1));
+    return {
+      rows,
+      bytesIn: this.bytesIn,
+      bytesOut: this.bytesOut,
+      framesIn: this.framesIn,
+      framesOut: this.framesOut,
+      walks: this.walkCount
+    };
+  }
+  /**
+   * Attributes one whole frame, envelope byte included. Never throws: a frame this ledger cannot
+   * read still contributes its full length, to `overhead/unattributed`.
+   */
+  attribute(dir, frame, options) {
+    if (dir === "in") {
+      this.framesIn++;
+      this.bytesIn += frame.length;
+    } else {
+      this.framesOut++;
+      this.bytesOut += frame.length;
+    }
+    const shared = options?.shared;
+    if (shared !== void 0) {
+      const cached = this.memo.get(shared);
+      if (cached) {
+        this.commit(dir, cached);
+        return;
+      }
+    }
+    const entries = shared !== void 0 ? [] : this.scratch;
+    entries.length = 0;
+    this.walkCount++;
+    this.describe(frame, entries, options);
+    const total = sum(entries);
+    if (total !== frame.length) {
+      entries.push({
+        kind: "overhead",
+        key: "unattributed",
+        bytes: frame.length - total
+      });
+    }
+    if (shared !== void 0) this.memo.set(shared, entries);
+    this.commit(dir, entries);
+  }
+  /**
+   * Attributes bare snapshot bytes under `join`. The room worker needs this: it hands the host
+   * snapshot bytes and the host wraps them in a `WELCOME`, so the room never sees that frame,
+   * but the bytes are still the room's egress and the join rows are the reason anyone profiles a
+   * join at all. A client, which does see the whole frame, uses `attribute` instead.
+   */
+  attributeSnapshot(dir, bytes) {
+    if (dir === "in") {
+      this.bytesIn += bytes.length;
+    } else {
+      this.bytesOut += bytes.length;
+    }
+    const entries = [];
+    this.walkCount++;
+    try {
+      this.snapshotBody(bytes, entries);
+    } catch {
+      entries.length = 0;
+    }
+    const total = sum(entries);
+    if (total !== bytes.length) {
+      entries.push({ kind: "overhead", key: "unattributed", bytes: bytes.length - total });
+    }
+    this.commit(dir, entries);
+  }
+  // -------------------------------------------------------------------------
+  commit(dir, entries) {
+    for (const e of entries) {
+      if (e.bytes === 0) continue;
+      let byKey = this.rows.get(e.kind);
+      if (!byKey) {
+        byKey = /* @__PURE__ */ new Map();
+        this.rows.set(e.kind, byKey);
+      }
+      let row = byKey.get(e.key);
+      if (!row) {
+        row = { out: 0, in: 0 };
+        byKey.set(e.key, row);
+      }
+      if (dir === "in") row.in += e.bytes;
+      else row.out += e.bytes;
+    }
+  }
+  describe(frame, out, options) {
+    if (frame.length === 0) return;
+    out.push({ kind: "overhead", key: "envelope", bytes: 1 });
+    const type = frame[0];
+    const payload = frame.subarray(1);
+    try {
+      switch (type) {
+        case FrameType.DELTA:
+          this.body(payload, out, "field", options?.churn, options?.spatialChurn === true);
+          return;
+        case FrameType.WRITE:
+          this.body(payload, out, "write", void 0);
+          return;
+        case FrameType.CORRECT: {
+          const r = new ByteReader3(payload);
+          this.body(r, out, "correction", void 0);
+          const tail = payload.length - r.pos;
+          if (tail > 0) out.push({ kind: "correction", key: "tail", bytes: tail });
+          return;
+        }
+        case FrameType.CALL: {
+          const r = new ByteReader3(payload);
+          const reqId = r.u32();
+          const rpcId = r.u16();
+          const name = this.rpcName(rpcId);
+          this.remember(options?.peer, reqId, name);
+          out.push({ kind: "rpc", key: name, bytes: payload.length });
+          return;
+        }
+        case FrameType.REPLY: {
+          const r = new ByteReader3(payload);
+          const reqId = r.u32();
+          out.push({ kind: "rpc", key: this.recall(options?.peer, reqId), bytes: payload.length });
+          return;
+        }
+        case FrameType.MSG: {
+          const kind = payload[0];
+          if (kind === 4) out.push({ kind: "voice", key: "signal", bytes: payload.length });
+          else if (kind !== void 0 && kind < MSG_KEYS.length) {
+            out.push({ kind: "message", key: MSG_KEYS[kind], bytes: payload.length });
+          }
+          return;
+        }
+        case FrameType.WELCOME:
+          this.welcome(payload, out);
+          return;
+        default: {
+          const key = CONTROL_KEYS[type];
+          if (key !== void 0) out.push({ kind: "control", key, bytes: payload.length });
+          return;
+        }
+      }
+    } catch {
+    }
+  }
+  /** WELCOME: the snapshot inside it is `join`; everything around it is `control/welcome`. */
+  welcome(payload, out) {
+    const r = new ByteReader3(payload);
+    skipStr(r);
+    skipStr(r);
+    r.u32();
+    const len = r.varint();
+    const before = r.pos;
+    if (r.remaining < len) throw new Error("welcome: short snapshot");
+    const consumed = this.snapshotBody(payload.subarray(before, before + len), out);
+    out.push({ kind: "control", key: "welcome", bytes: payload.length - consumed });
+  }
+  snapshotBody(bytes, out) {
+    const collect = this.collector(out, "join", "join", "header", void 0);
+    return walkSnapshot(this.schema, bytes, collect);
+  }
+  body(bytes, out, fieldKind, churn, spatialChurn = false) {
+    const collect = this.collector(out, fieldKind, "overhead", "delta-header", churn, spatialChurn);
+    walkDelta(this.schema, bytes, collect);
+  }
+  /**
+   * The walker's consumer. `op` latches: a churn op routes its own framing *and* every field
+   * that follows it into `churn`, because a synthetic add carries a whole record whose bytes are
+   * the cost of the entity crossing the boundary, not the cost of the fields changing.
+   */
+  collector(out, fieldKind, overheadKind, headerKey, churn, spatialChurn = false) {
+    let churnCollection;
+    return {
+      header: (bytes) => {
+        out.push({ kind: overheadKind, key: headerKey, bytes });
+      },
+      op: (c, kind, id, bytes) => {
+        const isChurn = kind !== "update" && (spatialChurn ? c.visibility === "spatial-grid" : churn !== void 0 && churn.get(c.name)?.has(id) === true);
+        churnCollection = isChurn ? c.name : void 0;
+        out.push(
+          churnCollection !== void 0 ? { kind: "churn", key: c.name, bytes } : { kind: overheadKind, key: overheadKind === "join" ? headerKey : "op", bytes }
+        );
+      },
+      field: (c, f, bytes) => {
+        if (churnCollection !== void 0) {
+          out.push({ kind: "churn", key: churnCollection, bytes });
+          return;
+        }
+        const key = `${c.name}.${f.name}`;
+        out.push({
+          kind: fieldKind === "field" && c.name === PRESENCE_COLLECTION ? "presence" : fieldKind,
+          key,
+          bytes
+        });
+      }
+    };
+  }
+  rpcName(rpcId) {
+    try {
+      return rpcByIdOf(this.rpcSchema, rpcId).name;
+    } catch {
+      return `rpc#${rpcId}`;
+    }
+  }
+  remember(peer, reqId, name) {
+    if (this.pending.size >= PENDING_CALLS_MAX) this.pending.clear();
+    this.pending.set(`${peer ?? ""}\0${reqId}`, name);
+  }
+  recall(peer, reqId) {
+    const k = `${peer ?? ""}\0${reqId}`;
+    const name = this.pending.get(k);
+    if (name === void 0) return "(unmatched reply)";
+    this.pending.delete(k);
+    return name;
+  }
+};
+function sum(entries) {
+  let n = 0;
+  for (const e of entries) n += e.bytes;
+  return n;
+}
+function skipStr(r) {
+  const n = r.varint();
+  if (r.remaining < n) throw new Error("unexpected end of buffer");
+  r.pos += n;
+}
+function diffProfiles(prev, next) {
+  const before = /* @__PURE__ */ new Map();
+  for (const r of prev.rows) before.set(`${r.kind} ${r.key}`, r);
+  const rows = [];
+  for (const r of next.rows) {
+    const b = before.get(`${r.kind} ${r.key}`);
+    const out = r.out - (b?.out ?? 0);
+    const inb = r.in - (b?.in ?? 0);
+    if (out !== 0 || inb !== 0) rows.push({ kind: r.kind, key: r.key, out, in: inb });
+  }
+  rows.sort((a, b) => b.out + b.in - (a.out + a.in) || (a.key < b.key ? -1 : 1));
+  return {
+    rows,
+    bytesIn: next.bytesIn - prev.bytesIn,
+    bytesOut: next.bytesOut - prev.bytesOut,
+    framesIn: next.framesIn - prev.framesIn,
+    framesOut: next.framesOut - prev.framesOut,
+    walks: next.walks - prev.walks
+  };
+}
+function topProfileRows(snap, n) {
+  return [...snap.rows].sort((a, b) => b.out + b.in - (a.out + a.in)).slice(0, n);
+}
+function scaleProfile(snap, n) {
+  if (n <= 1) return snap;
+  return {
+    rows: snap.rows.map((r) => ({ kind: r.kind, key: r.key, out: r.out / n, in: r.in / n })),
+    bytesIn: snap.bytesIn / n,
+    bytesOut: snap.bytesOut / n,
+    framesIn: snap.framesIn / n,
+    framesOut: snap.framesOut / n,
+    walks: snap.walks
+  };
+}
+function mergeProfiles(a, b) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const r of [...a.rows, ...b.rows]) {
+    const k = `${r.kind} ${r.key}`;
+    const row = byKey.get(k);
+    if (row) {
+      row.out += r.out;
+      row.in += r.in;
+    } else byKey.set(k, { kind: r.kind, key: r.key, out: r.out, in: r.in });
+  }
+  const rows = [...byKey.values()].sort(
+    (x, y) => y.out + y.in - (x.out + x.in) || (x.key < y.key ? -1 : 1)
+  );
+  return {
+    rows,
+    bytesIn: a.bytesIn + b.bytesIn,
+    bytesOut: a.bytesOut + b.bytesOut,
+    framesIn: a.framesIn + b.framesIn,
+    framesOut: a.framesOut + b.framesOut,
+    walks: a.walks + b.walks
+  };
+}
+
 // src/msg.ts
-import { ByteReader as ByteReader3, ByteWriter as ByteWriter3 } from "@irtio/schema";
+import { ByteReader as ByteReader4, ByteWriter as ByteWriter3 } from "@irtio/schema";
 var MSG_KIND_ALL = 0;
 var MSG_KIND_CLIENT = 1;
 var MSG_KIND_ROLE = 2;
 var MSG_KIND_SERVER = 3;
+var MSG_KIND_VOICE = 4;
+function isVoiceMsg(payload) {
+  return payload.length > 0 && payload[0] === MSG_KIND_VOICE;
+}
 function encodeMsg(m) {
   const w = new ByteWriter3();
   switch (m.target.kind) {
@@ -346,12 +848,15 @@ function encodeMsg(m) {
     case "server":
       w.u8(MSG_KIND_SERVER);
       break;
+    case "voice":
+      w.u8(MSG_KIND_VOICE);
+      break;
   }
   w.bytes(m.payload);
   return w.finish();
 }
 function decodeMsg(bytes) {
-  const r = new ByteReader3(bytes);
+  const r = new ByteReader4(bytes);
   const kind = r.u8();
   let target;
   switch (kind) {
@@ -367,6 +872,9 @@ function decodeMsg(bytes) {
     case MSG_KIND_SERVER:
       target = { kind: "server" };
       break;
+    case MSG_KIND_VOICE:
+      target = { kind: "voice" };
+      break;
     default:
       throw new Error(`decodeMsg: unknown target discriminator ${kind}`);
   }
@@ -374,36 +882,316 @@ function decodeMsg(bytes) {
   return { target, payload };
 }
 
-// src/presence.ts
-import { bool as bool2, defineSchema, entity, str as str2 } from "@irtio/schema";
-var presenceEntity = entity(
-  { clientId: str2(32), role: str2(32), name: str2(32), connected: bool2 },
-  { serverOwned: true }
-);
-var PRESENCE_COLLECTION = "clients";
-var extended = /* @__PURE__ */ new WeakMap();
-function withBuiltins(schema) {
-  let ext = extended.get(schema);
-  if (!ext) {
-    ext = defineSchema(
-      { ...schema.defs, [PRESENCE_COLLECTION]: presenceEntity },
-      {
-        rpc: schema.rpc,
-        roles: schema.roles,
-        ...schema.project !== void 0 ? { project: schema.project } : {},
-        allowReservedNames: true
-      }
-    );
-    extended.set(schema, ext);
+// src/voice.ts
+var ENC = new TextEncoder();
+var DEC = new TextDecoder();
+function encodeVoiceMessage(m) {
+  return ENC.encode(JSON.stringify(m));
+}
+function decodeVoiceMessage(bytes) {
+  try {
+    const parsed = JSON.parse(DEC.decode(bytes));
+    if (parsed === null || typeof parsed !== "object") return void 0;
+    if (typeof parsed.t !== "string") return void 0;
+    return parsed;
+  } catch {
+    return void 0;
   }
-  return ext;
 }
-var relaySchema = withBuiltins(defineSchema({}));
-var RELAY_HASH8 = new Uint8Array(8);
-function isRelayHash8(hash8) {
-  if (hash8.length !== 8) return false;
-  for (const b of hash8) if (b !== 0) return false;
-  return true;
+
+// src/codes.ts
+var CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+var ROOM_TYPE_DELIMITER = ":";
+var ROOM_TYPE_RE = /^[a-z0-9][a-z0-9_-]{0,23}$/;
+var ROOM_ID_RE = /^(?:[a-z0-9][a-z0-9_-]{0,23}:)?[A-Za-z0-9_-]{1,32}$/;
+var DEFAULT_ROOM_TYPE = "default";
+function parseRoomId(raw) {
+  if (!ROOM_ID_RE.test(raw)) return void 0;
+  const at = raw.indexOf(ROOM_TYPE_DELIMITER);
+  if (at < 0) return { type: void 0, id: raw };
+  return { type: raw.slice(0, at), id: raw.slice(at + 1) };
+}
+function formatRoomId(type, id) {
+  return type === void 0 ? id : `${type}${ROOM_TYPE_DELIMITER}${id}`;
+}
+var MATCH_CODE_LENGTH = 10;
+
+// src/bus.ts
+var BUS_LIMITS = {
+  /**
+   * Max UTF-8 bytes in one payload, for both verbs.
+   *
+   * 4 KiB is a quarter of the KV value limit, and it is sized for what the feature is for: a
+   * match-ready notice, an invite, a bracket announcement — an id, a couple of names, a reason.
+   * A payload is also a *store* cost for `send`, because a mailbox entry persists in the alarm
+   * sidecar, so the ceiling on one room's mailbox is this times `mailboxDepth`, and both numbers
+   * were picked together.
+   */
+  payloadBytes: 4 * 1024,
+  /** Max UTF-8 bytes in a channel name. Names are vocabulary, not data. */
+  channelBytes: 128,
+  /** Max channels one room may hold a subscription to at once. */
+  subscriptionsPerRoom: 32,
+  /**
+   * Max undelivered mailbox entries for one target room.
+   *
+   * This is a store bound as much as a memory one: entries live in the alarm sidecar, so at the
+   * payload cap above, a full mailbox is 256 KiB of persisted object. Past this, a `send` is
+   * refused at the sender with a named error rather than silently dropped at the target, because
+   * a sender that is outrunning a receiver is a fact the sender can act on.
+   */
+  mailboxDepth: 64,
+  /**
+   * How many times one mailbox entry may be delivered before it is dead-lettered.
+   *
+   * The bound exists because at-least-once and the room crash threshold compose badly on purpose.
+   * A handler that always throws surfaces as a crash, and the supervisor's window is 3 restarts in
+   * 60 seconds; an entry that re-armed forever would close the room in four deliveries, on every
+   * wake, for as long as the entry existed. Five attempts is enough to ride out a transient (a
+   * deploy mid-flight, a wake that raced a hibernate) and few enough that a genuinely poisonous
+   * message costs a room one bad minute rather than its life. What happens then is a log line and
+   * a drop: honest for v1, and the docs say so rather than implying a dead-letter queue exists.
+   */
+  maxDeliveryAttempts: 5,
+  /**
+   * Bus operations one room may issue per second, averaged, and the burst it may take at once.
+   *
+   * This is the "one hot room cannot melt the supervisor" guardrail D59 asks for. It counts both
+   * verbs together, because both cost the supervisor a fan-out or a store write, and a limiter
+   * that only counted the cheap one would be a limiter a room could route around.
+   */
+  opsPerSecond: 50,
+  opsBurst: 100,
+  /**
+   * How long a delivered-but-unacknowledged mailbox entry stays armed before it is delivered
+   * again. A visibility timeout, and it is what makes at-least-once actually true rather than
+   * nearly true.
+   *
+   * Posting a message to a worker is not the same as the worker running it: a room that dies
+   * between the post and the handler (a crash, a restart, a hibernate that raced the delivery)
+   * would otherwise lose the message with no trace, which is at-most-once wearing at-least-once's
+   * name. So an entry is re-armed for this long at the moment it is posted, and cleared only when
+   * the worker says the handler ran. 30 seconds is far longer than a handler takes and short
+   * enough that a genuinely lost delivery is retried while anyone still cares.
+   */
+  redeliveryDelayMs: 3e4
+};
+var BUS_CHANNEL_RE = /^[a-z0-9][a-z0-9._-]{0,127}$/;
+var BUS_ERRORS = {
+  badChannel: "E_BUS_BAD_CHANNEL",
+  payloadTooLarge: "E_BUS_PAYLOAD_TOO_LARGE",
+  tooManySubscriptions: "E_BUS_TOO_MANY_SUBSCRIPTIONS",
+  /** The named room does not exist in this tenant, or is a relay room and runs no handlers. */
+  noSuchRoom: "E_BUS_NO_SUCH_ROOM",
+  mailboxFull: "E_BUS_MAILBOX_FULL",
+  rateLimited: "E_BUS_RATE_LIMITED"
+};
+function utf8Bytes(s) {
+  return new TextEncoder().encode(s).length;
+}
+function busChannelProblem(channel) {
+  if (typeof channel !== "string" || channel === "") {
+    return { code: BUS_ERRORS.badChannel, message: "a channel name is required" };
+  }
+  if (utf8Bytes(channel) > BUS_LIMITS.channelBytes) {
+    return {
+      code: BUS_ERRORS.badChannel,
+      message: `channel name is longer than ${BUS_LIMITS.channelBytes} bytes`
+    };
+  }
+  if (!BUS_CHANNEL_RE.test(channel)) {
+    return {
+      code: BUS_ERRORS.badChannel,
+      message: `illegal channel name ${JSON.stringify(channel)}: lowercase, starts alphanumeric, and made of letters, digits, dots, underscores and dashes`
+    };
+  }
+  return void 0;
+}
+function busPayloadProblem(payload) {
+  if (typeof payload !== "string") {
+    return {
+      code: BUS_ERRORS.payloadTooLarge,
+      message: "a bus payload must be a string (serialise your own object)"
+    };
+  }
+  const bytes = utf8Bytes(payload);
+  if (bytes > BUS_LIMITS.payloadBytes) {
+    return {
+      code: BUS_ERRORS.payloadTooLarge,
+      message: `payload is ${bytes} bytes; the limit is ${BUS_LIMITS.payloadBytes}`
+    };
+  }
+  return void 0;
+}
+var BUS_MAILBOX_PREFIX = "__bus.";
+function isMailboxAlarm(name) {
+  return name.startsWith(BUS_MAILBOX_PREFIX);
+}
+var BUS_OUTBOX_PREFIX = "__busout.";
+function isOutboxAlarm(name) {
+  return name.startsWith(BUS_OUTBOX_PREFIX);
+}
+var BUS_OUTBOX = {
+  firstRetryMs: 1e3,
+  maxRetryMs: 6e4,
+  ttlMs: 60 * 60 * 1e3
+};
+var BUS_SHARD_STARTING = "E_SHARD_STARTING";
+
+// src/classes.ts
+var ROOM_MEMORY_MB_MIN = 32;
+var ROOM_MEMORY_MB_MAX = 1024;
+var ROOM_CLASS_MAX_MB = {
+  small: 64,
+  medium: 256,
+  large: ROOM_MEMORY_MB_MAX
+};
+function roomClassFor(memoryMb) {
+  if (memoryMb === void 0 || !Number.isFinite(memoryMb)) return "small";
+  if (memoryMb <= ROOM_CLASS_MAX_MB.small) return "small";
+  if (memoryMb <= ROOM_CLASS_MAX_MB.medium) return "medium";
+  return "large";
+}
+function roomHoursSourceFor(cls) {
+  return cls === "small" ? "room" : cls;
+}
+function roomClassOfSource(source) {
+  if (source === "room") return "small";
+  if (source === "medium" || source === "large") return source;
+  return void 0;
+}
+
+// src/sizing.ts
+var VM_MEM_MIB_MIN = 128;
+var VM_MEM_MIB_MAX = 4096;
+var SUPERVISOR_BASELINE_MIB = 54;
+var NATIVE_RESERVE_FRACTION = 8;
+var PHYSICS_HEADROOM_MIB = 112;
+var YOUNG_GEN_MB = 32;
+var DEFAULT_MEMORY_MB = 32;
+var DEFAULT_MAX_AWAKE = 1;
+var MAX_AWAKE_MAX = 256;
+function nativeReserveOf(vmMib) {
+  return Math.floor(vmMib / NATIVE_RESERVE_FRACTION);
+}
+function typeFootprintMib(type) {
+  const memoryMb = normalizeMemoryMb(type.memoryMb);
+  const maxAwake = normalizeMaxAwake(type.maxAwake);
+  return (memoryMb + YOUNG_GEN_MB) * maxAwake;
+}
+function normalizeMemoryMb(value) {
+  if (value === void 0 || !Number.isFinite(value) || value <= 0) return DEFAULT_MEMORY_MB;
+  return Math.floor(value);
+}
+function normalizeMaxAwake(value) {
+  if (value === void 0 || !Number.isFinite(value) || value <= 0) return DEFAULT_MAX_AWAKE;
+  return Math.min(MAX_AWAKE_MAX, Math.floor(value));
+}
+function vmSizeFor(types, options = {}) {
+  const baselineMib = options.baselineMib ?? SUPERVISOR_BASELINE_MIB;
+  let workersMib = 0;
+  let anyPhysics = false;
+  for (const type of types) {
+    workersMib += typeFootprintMib(type);
+    if (type.physics === true) anyPhysics = true;
+  }
+  const physicsHeadroomMib = anyPhysics ? PHYSICS_HEADROOM_MIB : 0;
+  const preReserveMib = workersMib + baselineMib + physicsHeadroomMib;
+  const unclamped = Math.ceil(
+    preReserveMib * NATIVE_RESERVE_FRACTION / (NATIVE_RESERVE_FRACTION - 1)
+  );
+  const vmMib = Math.min(VM_MEM_MIB_MAX, Math.max(VM_MEM_MIB_MIN, unclamped));
+  const clamped = unclamped < VM_MEM_MIB_MIN ? "floor" : unclamped > VM_MEM_MIB_MAX ? "ceiling" : void 0;
+  const parts = types.map(
+    (t) => `${t.type} ${normalizeMemoryMb(t.memoryMb)}+${YOUNG_GEN_MB} MB x ${normalizeMaxAwake(t.maxAwake)}`
+  ).join(", ");
+  const detail = `${vmMib} MiB from ${parts || "no room types"}, supervisor baseline ${baselineMib} MiB` + (physicsHeadroomMib > 0 ? `, physics headroom ${physicsHeadroomMib} MiB` : "") + `, native reserve ${vmMib - preReserveMib} MiB` + (clamped === "floor" ? ` (raised to the ${VM_MEM_MIB_MIN} MiB floor)` : clamped === "ceiling" ? ` (lowered to the ${VM_MEM_MIB_MAX} MiB ceiling)` : "");
+  return {
+    vmMib,
+    workersMib,
+    baselineMib,
+    physicsHeadroomMib,
+    preReserveMib,
+    nativeReserveMib: vmMib - preReserveMib,
+    ...clamped !== void 0 ? { clamped } : {},
+    detail
+  };
+}
+var ROOMS_PER_VCPU = {
+  small: 20,
+  medium: 8,
+  large: 5
+};
+var CPU_QUOTA_PCT_MIN = 10;
+var CPU_QUOTA_PCT_MAX = 100;
+function vmCpuFor(types) {
+  if (types.length === 0) {
+    return {
+      quotaPct: CPU_QUOTA_PCT_MAX,
+      rawPct: CPU_QUOTA_PCT_MAX,
+      undeclared: true,
+      detail: "no room types declared, so no CPU throttle"
+    };
+  }
+  const declared = types.some(
+    (t) => t.memoryMb !== void 0 || t.maxAwake !== void 0 && t.maxAwake > 0
+  );
+  if (!declared) {
+    return {
+      quotaPct: CPU_QUOTA_PCT_MAX,
+      rawPct: CPU_QUOTA_PCT_MAX,
+      undeclared: true,
+      detail: `${types.length} room type(s), none declaring memoryMb or maxAwake, so no CPU throttle`
+    };
+  }
+  let rawPct = 0;
+  const parts = [];
+  for (const type of types) {
+    const cls = roomClassFor(normalizeMemoryMbForClass(type.memoryMb));
+    const maxAwake = normalizeMaxAwake(type.maxAwake);
+    const density = ROOMS_PER_VCPU[cls];
+    const share = maxAwake * CPU_QUOTA_PCT_MAX / density;
+    rawPct += share;
+    parts.push(`${type.type} ${cls} x ${maxAwake} / ${density} per vCPU`);
+  }
+  const rounded = Math.ceil(rawPct);
+  const quotaPct = Math.min(CPU_QUOTA_PCT_MAX, Math.max(CPU_QUOTA_PCT_MIN, rounded));
+  const clamped = rounded < CPU_QUOTA_PCT_MIN ? "floor" : rounded > CPU_QUOTA_PCT_MAX ? "ceiling" : void 0;
+  return {
+    quotaPct,
+    rawPct,
+    undeclared: false,
+    ...clamped !== void 0 ? { clamped } : {},
+    detail: `CPUQuota ${quotaPct}% from ${parts.join(", ")}` + (clamped === "floor" ? ` (raised to the ${CPU_QUOTA_PCT_MIN}% floor)` : clamped === "ceiling" ? ` (lowered to the ${CPU_QUOTA_PCT_MAX}% ceiling from ${rounded}%)` : "")
+  };
+}
+function normalizeMemoryMbForClass(value) {
+  if (value === void 0 || !Number.isFinite(value) || value <= 0) return void 0;
+  return Math.floor(value);
+}
+function declarationsFit(vmMemMib, types, options = {}) {
+  const required = vmSizeFor(types, options);
+  return { fits: required.vmMib <= vmMemMib, required };
+}
+
+// src/retention.ts
+var RETENTION_RE = /^[1-9][0-9]{0,4}(m|h|d)$/;
+var RETENTION_MIN_MS = 6e4;
+var RETENTION_MAX_MS = 3650 * 24 * 60 * 60 * 1e3;
+var UNIT_MS = {
+  m: 6e4,
+  h: 60 * 60 * 1e3,
+  d: 24 * 60 * 60 * 1e3
+};
+function parseRetention(raw) {
+  if (typeof raw !== "string") return void 0;
+  if (!RETENTION_RE.test(raw)) return void 0;
+  const unit = raw.slice(-1);
+  const scale = UNIT_MS[unit];
+  if (scale === void 0) return void 0;
+  const ms = Number(raw.slice(0, -1)) * scale;
+  if (ms < RETENTION_MIN_MS || ms > RETENTION_MAX_MS) return void 0;
+  return ms;
 }
 
 // src/origin.ts
@@ -429,14 +1217,54 @@ function parseOriginList(raw) {
   return raw.split(",").map((o) => o.trim()).filter((o) => o.length > 0);
 }
 export {
+  BUS_CHANNEL_RE,
+  BUS_ERRORS,
+  BUS_LIMITS,
+  BUS_MAILBOX_PREFIX,
+  BUS_OUTBOX,
+  BUS_OUTBOX_PREFIX,
+  BUS_SHARD_STARTING,
+  CLOSE_EGRESS_WALL,
+  CLOSE_TRY_AGAIN_LATER,
+  CODE_ALPHABET,
+  CPU_QUOTA_PCT_MAX,
+  CPU_QUOTA_PCT_MIN,
+  DEFAULT_MAX_AWAKE,
+  DEFAULT_MEMORY_MB,
+  DEFAULT_ROOM_TYPE,
+  EMPTY_PROFILE,
   ERROR_CATALOGUE,
   ErrorCode,
   FrameType,
+  HELLO_SCHEMA_SWAP_BIT,
+  MATCH_CODE_LENGTH,
+  MAX_AWAKE_MAX,
+  NATIVE_RESERVE_FRACTION,
+  PHYSICS_HEADROOM_MIB,
   PRESENCE_COLLECTION,
+  PROFILE_KINDS,
   PROTOCOL_VERSION,
+  ProfileLedger,
   RELAY_HASH8,
+  RETENTION_MAX_MS,
+  RETENTION_MIN_MS,
+  RETENTION_RE,
+  ROOMS_PER_VCPU,
+  ROOM_CLASS_MAX_MB,
+  ROOM_ID_RE,
+  ROOM_MEMORY_MB_MAX,
+  ROOM_MEMORY_MB_MIN,
+  ROOM_TYPE_DELIMITER,
+  ROOM_TYPE_RE,
+  SUPERVISOR_BASELINE_MIB,
+  VM_MEM_MIB_MAX,
+  VM_MEM_MIB_MIN,
+  YOUNG_GEN_MB,
   builtinRpcs,
+  busChannelProblem,
+  busPayloadProblem,
   correctPayload,
+  declarationsFit,
   decodeCall,
   decodeErrorPayload,
   decodeFrame,
@@ -445,8 +1273,10 @@ export {
   decodePing,
   decodePong,
   decodeReply,
+  decodeVoiceMessage,
   decodeWelcome,
   deltaPayload,
+  diffProfiles,
   encodeCall,
   encodeCorrectFrame,
   encodeDeltaFrame,
@@ -457,23 +1287,43 @@ export {
   encodePing,
   encodePong,
   encodeReply,
+  encodeSchemaFrame,
+  encodeVoiceMessage,
   encodeWelcome,
   encodeWriteFrame,
   errorByCode,
   formatError,
+  formatRoomId,
   isFrameType,
   isLocalhostOrigin,
+  isMailboxAlarm,
+  isOutboxAlarm,
   isRelayHash8,
+  isVoiceMsg,
+  mergeProfiles,
+  nativeReserveOf,
   originAllowed,
   parseOriginList,
+  parseRetention,
+  parseRoomId,
   presenceEntity,
   readCorrectAppliedTick,
   readCorrectClientTick,
+  readSchemaPayload,
   relaySchema,
   requestOwnership,
+  roomClassFor,
+  roomClassOfSource,
+  roomHoursSourceFor,
   rpcByIdOf,
   rpcIdOf,
   rpcTable,
+  scaleProfile,
+  schemaPayload,
+  topProfileRows,
+  typeFootprintMib,
+  vmCpuFor,
+  vmSizeFor,
   withBuiltins,
   writePayload
 };