@woosh/meep-engine 3.14.2 → 3.14.4

package/src/engine/network/orchestrator/ServerAuthoritativeServer.js

@@ -9,6 +9,7 @@ import { make_owner_authorization } from "../ecs/owner_authorization.js";
 import { Replicator } from "../replication/Replicator.js";
 import { AlwaysRelevantScope } from "../replication/ScopeFilter.js";
 import { RewindEngine } from "../sim/RewindEngine.js";
+import { SENDER_DERIVED, SENDER_LOCAL } from "../sim/SimActionExecutor.js";
 import { NetworkPeer } from "./NetworkPeer.js";
 
 /**
@@ -22,20 +23,44 @@ import { NetworkPeer } from "./NetworkPeer.js";
  *      tagged with `(client_frame, sender_id, type_id, payload_bytes)`.
  *   2. Once per server tick, `tick(current_frame)` consumes the pending log:
  *      - Rejects entries older than the action_log's rewindable window.
- *      - Determines the oldest pending frame `replay_start`.
+ *      - Determines `replay_start`: the oldest pending frame carrying an
+ *        action the log does not already hold. The action stream re-sends
+ *        every unacked frame each tick, so most of pending is copies of
+ *        already-applied records; rewinding for those would replay the
+ *        world into the state it was already in.
  *      - Rewinds the server world back to end-of-(replay_start - 1) via the
  *        action_log's prior-state captures (see {@link RewindEngine}).
  *      - Replays forward `[replay_start, current_frame]`. For each frame `f`:
  *        - Read historical actions out of `action_log[f]` BEFORE
  *          `begin_frame(f)` recycles the buffer.
  *        - Append pending entries for `f`.
+ *        - Append anything queued by {@link enqueue_action}.
  *        - Stable-sort the merged list by `sender_id` (so multi-client order
  *          is deterministic across peers — relies on per-record sender_id in
- *          the action log).
- *        - `executor.execute` each in sorted order, then run the user-
- *          supplied local sim via {@link onLocalSim}.
+ *          the action log), and `executor.execute` each in that order.
+ *        - Run the user-supplied local sim via {@link onLocalSim}.
  *      - Clear pending.
  *
+ * A frame's records have one of two provenances, and the replay treats them
+ * differently:
+ *
+ *   - **Input** — actions that arrived from a peer, and actions the server
+ *     authored via {@link enqueue_action}. Each happened once, at a point in
+ *     time nothing can recompute, so a replay reapplies it from the log.
+ *   - **Derived output** — everything {@link onLocalSim} executes. The handler
+ *     runs again on every replay of the frame, against a world that now
+ *     includes whatever late input forced the replay, so the replay recomputes
+ *     it. Reapplying the previous pass's copy as well would apply the effect
+ *     twice — and three times on the next replay, and so on, without bound.
+ *     The executor stamps these {@link SENDER_DERIVED} while the handler runs
+ *     and {@link __read_historical} drops them.
+ *
+ * Derived records are still written, and still replicate: the prior-state
+ * capture is what lets a rewind undo the local sim's effect on replicated
+ * components (so derived output need not be idempotent — only deterministic
+ * in the frame's post-input state), and the action stream carries them to
+ * clients like any other record.
+ *
  * Net effect: a client action tagged at client tick K lands on the server as
  * if applied against end-of-K-1 server state, regardless of arrival timing
  * or order. Both peers compute identical world states for identical inputs.
@@ -67,6 +92,17 @@ export class ServerAuthoritativeServer {
     #historical_scratch = /** @type {Array<{type_id:number, sender_id:number, payload:Uint8Array}>} */ ([]);
     #sort_scratch = /** @type {Array<{sender_id:number, type_id:number, payload:Uint8Array}>} */ ([]);
     #payload_buf;
