@irtio/runtime 0.10.1 → 1.0.0

package/dist/{chunk-WNAEE4EP.js → chunk-YWDRE77H.js}

@@ -1,7 +1,7 @@
 import {
   parseHibernationBlob,
   writeHibernationBlob
-} from "./chunk-EENJ37KK.js";
+} from "./chunk-LT46QFLW.js";
 
 // src/migrate.ts
 import { PRESENCE_COLLECTION, withBuiltins } from "@irtio/protocol";

package/dist/{contract-C5aqs49-.d.ts → contract-UEKTud1Z.d.ts}

@@ -1,6 +1,6 @@
 import { AnySchema, PlainState, State, Tracked } from '@irtio/schema';
 import * as _irtio_protocol from '@irtio/protocol';
-import { ErrorCodeName } from '@irtio/protocol';
+import { PlatformNotice, ErrorCodeName } from '@irtio/protocol';
 import { RoomDefinition, Room, LeaveReason, NpcConfig } from '@irtio/server';
 
 /**
@@ -84,7 +84,9 @@ declare class TimelineRecorder {
 
 type RoomEventKind = 'join' | 'leave' | 'write' | 'write-rejected' | 'correct' | 'call' | 'reply' | 'msg' | 'alarm'
 /** D59: a bus event (a published message) or a directed bus send being delivered. */
