@woosh/meep-engine 3.14.3 → 3.14.5

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

@@ -8,7 +8,9 @@ import { NetworkIdentity } from "../ecs/components/NetworkIdentity.js";
 import { make_owner_authorization } from "../ecs/owner_authorization.js";
 import { Replicator } from "../replication/Replicator.js";
 import { AlwaysRelevantScope } from "../replication/ScopeFilter.js";
+import { ActionRecordCursor } from "../sim/ActionRecordCursor.js";
 import { RewindEngine } from "../sim/RewindEngine.js";
+import { SENDER_DERIVED, SENDER_LOCAL } from "../sim/SimActionExecutor.js";
 import { NetworkPeer } from "./NetworkPeer.js";
 
 /**
@@ -19,23 +21,48 @@ import { NetworkPeer } from "./NetworkPeer.js";
  *
  *   1. Inbound action packets do NOT execute on arrival. Instead, a deferral
  *      hook on the {@link Replicator} drops them into a per-tick pending log
- *      tagged with `(client_frame, sender_id, type_id, payload_bytes)`.
+ *      tagged with `(client_frame, sender_id, type_id, payload_bytes)` —
+ *      unless the action log already holds that record. The action stream
+ *      re-sends every unconfirmed frame each tick, so most arrivals at any
+ *      real latency are copies of applied records; those are dropped where
+ *      they arrive, and pending holds only input the log does not.
  *   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, which by the
+ *        above is the oldest frame whose outcome can change.
  *      - 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 +94,15 @@ 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;
+    // Walks a frame's records, for the history read and the arrival check.
+    #cursor = new ActionRecordCursor();
+    // 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;
     /**
      * Count of inbound pending entries dropped by the future-lead / total
      * bounds. See {@link onPendingActionDropped}.
@@ -92,8 +128,12 @@ export class ServerAuthoritativeServer {
      *   frame_capacity?: number,
      *   initial_buffer_size?: number,
      *   simulation_delay_ticks?: number,
+     *   max_packets_per_tick?: number,
      * }} options
      *
+     * `max_packets_per_tick`: forwarded to {@link NetworkPeer}; how many
+     * action-stream packets a tick may send one peer.
+     *
      * `simulation_delay_ticks`: server-side input buffer (Overwatch-style).
      * When > 0, {@link tick}(wall_frame) simulates
      * `sim_frame = wall_frame - simulation_delay_ticks`. Pending actions
@@ -116,6 +156,7 @@ export class ServerAuthoritativeServer {
         max_pending_total = 4096,
         identity_class = NetworkIdentity,
         server_peer_id = -1,
+        max_packets_per_tick,
     }) {
         assert.isNonNegativeInteger(simulation_delay_ticks, 'simulation_delay_ticks');
         assert.isPositiveInteger(max_pending_future_lead, 'max_pending_future_lead');
@@ -129,6 +170,7 @@ export class ServerAuthoritativeServer {
             scope_filter,
             frame_capacity,
             initial_buffer_size,
+            max_packets_per_tick,
         });
 
         /** @type {EntityComponentDataset} */
