@irtio/runtime 0.11.0 → 3.0.0

package/dist/{room-0FZBGyke.d.ts → room-CGbiPxi3.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 { 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-Hk4SkDtW.js';
+import { p as RoomHost, r as RoomStats, u as RpcTraceEntry, L as LogLevel, k as RoomCoreApi, l as RoomCoreOptions, n as RoomEventKind, y as TimelineRecorderOptions, T as TimelineDump, t as RpcTraceDump, q as RoomInspection, J as JoinOptions, e as JoinResult, d as HostCallResult } from './contract-BoCNAPZT.js';
 
 declare class Mulberry32 {
     /** Current internal state (u32). Survives hibernation. */
@@ -11,13 +11,6 @@ declare class Mulberry32 {
     next(): number;
 }
 
-/**
- * The internal seam between `RoomCore` (core/room.ts) and the modules it delegates to
- * (`loop`, `views`, `writes`, `rpc`, `messages`, `room-api`). Nothing here is public API —
- * `src/contract.ts` is. `RoomCore` implements `RoomInternals` structurally, so the modules
- * take it as a parameter and never import `room.ts` (no cycles).
- */
-
 type AnyRecord = Record<string, unknown>;
 /** `${collection}\0${id}` → leaf-path key → the value the runtime wrote for that leaf. */
 type AcceptedWrites = Map<string, Map<string, unknown>>;
@@ -36,9 +29,25 @@ interface ClientEntry {
      * reconnects, exactly like the client id it defaults to.
      */
     readonly playerId: string;
+    /**
+     * M8 lane 5: the verified identity subject behind this session, or `undefined` for a key join.
+     * Set once at the first join beside `playerId` and kept for the same reason: what a later HELLO
+     * on the same seat claims must not be able to change who the seat belongs to. `room.ban` reads
+     * it, and reading `undefined` is what makes "a key join cannot be banned durably" a fact of the
+     * data rather than a caveat in a doc.
+     */
+    readonly subject: string | undefined;
     role: string;
     name: string;
     connected: boolean;
+    /**
+     * `true` once this session's `WELCOME` snapshot has been encoded for the client, `false` while
+     * `join()` is running — including a resume, where the fresh snapshot supersedes anything the
+     * prior session held. `room.setRole` reads it: before the snapshot exists there is nothing to
+     * catch up, and a catch-up `DELTA` built pre-WELCOME would name record ids of collections the
+     * committed role cannot see.
+     */
+    welcomed: boolean;
     /** Pending `CORRECT` mask, encoded from current state at the next flush. */
     correction: DirtySet | undefined;
     /** Leaves this client's own accepted `WRITE`s produced during the current flush window. */
@@ -58,6 +67,13 @@ interface ClientEntry {
      * where on the server's tick stream its still-unjudged intents will land.
      */
     lastAppliedTick: number;
+    /**
+     * M7 pf3 (g): the room tick this client last joined at. The baseline `room.writerStaleness`
+     * measures from before the client's first write lands, so a fresh joiner in a long-running room
+     * is 0 ticks stale rather than `room.tick` ticks stale. Reset on every `join`, including a
+     * rejoin: a client that has just come back has not had a tick in which to write.
+     */
+    joinedTick: number;
     /**
      * Set at `join`: this client's own record(s) — its presence row and whatever entities its own
      * `onJoin` added, owned by it — as they stood right after join, per collection. Consumed once
@@ -87,6 +103,21 @@ interface QueuedFrame {
     readonly type: number;
     readonly payload: Uint8Array;
 }
+/**
+ * The managed registry of bodies that participate in the simulation and never reach the wire.
+ *
+ * Loosely typed here, as everything on this seam is; `@irtio/server`'s `UnsyncedBodies<Spec, Body>`
+ * is the typed surface room code sees. One instance per engine runtime, built in its constructor.
+ */
+interface UnsyncedRegistry {
+    create(key: string, spec: unknown): unknown;
+    get(key: string): unknown;
+    has(key: string): boolean;
+    remove(key: string): boolean;
+    readonly size: number;
+    keys(): IterableIterator<string>;
+    [Symbol.iterator](): IterableIterator<readonly [string, unknown]>;
+}
 /** What the core modules may do with the physics world (`core/physics.ts` implements it). */
 interface PhysicsApi {
     /** D45: which of the blessed engines this room is running. */
@@ -98,6 +129,11 @@ interface PhysicsApi {
     /** Body → schema, through the tracked proxies. */
     sync(): void;
     bodyFor(collection: string, id: string): unknown;
+    /** Switches one entity's body off (destroying it) or back on (rebuilt on the next reconcile). */
+    setSkipped(collection: string, id: string, on: boolean): void;
+    isSkipped(collection: string, id: string): boolean;
+    /** Bodies the world steps and the runtime owns, that no schema row and no wire byte describes. */
+    readonly unsynced: UnsyncedRegistry;
     /**
      * D72: every body this runtime tracks, in the same collection-then-instance order `sync()`
      * walks. Read-only and allocation-free: the pose history calls it once per tick to copy poses
@@ -125,6 +161,12 @@ interface LoopApi {
     clearTimer(handle: number): void;
     /** Drops every room timer (hibernation, stop). */
     clearAllTimers(): void;
+    /**
+     * The earliest pending room timer's due time on `host.now()`'s clock, or `undefined` when
+     * nothing is armed. Read at `serialize()` — before the timers are cleared — so the supervisor
+     * can guarantee the room is awake again by then. See `Loop.earliestTimerAt`.
+     */
+    earliestTimerAt(): number | undefined;
     /** Internal one-shot on the host clock (RPC timeouts in event mode). */
     after(ms: number, fn: () => void): void;
 }
@@ -157,6 +199,8 @@ interface RoomInternals {
     wallNow(): number;
     /** Runs a room handler; a throw is logged and counted, never rethrown. */
     guard<T>(name: string, fn: () => T): T | undefined;
+    /** `room.ban`. Returns the excluded subject, or `undefined` when the client is a key join. */
+    banClient(clientId: string, reason?: string, minutes?: number): string | undefined;
     /** D41: record this tick on the authoritative timeline. A no-op while the recorder is unarmed. */
     captureTimeline(): void;
     /**
@@ -167,6 +211,16 @@ interface RoomInternals {
     /** D72: `room.rewind(tick, fn)`. Throws when the room declares no `physics.history`. */
     rewind<T>(tick: number, fn: (past: RewindView) => T): T;
     recordEvent(kind: 'join' | 'leave' | 'write' | 'write-rejected' | 'correct' | 'call' | 'reply' | 'msg' | 'alarm' | 'bus' | 'error', clientId?: string, detail?: string): void;
+    /**
+     * M7 pf4: file one RPC on the dev trace ring. A no-op in a room that was not started with
+     * `traceRpc: true`, which is every room outside `irtio dev` and `testRoom`.
+     */
+    recordRpc(entry: Omit<RpcTraceEntry, 'seq'>): void;
+    /**
+     * M7 pf4: whether a trace ring exists. Callers check this before building anything, so the
+     * unarmed path — every production room — costs one boolean read and allocates nothing.
+     */
+    readonly rpcTraceArmed: boolean;
     /** `guard` that also reports whether the handler threw (the tick loop needs this). */
     tryRun<T>(name: string, fn: () => T): GuardResult<T>;
     log(level: LogLevel, ...args: unknown[]): void;
@@ -239,6 +293,14 @@ declare class Loop implements LoopApi {
     private consecutiveThrows;
     private lastActivity;
     private slept;
+    /**
+     * Whether this idle stretch has already spent its one deferral for a nearly-due room timer.
+     *
+     * Once, deliberately. A `setInterval(100)` in an otherwise silent room must not be able to pin
+     * the room resident forever — pending timers are explicitly *not* a reason to stay awake, the
+     * supervisor wakes the room at the due time instead. Reset by real activity.
+     */
+    private timerDeferred;
     constructor(core: RoomInternals);
     get intervalMs(): number;
     start(): void;
@@ -246,7 +308,27 @@ declare class Loop implements LoopApi {
     enqueue(frame: QueuedFrame): void;
     dropFramesFor(clientId: string): void;
     private drainInbound;
-    /** Applies one queued/immediate frame. Returns `false` on a malformed payload. */
+    /**
+     * Applies one queued/immediate frame. Returns `false` on a malformed payload.
+     *
+     * The `try` is containment, not error handling, and it is deliberately *here* rather than around
+     * the whole tick. Room code never throws through this line — `applyWrite` runs its validators
+     * under `core.tryRun`, and `handleCall` wraps the RPC handler in a `try` of its own that does
+     * the same bookkeeping by hand (`DenyError` answered as a refusal, anything else counted on
+     * `core.stats.handlerErrors` and answered `E_INTERNAL`) — so a throw that reaches this frame is by
+     * definition ours: a decode or an apply step that met a value it did not expect. Before this,
+     * such a throw went out through `runTick`/`applyEvent` uncaught and took the worker down, which
+     * meant one crafted frame could end a room (bugs.md: the non-finite `f32`, fixed at the decode
+     * in `@irtio/schema`, reached `normalizeValue` from outside `applyWrite`'s own try).
+     *
+     * Containing it at the frame keeps the blast radius the size of the mistake: the frame is
+     * *this* client's, so it is refused as malformed and the caller kicks that connection, and the
+     * room — every other player in it — keeps ticking. Wrapping the tick instead would have swallowed
+     * the frame's identity along with the throw and left the room running against half-applied
+     * state with nobody to attribute it to.
+     *
+     * Nothing about how a *handler* throw is treated changes: those never arrive here.
+     */
     applyFrame(f: QueuedFrame): boolean;
     private scheduleTick;
     private onWake;
@@ -261,6 +343,20 @@ declare class Loop implements LoopApi {
     setTimer(ms: number, fn: () => void, repeat: boolean): number;
     private armHostTimer;
     clearTimer(handle: number): void;
+    /**
+     * The earliest pending room timer's due time on `host.now()`'s clock, or `undefined` when the
+     * room has none armed.
+     *
+     * Read at `serialize()`, before `clearAllTimers()` drops the callbacks. The callbacks are
+     * closures and cannot be persisted — but the *time* can, and handing it to the supervisor is
+     * what turns "your timer is gone" into "your room is awake again by then", which is a contract
+     * room code can actually catch up against in `onWake`.
+     *
+     * Event mode reads the absolute due time stamped on the record at arm time; tick mode derives
+     * it from `dueTick`, because there a timer fires on the first tick at or after its deadline and
+     * the tick counter is the clock that decides it.
+     */
+    earliestTimerAt(): number | undefined;
     clearAllTimers(): void;
     after(ms: number, fn: () => void): void;
 }
@@ -316,6 +412,35 @@ interface MatterBodyRecord {
 }
 interface MatterSection {
     readonly bodies: readonly MatterBodyRecord[];
+    /**
+     * `${collection}\0${id}` for every entity whose body the room has switched off. Written as a
+     * trailing block only when non-empty, so a room that skips nothing emits the bytes it emitted
+     * before this existed. See `PhysicsSection.skipped`.
+     */
+    readonly skipped?: readonly string[];
+    /**
+     * The state of every managed unsynced body, by key.
+     *
+     * Unlike the two Rapier engines, matter2d has no world snapshot to bring the bodies themselves
+     * back: the world is rebuilt on every wake and `setup` runs again. So what rides here is what
+     * the runtime can reapply to a body `setup` has rebuilt under the same key, which is its pose,
+     * its velocity, and whether it was asleep. That is exactly what this section already does for
+     * entity-backed matter bodies, and it carries the same consequence: an unsynced body a matter2d
+     * room creates *outside* `setup` cannot come back, and the runtime says so by name on the wake
+     * that finds it missing.
+     */
+    readonly unsynced?: readonly MatterUnsyncedRecord[];
+}
+/** M7 pf3 (a): one unsynced body's restorable state. A `MatterBodyRecord` keyed by string. */
+interface MatterUnsyncedRecord {
+    readonly key: string;
+    readonly x: number;
+    readonly y: number;
+    readonly angle: number;
+    readonly vx: number;
+    readonly vy: number;
+    readonly angularVelocity: number;
+    readonly sleeping: boolean;
 }
 declare function encodeMatterBodies(section: MatterSection): Uint8Array;
 declare function decodeMatterBodies(bytes: Uint8Array): MatterSection;
@@ -355,10 +480,36 @@ declare class MatterRuntime {
     private readonly sourceRecords;
     /** `collection.field` pairs already warned about a channel a plane cannot hold. */
     private readonly warnedChannels;
+    /** See `PhysicsRuntime.skippedKeys`: entities whose body the room has switched off. */
+    private readonly skippedKeys;
+    private readonly unsyncedBodies;
+    /** Saved unsynced state, consumed as `setup` rebuilds each body under the same key. */
+    private restoreUnsynced;
+    /** One-shot: the first reconcile after a wake reports whatever `setup` did not rebuild. */
+    private reportedMissingUnsynced;
+    readonly unsynced: UnsyncedRegistry;
     constructor(core: RoomInternals, matter: MatterModule, options: MatterRuntimeOptions);
     get timestep(): number;
     runSetup(room: Room): void;
     free(): void;
+    /**
+     * bugs.md #100, the matter2d half. Rapier's bindings wake a contact island themselves when a
+     * member is removed (`PhysicsRuntime.destroyBody` / `Rapier2dRuntime.destroyBody`); matter.js
+     * does not, so a body sleeping against a victim about to be removed is left sleeping and
+     * motionless in mid-air once the victim is gone.
+     *
+     * `enableSleeping` is a property the room's own `setup` sets on `engine` (there is no config
+     * flag for it), so this only runs the geometry query when the room has actually turned sleeping
+     * on. `Matter.Query.collides` is matter's public narrow-phase check against a body's current
+     * vertices, run here against every other body in the world; it costs nothing extra to compute
+     * (matter.js does not expose a per-body contact list the way rapier's bindings do) but is bounded
+     * by the same room body count that every reconcile already walks. Sensors are skipped, matching
+     * the rapier fix: an intersection pair is not an island edge.
+     */
+    private wakeContactsOf;
+    /** The matter.js half of `PhysicsRuntime.setSkipped`; its comment is the whole argument. */
+    setSkipped(collection: string, id: string, on: boolean): void;
+    isSkipped(collection: string, id: string): boolean;
     bodyFor(collection: string, id: string): MatterBody | undefined;
     private create;
     /**
@@ -428,6 +579,27 @@ interface PhysicsSection {
      * whatever was created first (for pachinko, the floor).
      */
     readonly bodies: readonly (readonly [string, string, number])[];
+    /**
+     * `${collection}\0${id}` for every entity whose body the room has switched off. The set has to
+     * survive a wake or a room full of dormant spiders wakes up simulating all of them: the rows
+     * come back from the snapshot, `reconcile` sees rows with no body, and builds one for each.
+     *
+     * It rides as a **trailing block, written only when non-empty**, so a room that skips nothing
+     * emits the bytes it emitted before this existed — which is every blob ever written. The
+     * decoder reads it only when there is something left after the body map.
+     */
+    readonly skipped?: readonly string[];
+    /**
+     * `[key, handle]` for every managed unsynced body, in creation order.
+     *
+     * The world snapshot already carries the bodies themselves — they are ordinary Rapier bodies —
+     * so what has to ride here is only *which handle is which key*, exactly as `bodies` above does
+     * for entity-backed bodies. Losing that map is the leak this feature retires: a woken room with
+     * bodies it can no longer name is a room that can never remove them.
+     *
+     * Written in the same trailing block as {@link skipped}, and only when there is something to say.
+     */
+    readonly unsynced?: readonly (readonly [string, number])[];
 }
 declare function encodePhysicsSection(section: PhysicsSection): Uint8Array;
 /**
@@ -510,11 +682,60 @@ declare class PhysicsRuntime {
     private readonly sourceRecords;
     /** `collection.field` pairs already warned about a channel value the engine would not take. */
     private readonly warnedChannels;
+    /**
+     * Entities whose body the room has switched off. See {@link setSkipped} for what "off" means and
+     * why it is spelled as "no body" rather than as "a body that is not stepped".
+     */
+    private readonly skippedKeys;
+    /**
+     * Bodies with no schema row: rope anchors, dead-reckoned proxies, one-off sensors. Keyed by the
+     * room's own string rather than by `collection\0id`, because there is no collection and no id.
+     */
+    private readonly unsyncedBodies;
+    readonly unsynced: UnsyncedRegistry;
     constructor(core: RoomInternals, rapier: RapierModule, options: PhysicsRuntimeOptions);
     get timestep(): number;
     /** Runs the room's `setup` — static geometry — on a world that was built rather than restored. */
     runSetup(room: Room): void;
     free(): void;
+    /**
+     * bugs.md #99: every teardown path goes through here rather than calling `removeRigidBody`
+     * directly.
+     *
+     * A sleeping body is parked in an island wired through the contact graph. Pulling a body out
+     * from under one leaves the sleeper resting on nothing — and, in the failure this guards, leaves
+     * the island holding a body that no longer exists. Waking the contacting bodies first makes the
+     * removal a plain awake-island edit, and it is also what a room wants physically: the crate the
+     * floor vanished under should fall.
+     *
+     * The cost is one narrow-phase lookup per collider of the *victim* — `contactPairsWith` walks
+     * only that collider's own contact pairs — against the alternative of waking the world, which
+     * would un-sleep every dormant body in the room on every teardown. Sensors are skipped
+     * deliberately: an intersection pair is not an island edge, so it cannot be the thing at risk.
+     */
+    private destroyBody;
+    /**
+     * Switches one entity's body off, or back on.
+     *
+     * Undercity feedback 29: hundreds of dormant-by-design entities want "exists and syncs, but do
+     * not step or mirror until I say so". Rapier's own sleeping approximates it and still costs a
+     * broadphase entry and a sync slot per row per tick, and a sleeping body wakes on contact,
+     * which a dormant spider must not.
+     *
+     * **Skipped means no body.** The body is destroyed on the way in and rebuilt from the schema
+     * row on the way out, on the next `reconcile`. The alternative — keep the body, exclude it from
+     * the step — is not something an engine offers per body without also excluding it from
+     * collision, and it would leave the cost this exists to remove (a body in the world, in the
+     * broadphase, walked by `sync`) exactly where it was. The row is untouched and goes on syncing
+     * as ordinary state, which is what the ask asked for; a room that moves a skipped entity by
+     * assigning its fields is moving it, and unskipping resumes from wherever the row now says.
+     *
+     * What is lost across a skip is what a body has and a row does not: contacts, and velocity
+     * beyond the f32 the row carries. A skipped entity resumes at rest at its row's pose unless the
+     * row's velocity channels say otherwise.
+     */
+    setSkipped(collection: string, id: string, on: boolean): void;
+    isSkipped(collection: string, id: string): boolean;
     /** The body behind an instance, created on demand so a handler's own `add` is usable at once. */
     bodyFor(collection: string, id: string): RapierRigidBody | undefined;
     private create;
@@ -628,11 +849,25 @@ declare class Rapier2dRuntime {
     private readonly sourceRecords;
     /** `collection.field` pairs already warned about a channel value the engine would not take. */
     private readonly warnedChannels;
+    /** See `PhysicsRuntime.skippedKeys`: entities whose body the room has switched off. */
+    private readonly skippedKeys;
+    /** See `PhysicsRuntime.unsyncedBodies`: bodies the world steps that no schema row describes. */
+    private readonly unsyncedBodies;
+    readonly unsynced: UnsyncedRegistry;
     constructor(core: RoomInternals, rapier: Rapier2dModule, options: Rapier2dRuntimeOptions);
     get timestep(): number;
     /** Runs the room's `setup` — static geometry — on a world that was built rather than restored. */
     runSetup(room: Room): void;
     free(): void;
+    /**
+     * bugs.md #99, planar half: the teardown door every removal goes through. See
+     * `PhysicsRuntime.destroyBody` for the argument — one narrow-phase walk of the victim's own
+     * contact pairs, so a body resting on what is about to vanish is awake when it does.
+     */
+    private destroyBody;
+    /** The planar half of `PhysicsRuntime.setSkipped`; its comment is the whole argument. */
+    setSkipped(collection: string, id: string, on: boolean): void;
+    isSkipped(collection: string, id: string): boolean;
     /** The body behind an instance, created on demand so a handler's own `add` is usable at once. */
     bodyFor(collection: string, id: string): Rapier2dRigidBody | undefined;
     private create;
@@ -693,8 +928,15 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     readonly rng: Mulberry32;
     readonly clients: Map<string, ClientEntry>;
     readonly loop: Loop;
-    /** D22: the Rapier world, or `undefined` in a room whose config declares no physics. */
-    readonly physics: PhysicsRuntime | MatterRuntime | Rapier2dRuntime | undefined;
+    /**
+     * D22: the Rapier world, or `undefined` in a room whose config declares no physics.
+     *
+     * Not `readonly`, and the reason is M7 pf3 (a): each builder installs the runtime here *before*
+     * it calls `runSetup`, so `room.physics*` is readable from inside `physics.setup`. That is
+     * where an unsynced body belongs — it is static geometry with a handle — and it is the only
+     * place a matter2d room can put one and have it come back after a wake.
+     */
+    physics: PhysicsRuntime | MatterRuntime | Rapier2dRuntime | undefined;
     readonly stats: RoomStats;
     tick: number;
     stopped: boolean;
@@ -713,6 +955,11 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
      * end of every tick, which is the only moment in a tick where that state is settled.
      */
     private recorder;
+    /**
+     * M7 pf4: the RPC trace ring, constructed only when `RoomCoreOptions.traceRpc` asked for one.
+     * Every cost this lane has is behind this `undefined` — see `core/rpc-trace.ts`.
+     */
+    private readonly rpcTraceRing;
     /**
      * D65: the bandwidth ledger, present only when `RoomCoreOptions.profile` asked for one. Every
      * cost the profiler has is behind this `undefined`.
@@ -734,6 +981,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.
      *
@@ -796,6 +1063,19 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     recording(): TimelineDump | undefined;
     /** D41: called at the end of every tick (and every event-mode flush). No-op when unarmed. */
     captureTimeline(): void;
+    /**
+     * M7 pf4: file one RPC on the trace. Called from `core/rpc.ts` on every exit path a call has,
+     * and a no-op — not merely a cheap one, an untaken branch — in a room nobody armed.
+     */
+    recordRpc(entry: Omit<RpcTraceEntry, 'seq'>): void;
+    /**
+     * M7 pf4: whether this room has a trace ring at all. Read **before** an entry is built, so an
+     * unarmed room pays one property read per call rather than building an entry object and
+     * serializing a result for `recordRpc` to drop on the floor.
+     */
+    get rpcTraceArmed(): boolean;
+    /** M7 pf4: the trace so far, or `undefined` when this room was not armed. */
+    rpcTrace(): RpcTraceDump | undefined;
     /**
      * D72: record this tick's body poses, right after `physics.sync()` — the poses the clients are
      * about to be told about, under the tick number they will be told it under, which is the tick a
@@ -825,9 +1105,49 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
      * written.
      */
     snapshot(): Uint8Array;
+    /**
+     * The earliest pending room timer's due time at the last `serialize()`, on `host.now()`'s
+     * clock, or `undefined` if nothing was armed.
+     *
+     * `serialize()` is the departure, and it drops every room timer because a callback is a closure
+     * and there is nothing to persist. The *deadline* is persistable, though, and this is where the
+     * worker reads it to hand to the supervisor, which arms a wake for it. The contract room code
+     * gets: your callback does not survive hibernation, but your room is awake again at or shortly
+     * after the time it would have fired — so keep the deadline in state and catch up in `onWake`.
+     *
+     * Captured before `clearAllTimers()`, which is the only ordering that could ever have worked.
+     */
+    lastSerializeTimerAt: number | undefined;
     serialize(): Uint8Array;
     private get presence();
     private resolveRole;
+    /**
+     * Subjects `room.ban` has excluded, and when each stops being excluded. Values are wall-clock
+     * deadlines from `host.now()`; `Number.POSITIVE_INFINITY` is the default, "until this room
+     * closes".
+     *
+     * In memory and nowhere else, by decision. It is not in `state`, so it is not in a snapshot, so a
+     * hibernation drops it and a wake starts clean — the same call relay audience membership made,
+     * and for the same reason: this is a fact about a sitting, not about a save file. Exclusion that
+     * outlives a wake is what the control plane's `project_bans` is for, and that one is durable
+     * because it is a row in a database rather than a `Map` in a worker.
+     */
+    private readonly banned;
+    /**
+     * The room's own refusal, before a seat exists. Throws {@link AdmissionError} or returns.
+     *
+     * Order matters and is deliberate: the cooldown is checked first, so a subject the room already
+     * threw out cannot spend the room's `onAdmit` budget on every reconnect attempt.
+     */
+    private admit;
+    /**
+     * `room.ban`: kick this client and keep its subject out for a while.
+     *
+     * Returns the subject it excluded, or `undefined` when there was nothing durable to exclude —
+     * a key join, whose only name is a client id it can mint again. The kick happens either way,
+     * because a kick is a real thing to do to a session even when the exclusion cannot follow it.
+     */
+    banClient(clientId: string, reason?: string, minutes?: number): string | undefined;
     join(clientId: string, options?: JoinOptions): JoinResult;
     /** Event mode only: presence/lifecycle changes are their own event. No-op in tick mode. */
     private eventFlush;
@@ -881,6 +1201,8 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     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-0FZBGyke.js';
-export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-0FZBGyke.js';
+import { R as RoomCore } from '../room-CGbiPxi3.js';
+export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-CGbiPxi3.js';
 import { ErrorCodeName, FrameType } from '@irtio/protocol';
 import { NpcConfig, LeaveReason, Room, RoomDefinition } from '@irtio/server';
-import { n as RoomHost, L as LogLevel, i as RoomCoreApi, c as HostCall, d as HostCallResult, W as WriteCaps, p as RoomStats } from '../contract-Hk4SkDtW.js';
+import { p as RoomHost, L as LogLevel, k as RoomCoreApi, c as HostCall, d as HostCallResult, W as WriteCaps, r as RoomStats } from '../contract-BoCNAPZT.js';
 import { AnySchema, PlainState, EntityCollection, State } from '@irtio/schema';
 
 /**
@@ -141,6 +141,12 @@ declare class HarnessHost implements RoomHost {
     /** 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
@@ -283,7 +289,12 @@ interface FakeClient<S extends AnySchema = AnySchema> {
     /** 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`. */
-    call(name: string, params?: AnyRecord): Promise<unknown>;
+    /**
+     * `clientTick` is D72's caller stamp — the tick this client claims it was looking at. Real
+     * clients set it from their own state store; a fake one has to be told, and M7 pf4's stamp-lag
+     * column has nothing to show without it.
+     */
+    call(name: string, params?: AnyRecord, clientTick?: number): Promise<unknown>;
     /** The built-in `requestOwnership` RPC. */
     requestOwnership(entity: string, id: string): Promise<boolean>;
     /** Out-of-band `MSG`. */
@@ -317,6 +328,11 @@ interface HarnessOptions {
     readonly roomId?: string;
     /** Bytes from a previous `serialize()`: the room wakes instead of being created. */
     readonly restoreFrom?: Uint8Array;
+    /**
+     * M7 pf4: arm this room's RPC trace ring, so `h.core.rpcTrace()` answers something. Off by
+     * default, exactly as a deployed room is.
+     */
+    readonly traceRpc?: boolean;
     /** 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`. */
@@ -333,6 +349,12 @@ interface JoinSpec {
      * "a new browser does not" pair testable without a socket.
      */
     readonly playerId?: string;
+    /**
+     * The verified subject this join presents, or absent for a key join. Absent is the default,
+     * because a harness join presents no credential — which is exactly the case a room with an
+     * `onAdmit` that requires identity needs to be tested against.
+     */
+    readonly subject?: string;
 }
 interface UntilOptions {
     /** Default 1000. */

package/dist/test/index.js

@@ -5,7 +5,7 @@ import {
   initPhysics,
   initRapier2d,
   visibleNames
-} from "../chunk-GYPUNTQN.js";
+} from "../chunk-NPRIYYNM.js";
 
 // src/test/clock.ts
 var FakeClock = class {
@@ -209,6 +209,18 @@ var HarnessHost = class {
         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 ----
@@ -216,6 +228,11 @@ var HarnessHost = class {
   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)
   // -------------------------------------------------------------------------
@@ -469,7 +486,7 @@ var FakeClientImpl = class {
     );
   }
   // ---- end M6 lane K ----
-  call(name, params = {}) {
+  call(name, params = {}, clientTick) {
     const desc = this.descOf(name);
     const reqId = this.nextReqId++;
     return new Promise((resolve, reject) => {
@@ -477,7 +494,8 @@ var FakeClientImpl = class {
       const payload = encodeCall({
         reqId,
         rpcId: desc.index,
-        params: encodeFields(desc.params, params)
+        params: encodeFields(desc.params, params),
+        ...clientTick !== void 0 ? { clientTick } : {}
       });
       this.bridge.toCore(this.id, encodeFrame(FrameType.CALL, payload));
     });
@@ -729,6 +747,7 @@ var Harness = class {
       ...options.seed !== void 0 ? { seed: options.seed } : {},
       ...options.publicUrl !== void 0 ? { publicUrl: options.publicUrl } : {},
       ...options.restoreFrom !== void 0 ? { restoreFrom: options.restoreFrom } : {},
+      ...options.traceRpc === true ? { traceRpc: true } : {},
       // ---- M6 lane K: stateful relay ----
       ...options.caps !== void 0 ? { caps: options.caps } : {},
       ...options.wallNow !== void 0 ? { wallNow: options.wallNow } : {}
@@ -936,8 +955,11 @@ var Harness = class {
       role,
       ...spec.name !== void 0 ? { name: spec.name } : {},
       // ---- M6 lane K: stateful relay ----
-      ...spec.playerId !== void 0 ? { playerId: spec.playerId } : {}
+      ...spec.playerId !== void 0 ? { playerId: spec.playerId } : {},
       // ---- end M6 lane K ----
+      // ---- M8 lane 5: moderation ----
+      ...spec.subject !== void 0 ? { subject: spec.subject } : {}
+      // ---- end M8 lane 5 ----
     };
     const client = new FakeClientImpl(this.bridge, id, options);
     this.byId.set(id, client);