- | 'bus' | 'error';
+ | 'bus'
+/** M7 D-P2: a platform notice reaching `onPlatformNotice`; the detail is the phase. */
+ | 'notice' | 'error';
 interface RoomEvent {
     readonly tick: number;
     readonly kind: RoomEventKind;
@@ -100,6 +102,68 @@ interface RoomInspection {
     readonly recent: readonly RoomEvent[];
 }
 
+/**
+ * M6 lane K (D77 / O28): the write core's caps, and the named refusals that enforce them.
+ *
+ * ## Why these are here and not in the relay host
+ *
+ * The relay host is the reason they exist — it serves many tenants from one process, so a room
+ * that grows without limit is a room taking a box down with it — but the checks belong on the
+ * write path, which is the runtime's. Putting them here means a client `add` cannot get past them
+ * whichever host is running the room, and it means a test can drive them without a socket.
+ *
+ * ## They are walls, not budgets
+ *
+ * A write that would cross one is refused. The room carries on; every other client is unaffected;
+ * nothing is evicted, degraded, truncated or silently dropped. The refusal goes back to the writer
+ * as a **non-fatal** `ERROR` naming the cap it met ({@link ErrorCode.E_STATE_CAP},
+ * `E_RECORD_CAP`, `E_WRITE_RATE`), so a developer can tell a sizing decision from a bug without
+ * reading a log they may not have.
+ *
+ * ## What a room that did not ask for them pays
+ *
+ * Nothing. `stateBytes` and `writesPerSecond` are unset unless a host sets them, and the host that
+ * sets them is the relay host. A coded room in its own VM has its own memory ceiling and its own
+ * tick budget and does not need a second copy of either. The record cap is the exception and it is
+ * on by default, because client `add` is a new surface: no room written before this could regress
+ * on a limit that only applies to a thing it could not do.
+ *
+ * ## How state size is measured, and the error that leaves
+ *
+ * Encoding 512 KB of state on every write to find out how big it is would cost more than the write
+ * loop it guards. So: an exact measure (`encodeSnapshot(...).length`) is taken at most once a tick,
+ * and only once the running figure is over half the cap **or has gone `STALE_MEASURE_TICKS`
+ * without one**; between measures the figure is grown by a **conservative upper bound** of what
+ * each accepted write could add (a record's maximum encoded size, a string field's maximum encoded
+ * size).
+ *
+ * The invariant that buys, stated exactly: the figure is an upper bound on the truth *for
+ * everything it can see*, which is client writes, and it is re-anchored to the truth at least
+ * every `STALE_MEASURE_TICKS` ticks. It is emphatically **not** an upper bound between
+ * re-anchorings for what it cannot see — a `perPlayer` record added on join, an ownership change,
+ * a coded room's own handler writing state — and the staleness bound is what closes that: a leak
+ * the meter is blind to can outrun the figure for ten seconds at 30 Hz and no longer. Above the
+ * truth it can be by one tick of accepted client writes, which is what a slightly early refusal
+ * costs. A room under half the cap pays one measure per stale window and nothing else.
+ */
+
+/** O28's numbers, as the relay host sets them. One place, so lane J can move them once. */
+declare const RELAY_STATE_BYTES: number;
+declare const RELAY_RECORDS_PER_COLLECTION = 1024;
+declare const RELAY_WRITES_PER_SECOND = 35;
+/** The record cap every room gets, because client `add` is a surface no old room had. */
+declare const DEFAULT_RECORDS_PER_COLLECTION = 1024;
+interface WriteCaps {
+    /** Encoded state bytes. Unset (the default) means no wall: the host has its own memory ceiling. */
+    readonly stateBytes?: number;
+    /** Records one entity collection may hold. Defaults to {@link DEFAULT_RECORDS_PER_COLLECTION}. */
+    readonly recordsPerCollection?: number;
+    /** `WRITE` frames one client may send a second. Unset means no bucket. */
+    readonly writesPerSecond?: number;
+}
+/** What the relay host passes. Named so a test can assert the numbers rather than repeat them. */
+declare const RELAY_WRITE_CAPS: WriteCaps;
+
 type LogLevel = 'info' | 'warn' | 'error';
 /**
  * Week 12: host-side async work a room asked for — a save generation (D24) or a player-KV
@@ -194,6 +258,53 @@ type HostCall = {
     readonly playerId: string;
     readonly rating: number;
     readonly deviation?: number;
+}
+/**
+ * D81: `room.replay.clip(seconds)` — the assembled clip blob, on its way to storage.
+ *
+ * The one crossing this lane adds, and a host call for the reason every other one here is: the
+ * room has no network and no store. It is also the only host call that carries bulk bytes, so
+ * it is the only one with a size wall on the far side (`CLIP_MAX_BYTES`, checked by the
+ * supervisor before anything is written) — the ring's own bound already implies a smaller
+ * number, but that bound lives on the side of the seam the tenant's own code owns.
+ *
+ * The result's `value` is the minted clip id.
+ *
+ * M6 clip-TTL packet: `expiresAtEpochS` is the unix second this clip should die, computed here
+ * because this is where `replay.ttl` is declared and read. The supervisor clamps it into
+ * `[now + 1m, now + 3650d]` before minting an id from it, so choosing it inside the tenant's
+ * own worker buys a hostile room nothing an honest one cannot declare.
+ */
+ | {
+    readonly kind: 'clip';
+    readonly bytes: Uint8Array;
+    readonly expiresAtEpochS: number;
+}
+/**
+ * D81's `record: true`: one numbered chunk of a continuous recording, on its way to storage.
+ *
+ * The chunk is the ring's own evictions, kept — so this call carries bulk bytes for the same
+ * reason `clip` does, is walled on the far side for the same reason, and is the only other host
+ * call that does either.
+ *
+ * `recId` is `undefined` on the first chunk of a recording and the supervisor's reply carries
+ * the id it minted; every chunk after it names that id. The mint is on the supervisor's side
+ * because that is where the entropy and the key algebra live (the `clip` precedent), and the
+ * runtime never invents one — which is also what keeps two rooms recording in one project from
+ * ever sharing a prefix.
+ *
+ * M6 clip-TTL packet: `expiresAtEpochS` is the expiry computed when the recording STARTED, and
+ * every chunk carries that same number for the life of the recording. It only decides anything
+ * on the first chunk — the mint — because every chunk after it is addressed by the `recId` the
+ * mint produced, which is what makes a 40-minute match expire atomically instead of losing its
+ * opening while its ending is still being watched.
+ */
+ | {
+    readonly kind: 'record-chunk';
+    readonly recId: string | undefined;
+    readonly seq: number;
+    readonly bytes: Uint8Array;
+    readonly expiresAtEpochS: number;
 };
 /**
  * What a `HostCall` produced. `value` carries the save id for `save` and the stored string for
@@ -318,6 +429,21 @@ interface RoomCoreOptions {
      * `testRoom({ profile: true })` are what turn it on.
      */
     readonly profile?: boolean;
+    /**
+     * D77 / O28: the write core's caps — encoded state bytes, records per collection, writes per
+     * client per second. A host that sets none gets the record cap and nothing else, which is what
+     * every coded room in its own VM wants: it already has a memory ceiling and a tick budget. The
+     * relay host sets all three, because it serves many tenants from one process.
+     */
+    readonly caps?: WriteCaps;
+    /**
+     * D77: the wall clock, for hold deadlines and nothing else.
+     *
+     * A hold has to keep running while a room is hibernated, and `RoomHost.now()` is monotonic
+     * within one process, so it cannot answer "is this five-minute hold over?" for a room that slept
+     * through it. Defaults to `Date.now`; injectable so a test can move a long hold without waiting.
+     */
+    readonly wallNow?: () => number;
 }
 interface JoinOptions {
     /** Requested role; unknown/missing → `roles[0]` (logged) or `''` when the schema has no roles. */
@@ -441,8 +567,24 @@ interface RoomCoreApi<S extends AnySchema = AnySchema> {
     fireAlarm(name: string): void;
     /** D59: deliver one published message on a channel this room is subscribed to. */
     deliverBusEvent(channel: string, from: string, payload: string): void;
+    /**
+     * M7 D-P2: deliver a platform notice to `onPlatformNotice` and answer whether the supervisor
+     * should still broadcast it. `false` means the room vetoed; a throw, a missing handler and a
+     * stopped room all answer `true`.
+     */
+    deliverPlatformNotice(notice: PlatformNotice): boolean;
     /** D59: deliver one directed `room.bus.send`. At-least-once, so this may repeat a message. */
     deliverBusMessage(from: string, payload: string): void;
+    /**
+     * D77: the encoded size of this room's state, or `undefined` when no host asked for the state
+     * cap and nothing is metering it. What the room row and `irtio rooms` report, and the reason a
+     * developer sees the number climb long before the wall.
+     */
+    stateBytes(): number | undefined;
+    /** D77: how many records this room is holding for players who have left. */
+    holdCount(): number;
+    /** How many `transfer: 'ask'` requests are waiting on an owner's answer. Never survives sleep. */
+    askCount(): number;
 }
 
-export { DEFAULT_TIMELINE_MAX_RECORDS as D, EVENT_RING_SIZE as E, HOST_CALL_TIMEOUT_MS as H, type JoinOptions as J, type LogLevel as L, type RoomCoreApi as R, type TimelineDump as T, DEFAULT_TIMELINE_MAX_TICKS as a, type HostCall as b, type HostCallResult as c, type JoinResult as d, type RoomCoreOptions as e, type RoomEvent as f, type RoomEventKind as g, RoomFullError as h, type RoomHost as i, type RoomInspection as j, type RoomStats as k, type TimelineFrame as l, TimelineRecorder as m, type TimelineRecorderOptions as n, inspectState as o };
+export { DEFAULT_RECORDS_PER_COLLECTION as D, EVENT_RING_SIZE as E, HOST_CALL_TIMEOUT_MS as H, type JoinOptions as J, type LogLevel as L, RELAY_RECORDS_PER_COLLECTION as R, type TimelineDump as T, type WriteCaps as W, DEFAULT_TIMELINE_MAX_RECORDS as a, DEFAULT_TIMELINE_MAX_TICKS as b, type HostCall as c, type HostCallResult as d, type JoinResult as e, RELAY_STATE_BYTES as f, RELAY_WRITES_PER_SECOND as g, RELAY_WRITE_CAPS as h, type RoomCoreApi as i, type RoomCoreOptions as j, type RoomEvent as k, type RoomEventKind as l, RoomFullError as m, type RoomHost as n, type RoomInspection as o, type RoomStats as p, type TimelineFrame as q, TimelineRecorder as r, type TimelineRecorderOptions as s, inspectState as t };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { D as DEFAULT_TIMELINE_MAX_RECORDS, a as DEFAULT_TIMELINE_MAX_TICKS, E as EVENT_RING_SIZE, H as HOST_CALL_TIMEOUT_MS, b as HostCall, c as HostCallResult, J as JoinOptions, d as JoinResult, L as LogLevel, R as RoomCoreApi, e as RoomCoreOptions, f as RoomEvent, g as RoomEventKind, h as RoomFullError, i as RoomHost, j as RoomInspection, k as RoomStats, T as TimelineDump, l as TimelineFrame, m as TimelineRecorder, n as TimelineRecorderOptions, o as inspectState } from './contract-C5aqs49-.js';
-export { C as CRASH_AFTER_THROWS, M as MAX_CATCHUP, a as MatterBodyRecord, b as MatterSection, c as Mulberry32, P as PhysicsEngineTag, d as PhysicsSection, R as RoomCore, e as decodeMatterBodies, f as decodeMatterSectionEnvelope, g as decodePhysicsSection, h as decodeRapier2dSectionEnvelope, i as encodeMatterBodies, j as encodeMatterSectionEnvelope, k as encodePhysicsSection, l as encodeRapier2dSectionEnvelope, m as initMatter, n as initPhysics, o as initRapier2d, p as loadedMatter, q as loadedPhysics, r as loadedRapier2d, s as physicsSectionEngine, t as resetMatterForTests, u as resetPhysicsForTests, v as resetRapier2dForTests } from './room-Db3iPBKM.js';
+export { D as DEFAULT_RECORDS_PER_COLLECTION, a as DEFAULT_TIMELINE_MAX_RECORDS, b as DEFAULT_TIMELINE_MAX_TICKS, E as EVENT_RING_SIZE, H as HOST_CALL_TIMEOUT_MS, c as HostCall, d as HostCallResult, J as JoinOptions, e as JoinResult, L as LogLevel, R as RELAY_RECORDS_PER_COLLECTION, f as RELAY_STATE_BYTES, g as RELAY_WRITES_PER_SECOND, h as RELAY_WRITE_CAPS, i as RoomCoreApi, j as RoomCoreOptions, k as RoomEvent, l as RoomEventKind, m as RoomFullError, n as RoomHost, o as RoomInspection, p as RoomStats, T as TimelineDump, q as TimelineFrame, r as TimelineRecorder, s as TimelineRecorderOptions, W as WriteCaps, t as inspectState } from './contract-UEKTud1Z.js';
+export { C as CRASH_AFTER_THROWS, M as MAX_CATCHUP, a as MatterBodyRecord, b as MatterSection, c as Mulberry32, P as PhysicsEngineTag, d as PhysicsSection, R as RoomCore, e as decodeMatterBodies, f as decodeMatterSectionEnvelope, g as decodePhysicsSection, h as decodeRapier2dSectionEnvelope, i as encodeMatterBodies, j as encodeMatterSectionEnvelope, k as encodePhysicsSection, l as encodeRapier2dSectionEnvelope, m as initMatter, n as initPhysics, o as initRapier2d, p as loadedMatter, q as loadedPhysics, r as loadedRapier2d, s as physicsSectionEngine, t as resetMatterForTests, u as resetPhysicsForTests, v as resetRapier2dForTests } from './room-uhj3b-8E.js';
 import { CollectionDesc, AnySchema, PlainState, DirtySet } from '@irtio/schema';
 import '@irtio/protocol';
 import '@irtio/server';
@@ -118,11 +118,13 @@ interface ParsedSnapshot extends SnapshotHeader {
     readonly version: number;
     /** The encoded physics section, or `undefined` for a v1 blob / a room with no world. */
     readonly physics: Uint8Array | undefined;
+    /** M6 lane K (D77): the hold deadlines section, or `undefined` when the room held nothing. */
+    readonly holds: Uint8Array | undefined;
     /** The codec snapshot, encoded under `withBuiltins(schema)`. */
     readonly snapshot: Uint8Array;
 }
 declare function parseHibernationBlob(bytes: Uint8Array): ParsedSnapshot;
-declare function writeHibernationBlob(header: SnapshotHeader, snapshot: Uint8Array, physics?: Uint8Array): Uint8Array;
+declare function writeHibernationBlob(header: SnapshotHeader, snapshot: Uint8Array, physics?: Uint8Array, holds?: Uint8Array): Uint8Array;
 /** What {@link decodeSave} recovers from a room save's bytes. */
 interface DecodedSave extends SnapshotHeader {
     /** The blob's own format version byte: 1 (no physics section) or 2. */

package/dist/index.js

@@ -2,9 +2,10 @@ import {
   fromMigrationState,
   migrateSnapshot,
   toMigrationState
-} from "./chunk-WNAEE4EP.js";
+} from "./chunk-YWDRE77H.js";
 import {
   CRASH_AFTER_THROWS,
+  DEFAULT_RECORDS_PER_COLLECTION,
   DEFAULT_TIMELINE_MAX_RECORDS,
   DEFAULT_TIMELINE_MAX_TICKS,
   EVENT_RING_SIZE,
@@ -12,6 +13,10 @@ import {
   MAX_CATCHUP,
   Mulberry32,
   READABLE_SNAPSHOT_VERSIONS,
+  RELAY_RECORDS_PER_COLLECTION,
+  RELAY_STATE_BYTES,
+  RELAY_WRITES_PER_SECOND,
+  RELAY_WRITE_CAPS,
   RPC_TIMEOUT_MS,
   RoomCore,
   RoomFullError,
@@ -47,9 +52,10 @@ import {
   visibleNames,
   visibleTo,
   writeHibernationBlob
-} from "./chunk-EENJ37KK.js";
+} from "./chunk-LT46QFLW.js";
 export {
   CRASH_AFTER_THROWS,
+  DEFAULT_RECORDS_PER_COLLECTION,
   DEFAULT_TIMELINE_MAX_RECORDS,
   DEFAULT_TIMELINE_MAX_TICKS,
   EVENT_RING_SIZE,
@@ -57,6 +63,10 @@ export {
   MAX_CATCHUP,
   Mulberry32,
   READABLE_SNAPSHOT_VERSIONS,
+  RELAY_RECORDS_PER_COLLECTION,
+  RELAY_STATE_BYTES,
+  RELAY_WRITES_PER_SECOND,
+  RELAY_WRITE_CAPS,
   RPC_TIMEOUT_MS,
   RoomCore,
   RoomFullError,

package/dist/{room-Db3iPBKM.d.ts → room-uhj3b-8E.d.ts}

@@ -1,7 +1,7 @@
-import { AttributeOptions, ProfileSnapshot } from '@irtio/protocol';
+import { PlatformNotice, AttributeOptions, ProfileSnapshot } from '@irtio/protocol';
 import { DirtySet, AnySchema, PlainState, Tracked, State } from '@irtio/schema';
 import { RoomDefinition, RoomMode, Room, RewindView, Ctx, MatterModule, MatterEngine, MatterBody, RapierModule, RapierWorld, RapierRigidBody, Rapier2dModule, Rapier2dWorld, Rapier2dRigidBody, ResolvedRoomConfig, LeaveReason } from '@irtio/server';
-import { i as RoomHost, k as RoomStats, L as LogLevel, R as RoomCoreApi, e as RoomCoreOptions, g as RoomEventKind, n as TimelineRecorderOptions, T as TimelineDump, j as RoomInspection, J as JoinOptions, d as JoinResult, c as HostCallResult } from './contract-C5aqs49-.js';
+import { n as RoomHost, p as RoomStats, L as LogLevel, i as RoomCoreApi, j as RoomCoreOptions, l as RoomEventKind, s as TimelineRecorderOptions, T as TimelineDump, o as RoomInspection, J as JoinOptions, e as JoinResult, d as HostCallResult } from './contract-UEKTud1Z.js';
 
 declare class Mulberry32 {
     /** Current internal state (u32). Survives hibernation. */
@@ -153,6 +153,8 @@ interface RoomInternals {
     readonly physics: PhysicsApi | undefined;
     tick: number;
     stopped: boolean;
+    /** D77: the wall clock hold deadlines are measured against. See `RoomCoreOptions.wallNow`. */
+    wallNow(): number;
     /** Runs a room handler; a throw is logged and counted, never rethrown. */
     guard<T>(name: string, fn: () => T): T | undefined;
     /** D41: record this tick on the authoritative timeline. A no-op while the recorder is unarmed. */
@@ -696,6 +698,8 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     readonly stats: RoomStats;
     tick: number;
     stopped: boolean;
+    /** D77: the wall clock hold deadlines are measured against. See `RoomCoreOptions.wallNow`. */
+    readonly wallNow: () => number;
     /**
      * Called for every handler throw `tryRun` swallows, before it is logged. A test harness sets
      * this so a room that breaks fails the test that broke it (bug 2): the runtime's job is to
@@ -730,6 +734,26 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     constructor(definition: RoomDefinition<S>, host: RoomHost, options: RoomCoreOptions);
     private subscribeDeclaredChannels;
     private get busConfig();
+    /**
+     * M7 D-P2: the platform notice, and the room's veto.
+     *
+     * Answers whether the supervisor should broadcast. `false` — the veto — comes back for exactly
+     * one input: a handler that ran and returned `false`. Every other path answers `true`, and each
+     * one is a different way of the room having said nothing:
+     *
+     * - **No handler.** A room that never wrote this hook. The design's whole point is that its
+     *   players still hear the warning; a code-less room does not even reach this file.
+     * - **A handler that threw.** `tryRun` and not `guard`, so the throw counts toward the crash
+     *   threshold like any other, and it still does not become a veto. This is the one place the
+     *   convention differs from `onChat`, where a throw refuses, and the reason is the asymmetry of
+     *   the two losses: a chat line nobody sees is small; a save-loss warning nobody sees is the
+     *   feature not existing.
+     * - **A stopped room.** Nobody to ask, and for `closing` nobody left to veto for.
+     *
+     * The handler may also have written state, posted chat or started an end sequence. All of that
+     * is ordinary handler work and is flushed here the way an alarm's is.
+     */
+    deliverPlatformNotice(notice: PlatformNotice): boolean;
     /**
      * D59: one published message arriving on a channel this room is subscribed to.
      *
@@ -873,6 +897,12 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
      * `receive()` accepted, plus the join snapshots this room handed the host to wrap in a
      * `WELCOME` (the host builds that frame, so the room never sees it — see the docs page).
      */
+    /** D77: the encoded state size, when a host set the state cap. See `caps.ts`. */
+    stateBytes(): number | undefined;
+    /** D77: how many records are held for players who have left. */
+    holdCount(): number;
+    /** How many `transfer: 'ask'` requests are waiting on an owner's answer right now. */
+    askCount(): number;
     profile(): ProfileSnapshot | undefined;
     private badFrame;
     receive(clientId: string, frame: Uint8Array): void;

package/dist/test/index.d.ts

@@ -1,8 +1,8 @@
-import { R as RoomCore } from '../room-Db3iPBKM.js';
-export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-Db3iPBKM.js';
+import { R as RoomCore } from '../room-uhj3b-8E.js';
+export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-uhj3b-8E.js';
 import { ErrorCodeName, FrameType } from '@irtio/protocol';
 import { NpcConfig, LeaveReason, Room, RoomDefinition } from '@irtio/server';
-import { i as RoomHost, L as LogLevel, R as RoomCoreApi, b as HostCall, c as HostCallResult, k as RoomStats } from '../contract-C5aqs49-.js';
+import { n as RoomHost, L as LogLevel, i as RoomCoreApi, c as HostCall, d as HostCallResult, W as WriteCaps, p as RoomStats } from '../contract-UEKTud1Z.js';
 import { AnySchema, PlainState, EntityCollection, State } from '@irtio/schema';
 
 /**
@@ -138,6 +138,15 @@ declare class HarnessHost implements RoomHost {
     crashed(reason: string): void;
     hostCall(reqId: number, call: HostCall): void;
     private runHostCall;
+    /** D81: every clip the room wrote, in order: `clipId` -> the blob it was handed. */
+    readonly clips: Map<string, Uint8Array<ArrayBufferLike>>;
+    private nextClipId;
+    /** D81: every recording this room wrote: `recId` -> its chunks in the order they were sent. */
+    readonly recordings: Map<string, {
+        seq: number;
+        bytes: Uint8Array;
+    }[]>;
+    private nextRecordingId;
     /**
      * D44: the in-process harness has no supervisor, no sockets and therefore no loopback session
      * to open. Recording the request rather than faking a session is the honest option: a test that
@@ -267,6 +276,16 @@ interface FakeClient<S extends AnySchema = AnySchema> {
     readonly joinTick: number;
     /** Sends a `WRITE` update for `entity[id]` masking exactly the patch's leaves. */
     write(entity: string, id: string, patch: AnyRecord): void;
+    /** D77: sends a `WRITE` `add` — what a client of a `clientCreate` collection sends. */
+    add(entity: string, id: string, value: AnyRecord): void;
+    /** D77: sends a `WRITE` `remove`. */
+    remove(entity: string, id: string): void;
+    /** Non-fatal `ERROR` frames this client was sent, in order. The caps are read from here. */
+    readonly errors: readonly {
+        code: number;
+        message: string;
+        fatal: boolean;
+    }[];
     /** Sends an arbitrary framed payload (protocol-violation tests). */
     writeRaw(frame: Uint8Array): void;
     /** Client → server RPC. Settles when the `REPLY` is delivered — `h.tick()` first, then `await`. */
@@ -295,41 +314,6 @@ interface FakeClient<S extends AnySchema = AnySchema> {
     entity(name: string): EntityCollection;
 }
 
-/**
- * `createRoomHarness` — the in-process room harness. It runs a real `RoomCore`
- * against a fake clock and fake clients, in one synchronous, deterministic process. No sockets,
- * no worker, no Node built-ins: it runs anywhere Vitest does.
- *
- * ## Timing model
- *
- * The only clock is `FakeClock`. `h.tick(n)` advances exactly `n` tick intervals in tick mode
- * (running `n` ticks and delivering every frame they produce) and runs due timers without moving
- * the clock in event mode. `h.run(ms)` advances the clock by `ms`, firing ticks and timers in
- * order. Both return only after everything due has fired and every frame has been delivered.
- *
- * ## Frame delivery
- *
- * Frames the room sends are delivered to the `FakeClient` immediately (decoded, applied to its
- * view, traced). Frames a client sends are queued and handed to `RoomCore.receive` at the next
- * safe point — never re-entrantly inside the core — which is before `tick()`/`run()`/`join()`
- * returns, or immediately if nothing is currently executing.
- *
- * ## Promises
- *
- * `client.call()` settles when the `REPLY` is delivered, which happens inside a later
- * `h.tick()` / `h.run()`. Tests therefore read:
- *
- * ```ts
- * const p = a.call('start');
- * h.tick();
- * await expect(p).resolves.toEqual(...);
- * ```
- *
- * An **async** `onCall` implementation cannot reply synchronously: its `REPLY` is sent when the
- * promise settles, i.e. in a microtask. Tests must `await` (anything — `await null` is enough)
- * and then `h.tick()` so the room sees the reply.
- */
-
 interface HarnessOptions {
     /** `room.random()` seed; defaults to a hash of `roomId`, exactly as `RoomCore` does. */
     readonly seed?: number;
@@ -339,12 +323,22 @@ interface HarnessOptions {
     readonly roomId?: string;
     /** Bytes from a previous `serialize()`: the room wakes instead of being created. */
     readonly restoreFrom?: Uint8Array;
+    /** D77 / O28: the write-core caps this room runs under. Default: the record cap only. */
+    readonly caps?: WriteCaps;
+    /** D77: the wall clock hold deadlines are measured against. Default `Date.now`. */
+    readonly wallNow?: () => number;
 }
 interface JoinSpec {
     readonly role?: string;
     readonly name?: string;
     /** Default: `c1`, `c2`, … in join order. */
     readonly id?: string;
+    /**
+     * D77: the identity a hold binds to. Defaults to the client id, exactly as a real join does
+     * when the client presented no assertion — which is what makes the "another tab reclaims" and
+     * "a new browser does not" pair testable without a socket.
+     */
+    readonly playerId?: string;
 }
 interface UntilOptions {
     /** Default 1000. */

package/dist/test/index.js

@@ -5,7 +5,7 @@ import {
   initPhysics,
   initRapier2d,
   visibleNames
-} from "../chunk-EENJ37KK.js";
+} from "../chunk-LT46QFLW.js";
 
 // src/test/clock.ts
 var FakeClock = class {
@@ -203,8 +203,36 @@ var HarnessHost = class {
         if (existing === void 0 || call.score > existing) this.scores.set(key, call.score);
         return { ok: true };
       }
+      // ---- M6 lane N: replays ----
+      case "clip": {
+        const clipId = `clip${String(this.nextClipId++).padStart(4, "0")}`;
+        this.clips.set(clipId, call.bytes);
+        return { ok: true, value: clipId };
+      }
+      // ---- end M6 lane N ----
+      // ---- M6 record packet ----
+      case "record-chunk": {
+        const recId = call.recId ?? `rec${String(this.nextRecordingId++).padStart(4, "0")}`;
+        let chunks = this.recordings.get(recId);
+        if (!chunks) {
+          chunks = [];
+          this.recordings.set(recId, chunks);
+        }
+        chunks.push({ seq: call.seq, bytes: call.bytes });
+        return { ok: true, value: recId };
+      }
     }
   }
+  // ---- M6 lane N: replays ----
+  /** D81: every clip the room wrote, in order: `clipId` -> the blob it was handed. */
+  clips = /* @__PURE__ */ new Map();
+  nextClipId = 1;
+  // ---- end M6 lane N ----
+  // ---- M6 record packet ----
+  /** D81: every recording this room wrote: `recId` -> its chunks in the order they were sent. */
+  recordings = /* @__PURE__ */ new Map();
+  nextRecordingId = 1;
+  // ---- end M6 record packet ----
   // -------------------------------------------------------------------------
   // Week 12: durable alarms (D26)
   // -------------------------------------------------------------------------
@@ -293,6 +321,7 @@ import {
 import {
   FrameType,
   decodeCall,
+  decodeErrorPayload,
   decodeMsg,
   decodeReply,
   encodeCall,
@@ -311,7 +340,9 @@ import {
   decodeSnapshot,
   encodeDelta,
   encodeFields,
-  markField
+  markAdd,
+  markField,
+  markRemove
 } from "@irtio/schema";
 function structFields(t) {
   return Object.entries(t.fields).map(([name, type]) => ({ name, type }));
@@ -427,6 +458,34 @@ var FakeClientImpl = class {
   writeRaw(frame) {
     this.bridge.toCore(this.id, frame);
   }
+  // ---- M6 lane K: stateful relay ----
+  errors = [];
+  add(entity, id, value) {
+    const scratch = createState(this.bridge.ext);
+    entityOf(scratch, entity).add(id, value, { owner: this.id });
+    const dirty = createDirtySet();
+    markAdd(dirty, entity, id);
+    this.bridge.toCore(
+      this.id,
+      encodeFrame(
+        FrameType.WRITE,
+        encodeDelta(this.bridge.ext, scratch, dirty, { tick: this.bridge.tick })
+      )
+    );
+  }
+  remove(entity, id) {
+    const scratch = createState(this.bridge.ext);
+    const dirty = createDirtySet();
+    markRemove(dirty, entity, id);
+    this.bridge.toCore(
+      this.id,
+      encodeFrame(
+        FrameType.WRITE,
+        encodeDelta(this.bridge.ext, scratch, dirty, { tick: this.bridge.tick })
+      )
+    );
+  }
+  // ---- end M6 lane K ----
   call(name, params = {}) {
     const desc = this.descOf(name);
     const reqId = this.nextReqId++;
@@ -505,6 +564,13 @@ var FakeClientImpl = class {
       case FrameType.MSG:
         this.handleMsg(payload);
         return;
+      // ---- M6 lane K: stateful relay ----
+      case FrameType.ERROR: {
+        const e = decodeErrorPayload(payload);
+        this.errors.push({ code: e.code, message: e.message, fatal: e.fatal });
+        return;
+      }
+      // ---- end M6 lane K ----
       default:
         return;
     }
@@ -679,7 +745,11 @@ var Harness = class {
       roomId: options.roomId ?? "test-room",
       ...options.seed !== void 0 ? { seed: options.seed } : {},
       ...options.publicUrl !== void 0 ? { publicUrl: options.publicUrl } : {},
-      ...options.restoreFrom !== void 0 ? { restoreFrom: options.restoreFrom } : {}
+      ...options.restoreFrom !== void 0 ? { restoreFrom: options.restoreFrom } : {},
+      // ---- M6 lane K: stateful relay ----
+      ...options.caps !== void 0 ? { caps: options.caps } : {},
+      ...options.wallNow !== void 0 ? { wallNow: options.wallNow } : {}
+      // ---- end M6 lane K ----
     });
     this.host.core = this.coreRef;
     this.host.serializeForSave = () => this.coreRef.snapshot();
@@ -881,7 +951,10 @@ var Harness = class {
     const role = spec.role ?? roles[0] ?? "";
     const options = {
       role,
-      ...spec.name !== void 0 ? { name: spec.name } : {}
+      ...spec.name !== void 0 ? { name: spec.name } : {},
+      // ---- M6 lane K: stateful relay ----
+      ...spec.playerId !== void 0 ? { playerId: spec.playerId } : {}
+      // ---- end M6 lane K ----
     };
     const client = new FakeClientImpl(this.bridge, id, options);
     this.byId.set(id, client);

package/dist/worker/index.d.ts

@@ -1,5 +1,5 @@
-import { L as LogLevel, T as TimelineDump, k as RoomStats, b as HostCall, c as HostCallResult, R as RoomCoreApi, i as RoomHost } from '../contract-C5aqs49-.js';
-import { ErrorCodeName, ProfileSnapshot } from '@irtio/protocol';
+import { L as LogLevel, T as TimelineDump, p as RoomStats, c as HostCall, d as HostCallResult, i as RoomCoreApi, n as RoomHost } from '../contract-UEKTud1Z.js';
+import { ErrorCodeName, ProfileSnapshot, PlatformNotice } from '@irtio/protocol';
 import { NpcConfig, LeaveReason } from '@irtio/server';
 import '@irtio/schema';
 
@@ -132,6 +132,17 @@ type ToWorker = {
     name: string;
     from: string;
     payload: string;
+}
+/**
+ * M7 D-P2: the platform has something to tell this room's players, and the room gets the first
+ * look. Carries a `reqId` because the answer decides whether the supervisor broadcasts, so this
+ * is a request and not a notification — a rare thing on this side of the wire, and the reason is
+ * that a veto only means anything before the frame goes out.
+ */
+ | {
+    t: 'platformNotice';
+    reqId: number;
+    notice: PlatformNotice;
 } | {
     t: 'stop';
 };
@@ -224,6 +235,17 @@ type FromWorker = {
     reqId: number;
     ok: boolean;
 }
+/**
+ * M7 D-P2: the room's answer to a `platformNotice`. `broadcast: false` only when the handler
+ * returned exactly `false`. A handler that threw, a room with no handler, and a room whose core
+ * is not up all answer `true`, because the veto is a room saying "I will tell them myself" and
+ * none of those three said anything.
+ */
+ | {
+    t: 'platformNoticeResult';
+    reqId: number;
+    broadcast: boolean;
+}
 /** D41: the recorded timeline. `dump` absent when nobody armed the recorder. */
  | {
     t: 'timeline';
@@ -368,5 +390,17 @@ interface WorkerState {
  * killing the worker.
  */
 declare function handleMessage(state: WorkerState, host: RoomHost, post: (msg: FromWorker, transfer?: ArrayBuffer[]) => void, msg: ToWorker): Promise<void>;
+/**
+ * Replaces `Math.random` with sfc32 seeded from 16 host-supplied bytes.
+ *
+ * Box day 2 (2026-09-08) measured why this exists: two VMs restored from one golden snapshot
+ * handed their room workers **bit-for-bit identical `Math.random` streams** — V8 seeds a new
+ * isolate's PRNG from process state that a memory snapshot clones, and the kernel's VMGenID
+ * reseed does not reach it. `Math.random` is the only random primitive room code has (the
+ * sandbox refuses `node:crypto`), so an unseeded clone gives two different projects the same
+ * dice. The seed comes from the supervisor's clone-safe entropy mixer via `workerData`, so
+ * every worker — cold boot or restore, same VM or sibling clones — rolls its own.
+ */
+declare function seedMathRandom(seedHex: string): void;
 
-export { type FromWorker, type MigrationChainStep, type ToWorker, type WorkerState, createWorkerHost, handleMessage, transferList };
+export { type FromWorker, type MigrationChainStep, type ToWorker, type WorkerState, createWorkerHost, handleMessage, seedMathRandom, transferList };