@@ -180,6 +222,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 +267,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 +286,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 +411,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,8 +502,13 @@ 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 at or below
+        //    `sim_frame`. Pending holds only input the log does not already
+        //    hold — a retransmission of an applied record is dropped on
+        //    arrival, see __pending_add — so the oldest pending frame is the
+        //    oldest frame whose outcome can change, and a rewind to it is
+        //    never wasted. `__pending_referenced_frames` is sorted
+        //    ascending; entries `> sim_frame` stay buffered.
         let replay_start = sim_frame;
         const refs = this.#pending_referenced_frames;
         if (refs.length > 0 && refs[0] <= sim_frame) {
@@ -375,9 +522,11 @@ 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.
         for (let f = replay_start; f <= sim_frame; f++) {
-            this.#replay_frame(f);
+            this.#replay_frame(f, f === sim_frame);
         }
 
         // 5. Keep only `frame > sim_frame` pending (future buffer).
@@ -406,8 +555,57 @@ export class ServerAuthoritativeServer {
         return max - this.current_sim_frame;
     }
 
-    /** @private */
-    #replay_frame(f) {
+    /**
+     * 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 once per arriving action.
+     *
+     * 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 —
+     * self-limiting, because the sender stops re-sending the frame once it is
+     * acked.
+     *
+     * Caller must have checked `action_log.has_frame(frame_number)`, and that
+     * the frame is closed.
+     *
+     * @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 cursor = this.#cursor;
+        cursor.open(this.action_log, frame_number);
+        const bytes = cursor.buffer.raw_bytes;
+        while (cursor.next()) {
+            if (cursor.action_type_id !== type_id) continue;
+            if (cursor.sender_id !== sender_id) continue;
+            if (cursor.payload_len !== payload.length) continue;
+
+            const payload_start = cursor.payload_start;
+            let same = true;
+            for (let i = 0; i < payload.length; i++) {
+                if (bytes[payload_start + i] !== payload[i]) { same = false; break; }
+            }
+            if (same) return true;
+        }
+        return false;
+    }
+
+    /**
+     * Execute frame `f`: its history, its pending input and — when `fresh`,
+     * meaning this is the first time the frame is simulated — the
+     * locally-authored queue, merged and sorted, then the local sim.
+     *
+     * @param {number} f
+     * @param {boolean} fresh
+     * @private
+     */
+    #replay_frame(f, fresh) {
         this.#sort_scratch.length = 0;
 
         // Read historical actions out of action_log[f] BEFORE begin_frame(f)
@@ -420,15 +618,13 @@ export class ServerAuthoritativeServer {
             this.#sort_scratch.push({ sender_id: h.sender_id, type_id: h.type_id, payload: h.payload });
         }
 
-        // Append newly-arrived pending actions for this frame, deduplicating
-        // against historical entries. Retransmissions are routine on the
-        // wire — `Replicator.pack_for_peer` packs every frame in
-        // [last_acked + 1, current_frame] each tick, so an action lives in
-        // every outgoing packet for the round-trip duration of its ack.
-        // The server receives each retransmission as a fresh pending entry;
-        // without dedup, the rollback flow merges it with the historical
-        // record left over from the previous apply and executes the action
-        // twice (and three times, four times… until the ack arrives).
+        // Append the pending actions for this frame. Retransmissions of
+        // records the log already holds are dropped on arrival (see
+        // __pending_add), so in the supported call pattern nothing here
+        // duplicates history. The check stays as a safety net: a duplicate
+        // that reached this point would merge with the historical record and
+        // execute the action twice, diverging the world, and the cost of the
+        // check is a scan of a small frame's copied history.
         //
         // Dedup key: (sender_id, type_id, payload bytes). Two actions are
         // "the same arrival" if all three match. (Same sender_id and
@@ -450,6 +646,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 (fresh && 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 +677,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();
     }
 
@@ -491,23 +721,20 @@ export class ServerAuthoritativeServer {
     #read_historical(frame_number, out_array) {
         out_array.length = 0;
         if (!this.action_log.has_frame(frame_number)) return;
-        const buf = this.action_log.buffer_for(frame_number); // sets position = 0
-        const end = this.action_log.write_end_for(frame_number);
-        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 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));
-            buf.position += payload_len;
-            out_array.push({ type_id, sender_id, payload });
+        const cursor = this.#cursor;
+        cursor.open(this.action_log, frame_number);
+        const bytes = cursor.buffer.raw_bytes;
+        while (cursor.next()) {
+            // 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 (cursor.sender_id === SENDER_DERIVED) continue;
+
+            const payload = new Uint8Array(cursor.payload_len);
+            payload.set(bytes.subarray(cursor.payload_start, cursor.payload_start + cursor.payload_len));
+            out_array.push({ type_id: cursor.action_type_id, sender_id: cursor.sender_id, payload });
         }
     }
 
@@ -542,17 +769,17 @@ export class ServerAuthoritativeServer {
             return;
         }
 
