@irtio/runtime 0.5.1 → 0.6.0

package/dist/{room-9ZQoy9yi.d.ts → room-CfnEjlcg.d.ts}

@@ -1,6 +1,7 @@
+import { AttributeOptions, ProfileSnapshot } from '@irtio/protocol';
 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';
+import { RoomDefinition, RoomMode, Room, Ctx, MatterModule, MatterEngine, MatterBody, RapierModule, RapierWorld, RapierRigidBody, 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-BjMsoJIV.js';
 
 /**
  * `room.random()` — mulberry32 over a u32 seed. Deterministic, tiny, and serializable: the
@@ -27,6 +28,13 @@ 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;
+    /**
+     * D44: this session is a scripted NPC, spawned by room code rather than dialled from outside.
+     * It changes exactly two things: the idle clock does not count it (a room full of NPCs and no
+     * players hibernates like an empty one), and metrics report it separately. Everything else —
+     * `maxClients`, validation, ownership, presence — treats it as the client session it is.
+     */
+    readonly npc: boolean;
     /**
      * D25: the identity `ctx.playerId` reports. Set once at the first join and kept across
      * reconnects, exactly like the client id it defaults to.
@@ -85,6 +93,8 @@ interface QueuedFrame {
 }
 /** What the core modules may do with the physics world (`core/physics.ts` implements it). */
 interface PhysicsApi {
+    /** D45: which of the two blessed engines this room is running. */
+    readonly engineKind: 'rapier3d' | 'matter2d';
     readonly timestep: number;
     /** Creates bodies for new instances, destroys bodies whose instance is gone. */
     reconcile(): void;
@@ -92,8 +102,14 @@ interface PhysicsApi {
     /** Body → schema, through the tracked proxies. */
     sync(): void;
     bodyFor(collection: string, id: string): unknown;
+    /** rapier3d only. */
     readonly rapier: unknown;
+    /** rapier3d only. */
     readonly world: unknown;
+    /** matter2d only: the `matter-js` namespace. */
+    readonly matter: unknown;
+    /** matter2d only: the live `Matter.Engine`. */
+    readonly matterEngine: unknown;
 }
 interface LoopApi {
     start(): void;
@@ -133,7 +149,9 @@ interface RoomInternals {
     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;
+    /** D41: record this tick on the authoritative timeline. A no-op while the recorder is unarmed. */
+    captureTimeline(): void;
+    recordEvent(kind: 'join' | 'leave' | 'write' | 'write-rejected' | 'correct' | 'call' | 'reply' | 'msg' | 'alarm' | 'bus' | '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;
@@ -144,6 +162,13 @@ interface RoomInternals {
     correctionFor(clientId: string): DirtySet | undefined;
     /** Flushes the tracked dirty set: corrections first, then one `DELTA` per distinct view. */
     flush(): void;
+    /**
+     * Schedules an event-mode flush after the current microtask chain settles; a no-op in tick
+     * mode (the next tick flushes anyway) and while one is already pending. This is the
+     * "own event, then flush" step the host-call seam runs after `completeHostCall`, exposed so a
+     * promise the room API rejects *locally* (bug #48) settles in the same scheduling class.
+     */
+    scheduleContinuationFlush(): void;
     /** Invalidates the cached `room.clients` array. */
     invalidateClients(): void;
 }
@@ -225,6 +250,101 @@ declare class Loop implements LoopApi {
     after(ms: number, fn: () => void): void;
 }
 
+/**
+ * D45 part 1: the matter.js world inside the room.
+ *
+ * It sits in exactly the place `core/physics.ts` describes — reconcile, step, sync, between the
+ * `tick()` handler and the flush — and writes the same schema channels. What differs is everything
+ * underneath, and two differences are load-bearing enough to be worth stating here.
+ *
+ * ## There is no engine snapshot
+ *
+ * Rapier has `world.takeSnapshot()` / `restoreSnapshot()`, and a woken Rapier room is byte-for-byte
+ * the world that went to sleep, contacts included. matter.js has no equivalent: its world is plain
+ * JavaScript objects, and the honest options were to serialize the object graph ourselves or to
+ * rebuild the world and reapply per-body state. This module does the second. `setup` therefore runs
+ * on **every** matter2d wake, not only on a rebuild, and what is not restored is the solver's
+ * transient state: resting contacts, accumulated impulses, and the sleep timers behind them. A
+ * settled pile may re-settle with a small jolt. The measurement in `docs/m3-part5-report.md` says
+ * how big that jolt is on the fixture that ships with this.
+ *
+ * ## The units are matter.js's, not translated
+ *
+ * `gravity` goes into `engine.gravity` verbatim (matter's own default is `{ x: 0, y: 1 }` with
+ * `scale: 0.001`, and y is **down**), and `body.velocity` is matter's per-step displacement rather
+ * than a per-second velocity. Translating either would mean irtio inventing a unit system on top of
+ * an engine it promised to bless rather than abstract, and every matter.js tutorial would then be
+ * subtly wrong inside a room. The mapping onto the wire channels is in `@irtio/schema`
+ * (`channelOf2d`), and it is the only translation there is.
+ */
+
+/**
+ * Loads `matter-js` once per process. Pure JavaScript, so there is no `init()` to await and no
+ * WASM instance to keep unique — but the load is still async (it is an `import()`), and handlers
+ * are synchronous, so it happens before the room is constructed exactly as Rapier's does.
+ */
+declare function initMatter(): Promise<MatterModule>;
+declare function loadedMatter(): MatterModule | undefined;
+/** Test seam: forget the loaded engine. */
+declare function resetMatterForTests(): void;
+/** One body's restorable state. Everything a rebuild needs and nothing the world-builder gives. */
+interface MatterBodyRecord {
+    readonly collection: string;
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly angle: number;
+    readonly vx: number;
+    readonly vy: number;
+    readonly angularVelocity: number;
+    readonly sleeping: boolean;
+}
+interface MatterSection {
+    readonly bodies: readonly MatterBodyRecord[];
+}
+declare function encodeMatterBodies(section: MatterSection): Uint8Array;
+declare function decodeMatterBodies(bytes: Uint8Array): MatterSection;
+interface MatterRuntimeOptions {
+    readonly restore?: MatterSection;
+    readonly defaultTimestep: number;
+}
+declare class MatterRuntime {
+    readonly engineKind: "matter2d";
+    /** rapier3d only; present so both runtimes satisfy one internal shape. */
+    readonly rapier: undefined;
+    readonly world: undefined;
+    readonly matter: MatterModule;
+    readonly engine: MatterEngine;
+    /** Alias under the name `PhysicsApi` uses, so `room.physics2d` reads through one field. */
+    get matterEngine(): MatterEngine;
+    /** `true` when the blob carried no world at all: the caller logs it. */
+    readonly rebuilt: boolean;
+    /**
+     * Always `true`. Unlike Rapier's, a matter2d world is never restored as a world — only as
+     * per-body state on a world the builder made — so `setup` has to run every time.
+     */
+    readonly needsSetup = true;
+    private readonly core;
+    private readonly config;
+    private readonly collections;
+    private readonly bodies;
+    private readonly restore;
+    private readonly stepMs;
+    private readonly sleepSynced;
+    constructor(core: RoomInternals, matter: MatterModule, options: MatterRuntimeOptions);
+    get timestep(): number;
+    runSetup(room: Room): void;
+    free(): void;
+    bodyFor(collection: string, id: string): MatterBody | undefined;
+    private create;
+    private applyState;
+    private applyRecordToBody;
+    reconcile(): void;
+    step(): void;
+    sync(): void;
+    serialize(): MatterSection;
+}
+
 /**
  * D22 part 1: the Rapier world inside the room.
  *
@@ -281,6 +401,23 @@ interface PhysicsSection {
     readonly bodies: readonly (readonly [string, string, number])[];
 }
 declare function encodePhysicsSection(section: PhysicsSection): Uint8Array;
+/**
+ * D45: which engine wrote a v2 physics section.
+ *
+ * The discriminant is not a new leading byte, because a new leading byte would change every blob
+ * ever written. It is a **zero-length world**: a Rapier section starts with the varint length of
+ * `world.takeSnapshot()`, which is never zero, so `0` is a value no existing blob can hold. A
+ * matter2d section writes that zero, then a one-byte engine tag, then its own payload. Every
+ * pre-D45 blob is therefore byte-identical and reads as Rapier without a version bump, which is
+ * what the recommendation in the plan asked for and why format 3 was not needed.
+ */
+type PhysicsEngineTag = 'rapier3d' | 'matter2d';
+/** Reads the engine out of an encoded section without decoding the rest of it. */
+declare function physicsSectionEngine(bytes: Uint8Array): PhysicsEngineTag;
+/** Wraps a matter2d body-state payload in the discriminated envelope. */
+declare function encodeMatterSectionEnvelope(payload: Uint8Array): Uint8Array;
+/** The payload inside a matter2d envelope. Throws if the section is a Rapier one. */
+declare function decodeMatterSectionEnvelope(bytes: Uint8Array): Uint8Array;
 declare function decodePhysicsSection(bytes: Uint8Array): PhysicsSection;
 interface PhysicsRuntimeOptions {
     /** From a v2 hibernation blob. Absent → a fresh world, and `setup` runs. */
@@ -289,10 +426,16 @@ interface PhysicsRuntimeOptions {
     readonly defaultTimestep: number;
 }
 declare class PhysicsRuntime {
+    readonly engineKind: "rapier3d";
+    /** matter2d only; present so both runtimes satisfy one internal shape. */
+    readonly matter: undefined;
+    readonly matterEngine: undefined;
     readonly rapier: RapierModule;
     readonly world: RapierWorld;
     /** `true` when the world was built from scratch and `setup` has to run. */
     readonly rebuilt: boolean;
+    /** Rapier restores a whole world, contacts included, so `setup` runs only on a rebuild. */
+    get needsSetup(): boolean;
     private readonly core;
     private readonly config;
     /** Physics-backed collections, in schema (name-sorted) order. */
@@ -351,7 +494,7 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     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 physics: PhysicsRuntime | MatterRuntime | undefined;
     readonly stats: RoomStats;
     tick: number;
     stopped: boolean;
@@ -362,6 +505,17 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
      * into a timeout in an unrelated assertion ten seconds later. Unset in production.
      */
     onHandlerError: ((name: string, err: unknown) => void) | undefined;
+    /**
+     * D41: the recorded authoritative timeline. Armed by `startRecording()` and off otherwise, so a
+     * room nobody asked to record pays nothing. A room that was asked captures its own state at the
+     * end of every tick, which is the only moment in a tick where that state is settled.
+     */
+    private recorder;
+    /**
+     * D65: the bandwidth ledger, present only when `RoomCoreOptions.profile` asked for one. Every
+     * cost the profiler has is behind this `undefined`.
+     */
+    private readonly ledger;
     private readonly seed;
     private readonly api;
     private readonly internals;
@@ -369,6 +523,26 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     /** One pending continuation flush at a time; concurrent completions coalesce into it. */
     private continuationFlushPending;
     constructor(definition: RoomDefinition<S>, host: RoomHost, options: RoomCoreOptions);
+    private subscribeDeclaredChannels;
+    private get busConfig();
+    /**
+     * D59: one published message arriving on a channel this room is subscribed to.
+     *
+     * Same scheduling class as an alarm or an RPC — a discrete event between ticks — so a tick-mode
+     * room never sees a `tick` run half-delivered. `from` is supervisor-stamped, so the handler may
+     * trust it as far as it trusts its own project.
+     */
+    deliverBusEvent(channel: string, from: string, payload: string): void;
+    /**
+     * D59: one directed `room.bus.send` arriving. At-least-once, so this can run twice for one send;
+     * that is the receiver's problem to be idempotent about and the docs say so.
+     *
+     * A throw propagates through `guard` and counts toward the crash threshold exactly as any other
+     * handler throw does. That is deliberate, and it is why the supervisor bounds redelivery: the
+     * two behaviours together would otherwise let one poisonous message close a room on every wake,
+     * forever.
+     */
+    deliverBusMessage(from: string, payload: string): void;
     /**
      * D22: builds the world, or returns `undefined` for a room with no `physics:` config.
      *
@@ -381,6 +555,13 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
      * and is lost; a stack of boxes may settle again with a small visible jolt.
      */
     private buildPhysics;
+    /**
+     * D45: the matter2d half. It differs from Rapier's in one structural way — there is no engine
+     * snapshot to restore, so the world is always **built** and per-body state is reapplied on top
+     * of it. `setup` therefore runs on every wake, and only the "there was no world at all" case is
+     * worth logging.
+     */
+    private buildMatter;
     /** 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;
@@ -390,6 +571,16 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     tryRun<T>(name: string, fn: () => T): GuardResult<T>;
     private readonly events;
     recordEvent(kind: RoomEventKind, clientId?: string, detail?: string): void;
+    /**
+     * D41: begin (or restart) recording the authoritative timeline. Calling it again clears what
+     * was recorded, so two scenario runs against one long-lived dev server do not read each
+     * other's ticks.
+     */
+    startRecording(options?: TimelineRecorderOptions): void;
+    /** D41: what has been recorded so far, or `undefined` when nobody armed the recorder. */
+    recording(): TimelineDump | undefined;
+    /** D41: called at the end of every tick (and every event-mode flush). No-op when unarmed. */
+    captureTimeline(): void;
     /** Live JSON view of the room for the dev page / supervisor admin API. */
     inspect(): RoomInspection;
     guard<T>(name: string, fn: () => T): T | undefined;
@@ -434,8 +625,12 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
      * 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.
+     *
+     * Public on `RoomInternals` (bug #48) so the room API's local rejections — a float score, an
+     * empty bus target, a call to a client that is not connected — flush the state their `.catch()`
+     * writes, instead of leaving it for whatever frame happens to arrive next.
      */
-    private scheduleContinuationFlush;
+    scheduleContinuationFlush(): void;
     /**
      * 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
@@ -444,7 +639,19 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     fireAlarm(name: string): void;
     correctionFor(clientId: string): DirtySet | undefined;
     invalidateClients(): void;
-    send(clientId: string, frame: Uint8Array): void;
+    /**
+     * D65: `hint` is profiling context and nothing else — the payload object a per-view frame was
+     * built from (so one encode is walked once and replayed per recipient) and the AOI ids whose
+     * ops are visibility churn. Ignored entirely when this room is not profiling, which is why it
+     * is an optional argument rather than a second method.
+     */
+    send(clientId: string, frame: Uint8Array, hint?: AttributeOptions): void;
+    /**
+     * D65: the ledger so far. The room's own view, so it counts what `send()` sent and what
+     * `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).
+     */
+    profile(): ProfileSnapshot | undefined;
     private badFrame;
     receive(clientId: string, frame: Uint8Array): void;
     /**
@@ -455,4 +662,4 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
     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 };
+export { CRASH_AFTER_THROWS as C, MAX_CATCHUP as M, type PhysicsEngineTag as P, RoomCore as R, type MatterBodyRecord as a, type MatterSection as b, Mulberry32 as c, type PhysicsSection as d, decodeMatterBodies as e, decodeMatterSectionEnvelope as f, decodePhysicsSection as g, encodeMatterBodies as h, encodeMatterSectionEnvelope as i, encodePhysicsSection as j, initMatter as k, initPhysics as l, loadedMatter as m, loadedPhysics as n, resetPhysicsForTests as o, physicsSectionEngine as p, resetMatterForTests as r };

package/dist/test/index.d.ts

@@ -1,9 +1,9 @@
-import { R as RoomCore } from '../room-9ZQoy9yi.js';
-export { i as initPhysics } from '../room-9ZQoy9yi.js';
+import { R as RoomCore } from '../room-CfnEjlcg.js';
+export { k as initMatter, l as initPhysics } from '../room-CfnEjlcg.js';
 import { ErrorCodeName, FrameType } from '@irtio/protocol';
-import { h as RoomHost, L as LogLevel, R as RoomCoreApi, a as HostCall, b as HostCallResult, j as RoomStats } from '../contract-B8QSO0MH.js';
+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-BjMsoJIV.js';
 import { AnySchema, PlainState, EntityCollection, State } from '@irtio/schema';
-import { LeaveReason, Room, RoomDefinition } from '@irtio/server';
 
 /**
  * The harness clock: a deterministic fake `now()` plus an ordered timer queue. `RoomCore` only
@@ -90,6 +90,23 @@ declare class HarnessHost implements RoomHost {
     hostCallDelayMs: number;
     /** The in-memory player KV, keyed the way the real table's composite primary key is. */
     readonly kv: Map<string, string>;
+    /** D53: `"<board> <playerId>"` -> the best score submitted so far. */
+    readonly scores: Map<string, number>;
+    /** D63: every `room.ratings.report` the room asked for, in order. Recorded, never applied. */
+    readonly ratingReports: {
+        queue: string;
+        results: {
+            playerId: string;
+            place: number;
+        }[];
+    }[];
+    /** D63: every `room.ratings.set`, in order. */
+    readonly ratingSets: {
+        queue: string;
+        playerId: string;
+        rating: number;
+        deviation?: number;
+    }[];
     /** 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
@@ -121,6 +138,36 @@ declare class HarnessHost implements RoomHost {
     crashed(reason: string): void;
     hostCall(reqId: number, call: HostCall): void;
     private runHostCall;
+    /**
+     * 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
+     * wants to see an NPC *play* needs a real tenant (`packages/supervisor/test/npc.test.ts`), and
+     * one that wants to see a room ask for one reads these.
+     */
+    readonly spawnedNpcs: {
+        clientId: string;
+        config: NpcConfig;
+    }[];
+    readonly despawnedNpcs: string[];
+    spawnNpc(clientId: string, config: NpcConfig): void;
+    despawnNpc(clientId: string): void;
+    /** Every `room.bus.send` the room asked for, in order. */
+    readonly busSends: {
+        roomId: string;
+        payload: string;
+    }[];
+    /** Every `room.bus.publish`, in order. */
+    readonly busPublishes: {
+        channel: string;
+        payload: string;
+    }[];
+    /** The channels this room is currently subscribed to, in subscription order. */
+    readonly busSubscriptions: Set<string>;
+    /** D63-e: the harness has no room list to report on, so it records the value and stops. */
+    backfillOpen: boolean | undefined;
+    setBackfill(open: boolean): void;
+    busPublish(channel: string, payload: string): void;
+    busSubscribe(channel: string, subscribed: boolean): void;
     setAlarm(name: string, atMs: number | undefined): void;
     /**
      * Fires every alarm due at or before `now`, in **name order** (D34 determinism), removing each

package/dist/test/index.js

@@ -1,9 +1,10 @@
 import {
   RoomCore,
   createVisibilityPolicy,
+  initMatter,
   initPhysics,
   visibleNames
-} from "../chunk-5ZDQAAFJ.js";
+} from "../chunk-K42HA75G.js";
 
 // src/test/clock.ts
 var FakeClock = class {
@@ -79,6 +80,12 @@ var HarnessHost = class {
   hostCallDelayMs = 0;
   /** The in-memory player KV, keyed the way the real table's composite primary key is. */
   kv = /* @__PURE__ */ new Map();
+  /** D53: `"<board> <playerId>"` -> the best score submitted so far. */
+  scores = /* @__PURE__ */ new Map();
+  /** D63: every `room.ratings.report` the room asked for, in order. Recorded, never applied. */
+  ratingReports = [];
+  /** D63: every `room.ratings.set`, in order. */
+  ratingSets = [];
   /** Save generations this host minted: `saveId` -> the bytes it was handed. */
   saves = /* @__PURE__ */ new Map();
   /** What `room.save()` serializes. The harness sets it to `() => core.snapshot()` — the bytes
@@ -169,11 +176,72 @@ var HarnessHost = class {
       case "kvDelete":
         this.kv.delete(kvKey(call.playerId, call.key));
         return { ok: true };
+      case "busSend": {
+        this.busSends.push({ roomId: call.roomId, payload: call.payload });
+        return { ok: true };
+      }
+      case "ratingReport": {
+        this.ratingReports.push({
+          queue: call.queue,
+          results: call.results.map((r) => ({ ...r }))
+        });
+        return { ok: true };
+      }
+      case "ratingSet": {
+        this.ratingSets.push({
+          queue: call.queue,
+          playerId: call.playerId,
+          rating: call.rating,
+          ...call.deviation !== void 0 ? { deviation: call.deviation } : {}
+        });
+        return { ok: true };
+      }
+      case "lbSubmit": {
+        const key = `${call.board} ${call.playerId}`;
+        const existing = this.scores.get(key);
+        if (existing === void 0 || call.score > existing) this.scores.set(key, call.score);
+        return { ok: true };
+      }
     }
   }
   // -------------------------------------------------------------------------
   // Week 12: durable alarms (D26)
   // -------------------------------------------------------------------------
+  /**
+   * 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
+   * wants to see an NPC *play* needs a real tenant (`packages/supervisor/test/npc.test.ts`), and
+   * one that wants to see a room ask for one reads these.
+   */
+  spawnedNpcs = [];
+  despawnedNpcs = [];
+  spawnNpc(clientId, config) {
+    this.spawnedNpcs.push({ clientId, config });
+  }
+  despawnNpc(clientId) {
+    this.despawnedNpcs.push(clientId);
+  }
+  // -------------------------------------------------------------------------
+  // D59: the bus
+  // -------------------------------------------------------------------------
+  /** Every `room.bus.send` the room asked for, in order. */
+  busSends = [];
+  /** Every `room.bus.publish`, in order. */
+  busPublishes = [];
+  /** The channels this room is currently subscribed to, in subscription order. */
+  busSubscriptions = /* @__PURE__ */ new Set();
+  /** D63-e: the harness has no room list to report on, so it records the value and stops. */
+  backfillOpen;
+  setBackfill(open) {
+    this.backfillOpen = open;
+  }
+  busPublish(channel, payload) {
+    this.busPublishes.push({ channel, payload });
+  }
+  busSubscribe(channel, subscribed) {
+    if (subscribed) this.busSubscriptions.add(channel);
+    else this.busSubscriptions.delete(channel);
+  }
   setAlarm(name, atMs) {
     if (atMs === void 0) this.armedAlarms.delete(name);
     else this.armedAlarms.set(name, atMs);
@@ -905,5 +973,6 @@ export {
   HarnessHost,
   createRoomHarness,
   frameTypeName,
+  initMatter,
   initPhysics
 };