+    // Locally-authored actions waiting for the next fresh frame. Parallel
+    // arrays, serialized at enqueue time so the caller's instance is not
+    // retained (and so a bad action class is rejected at the call site rather
+    // than a tick later).
+    #local_type_ids = /** @type {number[]} */ ([]);
+    #local_payloads = /** @type {Uint8Array[]} */ ([]);
+    #local_buf;
+    // The frame this tick is simulating for the first time. Only it may take
+    // the locally-authored queue; every earlier frame in the replay window
+    // already holds, in its history, the actions it was given the first time.
+    #fresh_frame = -1;
     /**
      * Count of inbound pending entries dropped by the future-lead / total
      * bounds. See {@link onPendingActionDropped}.
@@ -180,6 +216,16 @@ export class ServerAuthoritativeServer {
          */
         this.simulation_delay_ticks = simulation_delay_ticks;
 
+        /**
+         * Peer id of this authoritative server, or `-1` when the session has no
+         * privileged peer. Actions from {@link enqueue_action} are tagged with
+         * it so they pass the owner-authorization gate on any entity (see
+         * {@link make_owner_authorization}), which is the documented convention
+         * for the server's own mutations.
+         * @type {number}
+         */
+        this.server_peer_id = server_peer_id;
+
         /**
          * Upper bound on how far ahead of the server's own simulation a peer
          * may tag an inbound action. `frame_number` is an attacker-controlled
@@ -215,6 +261,9 @@ export class ServerAuthoritativeServer {
         this.#payload_buf = new BinaryBuffer();
         this.#payload_buf.setCapacity(64);
 
+        this.#local_buf = new BinaryBuffer();
+        this.#local_buf.setCapacity(64);
+
         // Switch the Replicator to deferred-execute mode: incoming actions
         // accumulate in pending until tick() drains them.
         this.peer.replicator.on_pending_action = (peer_id, frame_number, type_id, buf, off, len) => {
@@ -231,13 +280,35 @@ export class ServerAuthoritativeServer {
         };
 
         /**
-         * Fires once per frame during the replay loop, AFTER all merged
-         * actions for that frame have been applied and BEFORE the action_log
-         * frame is closed. Use this for server-authoritative local sim
-         * (clamps, collision, AI step, etc.). The current world state
-         * reflects all inputs for this frame; the local sim should be
-         * idempotent under repeated application (because it may run many
-         * times under rollback).
+         * Fires once per execution of a frame, AFTER all input for that frame
+         * has been applied and BEFORE the action_log frame is closed. Use it
+         * for server-authoritative local sim: clamps, collision, AI step,
+         * damage resolution, spawning the effects a hit produces.
+         *
+         * **This is a derivation, not an event.** The handler runs again on
+         * every replay of the frame, and must produce the same result for the
+         * same post-input world state — it is a function OF that state, not a
+         * one-shot that happens to be called from it. Concretely:
+         *
+         *   - Decide from world state and the frame number. Both are restored
+         *     before the handler re-runs.
+         *   - Do NOT latch on handler-local flags (`if (already_fired) return`)
+         *     to make something happen once. The replay needs the handler to
+         *     re-emit; a latch makes it emit nothing, and the action is lost
+         *     the first time a rollback crosses its frame. For a genuine
+         *     one-shot — a lobby spawn, an admin command, anything decided
+         *     outside the simulation — use {@link enqueue_action}, which is
+         *     recorded as input and replayed rather than recomputed.
+         *
+         * Actions the handler executes are recorded as derived output: they
+         * replicate to clients and their prior state is captured so a rewind
+         * undoes them, but a replay recomputes them instead of reapplying the
+         * previous pass's copy. So they need not be idempotent — a handler may
+         * subtract hit points — only deterministic in the frame's post-input
+         * state. Components the handler mutates DIRECTLY, without going through
+         * an action, have no prior-state capture and are not undone by a
+         * rewind; those must additionally be idempotent, which is why a clamp
+         * is safe to write that way and `hp -= 10` is not.
          *
          * Args: `(frame_number)`.
          * @type {Signal}
@@ -334,6 +405,71 @@ export class ServerAuthoritativeServer {
         this.peer.send_time_dilation_feedback(peer_id, this.buffer_depth_for_peer(peer_id));
     }
 
+    /**
+     * Author a server-side action, to be applied on the next simulated frame.
+     *
+     * This is the supported path for a mutation the simulation cannot
+     * recompute — a spawn triggered by a lobby event, an admin command, a
+     * scripted trigger — as opposed to {@link onLocalSim}, which derives a
+     * frame's output from its state and is re-run on every replay.
+     *
+     * The action is serialized immediately (so the caller may reuse or discard
+     * the instance) and applied exactly once, on the next frame {@link tick}
+     * simulates for the first time, merged into that frame's input and ordered
+     * with it by sender. From then on it is ordinary history: replayed from the
+     * log like any other input, and never re-queued.
+     *
+     * Callable at any time EXCEPT from inside {@link onLocalSim}, which throws:
+     * that handler re-runs on every replay of its frame, so it would queue a
+     * fresh copy each time. (`executor.execute` is the opposite — it requires
+     * an open action_log frame, so it only works from inside the handler.)
+     *
+     * Recorded with {@link server_peer_id} as the sender when the session has
+     * one, so it passes the owner-authorization gate on any entity; with
+     * {@link SENDER_LOCAL} otherwise, which bypasses the gate.
+     *
+     * @param {SimAction} action
+     */
+    enqueue_action(action) {
+        assert.ok(action && action.isSimAction, 'enqueue_action: action must be a SimAction');
+        // Authoring from inside a derivation is always wrong, and unlike a
+        // latched handler it is exactly detectable, so it fails loudly here.
+        // onLocalSim runs again on every replay of its frame; each run would
+        // queue another copy, and each copy is recorded as input, so the
+        // applications compound per replay — the very shape this provenance
+        // split exists to stop. A handler that wants an effect every time the
+        // frame runs should `executor.execute` it as derived output instead.
+        // Real runtime check: asserts strip in prod.
+        if (this.executor.deriving) {
+            throw new Error(
+                'ServerAuthoritativeServer.enqueue_action: cannot author an action from inside onLocalSim — the handler re-runs on every replay, so the action would be queued again each time. Execute it through the executor to record it as derived output, or enqueue it from outside the local sim.',
+            );
+        }
+        const type_id = action.constructor.type_id;
+        assert.ok(
+            type_id >= 0,
+            `enqueue_action: action class '${action.constructor.action_type_name ?? action.constructor.name}' has no wire type_id — register it before enqueueing it`,
+        );
+
+        this.#local_buf.position = 0;
+        action.serialize(this.#local_buf);
+        const len = this.#local_buf.position;
+
+        const payload = new Uint8Array(len);
+        payload.set(this.#local_buf.raw_bytes.subarray(0, len));
+
+        this.#local_type_ids.push(type_id);
+        this.#local_payloads.push(payload);
+    }
+
+    /**
+     * Number of locally-authored actions waiting for the next simulated frame.
+     * @returns {number}
+     */
+    queued_local_action_count() {
+        return this.#local_type_ids.length;
+    }
+
     /**
      * Drive the rollback flow for one tick.
      *
@@ -360,12 +496,31 @@ export class ServerAuthoritativeServer {
             this.#pending_trim_to_window(window_oldest);
         }
 
-        // 2. Pick the replay window. `__pending_referenced_frames` is
-        //    sorted ascending; entries `> sim_frame` stay buffered.
+        // 2. Pick the replay window: the OLDEST pending frame that carries
+        //    input the action log doesn't already hold.
+        //
+        //    `__pending_referenced_frames` is sorted ascending; entries
+        //    `> sim_frame` stay buffered. Most of what it holds at any real
+        //    latency is retransmission: `Replicator.pack_for_peer` packs
+        //    every frame in [last_acked + 1, current] each tick, so each
+        //    action arrives once per tick until its ack round-trips, and the
+        //    deferral hook logs every copy. Taking `refs[0]` verbatim would
+        //    therefore rewind by the ACK round trip on every tick — and
+        //    `__replay_frame`'s dedup would then discard the very entries
+        //    that caused the rewind, leaving the world exactly as it was.
+        //    So run the same comparison here, before the window is chosen:
+        //    a frame whose every pending entry is already in the log needs
+        //    no rewind. What's left is genuinely late input, which is what
+        //    the rollback exists for.
         let replay_start = sim_frame;
         const refs = this.#pending_referenced_frames;
-        if (refs.length > 0 && refs[0] <= sim_frame) {
-            replay_start = refs[0];
+        for (let i = 0; i < refs.length; i++) {
+            const f = refs[i];
+            if (f > sim_frame) break;
+            if (this.#frame_has_unapplied_input(f)) {
+                replay_start = f;
+                break;
+            }
         }
 
         // 3. Rewind only if the replay window covers committed frames.
@@ -375,7 +530,10 @@ export class ServerAuthoritativeServer {
             this.onRewind.send3(committed_top, replay_start - 1, committed_top - (replay_start - 1));
         }
 
-        // 4. Replay [replay_start, sim_frame].
+        // 4. Replay [replay_start, sim_frame]. Only `sim_frame` is being
+        //    simulated for the first time; the rest are re-executions of
+        //    frames the log already holds.
+        this.#fresh_frame = sim_frame;
         for (let f = replay_start; f <= sim_frame; f++) {
             this.#replay_frame(f);
         }
@@ -406,6 +564,87 @@ export class ServerAuthoritativeServer {
         return max - this.current_sim_frame;
     }
 
+    /**
+     * Does frame `f` carry at least one pending entry the action log does not
+     * already hold? Only such a frame can change the world when replayed, so
+     * only such a frame is worth rewinding to.
+     *
+     * Same key as {@link __replay_frame}'s dedup — `(sender_id, type_id,
+     * payload bytes)` — asked one step earlier, against the log rather than
+     * against a scratch copy of it. The two must stay in step: a frame this
+     * call reports clean is never replayed, so an entry it treats as a
+     * duplicate that `__replay_frame` would have treated as new would be
+     * dropped from pending without ever being applied.
+     *
+     * Note the key can only recognise records the log actually holds. An
+     * action the executor REJECTED (owner authorization) writes nothing, so
+     * each of its retransmissions still reads as new input and still costs a
+     * rewind — unchanged from before this check existed, and self-limiting,
+     * because the sender stops re-sending the frame once it is acked.
+     *
+     * @param {number} f
+     * @returns {boolean}
+     * @private
+     */
+    #frame_has_unapplied_input(f) {
+        const has_history = this.action_log.has_frame(f);
+        for (let i = 0; i < this.#pending_frames.length; i++) {
+            if (this.#pending_frames[i] !== f) continue;
+            // Nothing recorded for this frame yet: every entry is new.
+            if (!has_history) return true;
+            if (!this.#log_holds_record(f, this.#pending_senders[i], this.#pending_type_ids[i], this.#pending_payloads[i])) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Walk `action_log[frame_number]` looking for a record identical to
+     * `(sender_id, type_id, payload)`. Compares the payload in place against
+     * the log's own bytes — no copy, unlike {@link __read_historical}, because
+     * this runs per pending entry on every tick.
+     *
+     * Caller must have checked `action_log.has_frame(frame_number)`.
+     *
+     * @param {number} frame_number
+     * @param {number} sender_id
+     * @param {number} type_id
+     * @param {Uint8Array} payload
+     * @returns {boolean}
+     * @private
+     */
+    #log_holds_record(frame_number, sender_id, type_id, payload) {
+        const buf = this.action_log.buffer_for(frame_number); // sets position = 0
+        const end = this.action_log.write_end_for(frame_number);
+        const bytes = buf.raw_bytes;
+        while (buf.position < end) {
+            const prior_count = buf.readUintVar();
+            for (let i = 0; i < prior_count; i++) {
+                buf.readUintVar();             // entity_id
+                buf.readUint8();               // component_type_id
+                const plen = buf.readUint32();
+                buf.position += plen;
+            }
+            const r_type_id = buf.readUint8();
+            const r_sender_id = buf.readUint8();
+            const r_payload_len = buf.readUint32();
+            const r_payload_start = buf.position;
+            buf.position += r_payload_len;
+
+            if (r_type_id !== type_id) continue;
+            if (r_sender_id !== sender_id) continue;
+            if (r_payload_len !== payload.length) continue;
+
+            let same = true;
+            for (let i = 0; i < r_payload_len; i++) {
+                if (bytes[r_payload_start + i] !== payload[i]) { same = false; break; }
+            }
+            if (same) return true;
+        }
+        return false;
+    }
+
     /** @private */
     #replay_frame(f) {
         this.#sort_scratch.length = 0;
@@ -450,6 +689,26 @@ export class ServerAuthoritativeServer {
             this.#sort_scratch.push({ sender_id: p_sender, type_id: p_type, payload: p_payload });
         }
 
+        // Locally-authored actions join the merge as input, and only on the
+        // frame being simulated for the first time — a replayed frame already
+        // holds, in the history read above, the ones it was given when it was
+        // fresh. They go in BEFORE the sort so a frame's input order does not
+        // depend on whether it is being simulated fresh or replayed: on replay
+        // these come back through __read_historical and are sorted with
+        // everything else, so the fresh pass has to sort them the same way.
+        if (f === this.#fresh_frame && this.#local_type_ids.length > 0) {
+            const sender = this.server_peer_id >= 0 ? this.server_peer_id : SENDER_LOCAL;
+            for (let i = 0; i < this.#local_type_ids.length; i++) {
+                this.#sort_scratch.push({
+                    sender_id: sender,
+                    type_id: this.#local_type_ids[i],
+                    payload: this.#local_payloads[i],
+                });
+            }
+            this.#local_type_ids.length = 0;
+            this.#local_payloads.length = 0;
+        }
+
         // Stable sort by sender. Array.prototype.sort is stable since ES2019;
         // equal sender_ids preserve insertion order, with historical entries
         // appearing before newly-arrived pending entries for the same sender.
@@ -461,10 +720,24 @@ export class ServerAuthoritativeServer {
             const s = this.#sort_scratch[i];
             this.#apply_payload(s.type_id, s.sender_id, s.payload);
         }
-        // Notify user code so server-side local sim runs at the right point
-        // in the frame (after inputs applied, before frame closed). Idempotent
-        // under repeated application across rollback replays.
-        this.onLocalSim.send1(f);
+
+        // Notify user code so server-side local sim runs at the right point in
+        // the frame: after all input for the frame is applied, before the frame
+        // is closed.
+        //
+        // Everything the handler executes is DERIVED output — the handler runs
+        // again on every replay of this frame, so the replay recomputes it
+        // rather than reapplying it. `deriving` makes the executor stamp those
+        // records SENDER_DERIVED, which is how __read_historical tells them
+        // from the input records above. Cleared in a finally: a handler that
+        // throws must not leave the executor stamping every later record as
+        // derived, which would silently drop that input from every replay.
+        this.executor.deriving = true;
+        try {
+            this.onLocalSim.send1(f);
+        } finally {
+            this.executor.deriving = false;
+        }
         this.action_log.end_frame();
     }
 
@@ -504,9 +777,18 @@ export class ServerAuthoritativeServer {
             const type_id = buf.readUint8();
             const sender_id = buf.readUint8();
             const payload_len = buf.readUint32();
-            const payload = new Uint8Array(payload_len);
-            payload.set(buf.raw_bytes.subarray(buf.position, buf.position + payload_len));
+            const payload_start = buf.position;
             buf.position += payload_len;
+
+            // Derived records are the previous pass's local-sim output. The
+            // caller re-runs onLocalSim for this frame, which recomputes them
+            // against a world that now includes the late input that forced the
+            // replay; carrying the stale copy forward as well would apply the
+            // effect twice, and the copies would accumulate one per replay.
+            if (sender_id === SENDER_DERIVED) continue;
+
+            const payload = new Uint8Array(payload_len);
+            payload.set(buf.raw_bytes.subarray(payload_start, payload_start + payload_len));
             out_array.push({ type_id, sender_id, payload });
         }
     }

