@irtio/runtime 0.1.0 → 0.3.0

package/dist/room-9ZQoy9yi.d.ts

@@ -0,0 +1,458 @@
+import { DirtySet, AnySchema, PlainState, Tracked, State } from '@irtio/schema';
+import { RoomDefinition, RoomMode, Room, Ctx, RapierModule, RapierWorld, RapierRigidBody, ResolvedRoomConfig, LeaveReason } from '@irtio/server';
+import { h as RoomHost, j as RoomStats, L as LogLevel, R as RoomCoreApi, d as RoomCoreOptions, f as RoomEventKind, i as RoomInspection, J as JoinOptions, c as JoinResult, b as HostCallResult } from './contract-B8QSO0MH.js';
+
+/**
+ * `room.random()` — mulberry32 over a u32 seed. Deterministic, tiny, and serializable: the
+ * generator's whole state is one u32, so `serialize()`/`restore()` round-trip it exactly.
+ */
+declare class Mulberry32 {
+    /** Current internal state (u32). Survives hibernation. */
+    state: number;
+    constructor(seed: number);
+    /** Next float in `[0, 1)`. */
+    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>>;
+/** One joined client. Presence is the wire truth; this is the runtime's bookkeeping. */
+interface ClientEntry {
+    readonly clientId: string;
+    /**
+     * D25: the identity `ctx.playerId` reports. Set once at the first join and kept across
+     * reconnects, exactly like the client id it defaults to.
+     */
+    readonly playerId: string;
+    role: string;
+    name: string;
+    connected: 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. */
+    readonly accepted: AcceptedWrites;
+    /**
+     * The tick stamped on the last `WRITE` this client sent (the client-local write counter in the
+     * delta header — week 8, D19), `0` before its first write. Every `CORRECT` sent to this client
+     * carries it as `clientTick`: "your writes through this tick are reflected in these values".
+     * An unprompted correction (a server-wins overwrite with no triggering write) echoes it
+     * unchanged — for a client that never wrote, that is `0`.
+     */
+    lastClientTick: number;
+    /**
+     * The room tick `lastClientTick`'s write was applied at, `0` before this client's first write.
+     * Sent alongside it on every `CORRECT` (bug 1). The two are a pair — one number on the
+     * client's stamp clock, one on the room's — and the client uses the gap between them to learn
+     * where on the server's tick stream its still-unjudged intents will land.
+     */
+    lastAppliedTick: 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
+     * by the very next `flush()`, which strips exactly the ids whose value (and owner) still match
+     * this capture from this client's delta only — an id mutated again before that flush (e.g. a
+     * same-window `room.setRole`) is left alone, since the join snapshot never saw that value.
+     * Every other client's delta is unaffected.
+     */
+    pendingJoinAdds: Map<string, ReadonlyMap<string, JoinAddCapture>> | undefined;
+    /** Last AOI membership sent to this client, keyed by spatial collection. */
+    spatialMembership: Map<string, Set<string>>;
+}
+/** What `join` captured for one of a client's own just-added records, for `flush`'s comparison. */
+interface JoinAddCapture {
+    readonly value: unknown;
+    readonly owner: string | undefined;
+}
+type GuardResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+};
+/** One queued inbound frame (tick mode). */
+interface QueuedFrame {
+    readonly clientId: string;
+    readonly type: number;
+    readonly payload: Uint8Array;
+}
+/** What the core modules may do with the physics world (`core/physics.ts` implements it). */
+interface PhysicsApi {
+    readonly timestep: number;
+    /** Creates bodies for new instances, destroys bodies whose instance is gone. */
+    reconcile(): void;
+    step(): void;
+    /** Body → schema, through the tracked proxies. */
+    sync(): void;
+    bodyFor(collection: string, id: string): unknown;
+    readonly rapier: unknown;
+    readonly world: unknown;
+}
+interface LoopApi {
+    start(): void;
+    stop(): void;
+    /** Event mode: an inbound frame or a join re-arms the idle timer. */
+    noteActivity(): void;
+    /** `room.setTimeout` / `room.setInterval`. Returns a numeric handle. */
+    setTimer(ms: number, fn: () => void, repeat: boolean): number;
+    clearTimer(handle: number): void;
+    /** Drops every room timer (hibernation, stop). */
+    clearAllTimers(): void;
+    /** Internal one-shot on the host clock (RPC timeouts in event mode). */
+    after(ms: number, fn: () => void): void;
+}
+/** What the core modules are allowed to see of `RoomCore`. */
+interface RoomInternals {
+    readonly definition: RoomDefinition;
+    /** `withBuiltins(definition.schema)` — what every frame and the codec use. */
+    readonly ext: AnySchema;
+    readonly host: RoomHost;
+    readonly roomId: string;
+    readonly mode: RoomMode;
+    /** The plain state the tracked proxies wrap (what the codec reads). */
+    readonly plain: PlainState;
+    readonly tracked: Tracked<AnySchema>;
+    /** The tracked proxy tree, loosely typed for internal use. */
+    readonly anyState: AnyRecord;
+    readonly room: Room;
+    readonly rng: Mulberry32;
+    readonly stats: RoomStats;
+    /** Joined clients in join order. */
+    readonly clients: Map<string, ClientEntry>;
+    readonly loop: LoopApi;
+    /** D22: the Rapier world, `undefined` in a room with no `physics:` config. */
+    readonly physics: PhysicsApi | undefined;
+    tick: number;
+    stopped: boolean;
+    /** Runs a room handler; a throw is logged and counted, never rethrown. */
+    guard<T>(name: string, fn: () => T): T | undefined;
+    recordEvent(kind: 'join' | 'leave' | 'write' | 'write-rejected' | 'correct' | 'call' | 'reply' | 'msg' | 'alarm' | 'error', clientId?: string, detail?: string): void;
+    /** `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;
+    /** Sends one framed protocol frame to a connected client and counts it. */
+    send(clientId: string, frame: Uint8Array): void;
+    ctxFor(clientId: string, reconnecting?: boolean): Ctx;
+    /** The client's pending `CORRECT` dirty set, created on demand. */
+    correctionFor(clientId: string): DirtySet | undefined;
+    /** Flushes the tracked dirty set: corrections first, then one `DELTA` per distinct view. */
+    flush(): void;
+    /** Invalidates the cached `room.clients` array. */
+    invalidateClients(): void;
+}
+
+/**
+ * Scheduling: the tick-mode fixed-step loop with catch-up, event-mode idle detection, and
+ * `room.setTimeout` / `room.setInterval`.
+ *
+ * Tick mode: one host timeout re-armed every `1000 / tickRate` ms. Each wake accumulates real
+ * elapsed time and runs up to `MAX_CATCHUP` ticks; a bigger backlog is dropped and counted as an
+ * overrun (logged once per burst). Room timers are tick-granular: `setTimeout(ms)` fires on the
+ * first tick at or after `now + ms`.
+ *
+ * Event mode: no tick timer. Room timers fire on the host clock, each firing advancing the tick
+ * and flushing. After `idleMs` with no inbound frames the host is asked to hibernate exactly once
+ * (re-armed by the next frame or join). Connected sockets do not keep an event room awake — a quiz
+ * hibernates between rounds with everyone still watching.
+ *
+ * Both modes hibernate, but "idle" cannot mean the same thing in each. A tick room *simulates* by
+ * definition: no inbound frames is its steady state, not its idleness. So a tick room sleeps after
+ * `idleMs` with **no connected clients**, which is the only sense in which a simulation nobody is
+ * watching is doing nothing worth paying for. `idleMs: 0` opts out in either mode and keeps the
+ * room resident (the same meaning it already has for relay rooms in the supervisor).
+ */
+
+/** Most ticks one wake may run before the backlog is dropped. */
+declare const MAX_CATCHUP = 5;
+/**
+ * Consecutive ticks in which a guarded stage threw before the host is told the room crashed.
+ *
+ * Any of them counts, not just `tick()` (bug 2). A room that cannot step its physics is not
+ * running — it is a socket that answers with a frozen world — and the runtime is the only thing
+ * that can tell the difference, because it is the only thing that sees the throw. The specific
+ * way this was found is worth keeping: one Rapier getter called from a room handler at the wrong
+ * moment leaves the rigid-body set borrowed in WASM, and *every* Rapier call after it throws.
+ * Nothing in JS can un-poison that world, so the honest response is to stop claiming to be up:
+ * crashing hands the room to the supervisor, which restarts it from its snapshot with a fresh
+ * world, and gives up out loud if the same thing happens again (`maxRestartsPerMin`).
+ */
+declare const CRASH_AFTER_THROWS = 3;
+declare class Loop implements LoopApi {
+    private readonly core;
+    readonly inbound: QueuedFrame[];
+    private readonly timers;
+    private readonly internal;
+    private nextTimerId;
+    private tickHandle;
+    private idleHandle;
+    private running;
+    private lastWake;
+    private accumulator;
+    private overrunLogged;
+    private consecutiveThrows;
+    private lastActivity;
+    private slept;
+    constructor(core: RoomInternals);
+    get intervalMs(): number;
+    start(): void;
+    stop(): void;
+    enqueue(frame: QueuedFrame): void;
+    dropFramesFor(clientId: string): void;
+    private drainInbound;
+    /** Applies one queued/immediate frame. Returns `false` on a malformed payload. */
+    applyFrame(f: QueuedFrame): boolean;
+    private scheduleTick;
+    private onWake;
+    /** One tick: inbound → room timers → `tick(state, dt, room)` → physics step → flush. */
+    runTick(): void;
+    private fireDueTimers;
+    /** Applies one frame as its own event: tick++, apply, flush. */
+    applyEvent(f: QueuedFrame): boolean;
+    noteActivity(): void;
+    private armIdle;
+    private onIdleCheck;
+    setTimer(ms: number, fn: () => void, repeat: boolean): number;
+    private armHostTimer;
+    clearTimer(handle: number): void;
+    clearAllTimers(): void;
+    after(ms: number, fn: () => void): void;
+}
+
+/**
+ * D22 part 1: the Rapier world inside the room.
+ *
+ * ## Where it sits in a tick
+ *
+ *   inbound frames (intents land) → room timers → `tick()` handler (forces) →
+ *   **reconcile → step → sync** → flush
+ *
+ * `reconcile` creates a body for every physics-backed instance that lacks one and destroys the
+ * bodies of instances that are gone; `step` advances the world by one fixed timestep; `sync`
+ * writes each body's declared channels back into the tracked schema state, so body movement
+ * leaves the room as an ordinary `DELTA` (and, for a client-owned body, as an unprompted
+ * `CORRECT` — server wins, week-8 semantics, intents replay and positions obey).
+ *
+ * Everything here iterates **in collection order** and then in instance (Map insertion) order:
+ * D34.3 promoted that to a stated guarantee, and body creation order is what decides Rapier's
+ * internal handle order, which is what makes the same build reproduce the same world.
+ *
+ * ## Determinism and the snapshot
+ *
+ * The world rides inside the hibernation blob (`snapshot.ts` writes the section this module
+ * encodes), so wake is atomic: state and world come back from the same bytes. Rapier's own
+ * `takeSnapshot()`/`restoreSnapshot()` preserves body handles, but not which entity each handle
+ * belongs to — that map is ours, and it is what the section carries alongside the world bytes.
+ *
+ * ## Async init, in a runtime with no async handlers
+ *
+ * Rapier's WASM needs `await RAPIER.init()`. The runtime's "handlers are synchronous" rule is not
+ * negotiable, so the engine is initialized **before the room is constructed** — by the worker
+ * host at bundle-load time, and by `initPhysics()` in the test harness. A `RoomCore` whose
+ * definition declares physics and finds no initialized engine throws with that instruction.
+ */
+
+/**
+ * Loads and initializes `@dimforge/rapier3d-compat` once per process. Idempotent and safe to
+ * call concurrently. Hosts call it before constructing a room whose definition declares physics;
+ * a room with no physics never pays the ~2.9 MB import.
+ */
+declare function initPhysics(): Promise<RapierModule>;
+/** The initialized engine, or `undefined` when `initPhysics()` has not resolved yet. */
+declare function loadedPhysics(): RapierModule | undefined;
+/** Test seam: forget the loaded engine (never used in production paths). */
+declare function resetPhysicsForTests(): void;
+/** The world plus the entity↔handle map, as it rides inside the hibernation blob. */
+interface PhysicsSection {
+    readonly world: Uint8Array;
+    /**
+     * `[collectionName, id, handle]`, in the order bodies were created. A Rapier `RigidBodyHandle`
+     * is the raw 64-bit (index, generation) pair *reinterpreted* as a JS number — handle 9 reads
+     * back as the denormal `4.4e-323`, not as `9`. It has to be written as an f64 so the bits
+     * survive; `u32` would truncate every handle to 0, which silently aliases every body to
+     * whatever was created first (for pachinko, the floor).
+     */
+    readonly bodies: readonly (readonly [string, string, number])[];
+}
+declare function encodePhysicsSection(section: PhysicsSection): Uint8Array;
+declare function decodePhysicsSection(bytes: Uint8Array): PhysicsSection;
+interface PhysicsRuntimeOptions {
+    /** From a v2 hibernation blob. Absent → a fresh world, and `setup` runs. */
+    readonly restore?: PhysicsSection;
+    /** Seconds per step when the config does not name one (the tick interval). */
+    readonly defaultTimestep: number;
+}
+declare class PhysicsRuntime {
+    readonly rapier: RapierModule;
+    readonly world: RapierWorld;
+    /** `true` when the world was built from scratch and `setup` has to run. */
+    readonly rebuilt: boolean;
+    private readonly core;
+    private readonly config;
+    /** Physics-backed collections, in schema (name-sorted) order. */
+    private readonly collections;
+    private readonly bodies;
+    /** Collections already warned about the friction-killing 2D lock recipe (bug 6). */
+    private readonly warnedPlanar;
+    /**
+     * Bodies whose sleep has already been synced. Rapier zeroes a body's velocity when it puts it
+     * to sleep — *after* the last awake-tick sync — so a body must be synced **once more** on the
+     * tick it falls asleep, or the schema keeps a phantom residual velocity forever (and a
+     * world rebuilt from schema state would wake it with a kick). Found by the drift check.
+     */
+    private readonly sleepSynced;
+    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;
+    /** 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;
+    private applyRecordToBody;
+    /**
+     * Creates bodies for new instances and destroys bodies whose instance is gone. Runs once per
+     * tick, right before the step, in collection order then instance order.
+     */
+    reconcile(): void;
+    step(): void;
+    /**
+     * Body → schema. Writes through the tracked proxies, so movement produces ordinary deltas.
+     * Values are `Math.fround`ed for f32 fields, so what room code reads is exactly what the wire
+     * carries — and so a field that has not really moved does not re-dirty every tick.
+     */
+    sync(): void;
+    serialize(): PhysicsSection;
+}
+
+/**
+ * `RoomCore` — the host-agnostic room runtime. It owns the extended schema, the
+ * tracked authority state, presence, the loop, and the frame dispatch; everything outside comes
+ * through `RoomHost` (`src/contract.ts`). The worker host and the test harness are adapters over
+ * exactly this surface and produce byte-identical frames.
+ */
+
+declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S> {
+    readonly definition: RoomDefinition<S>;
+    readonly ext: AnySchema;
+    readonly host: RoomHost;
+    readonly roomId: string;
+    readonly mode: RoomMode;
+    readonly plain: PlainState;
+    readonly tracked: Tracked<AnySchema>;
+    readonly anyState: AnyRecord;
+    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 | undefined;
+    readonly stats: RoomStats;
+    tick: number;
+    stopped: boolean;
+    /**
+     * 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
+     * keep the room up in production, but under test that same guarding turns a broken handler
+     * into a timeout in an unrelated assertion ten seconds later. Unset in production.
+     */
+    onHandlerError: ((name: string, err: unknown) => void) | undefined;
+    private readonly seed;
+    private readonly api;
+    private readonly internals;
+    private started;
+    /** One pending continuation flush at a time; concurrent completions coalesce into it. */
+    private continuationFlushPending;
+    constructor(definition: RoomDefinition<S>, host: RoomHost, options: RoomCoreOptions);
+    /**
+     * D22: builds the world, or returns `undefined` for a room with no `physics:` config.
+     *
+     * A v2 blob restores the world from its own bytes and `setup` does **not** run — the static
+     * geometry is already in there. Anything else (a fresh room, a v1 blob written before this
+     * room had physics, a migrated snapshot whose world was deliberately dropped) builds a world,
+     * runs `setup`, and lets the first tick's `reconcile` rebuild the bodies from schema state:
+     * positions and velocities live in schema fields, so the rebuild is faithful to what the state
+     * says. Transient contact state — resting contacts, accumulated impulses — is not in the schema
+     * and is lost; a stack of boxes may settle again with a small visible jolt.
+     */
+    private buildPhysics;
+    /** Convenience for hosts: `RoomCore.restore(def, bytes, host, opts)`. */
+    static restore<S2 extends AnySchema>(definition: RoomDefinition<S2>, bytes: Uint8Array, host: RoomHost, options: Omit<RoomCoreOptions, 'restoreFrom'>): RoomCore<S2>;
+    get schema(): S;
+    get config(): ResolvedRoomConfig<S>;
+    get state(): State<S>;
+    get room(): Room<S>;
+    tryRun<T>(name: string, fn: () => T): GuardResult<T>;
+    private readonly events;
+    recordEvent(kind: RoomEventKind, clientId?: string, detail?: string): void;
+    /** Live JSON view of the room for the dev page / supervisor admin API. */
+    inspect(): RoomInspection;
+    guard<T>(name: string, fn: () => T): T | undefined;
+    log(level: LogLevel, ...args: unknown[]): void;
+    start(): void;
+    stop(): void;
+    /**
+     * The hibernation blob's bytes, and **nothing else** — no `onSleep`, no timers cleared, no
+     * pending work rejected. A save (D24) is a *copy* of the room; hibernation is the room
+     * *leaving*. They want identical bytes and opposite side effects, so the bytes live here and
+     * the departure lives in `serialize()`.
+     *
+     * Conflating the two is not hypothetical: the first cut of `room.save()` routed through
+     * `serialize()`, which rejected every pending host call — including the `save()` that had just
+     * asked for it. The room waited out its own 10 s deadline for a save that had already been
+     * written.
+     */
+    snapshot(): Uint8Array;
+    serialize(): Uint8Array;
+    private get presence();
+    private resolveRole;
+    join(clientId: string, options?: JoinOptions): JoinResult;
+    /** Event mode only: presence/lifecycle changes are their own event. No-op in tick mode. */
+    private eventFlush;
+    leave(clientId: string, reason: LeaveReason): void;
+    markDisconnected(clientId: string): void;
+    ctxFor(clientId: string, reconnecting?: boolean): Ctx;
+    /**
+     * Week 12: the host answering a `room.save()` / `room.kv.*`. The continuation runs here — its
+     * own event, between ticks, off the back of a host turn — and the flush afterwards is what
+     * makes "state mutated in a continuation is tracked normally" true rather than aspirational.
+     */
+    completeHostCall(reqId: number, result: HostCallResult): void;
+    /**
+     * Flushes whatever a promise continuation wrote, as its own event, once the microtask queue
+     * that continuation lives on has drained.
+     *
+     * The subtlety this exists for: `resolve()` does not run the room's `.then` — it *queues* it,
+     * and every promise link between the resolve and the room's callback costs another microtask
+     * turn. A single `queueMicrotask(flush)` therefore only ever catches a continuation exactly one
+     * link deep, and silently drops the state written by anything the room chained further out.
+     * Draining a bounded number of turns first covers the chains rooms actually write, coalesces
+     * concurrent completions into one flush, and — unlike a `setTimeout(0)` — keeps working under
+     * the harness's synchronous fake clock, where a macrotask would fire *before* the microtasks.
+     */
+    private scheduleContinuationFlush;
+    /**
+     * D26: one durable alarm firing. Same scheduling class as an RPC — a discrete event between
+     * ticks — so a tick-mode room never sees a `tick` run half-alarmed, and a handler that re-arms
+     * its own name is the supported way to build a repeating timer.
+     */
+    fireAlarm(name: string): void;
+    correctionFor(clientId: string): DirtySet | undefined;
+    invalidateClients(): void;
+    send(clientId: string, frame: Uint8Array): void;
+    private badFrame;
+    receive(clientId: string, frame: Uint8Array): void;
+    /**
+     * Hands the tracked dirty set out: server-wins corrections first, then per connected client its
+     * pending `CORRECT` (before the delta, so it sees the correction and then the broadcast) and
+     * its view's `DELTA` — encoded once per distinct view.
+     */
+    flush(): void;
+}
+
+export { CRASH_AFTER_THROWS as C, MAX_CATCHUP as M, type PhysicsSection as P, RoomCore as R, Mulberry32 as a, decodePhysicsSection as d, encodePhysicsSection as e, initPhysics as i, loadedPhysics as l, resetPhysicsForTests as r };

