@irtio/runtime 4.4.0 → 4.5.1

package/dist/{chunk-JFC5BQ2N.js → chunk-23TKVLTX.js}

@@ -2478,8 +2478,9 @@ var Loop = class {
    * 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.
+   * the room resident forever — pending timers are explicitly *not* a reason to stay awake. A
+   * one-shot deadline is handed to the supervisor, which wakes the room at it; an interval is
+   * simply dropped, with a warning (bugs.md #142). Reset by real activity.
    */
   timerDeferred = false;
   get intervalMs() {
@@ -2750,22 +2751,51 @@ var Loop = class {
   }
   /**
    * The earliest pending room timer's due time on `host.now()`'s clock, or `undefined` when the
-   * room has none armed.
+   * room has none armed. Every timer counts here, repeating ones included, because this is what
+   * the idle check reads to decide whether a firing is close enough to defer the sleep past —
+   * and a firing milliseconds away is worth waiting out whatever kind of timer produced it.
    *
-   * 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`.
+   * What the *departure* reports to the supervisor is a narrower question with a different
+   * answer: see `departureTimers`.
    *
    * 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() {
+    return this.earliestAt(() => true);
+  }
+  /**
+   * What `serialize()` hands the supervisor: the earliest **one-shot** deadline the departure is
+   * about to clear, and how many *repeating* timers went with it.
+   *
+   * Read 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`.
+   *
+   * bugs.md #142: that contract is a statement about a **deadline**, and only a `setTimeout` has
+   * one. A `setInterval` has a cadence, so its next due time is one period away no matter when
+   * you ask — including one period after the room hibernates. Arming the wake for it made an
+   * interval mean "never let this room stay asleep": the room slept, the wake brought it back
+   * milliseconds or one period later, `onWake` re-armed the interval as the docs teach, and the
+   * next departure armed the wake again, forever, at a full snapshot-terminate-spawn per cycle.
+   * An explicit `room.sleep()` could not stick at all. So a repeating timer no longer arms the
+   * wake — the room sleeps until real activity, an alarm, or a one-shot deadline it also holds —
+   * and `serialize()` says so out loud, because the alternative to a dropped interval is a
+   * durable alarm and a room author cannot choose it without being told.
+   */
+  departureTimers() {
+    let repeating = 0;
+    for (const t of this.timers.values()) if (t.repeat) repeating++;
+    return { at: this.earliestAt((t) => !t.repeat), repeating };
+  }
+  earliestAt(want) {
     if (this.timers.size === 0) return void 0;
     const now = this.core.host.now();
     let best;
     for (const t of this.timers.values()) {
+      if (!want(t)) continue;
       const at = this.core.mode === "event" ? t.dueAtMs : now + Math.max(0, t.dueTick - this.core.tick) * this.intervalMs;
       if (best === void 0 || at < best) best = at;
     }
@@ -7099,8 +7129,8 @@ var RoomCore = class _RoomCore {
     );
   }
   /**
-   * The earliest pending room timer's due time at the last `serialize()`, on `host.now()`'s
-   * clock, or `undefined` if nothing was armed.
+   * The earliest pending **one-shot** timer deadline at the last `serialize()`, on `host.now()`'s
+   * clock, or `undefined` if no `room.setTimeout` 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
@@ -7108,13 +7138,26 @@ var RoomCore = class _RoomCore {
    * 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`.
    *
+   * A repeating timer is deliberately not in here: it has a cadence rather than a deadline, and a
+   * wake armed for it can only ever hand the room back its own next period (bugs.md #142, and
+   * `Loop.departureTimers` for the whole argument). The warning below is what a room holding one
+   * gets instead.
+   *
    * Captured before `clearAllTimers()`, which is the only ordering that could ever have worked.
    */
   lastSerializeTimerAt;
   serialize() {
     const onSleep = this.definition.config.onSleep;
     if (onSleep) this.guard("onSleep", () => onSleep(this.state, this.room));
-    this.lastSerializeTimerAt = this.loop.earliestTimerAt();
+    const departing = this.loop.departureTimers();
+    this.lastSerializeTimerAt = departing.at;
+    if (departing.repeating > 0) {
+      const n = departing.repeating;
+      this.log(
+        "warn",
+        `going to sleep with ${n} repeating room timer${n === 1 ? "" : "s"} armed (room.setInterval). The callback does not survive hibernation and an interval does not wake a sleeping room: re-arm it in onWake if the room only needs it while it is up, or use a durable alarm for a cadence that has to fire whether or not the room is awake. room.setTimeout is unaffected \u2014 a pending one still wakes the room at its deadline.`
+      );
+    }
     this.loop.clearAllTimers();
     cancelAllAsks(this.internals);
     rejectAllPending(this.internals, "room is hibernating");

package/dist/{chunk-GK53BSWK.js → chunk-VIN2SPZT.js}

@@ -3,7 +3,7 @@ import {
   parseHibernationBlob,
   sameSchemaHash,
   writeHibernationBlob
-} from "./chunk-JFC5BQ2N.js";
+} from "./chunk-23TKVLTX.js";
 
 // src/migrate.ts
 import { PRESENCE_COLLECTION, withBuiltins } from "@irtio/protocol";

package/dist/{contract-DHWlURaq.d.ts → contract-B72MNcCa.d.ts}

@@ -682,11 +682,13 @@ interface RoomCoreApi<S extends AnySchema = AnySchema> {
     /** 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()`.
+     * The earliest pending **one-shot** 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.
+     * A `room.setInterval` is not a deadline and is deliberately not reported (bugs.md #142); the
+     * departure logs a warning for one instead. `undefined` until the first `serialize()`, and
+     * never touched by `snapshot()`.
      */
     readonly lastSerializeTimerAt: number | undefined;
     /**

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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-DHWlURaq.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-BYhsLgQV.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-B72MNcCa.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-DY5J0VZR.js';
 import { CollectionDesc, AnySchema, PlainState, DirtySet } from '@irtio/schema';
 import '@irtio/protocol';
 import '@irtio/server';

package/dist/index.js

@@ -2,7 +2,7 @@ import {
   fromMigrationState,
   migrateSnapshot,
   toMigrationState
-} from "./chunk-GK53BSWK.js";
+} from "./chunk-VIN2SPZT.js";
 import {
   AdmissionError,
   CRASH_AFTER_THROWS,
@@ -59,7 +59,7 @@ import {
   visibleNames,
   visibleTo,
   writeHibernationBlob
-} from "./chunk-JFC5BQ2N.js";
+} from "./chunk-23TKVLTX.js";
 export {
   AdmissionError,
   CRASH_AFTER_THROWS,

package/dist/{room-BYhsLgQV.d.ts → room-DY5J0VZR.d.ts}

@@ -1,7 +1,7 @@
 import { PlatformNotice, AttributeOptions, ProfileSnapshot } from '@irtio/protocol';
 import { DirtySet, AnySchema, PlainState, Tracked, State } from '@irtio/schema';
 import { RoomDefinition, RoomMode, Room, RewindView, Ctx, CustomStepper, CustomPose, MatterModule, MatterEngine, MatterBody, RapierModule, RapierWorld, RapierRigidBody, Rapier2dModule, Rapier2dWorld, Rapier2dRigidBody, ResolvedRoomConfig, LeaveReason } from '@irtio/server';
-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-DHWlURaq.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-B72MNcCa.js';
 
 declare class Mulberry32 {
     /** Current internal state (u32). Survives hibernation. */
@@ -193,10 +193,19 @@ interface LoopApi {
     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`.
+     * nothing is armed. The idle check's read, so every timer counts. See `Loop.earliestTimerAt`.
      */
     earliestTimerAt(): number | undefined;
+    /**
+     * The departure's read, taken at `serialize()` before the timers are cleared: the earliest
+     * **one-shot** deadline, which the supervisor guarantees the room is awake again by, and the
+     * number of repeating timers dropped with no such guarantee (bugs.md #142). See
+     * `Loop.departureTimers`.
+     */
+    departureTimers(): {
+        readonly at: number | undefined;
+        readonly repeating: number;
+    };
     /** Internal one-shot on the host clock (RPC timeouts in event mode). */
     after(ms: number, fn: () => void): void;
 }
@@ -420,8 +429,9 @@ declare class Loop implements LoopApi {
      * 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.
+     * the room resident forever — pending timers are explicitly *not* a reason to stay awake. A
+     * one-shot deadline is handed to the supervisor, which wakes the room at it; an interval is
+     * simply dropped, with a warning (bugs.md #142). Reset by real activity.
      */
     private timerDeferred;
     constructor(core: RoomInternals);
@@ -468,18 +478,43 @@ declare class Loop implements LoopApi {
     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.
+     * room has none armed. Every timer counts here, repeating ones included, because this is what
+     * the idle check reads to decide whether a firing is close enough to defer the sleep past —
+     * and a firing milliseconds away is worth waiting out whatever kind of timer produced it.
      *
-     * 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`.
+     * What the *departure* reports to the supervisor is a narrower question with a different
+     * answer: see `departureTimers`.
      *
      * 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;
+    /**
+     * What `serialize()` hands the supervisor: the earliest **one-shot** deadline the departure is
+     * about to clear, and how many *repeating* timers went with it.
+     *
+     * Read 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`.
+     *
+     * bugs.md #142: that contract is a statement about a **deadline**, and only a `setTimeout` has
+     * one. A `setInterval` has a cadence, so its next due time is one period away no matter when
+     * you ask — including one period after the room hibernates. Arming the wake for it made an
+     * interval mean "never let this room stay asleep": the room slept, the wake brought it back
+     * milliseconds or one period later, `onWake` re-armed the interval as the docs teach, and the
+     * next departure armed the wake again, forever, at a full snapshot-terminate-spawn per cycle.
+     * An explicit `room.sleep()` could not stick at all. So a repeating timer no longer arms the
+     * wake — the room sleeps until real activity, an alarm, or a one-shot deadline it also holds —
+     * and `serialize()` says so out loud, because the alternative to a dropped interval is a
+     * durable alarm and a room author cannot choose it without being told.
+     */
+    departureTimers(): {
+        readonly at: number | undefined;
+        readonly repeating: number;
+    };
+    private earliestAt;
     clearAllTimers(): void;
     after(ms: number, fn: () => void): void;
 }
@@ -1235,8 +1270,8 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
      */
     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.
+     * The earliest pending **one-shot** timer deadline at the last `serialize()`, on `host.now()`'s
+     * clock, or `undefined` if no `room.setTimeout` 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
@@ -1244,6 +1279,11 @@ declare class RoomCore<S extends AnySchema = AnySchema> implements RoomCoreApi<S
      * 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`.
      *
+     * A repeating timer is deliberately not in here: it has a cadence rather than a deadline, and a
+     * wake armed for it can only ever hand the room back its own next period (bugs.md #142, and
+     * `Loop.departureTimers` for the whole argument). The warning below is what a room holding one
+     * gets instead.
+     *
      * Captured before `clearAllTimers()`, which is the only ordering that could ever have worked.
      */
     lastSerializeTimerAt: number | undefined;

package/dist/test/index.d.ts

@@ -1,8 +1,8 @@
-import { R as RoomCore } from '../room-BYhsLgQV.js';
-export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-BYhsLgQV.js';
+import { R as RoomCore } from '../room-DY5J0VZR.js';
+export { m as initMatter, n as initPhysics, o as initRapier2d } from '../room-DY5J0VZR.js';
 import { ErrorCodeName, FrameType } from '@irtio/protocol';
 import { NpcConfig, LeaveReason, Room, RoomDefinition } from '@irtio/server';
-import { p as RoomHost, L as LogLevel, k as RoomCoreApi, c as HostCall, d as HostCallResult, W as WriteCaps, r as RoomStats } from '../contract-DHWlURaq.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-B72MNcCa.js';
 import { AnySchema, PlainState, EntityCollection, State } from '@irtio/schema';
 
 /**

package/dist/test/index.js

@@ -6,7 +6,7 @@ import {
   initRapier2d,
   isPerClient,
   visibleNames
-} from "../chunk-JFC5BQ2N.js";
+} from "../chunk-23TKVLTX.js";
 
 // src/test/clock.ts
 var FakeClock = class {

package/dist/worker/index.d.ts

@@ -1,4 +1,4 @@
-import { L as LogLevel, t as RpcTraceDump, T as TimelineDump, r as RoomStats, c as HostCall, d as HostCallResult, k as RoomCoreApi, p as RoomHost } from '../contract-DHWlURaq.js';
+import { L as LogLevel, t as RpcTraceDump, T as TimelineDump, r as RoomStats, c as HostCall, d as HostCallResult, k as RoomCoreApi, p as RoomHost } from '../contract-B72MNcCa.js';
 import { ErrorCodeName, ProfileSnapshot, PlatformNotice } from '@irtio/protocol';
 import { NpcConfig, LeaveReason } from '@irtio/server';
 import '@irtio/schema';
@@ -230,13 +230,16 @@ type FromWorker = {
     reqId: number;
     bytes: Uint8Array;
     /**
-     * The earliest pending `room.setTimeout`/`setInterval` deadline the departure serialize
-     * just cleared, in **wall-clock ms** (`Date.now()`'s frame, translated in the worker the
-     * same way `setAlarm`'s `atMs` is — the room's own clock is `performance.now()` and means
-     * nothing to a supervisor that outlives the worker).
+     * The earliest pending `room.setTimeout` deadline the departure serialize just cleared, in
+     * **wall-clock ms** (`Date.now()`'s frame, translated in the worker the same way
+     * `setAlarm`'s `atMs` is — the room's own clock is `performance.now()` and means nothing to
+     * a supervisor that outlives the worker).
      *
-     * Absent when the room had no timers armed, and always absent for `forSave`, which clears
-     * nothing and therefore loses nothing. The supervisor arms an internal wake for it so the
+     * Absent when the room had no one-shot timer armed, and always absent for `forSave`, which
+     * clears nothing and therefore loses nothing. A `room.setInterval` never reports here: it
+     * is a cadence rather than a deadline, and a wake armed for one only ever hands the room
+     * its own next period, which is how an interval came to mean "this room never stays
+     * asleep" (bugs.md #142). The supervisor arms an internal wake for what does report, so the
      * room is up again by the time its timer would have fired.
      */
     nextTimerAt?: number;

package/dist/worker/index.js

@@ -1,6 +1,6 @@
 import {
   migrateSnapshot
-} from "../chunk-GK53BSWK.js";
+} from "../chunk-VIN2SPZT.js";
 import {
   AdmissionError,
   RoomCore,
@@ -10,7 +10,7 @@ import {
   initRapier2d,
   onFirstRapierStep,
   rapierHasStepped
-} from "../chunk-JFC5BQ2N.js";
+} from "../chunk-23TKVLTX.js";
 
 // src/worker/index.ts
 import { getHeapStatistics } from "v8";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@irtio/runtime",
-  "version": "4.4.0",
+  "version": "4.5.1",
   "description": "irtio room runtime: RoomCore, worker_threads host, in-process test harness",
   "license": "MIT",
   "repository": {
@@ -36,9 +36,9 @@
     "@dimforge/rapier2d-compat": "0.20.0",
     "@dimforge/rapier3d-compat": "0.20.0",
     "matter-js": "0.20.0",
-    "@irtio/protocol": "^4.4.0",
-    "@irtio/schema": "^4.4.0",
-    "@irtio/server": "^4.4.0"
+    "@irtio/protocol": "^4.5.1",
+    "@irtio/schema": "^4.5.1",
+    "@irtio/server": "^4.5.1"
   },
   "devDependencies": {
     "@types/matter-js": "0.20.2"