@irtio/protocol 0.5.1 → 0.6.0

package/dist/index.d.ts

@@ -5,8 +5,16 @@ import { ByteReader, RpcMap, ServerRpcs, AnySchema, RpcDesc, InstanceOf, Schema,
  * Frame envelope: one type byte, then an opaque payload. `encodeFrame`/`decodeFrame` only
  * handle the envelope — payload codecs live in `session.ts`, `rpc.ts`, `msg.ts`.
  */
-/** Wire protocol version (u8), bumped on any breaking change to framing or payload shapes. */
-declare const PROTOCOL_VERSION = 1;
+/**
+ * Wire protocol version (u8), bumped on any breaking change to framing or payload shapes.
+ *
+ * 2: `WELCOME`'s tick slot carries the room's tick rate in ticks per second, where version 1
+ * carried the interval in whole milliseconds. The slot kept its width and type, so a version 1
+ * client would read `60` as a 60 ms interval and quietly run a four-times-too-long interpolation
+ * delay and a wrong physics timestep. The bump turns that into `E_PROTOCOL_VERSION` at join,
+ * which is a client bundle that needs redeploying rather than an afternoon of debugging.
+ */
+declare const PROTOCOL_VERSION = 2;
 declare const FrameType: {
     readonly HELLO: 1;
     readonly WELCOME: 2;
@@ -26,6 +34,18 @@ declare const FrameType: {
      * the close to time out into `'timeout'`. Additive — protocol version stays 1.
      */
     readonly 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.
+     */
+    readonly SCHEMA: 13;
 };
 type FrameType = (typeof FrameType)[keyof typeof FrameType];
 interface Frame {
@@ -66,7 +86,7 @@ declare const ErrorCode: {
     };
     readonly E_ROOM_NOT_FOUND: {
         readonly code: 5;
-        readonly message: "room {roomId} not found — room ids are 1-32 of A-Z a-z 0-9 - _";
+        readonly message: "room {roomId} not found. Room ids are 1-32 of A-Z a-z 0-9 - _, optionally behind a lowercase <type>: prefix";
     };
     readonly E_ROOM_FULL: {
         readonly code: 6;
@@ -156,7 +176,96 @@ declare const ErrorCode: {
         readonly code: 27;
         readonly 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.
+     */
+    readonly E_USAGE_CAP: {
+        readonly code: 28;
+        readonly 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.
+     */
+    readonly E_ASSERTION_UNVERIFIABLE: {
+        readonly code: 29;
+        readonly 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.
+     */
+    readonly E_TYPE_AT_CAPACITY: {
+        readonly code: 30;
+        readonly 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.
+     */
+    readonly E_EGRESS_WALL: {
+        readonly code: 31;
+        readonly 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.
+     */
+    readonly E_TIER_LIMIT: {
+        readonly code: 32;
+        readonly 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.
+     */
+    readonly E_PLACEMENT: {
+        readonly code: 33;
+        readonly message: "no capacity in region {region}; add a server or raise maxVms";
+    };
 };
+/**
+ * The WebSocket close code the router uses for {@link ErrorCode.E_PLACEMENT}: RFC 6455's 1013,
+ * "try again later". Distinct from the 1008 policy close and the 1011 internal-error close the
+ * router uses for everything else, so a watcher of close codes can tell a full region from a bug.
+ */
+declare const CLOSE_TRY_AGAIN_LATER = 1013;
+/**
+ * The WebSocket close code for the egress wall (M5 part 3.5, Part C).
+ *
+ * In the application range (4000-4999) and distinct from the `1008` policy close, which is the
+ * whole point: when the wall trips, forwarding stops and sockets close, and a developer has to be
+ * able to tell that apart from a crash, a slow consumer or an origin refusal without reading a log
+ * they may not have. 4290 echoes HTTP 429 for the same reason a person would guess it does.
+ */
+declare const CLOSE_EGRESS_WALL = 4290;
 type ErrorCodeName = keyof typeof ErrorCode;
 interface ErrorCatalogueEntry {
     readonly name: ErrorCodeName;
@@ -192,6 +301,24 @@ type Credential = {
     readonly kind: 'jwt';
     readonly key: string;
     readonly token: string;
+}
+/**
+ * D53: the project key AND a platform identity **assertion** — audience-bound to this project,
+ * expiring in minutes, carrying a per-project pseudonymous subject, and signed asymmetrically
+ * so the guest can verify it but not mint it. Wire tag 3.
+ *
+ * A separate tag rather than a second flavour of `jwt` on purpose. The two are verified by
+ * different code with different key material and different trust: a BYO JWT is signed by the
+ * tenant's own secret (which the guest also holds), an assertion is signed by the platform
+ * (which the guest holds only the public half of). Sharing a tag would mean one verifier
+ * deciding between them from a header claim, which is the algorithm-confusion hole with extra
+ * steps. The player's actual identity credential is never on this wire at all — it is
+ * exchanged with control over HTTPS before the socket opens.
+ */
+ | {
+    readonly kind: 'assertion';
+    readonly key: string;
+    readonly token: string;
 };
 interface Hello {
     readonly protocolVersion: number;
@@ -205,7 +332,23 @@ interface Hello {
     readonly role?: string | undefined;
     /** Display name requested at join. */
     readonly name?: string | undefined;
+    /**
+     * D50: this client can rebuild its codec from a `SCHEMA` frame, so an additive deploy may swap
+     * its schema in place instead of closing the socket with `E_SCHEMA_MISMATCH`. Carried as a bit
+     * in the existing optional-presence mask rather than as an appended field, because `decodeHello`
+     * ends in `assertEof` and every deployed supervisor would reject trailing bytes.
+     *
+     * A capability, not a request: the server still decides, and still drains on a breaking change.
+     * Absent (the default) means today's behaviour exactly, and means the server must never send
+     * this session frame 13 — `decodeFrame` throws on an unknown type.
+     */
+    readonly schemaSwap?: boolean | undefined;
 }
+/**
+ * D50 capability bit. Bits 0-2 each announce an optional *value* that follows the mask; this one
+ * carries no payload, it is a pure flag, so it adds nothing to the encoded length. Bits 4-7 free.
+ */
+declare const HELLO_SCHEMA_SWAP_BIT: number;
 declare function encodeHello(h: Hello): Uint8Array;
 declare function decodeHello(bytes: Uint8Array): Hello;
 interface Welcome {
@@ -223,12 +366,24 @@ interface Welcome {
      */
     readonly roomId: string;
     /**
-     * The room's tick interval in milliseconds (`round(1000 / tickRate)`), or `0` when the sender
-     * does not know it (a relay room, or a pre-week-8 server). The client's interpolation delay
-     * defaults to `max(50, 2 × tickIntervalMs)` (D20). Appended after `roomId` in week 8, same
-     * additive style as `roomId` itself.
+     * The room's tick rate in ticks per second, or `0` when the sender does not know it (a relay
+     * room). The client derives everything it needs in milliseconds from this: the interpolation
+     * delay defaults to `max(50, 2000 / tickRate)` (D20), and a predicted physics world steps at
+     * `1 / tickRate` seconds.
+     *
+     * This slot carried `tickIntervalMs`, `round(1000 / tickRate)`, until `PROTOCOL_VERSION` 2.
+     * Rounding to whole milliseconds is lossy at exactly the rates games use: 60 Hz arrived as 17
+     * and 30 Hz as 33, so a client that inherited its timestep stepped its local world 2% slower
+     * than the server stepped its own, and paid for the drift in corrections. The rate is the
+     * number the room actually configured, and every derived millisecond figure is now exact.
      */
-    readonly tickIntervalMs: number;
+    readonly tickRate: number;
+    /**
+     * The room's configured client cap, or `0` when the sender does not know it (a relay room,
+     * or a server predating this field). Appended after `tickRate`, same additive style as
+     * `tickRate` itself.
+     */
+    readonly maxClients: number;
 }
 declare function encodeWelcome(w0: Welcome): Uint8Array;
 declare function decodeWelcome(bytes: Uint8Array): Welcome;
@@ -282,6 +437,20 @@ declare function readCorrectAppliedTick(r: ByteReader): number | undefined;
 declare function encodeDeltaFrame(codecBytes: Uint8Array): Uint8Array;
 declare function encodeWriteFrame(codecBytes: Uint8Array): Uint8Array;
 declare function encodeCorrectFrame(codecBytes: Uint8Array, clientTick: number, appliedTick?: number): Uint8Array;
+/**
+ * The `SCHEMA` frame payload: the new schema's canonical JSON as UTF-8, exactly the string
+ * `Schema.canonical` produces and `Deployment.schemaJson` already stores. No length prefix and no
+ * envelope — the frame body *is* the descriptor, so `encodeSchemaFrame`/`readSchemaPayload` are a
+ * `TextEncoder`/`TextDecoder` pair and nothing more.
+ *
+ * There is deliberately no new codec here. The largest schema in the repo is 4.3 KB raw and 557
+ * bytes gzipped (M4 part 1 report §8.1), which is not worth a wire format; and reusing the exact
+ * bytes the control plane already stores means the descriptor a client rebuilds from is provably
+ * the one that was deployed, not a re-serialisation of it.
+ */
+declare function schemaPayload(canonical: string): Uint8Array;
+declare function readSchemaPayload(payload: Uint8Array): string;
+declare function encodeSchemaFrame(canonical: string): Uint8Array;
 
 interface Call {
     readonly reqId: number;
@@ -328,6 +497,146 @@ declare function rpcByIdOf(schema: AnySchema, id: number): RpcDesc;
  */
 type ClientCallable<R extends RpcMap> = ServerRpcs<R> & typeof builtinRpcs;
 
+/**
+ * The bandwidth ledger (D65): cumulative bytes per direction, per row, for one room or one
+ * client session.
+ *
+ * The row set below is the product contract — the docs list it, the overlay renders it, and the
+ * CLI prints it — so it is a small closed vocabulary rather than free-form tags. Rates are never
+ * stored here: a reader diffs two snapshots over a window and divides. Cumulative counters
+ * survive a missed poll; a stored rate does not.
+ *
+ * ## Conservation
+ *
+ * For every frame handed to `attribute`, the rows it adds sum to exactly the frame's length,
+ * including the envelope byte. That is structural, not aspirational: the attribution is staged
+ * into a scratch list, and whatever the walker could not account for (a delta encoded against
+ * another schema, a truncated frame, a frame type from a newer peer) is committed to
+ * `overhead/unattributed` rather than dropped. A profiler that quietly loses bytes would be
+ * worse than no profiler, because its shares would look right.
+ */
+
+/**
+ * The closed kind vocabulary. `field` is the steady state; every other kind exists because
+ * lumping it into `field` would hide the thing a reader came to find.
+ */
+type ProfileKind = 'field' | 'presence' | 'correction' | 'write' | 'churn' | 'rpc' | 'message' | 'voice' | 'join' | 'overhead' | 'control';
+declare const PROFILE_KINDS: readonly ProfileKind[];
+interface ProfileRow {
+    readonly kind: ProfileKind;
+    /** `collection.field`, an rpc name, or one of the fixed keys the kind table documents. */
+    readonly key: string;
+    /** Cumulative bytes sent to the peer. */
+    readonly out: number;
+    /** Cumulative bytes received from the peer. */
+    readonly in: number;
+}
+/** A ledger, flattened for transport (the worker `stats` reply, `state.json`, the overlay). */
+interface ProfileSnapshot {
+    readonly rows: readonly ProfileRow[];
+    readonly bytesIn: number;
+    readonly bytesOut: number;
+    readonly framesIn: number;
+    readonly framesOut: number;
+    /**
+     * How many frames the walker actually read. Lower than `framesOut` exactly when a payload was
+     * shared by several recipients: the bytes count once per recipient (that is what left the box)
+     * but the walk happens once per encode. The adversarial tests read this.
+     */
+    readonly walks: number;
+}
+declare const EMPTY_PROFILE: ProfileSnapshot;
+/** AOI enter/leave ids for one client's frame, by collection. */
+type ChurnIds = ReadonlyMap<string, ReadonlySet<string>>;
+interface AttributeOptions {
+    /**
+     * Ids whose whole `add`/`remove` op is visibility churn rather than a real spawn or despawn.
+     * Server-side only: only the encoder knows which ops the global dirty set never contained.
+     */
+    readonly churn?: ChurnIds | undefined;
+    /**
+     * The shared payload object this frame was built from. Frames built from the same payload in
+     * one flush are walked once and replayed per recipient. Cleared by `newFlush()`.
+     */
+    readonly shared?: object | undefined;
+    /** Correlation scope for matching a REPLY back to its CALL's name. A client id, usually. */
+    readonly peer?: string | undefined;
+    /**
+     * The client's approximation of churn: every `add`/`remove` in a `spatial-grid` collection is
+     * counted as visibility churn, because a decoder genuinely cannot tell a synthetic add from a
+     * real spawn — they are the same bytes. Surfaces that use it must say so; the overlay labels
+     * the row `enter/leave (incl. spawns)`.
+     */
+    readonly spatialChurn?: boolean | undefined;
+}
+declare class ProfileLedger {
+    private readonly rows;
+    private readonly memo;
+    /** Peer and reqId to the rpc name its CALL carried, so the matching REPLY can be named too. */
+    private readonly pending;
+    private scratch;
+    private bytesIn;
+    private bytesOut;
+    private framesIn;
+    private framesOut;
+    private walkCount;
+    private 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.
+     */
+    private schema;
+    constructor(schema: AnySchema, rpcSchema?: AnySchema);
+    /**
+     * 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: AnySchema, rpcSchema?: AnySchema): void;
+    get walks(): number;
+    /** Drops the shared-payload memo. Call at the top of each flush. */
+    newFlush(): void;
+    reset(): void;
+    snapshot(): ProfileSnapshot;
+    /**
+     * 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: 'in' | 'out', frame: Uint8Array, options?: AttributeOptions): void;
+    /**
+     * 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: 'in' | 'out', bytes: Uint8Array): void;
+    private commit;
+    private describe;
+    /** WELCOME: the snapshot inside it is `join`; everything around it is `control/welcome`. */
+    private welcome;
+    private snapshotBody;
+    private body;
+    /**
+     * 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.
+     */
+    private collector;
+    private rpcName;
+    private remember;
+    private recall;
+}
+/** `next` minus `prev`, row by row. Rows that did not move are dropped. */
+declare function diffProfiles(prev: ProfileSnapshot, next: ProfileSnapshot): ProfileSnapshot;
+/** The `n` heaviest rows, by out + in. */
+declare function topProfileRows(snap: ProfileSnapshot, n: number): readonly ProfileRow[];
+/** Divides every counter by `n`, for the per-bot convention `simulate` already prints. */
+declare function scaleProfile(snap: ProfileSnapshot, n: number): ProfileSnapshot;
+/** Adds `b` into `a`, row by row. Used to roll several sessions into one table. */
+declare function mergeProfiles(a: ProfileSnapshot, b: ProfileSnapshot): ProfileSnapshot;
+
 /**
  * MSG frame payload: an out-of-band message with an addressing discriminator. The same
  * shape is reused in both directions — client→server as the send *target*, server→client as
@@ -343,15 +652,130 @@ type MsgTarget = {
     readonly role: string;
 } | {
     readonly kind: 'server';
+} | {
+    readonly kind: 'voice';
 };
 interface Msg {
     readonly target: MsgTarget;
     /** Rest-of-buffer: opaque application payload. */
     readonly payload: Uint8Array;
 }
+/**
+ * A one-byte peek: is this MSG payload voice signaling? The supervisor calls this on every MSG
+ * before deciding where the frame goes, so it must not allocate or decode. An empty payload is
+ * not voice (it is malformed, and the existing paths report that).
+ */
+declare function isVoiceMsg(payload: Uint8Array): boolean;
 declare function encodeMsg(m: Msg): Uint8Array;
 declare function decodeMsg(bytes: Uint8Array): Msg;
 
+/**
+ * D51 voice signaling — the message set that rides inside a `{ kind: 'voice' }` MSG.
+ *
+ * Two deliberate choices worth stating, because both are cheap to reverse later and expensive to
+ * get wrong now.
+ *
+ * **JSON, not the binary schema codec.** Every other payload on this socket is binary because it
+ * is on the tick path and its shape is fixed. Signaling is neither: a handful of messages per
+ * participant per call, carrying mediasoup's own RTP capability and DTLS parameter objects, whose
+ * shape is defined by mediasoup rather than by us. Re-encoding those into a hand-rolled binary
+ * format would buy nothing and would have to be revised every time mediasoup adds a field. The
+ * volume is a few kilobytes per join, once.
+ *
+ * **Everything here is per-project at most.** The blast radius note the docs repeat: transport
+ * parameters, ICE candidates and DTLS fingerprints are secrets about one call in one project's
+ * room. A tenant is assumed hostile and a hostile tenant can already do anything it likes to its
+ * own game — the same stance as BYO JWT signing keys. No platform credential, no agent token and
+ * no other project's identifier is representable in any message below, and the SFU never holds a
+ * credential of any kind for anything to leak (fact 5, and bug #27's lesson).
+ */
+/** Client → SFU. */
+type VoiceClientMessage = {
+    readonly t: 'join';
+    readonly rtpCapabilities: unknown;
+} | {
+    readonly t: 'connect';
+    readonly transportId: string;
+    readonly dtlsParameters: unknown;
+} | {
+    readonly t: 'produce';
+    readonly transportId: string;
+    readonly kind: 'audio';
+    readonly rtpParameters: unknown;
+} | {
+    readonly t: 'consume';
+    readonly producerId: string;
+    readonly rtpCapabilities: unknown;
+} | {
+    readonly t: 'resume';
+    readonly consumerId: string;
+}
+/**
+ * Mute is signalled, not merely stopped locally, because the meter depends on it: an SFU that
+ * only sees a silent stream cannot tell a muted participant from a quiet room, and §1.3 makes
+ * mute the boundary between minutes (which keep accruing) and egress (which stops).
+ */
+ | {
+    readonly t: 'mute';
+    readonly muted: boolean;
+} | {
+    readonly t: 'leave';
+};
+/** SFU → client. */
+type VoiceServerMessage = {
+    readonly t: 'joined';
+    readonly sendTransport: VoiceTransportInfo;
+    readonly recvTransport: VoiceTransportInfo;
+    readonly routerRtpCapabilities: unknown;
+    readonly peers: readonly VoicePeer[];
+} | {
+    readonly t: 'produced';
+    readonly producerId: string;
+} | {
+    readonly t: 'consumed';
+    readonly consumerId: string;
+    readonly producerId: string;
+    readonly peerId: string;
+    readonly kind: 'audio';
+    readonly rtpParameters: unknown;
+} | {
+    readonly t: 'connected';
+    readonly transportId: string;
+} | {
+    readonly t: 'peer-joined';
+    readonly peer: VoicePeer;
+} | {
+    readonly t: 'peer-left';
+    readonly peerId: string;
+} | {
+    readonly t: 'peer-muted';
+    readonly peerId: string;
+    readonly muted: boolean;
+} | {
+    readonly t: 'error';
+    readonly code: string;
+    readonly message: string;
+};
+interface VoiceTransportInfo {
+    readonly id: string;
+    readonly iceParameters: unknown;
+    readonly iceCandidates: unknown;
+    readonly dtlsParameters: unknown;
+}
+interface VoicePeer {
+    /** The room's client id — the same identifier the render store keys entities' owners by. */
+    readonly peerId: string;
+    readonly producerId?: string;
+    readonly muted: boolean;
+}
+declare function encodeVoiceMessage(m: VoiceClientMessage | VoiceServerMessage): Uint8Array;
+/**
+ * Returns `undefined` rather than throwing on anything malformed. This is parsing bytes that
+ * arrived over a socket from an untrusted peer; the callers all want "ignore it", and a throw on
+ * the supervisor's frame path would be a denial of service with extra steps.
+ */
+declare function decodeVoiceMessage<T extends VoiceClientMessage | VoiceServerMessage>(bytes: Uint8Array): T | undefined;
+
 declare const presenceEntity: _irtio_schema.EntityDef<{
     clientId: _irtio_schema.Type<string, false>;
     role: _irtio_schema.Type<string, false>;
@@ -384,6 +808,668 @@ declare const relaySchema: Schema<{
 declare const RELAY_HASH8: Uint8Array;
 declare function isRelayHash8(hash8: Uint8Array): boolean;
 
+/**
+ * Room-code constants, in the one package every component that has an opinion about them already
+ * depends on.
+ *
+ * They started in `@irtio/supervisor` (`codes.ts`), which is still the only place that *allocates*
+ * a code for a running room. D52 added a second minter: quick-match answers a filled queue with a
+ * fresh code from the control plane, which has no supervisor dependency and never will (control
+ * placing a room would drag cross-room state into a deliberately single-room component). Rather
+ * than let control keep a private copy of an alphabet that is a public contract, the contract
+ * moved here and `supervisor/codes.ts` re-exports it — the same move `auth.ts` already made for
+ * the origin policy when the router became a second enforcer of it.
+ */
+/** The unambiguous base-32 alphabet room codes are drawn from: no `0`/`O`, no `1`/`I`. */
+declare const CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+/**
+ * The one character that separates a room type from a room id, decided once (M5 part 2, shard
+ * note 1).
+ *
+ * Room types and tenant sharding both want to read structure out of a roomId, and if they reach
+ * for their own separators independently they collide. So the delimiter is a contract, stated
+ * here, and `parseRoomId` below is the only code that knows it. Two rules follow, binding on
+ * everything downstream:
+ *
+ * - It is never `/`. The alarm sidecar key is `${liveKey}/alarms` and its reverse parse assumes
+ *   the room segment holds no `/`.
+ * - Anything that special-cases a particular room (a directory-pinned `notifications:global`,
+ *   later) matches the whole roomId by value. It never splits on this character to do it.
+ */
+declare const ROOM_TYPE_DELIMITER = ":";
+/**
+ * A room type name: lowercase, starts alphanumeric, at most 24 characters.
+ *
+ * Narrower than the id charset on purpose. A type name is a filename in `irtio/rooms/`, so it has
+ * to survive a case-insensitive filesystem, and it must never be mistaken for a room code
+ * (`looksLikeRoomCode` upper-cases 4-5 character alphanumeric ids, and lowercase-only types plus
+ * the split-before-check rule in `normalizeRoomId` keep those two worlds apart).
+ */
+declare const ROOM_TYPE_RE: RegExp;
+/**
+ * Externally supplied room ids must match this (`E_ROOM_NOT_FOUND` otherwise).
+ *
+ * M5 part 2 widened it by exactly one optional prefix: `<type>:`. A plain id means the project's
+ * default room type and is accepted verbatim, exactly as it was before, which is what makes every
+ * roomId minted before this change keep meaning what it meant. The id half still carries its own
+ * 1-32 budget, so a type prefix costs a project nothing from the id it was already using.
+ */
+declare const ROOM_ID_RE: RegExp;
+/**
+ * The name the default room type is registered under.
+ *
+ * A plain roomId carries no type and means this one. It is a real name rather than a `null` key so
+ * that a project can also address it explicitly (`default:lobby` and `lobby` are the same room),
+ * and so that the supervisor's type map has no special case in it.
+ */
+declare const DEFAULT_ROOM_TYPE = "default";
+/** A roomId split into its optional type and its id half. */
+interface ParsedRoomId {
+    /** The declared room type, or `undefined` for a plain id, which means the default type. */
+    readonly type: string | undefined;
+    /** The id half: what a room code, a match code, or `__tenant` would be. */
+    readonly id: string;
+}
+/**
+ * Splits `<type>:<id>` into its halves, or returns `undefined` when the string is not a legal
+ * roomId at all. The sole reader of `ROOM_TYPE_DELIMITER`.
+ *
+ * A plain id parses to `{ type: undefined, id: raw }` rather than to a default type name, because
+ * the default type's *name* is a per-project fact the protocol package does not know.
+ */
+declare function parseRoomId(raw: string): ParsedRoomId | undefined;
+/** Joins a type and an id back into a roomId. A missing type gives the plain form. */
+declare function formatRoomId(type: string | undefined, id: string): string;
+/**
+ * How many characters a control-minted quick-match code carries.
+ *
+ * Ten, not four. The supervisor's own codes start at four because they are read aloud and typed
+ * in by a human, and it grows them on collision because it can see every room it holds. Control
+ * can see no such thing: it mints without asking any box whether the code is free (fact 2 — no
+ * occupancy read, no round trip), so the code has to be long enough that a collision is not a
+ * thing that happens rather than a thing that is retried. Ten characters of this alphabet is 50
+ * bits.
+ *
+ * It is also deliberately longer than five, which is what `looksLikeRoomCode` treats as
+ * code-shaped and upper-cases: a ten-character code is passed through verbatim by
+ * `normalizeRoomId`, so the string control hands a client is exactly the string the supervisor
+ * resolves.
+ */
+declare const MATCH_CODE_LENGTH = 10;
+
+/**
+ * D59: the tenant-local room bus — limits, error names, and the pure validators.
+ *
+ * This module is the shared half, and it lives in `@irtio/protocol` because the two sides that
+ * must agree on it are the room runtime (which is bundled into a room worker and cannot pull in
+ * anything heavy) and the supervisor (which enforces every one of these). Neither can be trusted
+ * to check on the other's behalf: the runtime's checks are a courtesy that gives a developer a
+ * message at the call site, and the supervisor's are the boundary, because room code runs inside
+ * a tenant VM and anything the runtime refuses is something a hostile bundle can simply not call.
+ *
+ * ## The two verbs, and why their guarantees differ
+ *
+ * `publish`/`subscribe` is fire-and-forget fan-out to *awake* subscribers. Nothing queues, nothing
+ * wakes, and there is no ordering promise across channels. A hibernated subscriber misses the
+ * message the same way it misses wall-clock time, and resyncs from state when it wakes.
+ *
+ * `send(roomId, payload)` is directed, durable and at-least-once, and it wakes the target. It
+ * rides the durable-alarm machinery: a mailbox entry is an alarm with a payload.
+ *
+ * These guarantees are deliberately weak. Sharding (M5 part 7) turns `send` into a network hop and
+ * `publish` into a shard fan-out, and nothing stronger would survive that. **At-least-once means
+ * at-least-once**: a handler can see the same message twice, and must be written to tolerate it.
+ *
+ * ## The boundary
+ *
+ * Tenant-scoped only, ever. There is no project argument on any verb, in any layer, at any depth.
+ * A room can name a channel and a roomId; it cannot name a project, so a cross-project reach is
+ * not something the supervisor refuses, it is something the API cannot express. The supervisor's
+ * bus registry is per-tenant because a supervisor *is* one tenant, and the roomId a `send` names
+ * is resolved against that supervisor's own room table and nothing else.
+ */
+/**
+ * Bus limits. Every number here is enforced in the supervisor, and each is small on purpose: the
+ * bus is signaling, not state transfer. Anything big goes through a room the recipient joins.
+ */
+declare const 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.
+     */
+    readonly payloadBytes: number;
+    /** Max UTF-8 bytes in a channel name. Names are vocabulary, not data. */
+    readonly channelBytes: 128;
+    /** Max channels one room may hold a subscription to at once. */
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly 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.
+     */
+    readonly opsPerSecond: 50;
+    readonly 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.
+     */
+    readonly redeliveryDelayMs: 30000;
+};
+/**
+ * A channel name: the same shape as a room type, widened to allow dots so a project can namespace
+ * its channels (`match.ready`, `party.invite`). Lowercase, starts alphanumeric, up to the byte
+ * cap. Narrow on purpose: a channel name is a map key that appears in logs and in a report a
+ * developer reads, and there is no reason for it to be able to hold arbitrary text.
+ */
+declare const BUS_CHANNEL_RE: RegExp;
+/**
+ * The named failures. Each one is a thing the caller can tell apart and act on differently: a
+ * payload the caller must shrink, a target the caller named wrong, a receiver the caller is
+ * outrunning, and a rate the caller must slow to.
+ */
+declare const BUS_ERRORS: {
+    readonly badChannel: "E_BUS_BAD_CHANNEL";
+    readonly payloadTooLarge: "E_BUS_PAYLOAD_TOO_LARGE";
+    readonly tooManySubscriptions: "E_BUS_TOO_MANY_SUBSCRIPTIONS";
+    /** The named room does not exist in this tenant, or is a relay room and runs no handlers. */
+    readonly noSuchRoom: "E_BUS_NO_SUCH_ROOM";
+    readonly mailboxFull: "E_BUS_MAILBOX_FULL";
+    readonly rateLimited: "E_BUS_RATE_LIMITED";
+};
+type BusErrorCode = (typeof BUS_ERRORS)[keyof typeof BUS_ERRORS];
+/** `{ code, message }` when the input is refused, `undefined` when it is fine. */
+interface BusProblem {
+    readonly code: BusErrorCode;
+    readonly message: string;
+}
+/** Validates a channel name. Shared by the runtime's courtesy check and the supervisor's real one. */
+declare function busChannelProblem(channel: unknown): BusProblem | undefined;
+/** Validates a payload. Bytes, not characters: the cap is a store and wire cost. */
+declare function busPayloadProblem(payload: unknown): BusProblem | undefined;
+/**
+ * The alarm-name prefix a durable mailbox entry is armed under.
+ *
+ * Mailbox entries ride `AlarmSet`, whose `set` **replaces by name**. Two sends of the same payload
+ * to the same room must deliver twice, so every entry gets a minted-unique name rather than a
+ * stable one. The prefix is what lets the supervisor tell a mailbox entry from a room's own alarm
+ * on the way out of `fireDue`, and it is not a legal `room.alarm` name (`isAlarmName` refuses a
+ * leading `__`), so a room cannot arm one itself or cancel someone else's.
+ */
+declare const BUS_MAILBOX_PREFIX = "__bus.";
+/** True for an alarm name that is a mailbox entry rather than one of the room's own alarms. */
+declare function isMailboxAlarm(name: string): boolean;
+/**
+ * What a mailbox entry's persisted payload holds. Serialised into the alarm sidecar's `payload`
+ * field, which is why the sidecar codec had to grow one.
+ *
+ * `from` is stamped by the supervisor from the sending room's own record, never read off anything
+ * the sender supplied. A room can therefore not forge a source: the field the receiver reads is
+ * written by the only party that knows the truth.
+ */
+interface BusMailboxEntry {
+    /** The roomId that sent this. Supervisor-stamped. */
+    readonly from: string;
+    readonly payload: string;
+    /** Deliveries attempted so far, including the one in flight. Dead-lettered past the cap. */
+    readonly attempts: number;
+}
+/**
+ * M5 part 7 (D67-e): the alarm-name prefix a **cross-shard outbox** entry is armed under, on the
+ * SENDER's own sidecar. A `send` to a room that is not on this shard parks the message here and
+ * forwards it through the control plane; the entry is the retry and the durability, exactly as
+ * `BUS_MAILBOX_PREFIX` is for a local delivery. Recognised by the supervisor before its generic
+ * alarm branch, or it would reach `onAlarm` as a garbage name; a platform rolled back to a
+ * supervisor older than this part would do exactly that, which the docs say beside the same
+ * warning for `__bus.`. Not a legal `room.alarm` name (`isAlarmName` refuses a leading `__`).
+ */
+declare const BUS_OUTBOX_PREFIX = "__busout.";
+/** True for an alarm name that is a cross-shard outbox entry. */
+declare function isOutboxAlarm(name: string): boolean;
+/**
+ * What an outbox entry's persisted payload holds. `to` is the target room; `id` is the entry's
+ * own name, carried end to end so a target that receives the same message twice (a lost
+ * acknowledgement) logs the duplicate by name. `firstAt` is when the message was parked, for the
+ * one-hour dead-letter bound; `attempts` counts forwards so the retry schedule doubles.
+ */
+interface BusOutboxEntry {
+    readonly to: string;
+    readonly from: string;
+    readonly payload: string;
+    readonly id: string;
+    readonly firstAt: number;
+    readonly attempts: number;
+}
+/**
+ * The cross-shard retry schedule (D67-e): 1, 2, 4 ... 60 seconds between forwards, for up to an
+ * hour after the message was parked, then a dead letter in the sender's log at warn. Enforced
+ * in the supervisor; every number is here so the docs and the code quote the same ones.
+ */
+declare const BUS_OUTBOX: {
+    readonly firstRetryMs: 1000;
+    readonly maxRetryMs: 60000;
+    readonly ttlMs: number;
+};
+/** D67-e: the target's shard is not running; the control plane is placing it. Retry later. */
+declare const BUS_SHARD_STARTING = "E_SHARD_STARTING";
+
+/**
+ * D60: room size classes, and the one place the mapping from a declaration to a billed class is
+ * written down.
+ *
+ * A class is a *billing* concept, and saying that plainly is the whole point of this file. What is
+ * enforced on a room is its worker heap cap, which part 2's declared sizing already handles. What
+ * a class does is decide the rate that room's hours are charged at.
+ *
+ * The classes are Small, Medium and Large, with the shared relay host beneath them. Relay is not a
+ * class: a relay room reserves no memory and holds no VM slot, so no declared `memoryMb` maps to
+ * it. Pricing amendment 1 (2026-09-01) retired the Nano class: with the M5 RAM guardrails enforced,
+ * a Nano room's real footprint was a VM slot plus a 32 MB heap floor, which is not meaningfully
+ * cheaper to host than a Small room. A room that would once have been Nano is Small now, and a
+ * schema declaring `nano` fails classification the same way any unknown class does.
+ *
+ * ## Why the class is derived, not declared separately
+ *
+ * `memoryMb` on `defineRoom` already exists, is validated to a whole 32..1024, drives the worker's
+ * `resourceLimits`, and is summed by `checkDeclaredFit` against the VM budget. Deriving the class
+ * from it means a project has one number to think about and the bill cannot disagree with the
+ * enforcement. A separate `class` field could say Small while `memoryMb` said 512, and then the
+ * invoice and the room would be telling different stories about the same room, with no way for a
+ * developer to tell which one was the lie.
+ *
+ * The cost of deriving is that the thresholds are a policy that a project reads off a table rather
+ * than states outright. That is the better trade here: the table is short, it is in the pricing
+ * docs, and the alternative failure mode is a wrong bill.
+ */
+/** The size classes, smallest first. `small` is what every room that predates D60 is. */
+type RoomSizeClass = 'small' | 'medium' | 'large';
+/**
+ * The floor on a declared `memoryMb`.
+ *
+ * The same 32 {@link DEFAULT_MEMORY_MB} is: V8's usable old-generation floor, below which a worker
+ * cannot boot a room at all, so accepting a smaller declaration would only move the failure later.
+ */
+declare const ROOM_MEMORY_MB_MIN = 32;
+/**
+ * The ceiling on a declared `memoryMb`, and the top of the Large class.
+ *
+ * M5 part 3.6: 1024, down from the 4096 that `VM_MEM_MIB_MAX` used to lend it by accident. Large is
+ * *advertised* on a 1 GiB basis and priced on one, and until this cap existed a room could declare
+ * 4096 and pay Large's rate for four times Large's memory. The under-charge was the whole band from
+ * 1025 to 4096, silently, with the class table below saying otherwise.
+ *
+ * This is deliberately **not** `VM_MEM_MIB_MAX`. The two numbers answer different questions: this
+ * one is the largest room a project may declare, and 4096 is the largest machine the platform will
+ * build for a project's declarations. Three 1024 MB types at `maxAwake` 1 is still a legal tenant,
+ * so the VM ceiling stays where it is.
+ *
+ * It lives in this file rather than beside the VM sizing constants because it is a *class*
+ * boundary — the top of Large — and because `ROOM_CLASS_MAX_MB` below must be able to read it
+ * without the two modules importing each other.
+ */
+declare const ROOM_MEMORY_MB_MAX = 1024;
+/**
+ * The declared-memory ceiling for each class, in MB, as declared on `defineRoom`.
+ *
+ * `small` is 64 because that is the historical default and the rate every existing project is on,
+ * so the boundary is placed where nothing already deployed moves class. Small is also the bottom of
+ * the table: every declaration from V8's 32 MB floor up to 64 is Small, which is what retiring Nano
+ * means in one line.
+ *
+ * `large` is 1024 because that is the 1 GiB basis Large is advertised and priced on, and because
+ * M5 part 3.6 made it the ceiling on a declaration rather than a decoration
+ * ({@link ROOM_MEMORY_MB_MAX}). Before that, `large` read 4096 and a room could declare four times
+ * the memory Large's rate is derived from and pay Large's rate for it. The top of the top class and
+ * the largest declarable room are now the same number by construction, so no band is left between
+ * what a project may ask for and what any class is priced to cover.
+ */
+declare const ROOM_CLASS_MAX_MB: Readonly<Record<RoomSizeClass, number>>;
+/**
+ * The class a room with this declared `memoryMb` is billed as.
+ *
+ * An undeclared room is `small`, which is the compatibility rule that matters: every project that
+ * existed before D60 declared nothing, ran on the 64 MB default, and was billed at Small's rate,
+ * and all three of those stay true.
+ */
+declare function roomClassFor(memoryMb: number | undefined): RoomSizeClass;
+/**
+ * The `source` a class's room-hours are reported under.
+ *
+ * The size-class dimension rides the existing `source` column rather than a new one, and that is a
+ * deliberate reuse rather than a shortcut. `source` is already in the usage table's primary key
+ * (`project, meter, window_start, source, engine`), it already distinguishes writers of one meter
+ * that must not overwrite each other, and the relay host's `$0.001` rate was already decided to
+ * ride it. One dimension answering "what kind of thing produced this hour" is easier to reason
+ * about than two that can disagree.
+ *
+ * Small stays `room`, unchanged, which is what keeps every window ever written still meaning what
+ * it meant and keeps a Small project's bill byte-identical.
+ */
+declare function roomHoursSourceFor(cls: RoomSizeClass): string;
+/** The class a room-hours `source` denotes, or `undefined` when it is not a class at all. */
+declare function roomClassOfSource(source: string): RoomSizeClass | undefined;
+
+/**
+ * M5 part 3.5: a tenant VM's memory is arithmetic over its room types' declarations.
+ *
+ * Before this file, `vmMemSizeMibFor` answered the question with two guesses: 256 MiB when any
+ * schema declared physics, 128 MiB otherwise. Both numbers were chosen before anything measured
+ * either of the terms they were standing in for, and part 1 measured them: the supervisor's own
+ * resident set is roughly 53 MiB, so a 128 MiB VM has about 70 MiB for every room in it, and one
+ * minimally-sized worker very nearly exhausts that. The 128 was not a small VM, it was a VM that
+ * could not host a room of any size and did not say so.
+ *
+ * The replacement is a sum, and the whole design is that the sum's terms are things a project
+ * *declared* rather than things the platform inferred:
+ *
+ * ```
+ * S     = Σ_type (memoryMb + youngGenMb) × maxAwake
+ *         + supervisorBaselineMib
+ *         + physicsHeadroomMib   (once per VM, when any type declares physics)
+ * vmMib = clamp(ceil(S × 8/7), 128, 4096)
+ * ```
+ *
+ * Three things about that arithmetic are load-bearing and are stated here rather than left to be
+ * rediscovered by whoever changes it next.
+ *
+ * **The native reserve is closed-form.** Part 1's derivation reserves `vmMib / 8` for off-heap
+ * cost (worker stacks, the Rapier WASM code, socket buffers, the encode scratch). That is circular
+ * when `vmMib` is the output rather than the input, so the reserve is solved for instead of
+ * iterated: `vmMib = S × 8/7` makes `vmMib - S` exactly `vmMib / 8`. Pinned by
+ * {@link nativeReserveOf} and a round-trip test — the derived worker caps, applied back to the
+ * size this function returned, must still leave every declared worker fitting.
+ *
+ * **The physics headroom is measured and it is big.** A Rapier world's first step costs a
+ * transient while V8 tier-compiles the WASM on background threads: measured in a real 1-vCPU
+ * guest at **+97.6 MiB over pre-step RSS**, settling to +28 (part 1 report addendum, live probe
+ * 2026-08-31). It is added once per VM rather than per type or per room, because the compile
+ * happens once per process, and it is added at all because without it arithmetic sizing would
+ * recreate exactly the OOM class D55 was built to fix.
+ *
+ * **`maxAwake` is what makes the sum well-defined.** Part 2 summed every declared type once,
+ * because nothing could know how many rooms of a type would be awake together, and recorded the
+ * pessimism as a debt. Multiplying by a declared concurrency is the answer that debt asked for,
+ * and it is only honest because the supervisor *enforces* it: room N+1 of a type is refused. A
+ * `maxAwake` nobody enforced would be a number that made the VM look big enough.
+ *
+ * This module is in `@irtio/protocol` because three packages need the same answer and must not
+ * each carry their own copy of it: the host agent sizes the Firecracker machine, the supervisor
+ * checks the size it was given against what it is about to run, and (part 7) control's
+ * `pickServer` needs to know what a tenant will cost a box before choosing one. The fleet
+ * protocol module is deliberately zero-dependency, which is what lets all three import it.
+ */
+
+/** The floor. A guest kernel plus a Node process make anything smaller pointless. */
+declare const VM_MEM_MIB_MIN = 128;
+/** The ceiling. A guard against a typo booking a whole box's memory for one tenant. */
+declare const VM_MEM_MIB_MAX = 4096;
+/**
+ * The supervisor's own resident set with zero rooms awake, in MiB, measured rather than guessed.
+ *
+ * Method (part 1's, re-run in part 3.5 after the baseline-shaving work): `supervisor/dist/bin.js`
+ * booted as a child process with the placed-shaped environment `buildSupervisorEnv` emits, one
+ * minimal room bundled by the real `bundleRoom`, six `/admin/metrics` readings over ~36 s with
+ * `roomsByState` all zero and `sockets: 0` on every one. Rounded up to the next whole MiB.
+ * Provenance, the raw readings and the before/after of the shaving are in
+ * `docs/m5-part3.5-report.md`.
+ *
+ * This is a *constant term* in every VM's size, so a MiB here is a MiB on every tenant on every
+ * box. Re-measure it by the same method if the supervisor's boot-time module graph changes
+ * materially, and record the new provenance rather than nudging the number.
+ *
+ * **54, and most of the drop from part 1's 57 is a re-measurement rather than a saving.** Measured
+ * on the same machine, by the same method, on both builds: the pre-shave build reads a settled max
+ * of 53.46 MiB and the shaved build 53.20, so the lazy-import work is worth about a third of a MiB
+ * and the other two and a half are part 1's number having been taken on a process whose first
+ * reading had not settled. Both halves are in the report, because a constant that quietly improved
+ * would be worse than one that says how little it moved.
+ */
+declare const SUPERVISOR_BASELINE_MIB = 54;
+/**
+ * Off-heap headroom, as a fraction of the final VM size: `vmMib / NATIVE_RESERVE_FRACTION`.
+ * A fraction rather than a constant because the things it covers — worker stacks, native
+ * allocations, socket buffers, encode scratch — scale with what a bigger VM was made bigger for.
+ */
+declare const NATIVE_RESERVE_FRACTION = 8;
+/**
+ * Added once per VM when any room type declares physics.
+ *
+ * 112, not the measured 97.6: the peak is what a guest must survive, and rounding a survival
+ * margin down is how the week-9 pachinko OOM happened. The nearest power-of-two-ish number above
+ * the peak is the honest rounding direction for a number whose failure mode is the VM dying.
+ */
+declare const PHYSICS_HEADROOM_MIB = 112;
+/** Every worker's young generation. Small, and scaling it buys nothing. */
+declare const YOUNG_GEN_MB = 32;
+/**
+ * What an undeclared room type is counted at.
+ *
+ * 32 is V8's usable floor for an old generation and the smallest cap the platform can apply, so
+ * counting an undeclared type at anything larger would be inventing a promise the project never
+ * made. Together with {@link DEFAULT_MAX_AWAKE} it is the honest reading of part 1's 128 MiB
+ * finding: one real worker, minimally sized, is what a project that declared nothing was actually
+ * being given.
+ */
+declare const DEFAULT_MEMORY_MB = 32;
+/**
+ * How many rooms of an undeclared type may be awake at once.
+ *
+ * One. That is the conservative reading and it is deliberately the number that makes an
+ * undeclared single-type project size to the 128 MiB floor, which is the VM it has always had.
+ * A project that wants more says so, and the sum grows to match, which is the entire point.
+ */
+declare const DEFAULT_MAX_AWAKE = 1;
+/**
+ * The ceiling on a declared `maxAwake`.
+ *
+ * 256 rooms of the smallest declarable type (32 + 32 MB) is already 16 GiB before the baseline,
+ * four times the largest VM the platform will build, so anything above it is a number that cannot
+ * be honoured rather than a bigger project. The ceiling exists so the refusal names the mistake at
+ * `defineRoom` time instead of at placement time, where it would be a clamp nobody saw.
+ */
+declare const MAX_AWAKE_MAX = 256;
+/** One room type's sizing declarations, as `defineRoom` took them. */
+interface RoomTypeSizing {
+    readonly type: string;
+    /** Declared worker old-generation cap in MB; `undefined` counts as {@link DEFAULT_MEMORY_MB}. */
+    readonly memoryMb?: number;
+    /** Declared concurrent awake rooms; `undefined` counts as {@link DEFAULT_MAX_AWAKE}. */
+    readonly maxAwake?: number;
+    /** Whether this type's schema declares physics. Adds the headroom once per VM, not per type. */
+    readonly physics?: boolean;
+}
+/** The size, and every term that produced it, so a log line or a report can show its working. */
+interface VmSizing {
+    /** The answer: what the VM is built with, after the reserve and the clamp. */
+    readonly vmMib: number;
+    /** Σ over the declarations, before the baseline and the headroom. */
+    readonly workersMib: number;
+    readonly baselineMib: number;
+    readonly physicsHeadroomMib: number;
+    /** `workersMib + baselineMib + physicsHeadroomMib` — the sum the reserve is solved against. */
+    readonly preReserveMib: number;
+    /** `vmMib - preReserveMib`, which is `vmMib / 8` whenever the clamp did not bite. */
+    readonly nativeReserveMib: number;
+    /** `'floor'` / `'ceiling'` when the clamp moved the answer, else `undefined`. */
+    readonly clamped?: 'floor' | 'ceiling';
+    /** One line naming the arithmetic, for a boot log or an error. */
+    readonly detail: string;
+}
+/** The reserve a VM of this size carries: one eighth, floored. */
+declare function nativeReserveOf(vmMib: number): number;
+/** What one declared type contributes to the sum: `(memoryMb + youngGen) × maxAwake`. */
+declare function typeFootprintMib(type: RoomTypeSizing): number;
+/**
+ * The VM size a project's declarations ask for.
+ *
+ * A project with no room types at all — a relay-only tenant, which still gets a VM until D66's
+ * second half lands — sizes to the floor. So does an undeclared single-type project, which is
+ * the compatibility-shaped case even though compatibility is not what is being kept here: it is
+ * the size that project has always had, and the arithmetic agrees with it rather than being made
+ * to.
+ */
+declare function vmSizeFor(types: readonly RoomTypeSizing[], options?: {
+    readonly baselineMib?: number;
+}): VmSizing;
+/**
+ * How many awake rooms of each class one vCPU is expected to carry.
+ *
+ * The CPU allowance is arithmetic over declarations for the same reason the memory size is: the
+ * alternative is a number chosen from a marketing table that the throttle then has to pretend to
+ * honour. A project declares `memoryMb` and `maxAwake`, the class comes from the memory, and the
+ * quota comes from the sum. One number decides the class, the bill, the heap cap and now the CPU
+ * share, so none of them can disagree with the others.
+ *
+ * **Where these came from.** Small and Large are the owner's anchors. Medium is 8 rather than
+ * the plan's 10, **set from measurement and owner-reviewable at merge**: a density bench against a
+ * real supervisor with real WebSocket clients measured marginal CPU per room on the full
+ * supervisor-and-network path at 1.2% for a casual tick room, 2.3% for an active one, and 7.1% for
+ * a physics room of 60 Rapier bodies. That is about 8.5 physics rooms per core at 60% utilisation
+ * on the bench machine, and the production box is slower per core, so 10 would have over-promised
+ * for exactly the rooms that land in Medium by default. The bench numbers and their caveats are in
+ * `docs/m5-part3.6-report.md`.
+ *
+ * Keep them here, in one table, so an owner adjustment is one line rather than an audit.
+ */
+declare const ROOMS_PER_VCPU: Readonly<Record<RoomSizeClass, number>>;
+/** The floor on a derived quota, as a percentage of one vCPU. Below this a room cannot serve. */
+declare const CPU_QUOTA_PCT_MIN = 10;
+/** The ceiling: one whole vCPU, which is all a Firecracker guest is built with. */
+declare const CPU_QUOTA_PCT_MAX = 100;
+/** A tenant's CPU allowance, and the terms that produced it. */
+interface VmCpuSizing {
+    /** The answer: percent of one vCPU, for `systemctl set-property … CPUQuota=<n>%`. */
+    readonly quotaPct: number;
+    /** The sum before the clamp, so a log line can show an over-declared project its own number. */
+    readonly rawPct: number;
+    /** `true` when the project declared nothing at all and is therefore not throttled. */
+    readonly undeclared: boolean;
+    /** `'floor'` / `'ceiling'` when the clamp moved the answer, else `undefined`. */
+    readonly clamped?: 'floor' | 'ceiling';
+    /** One line naming the arithmetic, for a boot log. */
+    readonly detail: string;
+}
+/**
+ * The CPU quota a project's declarations ask for, as a percentage of the VM's one vCPU.
+ *
+ * ```
+ * rawPct   = Σ_type ceil-free (maxAwake × 100 / roomsPerVcpu(class(memoryMb)))
+ * quotaPct = clamp(ceil(rawPct), 10, 100)
+ * ```
+ *
+ * **An undeclared project gets no throttle**, which is the same posture `maxAwake` enforcement took
+ * in part 3.5 and is stated here because it is the rule most likely to be read as an oversight.
+ * Only declarations are held against a project. A project that declared nothing made no promise
+ * about its concurrency, so there is no sum to derive a share from, and inventing one would throttle
+ * every tenant that predates this function on a number it never said.
+ *
+ * **The quota is a ceiling, not a reservation.** `CPUQuota=` bounds what a VM may take; it does not
+ * hold anything back for it. So a project that declares more concurrency than its class density
+ * supports is not taking CPU from its neighbours on the box, it is spreading its own allowance
+ * thinner across its own rooms. The failure mode of an optimistic density is a project's own rooms
+ * ticking late, which is the right place for it to land.
+ *
+ * The class comes from {@link roomClassFor} over the same `memoryMb` that decides the bill, so the
+ * CPU share and the invoice cannot tell different stories about one room.
+ */
+declare function vmCpuFor(types: readonly RoomTypeSizing[]): VmCpuSizing;
+/**
+ * Does what a project declared fit a VM of this size?
+ *
+ * Under arithmetic sizing this can only be false one way: a project set an explicit `vmMemMib`
+ * override smaller than its own declarations. That is why the supervisor treats a false answer as
+ * a refusal to boot rather than a log line. Pre-release, an override that lies about the machine
+ * its rooms are running in should fail where somebody is looking.
+ */
+declare function declarationsFit(vmMemMib: number, types: readonly RoomTypeSizing[], options?: {
+    readonly baselineMib?: number;
+}): {
+    readonly fits: boolean;
+    readonly required: VmSizing;
+};
+
+/**
+ * Room retention: how long a room outlives its last activity, as a room type declares it.
+ *
+ * A room type declares `retention: '10m'` beside `memoryMb` and `maxAwake`, and control's reaper
+ * deletes the room's stored objects once that long has passed since the room last hibernated.
+ * Absent means forever, which is what every room has always had and stays the default.
+ *
+ * **Why a string and not a number of milliseconds.** Every other duration in this repository is a
+ * `durationMs` number, and this one deliberately is not. The declaration is read by a human in a
+ * room file and it is the one number in that file whose mistakes delete data: `retention: 600000`
+ * and `retention: 600_000_000` look alike at a glance, and `'10m'` and `'10000m'` do not. The
+ * parsed number never reaches storage either — control stores the declared string, so a row can
+ * always be read back as the thing the developer wrote.
+ *
+ * **The grammar is narrow on purpose.** One integer, one unit, no space, no fraction, no compound
+ * (`'1h30m'`), no seconds. A window is a coarse promise about when data goes away and the sweep
+ * cadence is its real resolution, so a grammar that can express a precision the platform does not
+ * have would be a lie in the type system. Anything outside it is refused by name at every door
+ * rather than coerced: a retention that was silently rounded, clamped or defaulted is the exact
+ * failure mode a deletion feature must not have.
+ *
+ * This lives in `@irtio/protocol` because it is a declaration constant shared by more than one
+ * package, which is what `sizing.ts` and `classes.ts` are already here for. `@irtio/server` is on
+ * the room-bundle side of the fence and may not import it, so it carries the same grammar and the
+ * same bounds as literals, pinned equal by `packages/supervisor/test/declaration-doors.test.ts`.
+ */
+/**
+ * The declared form: a positive integer of up to five digits, then one of `m`, `h`, `d`.
+ *
+ * Five digits because the ceiling (3650 days) needs four in days, five in hours, and seven in
+ * minutes would be past the ceiling anyway — the bounds check below is what actually decides, and
+ * the digit cap only exists so a pathological input cannot be a number at all.
+ */
+declare const RETENTION_RE: RegExp;
+/** One minute. Below this the sweep cadence (15 minutes by default) is the whole window. */
+declare const RETENTION_MIN_MS = 60000;
+/** Ten years. A declaration above this is asking for "forever", which is written by omitting it. */
+declare const RETENTION_MAX_MS: number;
+/**
+ * The window in milliseconds, or `undefined` when `raw` is not a legal declaration.
+ *
+ * `undefined` is the single answer for every rejection — malformed, out of range, wrong type —
+ * because every caller does the same thing with it: refuse by name, naming the value it was given.
+ * A caller that needs to say *why* has the value in hand and the bounds exported beside this.
+ */
+declare function parseRetention(raw: unknown): number | undefined;
+
 /**
  * Browser-origin policy, shared by every component that has to answer "may this page connect?"
  *
@@ -432,4 +1518,4 @@ declare function originAllowed(origins: readonly string[], allowNoOrigin: boolea
  */
 declare function parseOriginList(raw: string | undefined): readonly string[];
 
-export { type Call, type ClientCallable, type Credential, ERROR_CATALOGUE, type ErrorCatalogueEntry, ErrorCode, type ErrorCodeDef, type ErrorCodeName, type ErrorPayload, type Frame, FrameType, type Hello, type Msg, type MsgTarget, PRESENCE_COLLECTION, PROTOCOL_VERSION, type Ping, type Pong, type PresenceRecord, RELAY_HASH8, type Reply, type Welcome, builtinRpcs, correctPayload, decodeCall, decodeErrorPayload, decodeFrame, decodeHello, decodeMsg, decodePing, decodePong, decodeReply, decodeWelcome, deltaPayload, encodeCall, encodeCorrectFrame, encodeDeltaFrame, encodeErrorPayload, encodeFrame, encodeHello, encodeMsg, encodePing, encodePong, encodeReply, encodeWelcome, encodeWriteFrame, errorByCode, formatError, isFrameType, isLocalhostOrigin, isRelayHash8, originAllowed, parseOriginList, presenceEntity, readCorrectAppliedTick, readCorrectClientTick, relaySchema, requestOwnership, rpcByIdOf, rpcIdOf, rpcTable, withBuiltins, writePayload };
+export { type AttributeOptions, BUS_CHANNEL_RE, BUS_ERRORS, BUS_LIMITS, BUS_MAILBOX_PREFIX, BUS_OUTBOX, BUS_OUTBOX_PREFIX, BUS_SHARD_STARTING, type BusErrorCode, type BusMailboxEntry, type BusOutboxEntry, type BusProblem, CLOSE_EGRESS_WALL, CLOSE_TRY_AGAIN_LATER, CODE_ALPHABET, CPU_QUOTA_PCT_MAX, CPU_QUOTA_PCT_MIN, type Call, type ChurnIds, type ClientCallable, type Credential, DEFAULT_MAX_AWAKE, DEFAULT_MEMORY_MB, DEFAULT_ROOM_TYPE, EMPTY_PROFILE, ERROR_CATALOGUE, type ErrorCatalogueEntry, ErrorCode, type ErrorCodeDef, type ErrorCodeName, type ErrorPayload, type Frame, FrameType, HELLO_SCHEMA_SWAP_BIT, type Hello, MATCH_CODE_LENGTH, MAX_AWAKE_MAX, type Msg, type MsgTarget, NATIVE_RESERVE_FRACTION, PHYSICS_HEADROOM_MIB, PRESENCE_COLLECTION, PROFILE_KINDS, PROTOCOL_VERSION, type ParsedRoomId, type Ping, type Pong, type PresenceRecord, type ProfileKind, ProfileLedger, type ProfileRow, type ProfileSnapshot, 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, type Reply, type RoomSizeClass, type RoomTypeSizing, SUPERVISOR_BASELINE_MIB, VM_MEM_MIB_MAX, VM_MEM_MIB_MIN, type VmCpuSizing, type VmSizing, type VoiceClientMessage, type VoicePeer, type VoiceServerMessage, type VoiceTransportInfo, type Welcome, YOUNG_GEN_MB, builtinRpcs, busChannelProblem, busPayloadProblem, correctPayload, declarationsFit, decodeCall, decodeErrorPayload, decodeFrame, decodeHello, decodeMsg, decodePing, decodePong, decodeReply, decodeVoiceMessage, decodeWelcome, deltaPayload, diffProfiles, encodeCall, encodeCorrectFrame, encodeDeltaFrame, encodeErrorPayload, encodeFrame, encodeHello, encodeMsg, 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 };