package/dist/test/index.d.ts

@@ -1,8 +1,9 @@
+import { R as RoomCore } from '../room-9ZQoy9yi.js';
+export { i as initPhysics } from '../room-9ZQoy9yi.js';
 import { ErrorCodeName, FrameType } from '@irtio/protocol';
-import { f as RoomHost, L as LogLevel, h as RoomStats } from '../contract-BhD88PGb.js';
+import { h as RoomHost, L as LogLevel, R as RoomCoreApi, a as HostCall, b as HostCallResult, j as RoomStats } from '../contract-B8QSO0MH.js';
 import { AnySchema, PlainState, EntityCollection, State } from '@irtio/schema';
 import { LeaveReason, Room, RoomDefinition } from '@irtio/server';
-import { R as RoomCore } from '../room-CBsSCueH.js';
 
 /**
  * The harness clock: a deterministic fake `now()` plus an ordered timer queue. `RoomCore` only
@@ -30,6 +31,18 @@ declare class FakeClock {
  * `HarnessHost` — the `RoomHost` the harness gives `RoomCore`. Everything the host is told is
  * recorded so a test can assert on it: logs, kicks, `close()`, `sleep()`, `crashed()`, and how
  * many frames/bytes went out (per client and in total).
+ *
+ * Week 12 adds the two host capabilities a room can now reach for, both modelled the way the
+ * real supervisor models them:
+ *
+ * - **Host calls** (`room.save()`, `room.kv.*`) are answered on a fake-clock timer, never
+ *   synchronously. `hostCallDelayMs` defaults to 0, and even 0 goes through `clock.setTimeout` —
+ *   which is the point: it makes "the continuation is its own event" the same structural fact in
+ *   the harness that it is in the worker.
+ * - **Alarms** are *host* state, exactly as they are in the supervisor: `setAlarm` records a due
+ *   time here and nothing goes near the hibernation blob. `fireDue()` runs what is due, in name
+ *   order, and a test simulating hibernation builds a new core while keeping this host's
+ *   `armedAlarms` — which is precisely what the supervisor does across a wake.
  */
 
 interface KickRecord {
@@ -45,6 +58,11 @@ interface SendCounts {
     frames: number;
     bytes: number;
 }
+/** One `hostCall` the room made, in order, for assertions. */
+interface HostCallRecord {
+    readonly reqId: number;
+    readonly call: HostCall;
+}
 declare class HarnessHost implements RoomHost {
     private readonly clock;
     readonly logs: LogRecord[];
@@ -61,6 +79,32 @@ declare class HarnessHost implements RoomHost {
     readonly sentByClient: Map<string, SendCounts>;
     /** Set by the harness: where an outbound frame goes. */
     onSend: (clientId: string, frame: Uint8Array) => void;
+    /**
+     * The core this host answers. Set by whoever built the pair — the host has to call back into
+     * `completeHostCall`/`fireAlarm`, which runs in the same direction `receive()` does.
+     */
+    core: RoomCoreApi | undefined;
+    /** Every `room.save()` / `room.kv.*` the room asked for, in order. */
+    readonly hostCalls: HostCallRecord[];
+    /** Fake ms between a host call and its answer. 0 still means "a later event", not "inline". */
+    hostCallDelayMs: number;
+    /** The in-memory player KV, keyed the way the real table's composite primary key is. */
+    readonly kv: Map<string, string>;
+    /** Save generations this host minted: `saveId` -> the bytes it was handed. */
+    readonly saves: Map<string, Uint8Array<ArrayBufferLike>>;
+    /** What `room.save()` serializes. The harness sets it to `() => core.snapshot()` — the bytes
+     *  without hibernation's side effects, exactly as the supervisor asks for them. */
+    serializeForSave: (() => Uint8Array) | undefined;
+    /**
+     * Override the host-call backend. Return `undefined` to fall through to the built-in in-memory
+     * one; return a result to answer it yourself — how the limit and outage tests are written.
+     */
+    handleHostCall: ((call: HostCall) => HostCallResult | undefined) | undefined;
+    private nextSaveId;
+    /** D26: armed alarms, `name` -> due time on the fake clock. Host state, never room state. */
+    readonly armedAlarms: Map<string, number>;
+    /** Every alarm that fired, in order, as `name@dueMs`. */
+    readonly firedAlarms: string[];
     constructor(clock: FakeClock);
     /** `true` once the runtime has asked to hibernate at least once. */
     get slept(): boolean;
@@ -75,6 +119,17 @@ declare class HarnessHost implements RoomHost {
     sleep(): void;
     log(level: LogLevel, args: unknown[]): void;
     crashed(reason: string): void;
+    hostCall(reqId: number, call: HostCall): void;
+    private runHostCall;
+    setAlarm(name: string, atMs: number | undefined): void;
+    /**
+     * Fires every alarm due at or before `now`, in **name order** (D34 determinism), removing each
+     * before it runs so a handler that re-arms its own name arms the *next* one rather than having
+     * this pass cancel it straight back out.
+     */
+    fireDue(now?: number): string[];
+    /** The earliest due time across armed alarms — what the supervisor reports to control. */
+    get dueAlarmAt(): number | undefined;
     /** Logged messages of one level, flattened to strings (handy in assertions). */
     logsOf(level: LogLevel): string[];
 }
@@ -109,6 +164,8 @@ interface VisibilityLeak {
     /** Ids involved (`['']` for a singleton). */
     readonly ids: readonly string[];
     readonly tick: number;
+    /** Spatial diagnostics when available. */
+    readonly detail?: string;
 }
 
 /**