@irtio/runtime 0.1.0 → 0.2.0

package/dist/{contract-BhD88PGb.d.ts → contract-B8QSO0MH.d.ts}

@@ -7,7 +7,7 @@ import { RoomDefinition, Room, LeaveReason } from '@irtio/server';
  * the room's state plus a ring of recent events. Always on; recording is O(1) per event.
  */
 
-type RoomEventKind = 'join' | 'leave' | 'write' | 'write-rejected' | 'correct' | 'call' | 'reply' | 'msg' | 'error';
+type RoomEventKind = 'join' | 'leave' | 'write' | 'write-rejected' | 'correct' | 'call' | 'reply' | 'msg' | 'alarm' | 'error';
 interface RoomEvent {
     readonly tick: number;
     readonly kind: RoomEventKind;
@@ -24,6 +24,45 @@ interface RoomInspection {
 }
 
 type LogLevel = 'info' | 'warn' | 'error';
+/**
+ * Week 12: host-side async work a room asked for — a save generation (D24) or a player-KV
+ * operation (D25). Room handlers are synchronous and there is no way to block one on I/O, so
+ * every one of these is started by `RoomHost.hostCall` and *finished* by the host calling
+ * `RoomCoreApi.completeHostCall` — the same way an inbound frame arrives. That is what makes
+ * "the continuation runs as its own event between ticks" a structural property of the seam
+ * rather than a promise the runtime makes and hopes the host keeps.
+ */
+type HostCall = {
+    readonly kind: 'save';
+} | {
+    readonly kind: 'kvGet';
+    readonly playerId: string;
+    readonly key: string;
+} | {
+    readonly kind: 'kvSet';
+    readonly playerId: string;
+    readonly key: string;
+    readonly value: string;
+} | {
+    readonly kind: 'kvDelete';
+    readonly playerId: string;
+    readonly key: string;
+};
+/**
+ * What a `HostCall` produced. `value` carries the save id for `save` and the stored string for
+ * `kvGet` (absent = the key was never written, which resolves `undefined` rather than rejecting).
+ * A failure carries a named `E_*` code so the room can tell a size limit from an outage.
+ */
+type HostCallResult = {
+    readonly ok: true;
+    readonly value?: string;
+} | {
+    readonly ok: false;
+    readonly code: string;
+    readonly message: string;
+};
+/** How long a `HostCall` may stay outstanding before the runtime rejects it itself. */
+declare const HOST_CALL_TIMEOUT_MS = 10000;
 /** Everything the room needs from the outside world. No timers, sockets, clocks, or console inside. */
 interface RoomHost {
     /** Monotonic ms. Fake in the harness. */
@@ -41,6 +80,19 @@ interface RoomHost {
     log(level: LogLevel, args: unknown[]): void;
     /** N consecutive tick throws; the runtime does not recover itself. */
     crashed(reason: string): void;
+    /**
+     * Week 12: start host-side async work (D24 save, D25 KV). The host **must** deliver the
+     * outcome by calling `RoomCoreApi.completeHostCall(reqId, result)` from its own event loop
+     * turn, never synchronously from inside this call — a handler is on the stack.
+     */
+    hostCall(reqId: number, call: HostCall): void;
+    /**
+     * D26: arm the durable alarm `name` for `atMs`, or cancel it when `atMs` is `undefined`.
+     * Arming a name that is already armed replaces its due time. Alarm state is the **host's**,
+     * not the room's: nothing about it goes into the hibernation blob, and the host fires one by
+     * calling `RoomCoreApi.fireAlarm(name)`.
+     */
+    setAlarm(name: string, atMs: number | undefined): void;
 }
 interface RoomCoreOptions {
     readonly roomId: string;
@@ -57,6 +109,13 @@ interface JoinOptions {
     readonly name?: string;
     /** A resumed session: presence record kept, `ctx.reconnecting = true`. */
     readonly reconnecting?: boolean;
+    /**
+     * D25: the identity `ctx.playerId` reports and `room.kv` is meant to be keyed by. Defaults to
+     * `clientId`, which — because a resume token carries the client id across a reconnect — is
+     * exactly the resume-token identity, and no more stable than that token. Week 13 (D27) passes
+     * a JWT subject here instead without anything else changing.
+     */
+    readonly playerId?: string;
 }
 interface JoinResult {
     readonly tick: number;
@@ -81,6 +140,13 @@ interface RoomStats {
     bytesOutByClient: Map<string, number>;
     handlerErrors: number;
     encodesLastFlush: number;
+    aoiEncodesLastFlush: number;
+    gridBuildMs: number;
+    gridQueryMs: number;
+    aoiEncodeMs: number;
+    visibleIdsTotal: number;
+    membershipEnters: number;
+    membershipLeaves: number;
     corrections: number;
 }
 /** The surface the worker host and the harness drive. Implemented by `RoomCore`. */
@@ -113,8 +179,26 @@ interface RoomCoreApi<S extends AnySchema = AnySchema> {
     receive(clientId: string, frame: Uint8Array): void;
     /** Full state + tick + rng for hibernation. Runs `onSleep`. Clears timers. */
     serialize(): Uint8Array;
+    /**
+     * 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
+     * a room going to sleep is written from.
+     */
+    snapshot(): Uint8Array;
     /** Live JSON view of the room (dev page / supervisor admin API). */
     inspect(): RoomInspection;
+    /**
+     * 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
+     * a continuation mutated goes out exactly like state a handler mutated.
+     */
+    completeHostCall(reqId: number, result: HostCallResult): void;
+    /**
+     * D26: runs the `alarms[name]` handler as its own event between ticks, then flushes. Unknown
+     * names are logged and ignored — a room that dropped a handler in a redeploy must not crash on
+     * an alarm armed by the version before it.
+     */
+    fireAlarm(name: string): void;
 }
 
-export { EVENT_RING_SIZE as E, type JoinOptions as J, type LogLevel as L, type RoomCoreApi as R, type JoinResult as a, type RoomCoreOptions as b, type RoomEvent as c, type RoomEventKind as d, RoomFullError as e, type RoomHost as f, type RoomInspection as g, type RoomStats as h, inspectState as i };
+export { EVENT_RING_SIZE as E, HOST_CALL_TIMEOUT_MS as H, type JoinOptions as J, type LogLevel as L, type RoomCoreApi as R, type HostCall as a, type HostCallResult as b, type JoinResult as c, type RoomCoreOptions as d, type RoomEvent as e, type RoomEventKind as f, RoomFullError as g, type RoomHost as h, type RoomInspection as i, type RoomStats as j, inspectState as k };

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { E as EVENT_RING_SIZE, J as JoinOptions, a as JoinResult, L as LogLevel, R as RoomCoreApi, b as RoomCoreOptions, c as RoomEvent, d as RoomEventKind, e as RoomFullError, f as RoomHost, g as RoomInspection, h as RoomStats, i as inspectState } from './contract-BhD88PGb.js';
-export { C as CRASH_AFTER_THROWS, M as MAX_CATCHUP, a as Mulberry32, R as RoomCore } from './room-CBsSCueH.js';
-import { AnySchema, PlainState, DirtySet, CollectionDesc } from '@irtio/schema';
+export { E as EVENT_RING_SIZE, H as HOST_CALL_TIMEOUT_MS, a as HostCall, b as HostCallResult, J as JoinOptions, c as JoinResult, L as LogLevel, R as RoomCoreApi, d as RoomCoreOptions, e as RoomEvent, f as RoomEventKind, g as RoomFullError, h as RoomHost, i as RoomInspection, j as RoomStats, k as inspectState } from './contract-B8QSO0MH.js';
+export { C as CRASH_AFTER_THROWS, M as MAX_CATCHUP, a as Mulberry32, P as PhysicsSection, R as RoomCore, d as decodePhysicsSection, e as encodePhysicsSection, i as initPhysics, l as loadedPhysics, r as resetPhysicsForTests } from './room-BfALTh7M.js';
+import { CollectionDesc, AnySchema, PlainState, DirtySet } from '@irtio/schema';
 import '@irtio/protocol';
 import '@irtio/server';
 
@@ -40,7 +40,16 @@ declare function visibleNames(ext: AnySchema, role: string): ReadonlySet<string>
  */
 declare function viewKeyFor(ext: AnySchema, role: string): string;
 /** The `join` snapshot: full state restricted to the client's view. */
-declare function encodeViewSnapshot(ext: AnySchema, plain: PlainState, role: string, tick: number): Uint8Array;
+declare function encodeViewSnapshot(ext: AnySchema, plain: PlainState, role: string, tick: number, memberships?: ReadonlyMap<string, ReadonlySet<string>>): Uint8Array;
+interface VisibilityPolicy {
+    readonly memberships: ReadonlyMap<string, ReadonlySet<string>>;
+    maySeeCollection(desc: CollectionDesc): boolean;
+    maySeeEntity(desc: CollectionDesc, id: string): boolean;
+    /** Viewer cell, offending cells, and the radius — the diagnostics a leak report needs. */
+    describeSpatial(desc: CollectionDesc, ids: readonly string[]): string | undefined;
+}
+/** Reusable authority-based policy for runtime, harness, and bot leak checks. */
+declare function createVisibilityPolicy(ext: AnySchema, plain: PlainState, clientId: string, role: string): VisibilityPolicy;
 /** One view's `DELTA` payload, or `null` when nothing visible to `role` changed. */
 declare function encodeViewDelta(ext: AnySchema, plain: PlainState, dirty: DirtySet, role: string, tick: number): Uint8Array | null;
 /**
@@ -61,14 +70,28 @@ declare function catchUpDirty(ext: AnySchema, plain: PlainState, fromRole: strin
  *   u32 rng state
  *   u32 tick
  *   u8  mode (1 = event, 0 = tick)
+ *   [v2] blob physics section (varint length + bytes; length 0 = no world)
  *   ... encodeSnapshot(withBuiltins(schema), state)
  *
+ * **v2 (week 9, D22)** adds the physics section: the Rapier world snapshot plus the entity↔handle
+ * map (`core/physics.ts` encodes it). It rides *inside* this blob rather than beside it so that
+ * wake is atomic — state and world always come back from the same bytes, and every store, cache
+ * and transfer path that already moves one array keeps working untouched.
+ *
+ * A **v1 blob still reads**: it simply has no physics section. For a room that has since gained
+ * physics that is the pre-physics-deploy case — the world is rebuilt from schema state and the
+ * room's `setup` runs again, which is logged. Writers emit v1 when there is no world, so a room
+ * without physics produces byte-identical blobs to the ones week 8 wrote.
+ *
  * Note: the *deployment* version is deliberately **not** in here. It lives in the store
  * key (`<project>/<room>@v<deployment>`), which keeps the blob format frozen — an old snapshot
  * stays valid across deployments — and lets a wake path discover the version by listing keys
  * instead of parsing bytes it may not yet know how to read.
  */
-declare const SNAPSHOT_FORMAT_VERSION = 1;
+/** Written when the blob carries a physics world; v1 otherwise (and v1 is still read). */
+declare const SNAPSHOT_FORMAT_VERSION = 2;
+/** Versions this build can parse. */
+declare const READABLE_SNAPSHOT_VERSIONS: readonly number[];
 type SnapshotMode = 'tick' | 'event';
 interface SnapshotHeader {
     readonly seed: number;
@@ -77,11 +100,15 @@ interface SnapshotHeader {
     readonly mode: SnapshotMode;
 }
 interface ParsedSnapshot extends SnapshotHeader {
+    /** The blob's own format version (1 or 2). */
+    readonly version: number;
+    /** The encoded physics section, or `undefined` for a v1 blob / a room with no world. */
+    readonly physics: Uint8Array | undefined;
     /** The codec snapshot, encoded under `withBuiltins(schema)`. */
     readonly snapshot: Uint8Array;
 }
 declare function parseHibernationBlob(bytes: Uint8Array): ParsedSnapshot;
-declare function writeHibernationBlob(header: SnapshotHeader, snapshot: Uint8Array): Uint8Array;
+declare function writeHibernationBlob(header: SnapshotHeader, snapshot: Uint8Array, physics?: Uint8Array): Uint8Array;
 
 /**
  * Wake-time schema migration.
@@ -123,7 +150,11 @@ interface MigrationHelpers {
 }
 interface MigrationModule {
     up(state: MigrationState, s: MigrationHelpers): MigrationState | void;
-    /** Scaffolded by `irtio migrate create` and stored; unused until rollback ships. */
+    /**
+     * Scaffolded by `irtio migrate create` and stored, but never called. `irtio rollback` restores
+     * the pre-migration save generation the `migrate` deploy wrote rather than running an inverse
+     * transform, which is how it undoes migrations that have no `down` at all.
+     */
     down?(state: MigrationState, s: MigrationHelpers): MigrationState | void;
 }
 /**
@@ -158,4 +189,4 @@ declare function migrateSnapshot(blob: Uint8Array, chain: readonly MigrationStep
 declare function toMigrationState(schema: AnySchema, plain: PlainState): MigrationState;
 declare function fromMigrationState(schema: AnySchema, state: MigrationState, version: number): PlainState;
 
-export { type MigrateOptions, type MigrationEntity, type MigrationHelpers, type MigrationModule, type MigrationOutcome, type MigrationRecord, type MigrationState, type MigrationStep, type ParsedSnapshot, RPC_TIMEOUT_MS, SNAPSHOT_FORMAT_VERSION, type SnapshotHeader, type SnapshotMode, catchUpDirty, encodeViewDelta, encodeViewSnapshot, fromMigrationState, isVisible, migrateSnapshot, parseHibernationBlob, toMigrationState, viewKeyFor, visibleNames, visibleTo, writeHibernationBlob };
+export { type MigrateOptions, type MigrationEntity, type MigrationHelpers, type MigrationModule, type MigrationOutcome, type MigrationRecord, type MigrationState, type MigrationStep, type ParsedSnapshot, READABLE_SNAPSHOT_VERSIONS, RPC_TIMEOUT_MS, SNAPSHOT_FORMAT_VERSION, type SnapshotHeader, type SnapshotMode, type VisibilityPolicy, catchUpDirty, createVisibilityPolicy, encodeViewDelta, encodeViewSnapshot, fromMigrationState, isVisible, migrateSnapshot, parseHibernationBlob, toMigrationState, viewKeyFor, visibleNames, visibleTo, writeHibernationBlob };

package/dist/index.js

@@ -2,44 +2,60 @@ import {
   fromMigrationState,
   migrateSnapshot,
   toMigrationState
-} from "./chunk-3DQHT4CM.js";
+} from "./chunk-FA4IOC2Z.js";
 import {
   CRASH_AFTER_THROWS,
   EVENT_RING_SIZE,
+  HOST_CALL_TIMEOUT_MS,
   MAX_CATCHUP,
   Mulberry32,
+  READABLE_SNAPSHOT_VERSIONS,
   RPC_TIMEOUT_MS,
   RoomCore,
   RoomFullError,
   SNAPSHOT_FORMAT_VERSION,
   catchUpDirty,
+  createVisibilityPolicy,
+  decodePhysicsSection,
+  encodePhysicsSection,
   encodeViewDelta,
   encodeViewSnapshot,
+  initPhysics,
   inspectState,
   isVisible,
+  loadedPhysics,
   parseHibernationBlob,
+  resetPhysicsForTests,
   viewKeyFor,
   visibleNames,
   visibleTo,
   writeHibernationBlob
-} from "./chunk-X5S364FY.js";
+} from "./chunk-GKMD3ICD.js";
 export {
   CRASH_AFTER_THROWS,
   EVENT_RING_SIZE,
+  HOST_CALL_TIMEOUT_MS,
   MAX_CATCHUP,
   Mulberry32,
+  READABLE_SNAPSHOT_VERSIONS,
   RPC_TIMEOUT_MS,
   RoomCore,
   RoomFullError,
   SNAPSHOT_FORMAT_VERSION,
   catchUpDirty,
+  createVisibilityPolicy,
+  decodePhysicsSection,
+  encodePhysicsSection,
   encodeViewDelta,
   encodeViewSnapshot,
   fromMigrationState,
+  initPhysics,
   inspectState,
   isVisible,
+  loadedPhysics,
   migrateSnapshot,
   parseHibernationBlob,
+  resetPhysicsForTests,
   toMigrationState,
   viewKeyFor,
   visibleNames,