package/src/engine/network/replication/Replicator.d.ts

@@ -111,12 +111,25 @@ export class Replicator {
      *
      * Writes nothing if no in-scope actions are found.
      *
+     * `max_bytes` caps how many bytes this call may add. Frame groups are
+     * written whole or not at all: when the next group would cross the cap, the
+     * pack stops before it and the return value reports how far it got, so the
+     * caller can credit exactly what it sent and pick the rest up on a later
+     * pass. The one exception is a first group that does not fit by itself —
+     * that one is written anyway, because no smaller pack could ever carry the
+     * frame and dropping it would strand those actions forever.
+     *
      * @param {number} peer_id
      * @param {number} start_frame inclusive; if no frame in range is in the log, that frame is skipped
      * @param {number} end_frame inclusive
      * @param {BinaryBuffer} out_buffer
+     * @param {number} [max_bytes] byte budget for this call; unbounded by default
+     * @returns {number} the last frame this pack covers, or `start_frame - 1` if
+     *   it covers nothing. A frame that was skipped — absent from the log, or
+     *   holding nothing in scope — counts as covered: the receiver has nothing
+     *   to apply for it, so the caller may credit it.
      */
-    pack_for_peer(peer_id: number, start_frame: number, end_frame: number, out_buffer: BinaryBuffer): void;
+    pack_for_peer(peer_id: number, start_frame: number, end_frame: number, out_buffer: BinaryBuffer, max_bytes?: number): number;
     /**
      * Parse and apply actions from `in_buffer` into the local world via the executor.
      * Each frame in the packet opens a new entry in the local action log under the

package/src/engine/network/replication/Replicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IA2DI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OA8BpF;IAvED;;;;;;;;;;;;OAYG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,2CAA2C,MAAM,eAAe,MAAM,KAAK,IAAI,CAE/H;IAYrB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH;oCAFwC,MAAM,cAAc,MAAM,GAAG,OAAO;MAE5C;IAGpC;;;;;;;;;;OAUG;IACH,uBALW,MAAM,eACN,MAAM,aACN,MAAM,kCA2ChB;IAED;;;;;;;;;OASG;IACH,0BAJW,MAAM,0CAEN,MAAM,QA4GhB;IAED;;;;;;OAMG;IACH,qBAFW,MAAM,QAKhB;;CAuFJ;mBAnZkB,uCAAuC"}
+{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IA2DI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OA8BpF;IAvED;;;;;;;;;;;;OAYG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,2CAA2C,MAAM,eAAe,MAAM,KAAK,IAAI,CAE/H;IAYrB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH;oCAFwC,MAAM,cAAc,MAAM,GAAG,OAAO;MAE5C;IAGpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAVW,MAAM,eACN,MAAM,aACN,MAAM,wCAEN,MAAM,GACJ,MAAM,CAyElB;IAED;;;;;;;;;OASG;IACH,0BAJW,MAAM,0CAEN,MAAM,QA4GhB;IAED;;;;;;OAMG;IACH,qBAFW,MAAM,QAKhB;;CAuFJ;mBA5bkB,uCAAuC"}

package/src/engine/network/replication/Replicator.js

@@ -140,18 +140,40 @@ export class Replicator {
      *
      * Writes nothing if no in-scope actions are found.
      *
+     * `max_bytes` caps how many bytes this call may add. Frame groups are
+     * written whole or not at all: when the next group would cross the cap, the
+     * pack stops before it and the return value reports how far it got, so the
+     * caller can credit exactly what it sent and pick the rest up on a later
+     * pass. The one exception is a first group that does not fit by itself —
+     * that one is written anyway, because no smaller pack could ever carry the
+     * frame and dropping it would strand those actions forever.
+     *
      * @param {number} peer_id
      * @param {number} start_frame inclusive; if no frame in range is in the log, that frame is skipped
      * @param {number} end_frame inclusive
      * @param {BinaryBuffer} out_buffer
+     * @param {number} [max_bytes] byte budget for this call; unbounded by default
+     * @returns {number} the last frame this pack covers, or `start_frame - 1` if
+     *   it covers nothing. A frame that was skipped — absent from the log, or
+     *   holding nothing in scope — counts as covered: the receiver has nothing
+     *   to apply for it, so the caller may credit it.
      */
-    pack_for_peer(peer_id, start_frame, end_frame, out_buffer) {
+    pack_for_peer(peer_id, start_frame, end_frame, out_buffer, max_bytes = Number.MAX_SAFE_INTEGER) {
         assert.isNonNegativeInteger(peer_id, 'peer_id');
         assert.isNonNegativeInteger(start_frame, 'start_frame');
         assert.isNonNegativeInteger(end_frame, 'end_frame');
 
+        // Budget is measured from wherever the caller had already written to,
+        // so a caller that prefixed a packet-type byte gets it counted.
+        const budget_end = out_buffer.position + max_bytes;
+        let last_packed = start_frame - 1;
+        let wrote_any_group = false;
+
         for (let frame = start_frame; frame <= end_frame; frame++) {
-            if (!this.action_log.has_frame(frame)) continue;
+            if (!this.action_log.has_frame(frame)) {
+                last_packed = frame;
+                continue;
+            }
 
             const buffer = this.action_log.buffer_for(frame);
             const end = this.action_log.write_end_for(frame);
@@ -173,9 +195,15 @@ export class Replicator {
                 }
             }
 
-            if (in_scope_count === 0) continue;
+            if (in_scope_count === 0) {
+                last_packed = frame;
+                continue;
+            }
 
             // Second pass: write the frame header + each in-scope action's payload only.
+            // The group's encoded size is only known once written (varint frame
+            // numbers and counts), so write it and roll back if it overran.
+            const group_start = out_buffer.position;
             out_buffer.writeUintVar(frame);
             out_buffer.writeUintVar(in_scope_count);
 
@@ -184,7 +212,20 @@ export class Replicator {
                 buffer.position = rs;
                 this.#copy_action_to(buffer, out_buffer);
             }
+
+            if (wrote_any_group && out_buffer.position > budget_end) {
+                // Doesn't fit alongside what we already have. Un-write it and
+                // stop — the caller credits only up to the previous frame and
+                // this one leads the next pack.
+                out_buffer.position = group_start;
+                break;
+            }
+
+            wrote_any_group = true;
+            last_packed = frame;
         }
+
+        return last_packed;
     }
 
     /**

package/src/engine/network/sim/ActionLog.d.ts

@@ -12,7 +12,7 @@
  *     uint32:  prior_payload_len
  *     bytes:   prior_payload       (adapter.serialize of the component's prior state)
  *   uint8:     action_type_id
- *   uint8:     sender_id           (peer that originated the action; local-only,
+ *   uint8:     sender_id           (provenance of the record; local-only,
  *                                   STRIPPED by Replicator before send)
  *   uint32:    action_payload_len
  *   bytes:     action_payload      (the action's own serialize output)
@@ -22,8 +22,18 @@
  * which means rewind code can walk records forward to find boundaries, then
  * iterate backward to apply prior states — no need to instantiate any actions.
  *
- * Note that `sender_id` is recorded in-buffer for local rollback orchestrators
- * (stable-sort tie-breaking by sender on replay) but never crosses the wire —
+ * `sender_id` says where the record came from, which is what a rollback replay
+ * needs in order to decide what to do with it:
+ *
+ *   - a peer id `[0, 253]` — arrived from that peer;
+ *   - `SENDER_LOCAL` (255) — authored on this peer;
+ *   - `SENDER_DERIVED` (254) — computed by this peer's simulation from the
+ *     frame's own state. A replay of the frame recomputes these rather than
+ *     reapplying them (see `ServerAuthoritativeServer.__read_historical`), so
+ *     the sim's output does not accumulate a copy per replay.
+ *
+ * It also gives the replay a stable sort key, so multi-client action order is
+ * deterministic across peers. It never crosses the wire —
  * {@link Replicator#pack_for_peer} strips it and the receiver derives sender
  * from the inbound packet's peer_id, so a hostile peer cannot impersonate.
  *
@@ -60,6 +70,14 @@ export class ActionLog {
      * Close the currently-open frame.
      */
     end_frame(): void;
+    /**
+     * Is a frame open for writing? {@link current_buffer} — and therefore
+     * `SimActionExecutor.execute` — throws when it is not, so a caller that can
+     * run either inside or outside a frame checks this to pick its path.
+     *
+     * @returns {boolean}
+     */
+    has_open_frame(): boolean;
     /**
      * Get the buffer for the currently-open frame for direct writing.
      *

package/src/engine/network/sim/ActionLog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionLog.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/ActionLog.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH;IAoBI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;;OAIG;IACH,sCAEC;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAShB;IAED;;OAEG;IACH,kBASC;IAED;;;;OAIG;IACH,+BAMC;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,kBAHW,MAAM,gBAKhB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;;CACJ"}
+{"version":3,"file":"ActionLog.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/ActionLog.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IAoBI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;;OAIG;IACH,sCAEC;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAShB;IAED;;OAEG;IACH,kBASC;IAED;;;;;;OAMG;IACH,kBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,+BAMC;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,kBAHW,MAAM,gBAKhB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;;CACJ"}

package/src/engine/network/sim/ActionLog.js

@@ -14,7 +14,7 @@ import { FrameBufferRing } from "../state/FrameBufferRing.js";
  *     uint32:  prior_payload_len
  *     bytes:   prior_payload       (adapter.serialize of the component's prior state)
  *   uint8:     action_type_id
- *   uint8:     sender_id           (peer that originated the action; local-only,
+ *   uint8:     sender_id           (provenance of the record; local-only,
  *                                   STRIPPED by Replicator before send)
  *   uint32:    action_payload_len
  *   bytes:     action_payload      (the action's own serialize output)
@@ -24,8 +24,18 @@ import { FrameBufferRing } from "../state/FrameBufferRing.js";
  * which means rewind code can walk records forward to find boundaries, then
  * iterate backward to apply prior states — no need to instantiate any actions.
  *
- * Note that `sender_id` is recorded in-buffer for local rollback orchestrators
- * (stable-sort tie-breaking by sender on replay) but never crosses the wire —
+ * `sender_id` says where the record came from, which is what a rollback replay
+ * needs in order to decide what to do with it:
+ *
+ *   - a peer id `[0, 253]` — arrived from that peer;
+ *   - `SENDER_LOCAL` (255) — authored on this peer;
+ *   - `SENDER_DERIVED` (254) — computed by this peer's simulation from the
+ *     frame's own state. A replay of the frame recomputes these rather than
+ *     reapplying them (see `ServerAuthoritativeServer.__read_historical`), so
+ *     the sim's output does not accumulate a copy per replay.
+ *
+ * It also gives the replay a stable sort key, so multi-client action order is
+ * deterministic across peers. It never crosses the wire —
  * {@link Replicator#pack_for_peer} strips it and the receiver derives sender
  * from the inbound packet's peer_id, so a hostile peer cannot impersonate.
  *
@@ -102,6 +112,17 @@ export class ActionLog {
         this.#current_buffer = null;
     }
 
+    /**
+     * Is a frame open for writing? {@link current_buffer} — and therefore
+     * `SimActionExecutor.execute` — throws when it is not, so a caller that can
+     * run either inside or outside a frame checks this to pick its path.
+     *
+     * @returns {boolean}
+     */
+    has_open_frame() {
+        return this.#current_frame !== -1;
+    }
+
     /**
      * Get the buffer for the currently-open frame for direct writing.
      *