-        // Dedup against other pending entries for the same frame. Multiple
-        // retransmission packets routinely arrive in the same c2s.tick
-        // window when ack RTT exceeds tick period; each carries the same
-        // action records for the same frames. The __replay_frame dedup
-        // catches retransmissions across server ticks (where historical
-        // already has the record), but the SAME server tick can collect
-        // multiple identical pending entries before historical exists. So
-        // also dedup here, against everything already in pending for this
-        // frame. Match on (sender_id, type_id, payload bytes) — distinct
-        // payloads from the same sender at the same frame are legitimately
-        // different actions (move + fire) and both flow through.
+        // Retransmissions are routine on the wire: `Replicator.pack_for_peer`
+        // packs every frame in [last_acked + 1, current_frame] each tick, so
+        // an action arrives once per tick until its ack round-trips, and
+        // several copies can land in the same server tick when the round trip
+        // exceeds the tick period. A copy is recognised by its whole identity,
+        // (sender_id, type_id, payload bytes) — distinct payloads from the
+        // same sender at the same frame are legitimately different actions
+        // (move + fire) and both flow through.
+        //
+        // First against everything already pending for the frame, which
+        // catches the copies that arrive before the frame is simulated.
         for (let i = 0; i < this.#pending_frames.length; i++) {
             if (this.#pending_frames[i] !== frame_number) continue;
             if (this.#pending_senders[i] !== sender_id) continue;
@@ -560,6 +787,26 @@ export class ServerAuthoritativeServer {
             if (fastArrayEquals(this.#pending_payloads[i], payload)) return; // duplicate already in pending; drop
         }
 
+        // Then against the action log, which catches the copies that arrive
+        // after it. A record the log already holds is not input — applying it
+        // again would apply the action twice, and rewinding for it would
+        // replay the world into the state it is already in — so it is dropped
+        // here, and pending holds only input the log does not. That is what
+        // lets `tick` take the oldest pending frame as its replay window
+        // without a second look.
+        //
+        // Frames are only open inside `tick`, and packets arrive between
+        // ticks, so an open frame here means a call pattern this orchestrator
+        // does not support (a packet delivered from inside a local-sim
+        // handler). The check is skipped rather than reading an open frame's
+        // stale length; the copy then costs one spurious rewind, and
+        // `__replay_frame`'s own dedup keeps it from applying twice.
+        if (this.action_log.has_frame(frame_number)
+            && !this.action_log.has_open_frame()
+            && this.#log_holds_record(frame_number, sender_id, type_id, payload)) {
+            return;
+        }
+
         this.#pending_frames.push(frame_number);
         this.#pending_senders.push(sender_id);
         this.#pending_type_ids.push(type_id);

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

@@ -25,6 +25,10 @@
  *       uint32:  action_payload_len
  *       bytes:   action_payload
  * ```
+ * {@link NetworkPeer} prefixes each packet of this with a slice header — the
+ * frame range the packet covers and whether it is the first of the sender's
+ * tick — which it parses itself and hands to {@link unpack_from_peer} as
+ * `slice`, so the receiver can apply the sender's packets in frame order.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
@@ -56,8 +60,9 @@ export class Replicator {
      * or anything else that needs to know "frame N from peer P has just
      * been applied to the local world."
      *
-     * Fires in frame-ascending order within a single packet (the order
-     * the wire format encodes them in).
+     * Fires in frame order — within a packet, which encodes its frames
+     * ascending, and across packets, because a later slice of a sender's tick
+     * is held until the slices before it have landed.
      *
      * @type {Signal}
      */
@@ -111,27 +116,57 @@ 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
      * sender's frame number, ensuring the rewind/replay machinery sees consistent
      * frame indexing across peers.
      *
+     * `slice` is the sender's description of the packet, from the
+     * {@link NetworkPeer} slice header: the frame range it covers and whether
+     * it is the first packet of the sender's tick. Frames are applied in frame
+     * order. A slice that starts past the frames applied so far and is not a
+     * head is a later slice of a burst whose earlier slice has not landed; it
+     * is held and applied once the gap before it fills. A head is applied as
+     * soon as it arrives, because nothing the sender can still send lies
+     * before it — that is also how the receiver moves past frames lost for
+     * good. Without `slice` (callers that pack and unpack directly) the packet
+     * is taken as a head covering the frames it carries.
+     *
      * @param {number} peer_id
      * @param {BinaryBuffer} in_buffer
      * @param {number} in_buffer_end byte position to stop reading at
+     * @param {{frame_start: number, frame_end: number, head: boolean}|null} [slice]
      */
-    unpack_from_peer(peer_id: number, in_buffer: BinaryBuffer, in_buffer_end: number): void;
+    unpack_from_peer(peer_id: number, in_buffer: BinaryBuffer, in_buffer_end: number, slice?: {
+        frame_start: number;
+        frame_end: number;
+        head: boolean;
+    } | null): void;
     /**
-     * Forget the per-peer apply watermark. Call when a peer disconnects so a
-     * later peer reusing the same id (or the same peer resuming a session whose
-     * frame numbering restarts) is not wrongly deduped against stale state.
+     * Forget a peer's inbound state — its apply watermark and any slices held
+     * for it. Call when a peer disconnects so a later peer reusing the same id
+     * (or the same peer resuming a session whose frame numbering restarts) is
+     * not wrongly deduped against stale state.
      *
      * @param {number} peer_id
      */
@@ -139,4 +174,5 @@ export class Replicator {
     #private;
 }
 import Signal from "../../../core/events/signal/Signal.js";
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 //# sourceMappingURL=Replicator.d.ts.map

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":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IAkFI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OA8BpF;IA/ED;;;;;;;;;;;;;OAaG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,aAAa,YAAY,kBAAkB,MAAM,eAAe,MAAM,KAAK,IAAI,CAE/H;IAmBrB;;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,cACN,YAAY,cACZ,MAAM,GACJ,MAAM,CA4ElB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,0BALW,MAAM,aACN,YAAY,iBACZ,MAAM,UACN;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC,GAAC,IAAI,QAmEtE;IAyLD;;;;;;;OAOG;IACH,qBAFW,MAAM,QAKhB;;CA8CJ;mBAxlBkB,uCAAuC;6BAD7B,sCAAsC"}