@irtio/runtime 1.0.0 → 3.0.0

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

@@ -3,6 +3,80 @@ import * as _irtio_protocol from '@irtio/protocol';
 import { PlatformNotice, ErrorCodeName } from '@irtio/protocol';
 import { RoomDefinition, Room, LeaveReason, NpcConfig } from '@irtio/server';
 
+/**
+ * M7 pf4: the per-room RPC trace ring.
+ *
+ * One entry per client→server RPC: who called, what they called, the two clocks the call was
+ * judged against (`ctx.tick` and `ctx.clientTick`), how it ended, and a truncated summary of what
+ * came back. It is a **separate** store from `EventRing`, on purpose. The event ring is always on
+ * and 100 entries wide, and it is the thing every deployed room pays for; making it rich enough to
+ * answer "why did this shot produce no tracer" would make every production room pay for a
+ * development question. So this ring is armed — `irtio dev --trace-rpc`, `SupervisorConfig.traceRpc`
+ * — and a room nobody armed never constructs one. `RoomCore.recordRpc` is a call into an
+ * `undefined`, which is the same cost `captureTimeline` pays when the recorder is unarmed.
+ *
+ * The stamp-lag table (ask b) rides here rather than in a second structure: the last traced call
+ * per client is kept in its own map, so a client whose entry has already been evicted from the ring
+ * still reports the lag its last call had. That is the whole reason the ask says "rides on whatever
+ * the RPC trace stores" — the server keeps no per-session stamp record otherwise.
+ */
+/** Entries kept per room. Bounded because a dev session left running overnight is a real thing. */
+declare const RPC_TRACE_SIZE = 200;
+/**
+ * Longest result summary kept, in UTF-16 code units of JSON. A summary is a diagnostic, not a
+ * record: an RPC returning a 10 kB payload should cost the trace a line, not 10 kB × 200.
+ */
+declare const RPC_TRACE_SUMMARY_MAX = 200;
+/**
+ * How a call ended. `deny:<reason>` is `ctx.deny(reason)` — an application refusal, which is the
+ * distinction the whole ask exists for: a refusal is not an error, and a trace that spelled both
+ * `error` would answer the question with the answer that lost the evening.
+ */
+type RpcOutcome = 'ok' | 'error' | `deny:${string}`;
+interface RpcTraceEntry {
+    /** Monotonic within a room, so a reader can tell "no new calls" from "the ring rolled". */
+    readonly seq: number;
+    readonly clientId: string;
+    readonly rpc: string;
+    /** The server tick the call was applied at (`ctx.tick`). */
+    readonly tick: number;
+    /** The caller's own stamp (`ctx.clientTick`), absent when the client sent none. */
+    readonly clientTick?: number;
+    readonly outcome: RpcOutcome;
+    /** JSON-ish rendering of the reply, truncated at {@link RPC_TRACE_SUMMARY_MAX}. */
+    readonly result?: string;
+}
+/** One client's last traced call — what the inspector's stamp-lag column reads. */
+interface StampLag {
+    readonly tick: number;
+    readonly clientTick: number | undefined;
+    /** `ctx.tick - ctx.clientTick`, or `undefined` when the call carried no stamp. */
+    readonly lag: number | undefined;
+    readonly rpc: string;
+    readonly seq: number;
+}
+/** Renders a reply for the trace: JSON, truncated, and never able to throw. */
+declare function summarize(value: unknown): string | undefined;
+declare class RpcTraceRing {
+    private readonly items;
+    private readonly lastByClient;
+    private seq;
+    push(entry: Omit<RpcTraceEntry, 'seq'>): RpcTraceEntry;
+    list(): readonly RpcTraceEntry[];
+    /** Client id → its last traced call. Survives the entry itself being evicted from the ring. */
+    stampLag(): ReadonlyMap<string, StampLag>;
+    /** A client that left takes its stamp row with it; the ring entries stay. */
+    forget(clientId: string): void;
+    /** JSON shape served by `/__irt/rpc-trace.json` and carried on `inspect`. */
+    dump(): RpcTraceDump;
+}
+interface RpcTraceDump {
+    readonly entries: readonly RpcTraceEntry[];
+    readonly stampLag: readonly ({
+        readonly clientId: string;
+    } & StampLag)[];
+}
+
 /**
  * D41: the recorded authoritative timeline.
  *
@@ -429,6 +503,14 @@ interface RoomCoreOptions {
      * `testRoom({ profile: true })` are what turn it on.
      */
     readonly profile?: boolean;
+    /**
+     * M7 pf4: keep a bounded RPC trace ring for this room. Off by default and free when off — a
+     * room nobody armed constructs no ring and `recordRpc` is a call into an `undefined`, exactly
+     * as `captureTimeline` is when the D41 recorder is unarmed. `irtio dev --trace-rpc`,
+     * `SupervisorConfig.traceRpc` and `testRoom({ traceRpc: true })` are what turn it on; nothing
+     * in a deployed tenant does.
+     */
+    readonly traceRpc?: boolean;
     /**
      * D77 / O28: the write core's caps — encoded state bytes, records per collection, writes per
      * client per second. A host that sets none gets the record cap and nothing else, which is what
@@ -460,6 +542,16 @@ interface JoinOptions {
     readonly playerId?: string;
     /** D44: this join is a scripted NPC's loopback session. */
     readonly npc?: boolean;
+    /**
+     * The **verified** identity subject behind this join, or `undefined` when there is none.
+     *
+     * Deliberately not `playerId`. `playerId` always has a value — it falls back to the client id —
+     * and that fallback is exactly what a moderation decision must not be fooled by: a key join's
+     * `playerId` is a resume token's client id, which a returning stranger simply mints again. This
+     * is the narrower fact: present only when a credential was verified, absent for a key join, and
+     * therefore the only thing `room.ban` can key a cooldown on honestly.
+     */
+    readonly subject?: string;
 }
 interface JoinResult {
     readonly tick: number;
@@ -472,6 +564,29 @@ declare class RoomFullError extends Error {
     readonly name = "RoomFullError";
     constructor(maxClients: number);
 }
+/**
+ * M8 lane 5: this join was refused before it had a seat.
+ *
+ * Thrown by `RoomCore.join` for all four of the room's own refusals — a subject inside a
+ * `room.ban` cooldown, an `onAdmit` that called `ctx.deny`, an `onAdmit` that never answered
+ * (`admission timed out`), and an `onAdmit` that threw (`admission check failed`) — and mapped to
+ * `E_ADMISSION` at the
+ * worker boundary, exactly where `RoomFullError` becomes `E_ROOM_FULL`. Its own class rather than
+ * a `DenyError` reaching the host, so the host can tell a refusal it should answer with a typed
+ * error from a handler that broke.
+ */
+declare class AdmissionError extends Error {
+    readonly reason: string;
+    readonly name = "AdmissionError";
+    constructor(reason: string);
+}
+/**
+ * M7 pf3 (f): the smoothing on `RoomStats.physicsStepMsAvg`.
+ *
+ * 0.1 is roughly a ten-tick window: half a second at 20 Hz, which is short enough to show a pile
+ * of crates settling and long enough that one preempted step does not read as a regression.
+ */
+declare const PHYSICS_STEP_EMA_ALPHA = 0.1;
 interface RoomStats {
     ticks: number;
     lastTickMs: number;
@@ -488,6 +603,22 @@ interface RoomStats {
     gridBuildMs: number;
     gridQueryMs: number;
     aoiEncodeMs: number;
+    /**
+     * Wall milliseconds the last world step took, measured around the engine's own `step()` and
+     * nothing else: not `reconcile`, not `sync`, not the room's `tick()` handler. `0` in a room
+     * with no physics, and `0` until the first step.
+     *
+     * Deliberately narrow. `lastTickMs` already covers the whole tick, and the question this
+     * answers — "is the engine the thing that is slow?" — is the one a room cannot answer by
+     * subtracting numbers it does not have.
+     */
+    physicsStepMs: number;
+    /**
+     * An exponential moving average of {@link physicsStepMs}, alpha {@link PHYSICS_STEP_EMA_ALPHA}.
+     * A single step's timing is mostly noise on a shared machine; this is the number to compare
+     * against a budget or to plot.
+     */
+    physicsStepMsAvg: number;
     visibleIdsTotal: number;
     membershipEnters: number;
     membershipLeaves: number;
@@ -530,6 +661,14 @@ interface RoomCoreApi<S extends AnySchema = AnySchema> {
     receive(clientId: string, frame: Uint8Array): void;
     /** Full state + tick + rng for hibernation. Runs `onSleep`. Clears timers. */
     serialize(): Uint8Array;
+    /**
+     * The earliest pending room-timer deadline the last `serialize()` cleared, on `host.now()`'s
+     * clock, or `undefined` if there was none. The worker translates it to wall clock and hands it
+     * to the supervisor, which wakes the room at it — a `room.setTimeout` loses its callback to a
+     * hibernation but no longer loses the room's chance to act on the deadline. `undefined` until
+     * the first `serialize()`, and never touched by `snapshot()`.
+     */
+    readonly lastSerializeTimerAt: number | undefined;
     /**
      * D24: the same bytes `serialize()` produces, with none of its side effects — the room carries
      * on exactly as it was. This is what a save generation is written from; `serialize()` is what
@@ -553,6 +692,12 @@ interface RoomCoreApi<S extends AnySchema = AnySchema> {
     recording(): TimelineDump | undefined;
     /** D41: capture one tick. Called by the loop; a no-op while the recorder is unarmed. */
     captureTimeline(): void;
+    /**
+     * M7 pf4: the RPC trace so far, or `undefined` when this room was not started with
+     * `traceRpc: true`. Like `profile()`, `undefined` and "empty" are different readings: a room
+     * nobody armed and a room nobody called must not look the same.
+     */
+    rpcTrace(): RpcTraceDump | undefined;
     /**
      * Week 12: settles the promise `hostCall(reqId, …)` returned. The host calls this from its own
      * turn; the runtime runs the continuation as a discrete event and flushes afterwards, so state
@@ -587,4 +732,4 @@ interface RoomCoreApi<S extends AnySchema = AnySchema> {
     askCount(): number;
 }
 
-export { DEFAULT_RECORDS_PER_COLLECTION as D, EVENT_RING_SIZE as E, HOST_CALL_TIMEOUT_MS as H, type JoinOptions as J, type LogLevel as L, RELAY_RECORDS_PER_COLLECTION as R, type TimelineDump as T, type WriteCaps as W, DEFAULT_TIMELINE_MAX_RECORDS as a, DEFAULT_TIMELINE_MAX_TICKS as b, type HostCall as c, type HostCallResult as d, type JoinResult as e, RELAY_STATE_BYTES as f, RELAY_WRITES_PER_SECOND as g, RELAY_WRITE_CAPS as h, type RoomCoreApi as i, type RoomCoreOptions as j, type RoomEvent as k, type RoomEventKind as l, RoomFullError as m, type RoomHost as n, type RoomInspection as o, type RoomStats as p, type TimelineFrame as q, TimelineRecorder as r, type TimelineRecorderOptions as s, inspectState as t };
+export { AdmissionError as A, summarize as B, DEFAULT_RECORDS_PER_COLLECTION as D, EVENT_RING_SIZE as E, HOST_CALL_TIMEOUT_MS as H, type JoinOptions as J, type LogLevel as L, PHYSICS_STEP_EMA_ALPHA as P, RELAY_RECORDS_PER_COLLECTION as R, type StampLag as S, type TimelineDump as T, type WriteCaps as W, DEFAULT_TIMELINE_MAX_RECORDS as a, DEFAULT_TIMELINE_MAX_TICKS as b, type HostCall as c, type HostCallResult as d, type JoinResult as e, RELAY_STATE_BYTES as f, RELAY_WRITES_PER_SECOND as g, RELAY_WRITE_CAPS as h, RPC_TRACE_SIZE as i, RPC_TRACE_SUMMARY_MAX as j, type RoomCoreApi as k, type RoomCoreOptions as l, type RoomEvent as m, type RoomEventKind as n, RoomFullError as o, type RoomHost as p, type RoomInspection as q, type RoomStats as r, type RpcOutcome as s, type RpcTraceDump as t, type RpcTraceEntry as u, RpcTraceRing as v, type TimelineFrame as w, TimelineRecorder as x, type TimelineRecorderOptions as y, inspectState as z };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-export { D as DEFAULT_RECORDS_PER_COLLECTION, a as DEFAULT_TIMELINE_MAX_RECORDS, b as DEFAULT_TIMELINE_MAX_TICKS, E as EVENT_RING_SIZE, H as HOST_CALL_TIMEOUT_MS, c as HostCall, d as HostCallResult, J as JoinOptions, e as JoinResult, L as LogLevel, R as RELAY_RECORDS_PER_COLLECTION, f as RELAY_STATE_BYTES, g as RELAY_WRITES_PER_SECOND, h as RELAY_WRITE_CAPS, i as RoomCoreApi, j as RoomCoreOptions, k as RoomEvent, l as RoomEventKind, m as RoomFullError, n as RoomHost, o as RoomInspection, p as RoomStats, T as TimelineDump, q as TimelineFrame, r as TimelineRecorder, s as TimelineRecorderOptions, W as WriteCaps, t as inspectState } from './contract-UEKTud1Z.js';
-export { C as CRASH_AFTER_THROWS, M as MAX_CATCHUP, a as MatterBodyRecord, b as MatterSection, c as Mulberry32, P as PhysicsEngineTag, d as PhysicsSection, R as RoomCore, e as decodeMatterBodies, f as decodeMatterSectionEnvelope, g as decodePhysicsSection, h as decodeRapier2dSectionEnvelope, i as encodeMatterBodies, j as encodeMatterSectionEnvelope, k as encodePhysicsSection, l as encodeRapier2dSectionEnvelope, m as initMatter, n as initPhysics, o as initRapier2d, p as loadedMatter, q as loadedPhysics, r as loadedRapier2d, s as physicsSectionEngine, t as resetMatterForTests, u as resetPhysicsForTests, v as resetRapier2dForTests } from './room-uhj3b-8E.js';
+export { A as AdmissionError, D as DEFAULT_RECORDS_PER_COLLECTION, a as DEFAULT_TIMELINE_MAX_RECORDS, b as DEFAULT_TIMELINE_MAX_TICKS, E as EVENT_RING_SIZE, H as HOST_CALL_TIMEOUT_MS, c as HostCall, d as HostCallResult, J as JoinOptions, e as JoinResult, L as LogLevel, P as PHYSICS_STEP_EMA_ALPHA, R as RELAY_RECORDS_PER_COLLECTION, f as RELAY_STATE_BYTES, g as RELAY_WRITES_PER_SECOND, h as RELAY_WRITE_CAPS, i as RPC_TRACE_SIZE, j as RPC_TRACE_SUMMARY_MAX, k as RoomCoreApi, l as RoomCoreOptions, m as RoomEvent, n as RoomEventKind, o as RoomFullError, p as RoomHost, q as RoomInspection, r as RoomStats, s as RpcOutcome, t as RpcTraceDump, u as RpcTraceEntry, v as RpcTraceRing, S as StampLag, T as TimelineDump, w as TimelineFrame, x as TimelineRecorder, y as TimelineRecorderOptions, W as WriteCaps, z as inspectState, B as summarizeRpcResult } from './contract-BoCNAPZT.js';
+export { C as CRASH_AFTER_THROWS, M as MAX_CATCHUP, a as MatterBodyRecord, b as MatterSection, c as Mulberry32, P as PhysicsEngineTag, d as PhysicsSection, R as RoomCore, e as decodeMatterBodies, f as decodeMatterSectionEnvelope, g as decodePhysicsSection, h as decodeRapier2dSectionEnvelope, i as encodeMatterBodies, j as encodeMatterSectionEnvelope, k as encodePhysicsSection, l as encodeRapier2dSectionEnvelope, m as initMatter, n as initPhysics, o as initRapier2d, p as loadedMatter, q as loadedPhysics, r as loadedRapier2d, s as physicsSectionEngine, t as resetMatterForTests, u as resetPhysicsForTests, v as resetRapier2dForTests } from './room-CGbiPxi3.js';
 import { CollectionDesc, AnySchema, PlainState, DirtySet } from '@irtio/schema';
 import '@irtio/protocol';
 import '@irtio/server';
@@ -28,7 +28,10 @@ declare const RPC_TIMEOUT_MS = 5000;
  * adds and removes, so a client never learns such a record exists.
  */
 
-/** Is `c` visible to `role`? */
+/**
+ * Is `c` visible to `role`? A `visibility: 'server'` collection is visible to none — the same
+ * answer `visibility: 'role'` with an empty `roles` list has always given, said on purpose.
+ */
 declare function isVisible(c: CollectionDesc, role: string): boolean;
 /** A `SnapshotOptions.collections` predicate for one role. */
 declare function visibleTo(role: string): (c: CollectionDesc) => boolean;

package/dist/index.js

@@ -2,8 +2,9 @@ import {
   fromMigrationState,
   migrateSnapshot,
   toMigrationState
-} from "./chunk-YWDRE77H.js";
+} from "./chunk-3BCTP4YS.js";
 import {
+  AdmissionError,
   CRASH_AFTER_THROWS,
   DEFAULT_RECORDS_PER_COLLECTION,
   DEFAULT_TIMELINE_MAX_RECORDS,
@@ -12,14 +13,18 @@ import {
   HOST_CALL_TIMEOUT_MS,
   MAX_CATCHUP,
   Mulberry32,
+  PHYSICS_STEP_EMA_ALPHA,
   READABLE_SNAPSHOT_VERSIONS,
   RELAY_RECORDS_PER_COLLECTION,
   RELAY_STATE_BYTES,
   RELAY_WRITES_PER_SECOND,
   RELAY_WRITE_CAPS,
   RPC_TIMEOUT_MS,
+  RPC_TRACE_SIZE,
+  RPC_TRACE_SUMMARY_MAX,
   RoomCore,
   RoomFullError,
+  RpcTraceRing,
   SNAPSHOT_FORMAT_VERSION,
   TimelineRecorder,
   catchUpDirty,
@@ -48,12 +53,14 @@ import {
   resetMatterForTests,
   resetPhysicsForTests,
   resetRapier2dForTests,
+  summarize,
   viewKeyFor,
   visibleNames,
   visibleTo,
   writeHibernationBlob
-} from "./chunk-LT46QFLW.js";
+} from "./chunk-NPRIYYNM.js";
 export {
+  AdmissionError,
   CRASH_AFTER_THROWS,
   DEFAULT_RECORDS_PER_COLLECTION,
   DEFAULT_TIMELINE_MAX_RECORDS,
@@ -62,14 +69,18 @@ export {
   HOST_CALL_TIMEOUT_MS,
   MAX_CATCHUP,
   Mulberry32,
+  PHYSICS_STEP_EMA_ALPHA,
   READABLE_SNAPSHOT_VERSIONS,
   RELAY_RECORDS_PER_COLLECTION,
   RELAY_STATE_BYTES,
   RELAY_WRITES_PER_SECOND,
   RELAY_WRITE_CAPS,
   RPC_TIMEOUT_MS,
+  RPC_TRACE_SIZE,
+  RPC_TRACE_SUMMARY_MAX,
   RoomCore,
   RoomFullError,
+  RpcTraceRing,
   SNAPSHOT_FORMAT_VERSION,
   TimelineRecorder,
   catchUpDirty,
@@ -100,6 +111,7 @@ export {
   resetMatterForTests,
   resetPhysicsForTests,
   resetRapier2dForTests,
+  summarize as summarizeRpcResult,
   toMigrationState,
   viewKeyFor,
   visibleNames,