@woosh/meep-engine 3.64.1 → 3.67.0

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

@@ -1,8 +1,6 @@
 import { assert } from "../../../core/assert.js";
 import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
-import { binarySearchHighIndex } from "../../../core/collection/array/binarySearchHighIndex.js";
 import Signal from "../../../core/events/signal/Signal.js";
-import { number_compare_ascending } from "../../../core/primitives/numbers/number_compare_ascending.js";
 import { NetworkIdentity } from "../ecs/components/NetworkIdentity.js";
 import { make_owner_authorization } from "../ecs/owner_authorization.js";
 import { Replicator } from "../replication/Replicator.js";
@@ -104,26 +102,71 @@ export const LateInput = Object.freeze({
  * @copyright Company Named Limited (c) 2026
  */
 export class ServerAuthoritativeServer {
-    // Per-tick pending input log. Parallel arrays (no per-action object
-    // alloc) of newly-arrived action records, plus a sorted unique set
-    // of the frames they reference.
+    // Pending input: the records that have arrived and are not applied yet. Parallel arrays, of
+    // which the first #pending_count entries are the records. Like every scratch list here, the
+    // arrays are written over from the start and never cut short: an array cut to length 0 gives
+    // up its storage, and the next record allocates it again.
+    #pending_count = 0;
     #pending_frames = /** @type {number[]} */ ([]);
     #pending_senders = /** @type {number[]} */ ([]);
     #pending_type_ids = /** @type {number[]} */ ([]);
+    // each from the payload pool, and at least as long as the record: see #pending_lengths
     #pending_payloads = /** @type {Uint8Array[]} */ ([]);
-    #pending_referenced_frames = /** @type {number[]} */ ([]);
+    #pending_lengths = /** @type {number[]} */ ([]);
+
+    /**
+     * The oldest frame a pending record is tagged for: where a tick's replay starts. Infinity
+     * while nothing is pending.
+     * @type {number}
+     */
+    #pending_oldest_frame = Infinity;
+
     #peer_max_received_frame;
-    // Scratch for the replay loop.
-    #historical_scratch = /** @type {Array<{type_id:number, sender_id:number, payload:Uint8Array}>} */ ([]);
+
+    /**
+     * Byte arrays for record payloads, free to be taken: the first {@link #payload_pool_count}
+     * entries. A record is copied out of a buffer that is about to be reused — a receive buffer, a
+     * log frame being reopened — and its copy goes back here once the record is applied or dropped,
+     * so a steady stream of input allocates none.
+     * @type {Uint8Array[]}
+     */
+    #payload_pool = [];
+    #payload_pool_count = 0;
 
     /**
      * The recorded — not executed — records of the frame being replayed ({@link SENDER_RECORDED}),
      * in log order: carried into the replayed frame as they are, since what produced them is not
-     * re-run by a replay.
-     * @type {Array<{type_id:number, payload:Uint8Array}>}
+     * re-run by a replay. Parallel arrays, the first {@link #carried_count} entries; the payloads
+     * are from the pool.
+     */
+    #carried_count = 0;
+    #carried_type_ids = /** @type {number[]} */ ([]);
+    #carried_payloads = /** @type {Uint8Array[]} */ ([]);
+    #carried_lengths = /** @type {number[]} */ ([]);
+
+    // The input of the frame being opened — its history, its pending records, the local queue —
+    // before it is put in sender order. Parallel arrays, the first #sort_count entries.
+    #sort_count = 0;
+    #sort_senders = /** @type {number[]} */ ([]);
+    #sort_type_ids = /** @type {number[]} */ ([]);
+    #sort_payloads = /** @type {Uint8Array[]} */ ([]);
+    #sort_lengths = /** @type {number[]} */ ([]);
+    // whether the payload is the frame's own copy, from the pool, to give back once applied
+    #sort_pooled = /** @type {boolean[]} */ ([]);
+
+    /**
+     * The frame's input in the order it is applied: indices into the sort arrays, by sender, and
+     * within a sender in the order they were added.
+     * @type {Int32Array}
+     */
+    #sort_order = new Int32Array(64);
+
+    /**
+     * Counting-sort scratch: per sender byte, where its records start in {@link #sort_order}.
+     * @type {Int32Array}
      */
-    #carried_scratch = [];
-    #sort_scratch = /** @type {Array<{sender_id:number, type_id:number, payload:Uint8Array}>} */ ([]);
+    #sort_sender_starts = new Int32Array(257);
+
     #payload_buf;
     // Walks a frame's records, for the history read.
     #cursor = new ActionRecordCursor();
@@ -377,9 +420,7 @@ export class ServerAuthoritativeServer {
         // accumulate in pending until tick() drains them.
         this.peer.replicator.on_pending_action = (peer_id, frame_number, type_id, buf, off, len, ordinal) => {
             assert.isNonNegativeInteger(ordinal, 'ordinal');
-            const payload = new Uint8Array(len);
-            payload.set(buf.raw_bytes.subarray(off, off + len));
-            this.#pending_add(frame_number, ordinal, peer_id, type_id, payload);
+            this.#pending_add(frame_number, ordinal, peer_id, type_id, buf.raw_bytes, off, len);
             if (frame_number > this.last_client_frame_processed) {
                 this.last_client_frame_processed = frame_number;
             }
@@ -641,7 +682,7 @@ export class ServerAuthoritativeServer {
 
         // 1. Drop pending entries outside the action_log's rewindable window.
         const window_oldest = Math.max(0, sim_frame - this.action_log.frame_capacity + 1);
-        if (this.#pending_frames.length > 0 && this.#pending_referenced_frames[0] < window_oldest) {
+        if (this.#pending_oldest_frame < window_oldest) {
             this.#pending_trim_to_window(window_oldest);
         }
 
@@ -655,12 +696,10 @@ export class ServerAuthoritativeServer {
         //    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.
+        //    never wasted. Entries `> sim_frame` stay buffered.
         let replay_start = sim_frame;
-        const refs = this.#pending_referenced_frames;
-        if (refs.length > 0 && refs[0] <= sim_frame) {
-            replay_start = refs[0];
+        if (this.#pending_oldest_frame <= sim_frame) {
+            replay_start = this.#pending_oldest_frame;
         }
 
         try {
@@ -768,29 +807,29 @@ export class ServerAuthoritativeServer {
      * @private
      */
     #open_frame(f, fresh) {
-        this.#sort_scratch.length = 0;
+        // also gives back what a frame that did not finish left behind
+        this.#sort_reset();
 
         // Read historical actions out of action_log[f] BEFORE begin_frame(f)
         // recycles the buffer. The sender_id is recorded per-record (see
         // SimActionExecutor), so the stable sort below produces deterministic
         // order regardless of how history was originally interleaved.
-        this.#read_historical(f, this.#historical_scratch);
-        for (let i = 0; i < this.#historical_scratch.length; i++) {
-            const h = this.#historical_scratch[i];
-            this.#sort_scratch.push({ sender_id: h.sender_id, type_id: h.type_id, payload: h.payload });
-        }
+        this.#read_historical(f);
 
         // Append the pending actions for this frame. Pending holds only records that had not
         // arrived before (see #pending_add): a copy of what the log already holds is recognised on
         // arrival by its identity and never gets here, so nothing in it duplicates history. Nothing
         // is compared by bytes — two records alike in every byte are two records (a held key).
-        for (let i = 0; i < this.#pending_frames.length; i++) {
+        const pending_count = this.#pending_count;
+        for (let i = 0; i < pending_count; i++) {
             if (this.#pending_frames[i] !== f) continue;
-            this.#sort_scratch.push({
-                sender_id: this.#pending_senders[i],
-                type_id: this.#pending_type_ids[i],
-                payload: this.#pending_payloads[i],
-            });
+            this.#sort_push(
+                this.#pending_senders[i],
+                this.#pending_type_ids[i],
+                this.#pending_payloads[i],
+                this.#pending_lengths[i],
+                false,
+            );
         }
 
         // Locally-authored actions join the merge as input, and only on the
@@ -803,27 +842,138 @@ export class ServerAuthoritativeServer {
         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],
-                });
+                const payload = this.#local_payloads[i];
+
+                this.#sort_push(sender, this.#local_type_ids[i], payload, payload.length, false);
             }
             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.
-        this.#sort_scratch.sort((a, b) => a.sender_id - b.sender_id);
+        // Stable order by sender: equal sender_ids keep the order they were added in, with
+        // historical entries appearing before newly-arrived pending entries for the same sender.
+        this.#sort_by_sender();
 
         // Open the frame, execute all.
         this.action_log.begin_frame(f);
-        for (let i = 0; i < this.#sort_scratch.length; i++) {
-            const s = this.#sort_scratch[i];
-            this.#apply_payload(s.type_id, s.sender_id, s.payload);
+
+        const count = this.#sort_count;
+        const order = this.#sort_order;
+
+        for (let i = 0; i < count; i++) {
+            const k = order[i];
+
+            this.#apply_payload(this.#sort_type_ids[k], this.#sort_senders[k], this.#sort_payloads[k], this.#sort_lengths[k]);
         }
+
+        this.#sort_reset();
+    }
+
+    /**
+     * Add a record to the input of the frame being opened.
+     *
+     * @param {number} sender_id a sender byte, `[0, 255]`
+     * @param {number} type_id
+     * @param {Uint8Array} payload
+     * @param {number} length how many of `payload`'s bytes are the record
+     * @param {boolean} pooled the payload is the frame's own copy, to give back once applied
+     * @private
+     */
+    #sort_push(sender_id, type_id, payload, length, pooled) {
+        const index = this.#sort_count++;
+
+        this.#sort_senders[index] = sender_id;
+        this.#sort_type_ids[index] = type_id;
+        this.#sort_payloads[index] = payload;
+        this.#sort_lengths[index] = length;
+        this.#sort_pooled[index] = pooled;
+    }
+
+    /**
+     * Empty the frame's input, giving back the payloads that were its own copies.
+     * @private
+     */
+    #sort_reset() {
+        const count = this.#sort_count;
+
+        for (let i = 0; i < count; i++) {
+            if (this.#sort_pooled[i]) {
+                this.#payload_release(this.#sort_payloads[i]);
+            }
+        }
+
+        this.#sort_count = 0;
+    }
+
+    /**
+     * Fill {@link #sort_order} with the frame's input by sender, keeping, within a sender, the
+     * order the records were added in. A counting sort over the sender byte: linear in the records,
+     * and nothing is allocated unless the frame holds more records than any before it.
+     * @private
+     */
+    #sort_by_sender() {
+        const count = this.#sort_count;
+        const senders = this.#sort_senders;
+        const starts = this.#sort_sender_starts;
+
+        if (this.#sort_order.length < count) {
+            this.#sort_order = new Int32Array(Math.max(count, this.#sort_order.length * 2));
+        }
+
+        const order = this.#sort_order;
+
+        starts.fill(0);
+
+        // how many records each sender has, one slot along...
+        for (let i = 0; i < count; i++) {
+            starts[senders[i] + 1]++;
+        }
+
+        // ...summed, is where each sender's records start
+        for (let s = 0; s < 256; s++) {
+            starts[s + 1] += starts[s];
+        }
+
+        for (let i = 0; i < count; i++) {
+            order[starts[senders[i]]++] = i;
+        }
+    }
+
+    /**
+     * A byte array of at least `length` bytes for a record's payload, from the pool when it has
+     * one long enough on top. One that is too short is let go of, so the pool's arrays grow to the
+     * records that pass through it.
+     *
+     * @param {number} length
+     * @returns {Uint8Array}
+     * @private
+     */
+    #payload_acquire(length) {
+        const count = this.#payload_pool_count;
+
+        if (count > 0) {
+            const pool = this.#payload_pool;
+            const top = pool[count - 1];
+
+            pool[count - 1] = null;
+            this.#payload_pool_count = count - 1;
+
+            if (top.length >= length) {
+                return top;
+            }
+        }
+
+        return new Uint8Array(length);
+    }
+
+    /**
+     * Give a payload array back to the pool. The caller no longer reads it.
+     *
+     * @param {Uint8Array} payload
+     * @private
+     */
+    #payload_release(payload) {
+        this.#payload_pool[this.#payload_pool_count++] = payload;
     }
 
     /**
@@ -865,21 +1015,23 @@ export class ServerAuthoritativeServer {
      * @private
      */
     #record_carried() {
-        const carried = this.#carried_scratch;
+        const count = this.#carried_count;
 
-        for (let i = 0; i < carried.length; i++) {
-            const { type_id, payload } = carried[i];
+        for (let i = 0; i < count; i++) {
+            const type_id = this.#carried_type_ids[i];
+            const payload = this.#carried_payloads[i];
+            const length = this.#carried_lengths[i];
 
             const klass = this.action_registry.klass_for(type_id);
             if (klass === undefined) continue;
 
             const action = this.action_registry.acquire(klass);
             try {
-                if (this.#payload_buf.raw_bytes.length < payload.length) {
-                    this.#payload_buf.setCapacity(payload.length);
+                if (this.#payload_buf.raw_bytes.length < length) {
+                    this.#payload_buf.setCapacity(length);
                 }
                 this.#payload_buf.position = 0;
-                this.#payload_buf.writeBytes(payload, 0, payload.length);
+                this.#payload_buf.writeBytes(payload, 0, length);
                 this.#payload_buf.position = 0;
                 action.deserialize(this.#payload_buf);
                 this.executor.record(action);
@@ -888,7 +1040,21 @@ export class ServerAuthoritativeServer {
             }
         }
 
-        carried.length = 0;
+        this.#carried_reset();
+    }
+
+    /**
+     * Empty the carried records, giving their payloads back.
+     * @private
+     */
+    #carried_reset() {
+        const count = this.#carried_count;
+
+        for (let i = 0; i < count; i++) {
+            this.#payload_release(this.#carried_payloads[i]);
+        }
+
+        this.#carried_count = 0;
     }
 
     /**
@@ -896,18 +1062,23 @@ export class ServerAuthoritativeServer {
      * — is reported and passed over: the executor leaves nothing of it behind, and the rest of the
      * frame's input, and the frame itself, go ahead. Letting it escape would leave the frame open
      * with nothing left to close it.
+     *
+     * @param {number} type_id
+     * @param {number} sender_id
+     * @param {Uint8Array} payload
+     * @param {number} length how many of `payload`'s bytes are the record
      * @private
      */
-    #apply_payload(type_id, sender_id, payload) {
+    #apply_payload(type_id, sender_id, payload, length) {
         const klass = this.action_registry.klass_for(type_id);
         if (klass === undefined) return;
         const action = this.action_registry.acquire(klass);
         try {
-            if (this.#payload_buf.raw_bytes.length < payload.length) {
-                this.#payload_buf.setCapacity(payload.length);
+            if (this.#payload_buf.raw_bytes.length < length) {
+                this.#payload_buf.setCapacity(length);
             }
             this.#payload_buf.position = 0;
-            this.#payload_buf.writeBytes(payload, 0, payload.length);
+            this.#payload_buf.writeBytes(payload, 0, length);
             this.#payload_buf.position = 0;
             action.deserialize(this.#payload_buf);
             this.executor.execute(action, sender_id);
@@ -918,10 +1089,17 @@ export class ServerAuthoritativeServer {
         }
     }
 
-    /** @private */
-    #read_historical(frame_number, out_array) {
-        out_array.length = 0;
-        this.#carried_scratch.length = 0;
+    /**
+     * Read frame `frame_number`'s records out of the log, before the frame is reopened over them:
+     * its input into the frame's input ({@link #sort_push}), what was recorded and not executed
+     * into the carried records. Each payload is copied into an array from the pool.
+     *
+     * @param {number} frame_number
+     * @private
+     */
+    #read_historical(frame_number) {
+        // also gives back what a frame that never recorded its carried records left behind
+        this.#carried_reset();
         if (!this.action_log.has_frame(frame_number)) return;
         const cursor = this.#cursor;
         cursor.open(this.action_log, frame_number);
@@ -934,17 +1112,28 @@ export class ServerAuthoritativeServer {
             // 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));
+            const length = cursor.payload_len;
+            const start = cursor.payload_start;
+
+            const payload = this.#payload_acquire(length);
+
+            for (let i = 0; i < length; i++) {
+                payload[i] = bytes[start + i];
+            }
 
             // A record of what the engine's systems produced — the host publishing its physics, say.
             // Neither input to reapply nor output the replay recomputes: carried over as it is.
             if (cursor.sender_id === SENDER_RECORDED) {
-                this.#carried_scratch.push({ type_id: cursor.action_type_id, payload });
+                const index = this.#carried_count++;
+
+                this.#carried_type_ids[index] = cursor.action_type_id;
+                this.#carried_payloads[index] = payload;
+                this.#carried_lengths[index] = length;
+
                 continue;
             }
 
-            out_array.push({ type_id: cursor.action_type_id, sender_id: cursor.sender_id, payload });
+            this.#sort_push(cursor.sender_id, cursor.action_type_id, payload, length, true);
         }
     }
 
@@ -980,10 +1169,12 @@ export class ServerAuthoritativeServer {
      * @param {number} ordinal the record's index in the sender's frame, from the wire
      * @param {number} sender_id
      * @param {number} type_id
-     * @param {Uint8Array} payload
+     * @param {Uint8Array} bytes the buffer the record arrived in; copied only if the record is taken
+     * @param {number} offset where the record's payload starts in `bytes`
+     * @param {number} length the payload's length
      * @private
      */
-    #pending_add(frame_number, ordinal, sender_id, type_id, payload) {
+    #pending_add(frame_number, ordinal, sender_id, type_id, bytes, offset, length) {
         const ring = this.#arrival_ring_for(sender_id);
 
         // A copy first — already pending, already in the log, or already folded into a later
@@ -1024,18 +1215,32 @@ export class ServerAuthoritativeServer {
         }
         // Absolute backstop on buffered entries: within the window and the
         // ordinal bound a peer can still pile up distinct entries.
-        if (this.#pending_frames.length >= this.max_pending_total) {
+        if (this.#pending_count >= this.max_pending_total) {
             this.#drop_pending(sender_id, frame_number, 'capacity');
             return;
         }
 
         ring.mark(frame_number, ordinal);
 
-        this.#pending_frames.push(frame_number);
-        this.#pending_senders.push(sender_id);
-        this.#pending_type_ids.push(type_id);
-        this.#pending_payloads.push(payload);
-        this.#track_referenced_frame(frame_number);
+        // Taken: only now is the payload copied out of the receive buffer. Most of what arrives is
+        // a copy of a record already taken, and costs nothing.
+        const payload = this.#payload_acquire(length);
+
+        for (let i = 0; i < length; i++) {
+            payload[i] = bytes[offset + i];
+        }
+
+        const index = this.#pending_count++;
+
+        this.#pending_frames[index] = frame_number;
+        this.#pending_senders[index] = sender_id;
+        this.#pending_type_ids[index] = type_id;
+        this.#pending_payloads[index] = payload;
+        this.#pending_lengths[index] = length;
+
+        if (frame_number < this.#pending_oldest_frame) {
+            this.#pending_oldest_frame = frame_number;
+        }
     }
 
     /**
@@ -1078,47 +1283,55 @@ export class ServerAuthoritativeServer {
     }
 
     /**
-     * Insert `frame_number` into the monotonically-sorted referenced-frames
-     * index, leaving it untouched if already present. Single source of truth
-     * for the three sites (per-add, post-trim, post-filter) that maintain
-     * this index, so the binary-search invariant and uniqueness check live
-     * in one place.
-     * @param {number} frame_number
+     * Keep the pending entries tagged for a frame of at least `oldest_kept`, in their order, and
+     * give the payloads of the rest back to the pool. {@link #pending_oldest_frame} follows.
+     *
+     * @param {number} oldest_kept
+     * @param {boolean} report report each entry dropped (`'window'`)
      * @private
      */
-    #track_referenced_frame(frame_number) {
-        const arr = this.#pending_referenced_frames;
-        const i = binarySearchHighIndex(arr, frame_number, number_compare_ascending);
-        if (arr[i] !== frame_number) arr.splice(i, 0, frame_number);
-    }
+    #pending_keep_from(oldest_kept, report) {
+        const count = this.#pending_count;
 
-    /**
-     * Drop every pending entry tagged below `window_oldest` — input that waited in pending while the
-     * window moved past it — and report each (`'window'`).
-     * @param {number} window_oldest
-     * @private
-     */
-    #pending_trim_to_window(window_oldest) {
         let kept = 0;
-        for (let i = 0; i < this.#pending_frames.length; i++) {
-            if (this.#pending_frames[i] >= window_oldest) {
-                this.#pending_frames[kept]   = this.#pending_frames[i];
+        let oldest = Infinity;
+
+        for (let i = 0; i < count; i++) {
+            const frame = this.#pending_frames[i];
+
+            if (frame >= oldest_kept) {
+                this.#pending_frames[kept]   = frame;
                 this.#pending_senders[kept]  = this.#pending_senders[i];
                 this.#pending_type_ids[kept] = this.#pending_type_ids[i];
                 this.#pending_payloads[kept] = this.#pending_payloads[i];
+                this.#pending_lengths[kept]  = this.#pending_lengths[i];
                 kept++;
+
+                if (frame < oldest) oldest = frame;
             } else {
-                this.#drop_pending(this.#pending_senders[i], this.#pending_frames[i], 'window');
+                // read before the report: a listener must not find the entry half gone
+                const sender = this.#pending_senders[i];
+
+                this.#payload_release(this.#pending_payloads[i]);
+
+                if (report) {
+                    this.#drop_pending(sender, frame, 'window');
+                }
             }
         }
-        this.#pending_frames.length   = kept;
-        this.#pending_senders.length  = kept;
-        this.#pending_type_ids.length = kept;
-        this.#pending_payloads.length = kept;
-        this.#pending_referenced_frames.length = 0;
-        for (const f of this.#pending_frames) {
-            this.#track_referenced_frame(f);
-        }
+
+        this.#pending_count = kept;
+        this.#pending_oldest_frame = oldest;
+    }
+
+    /**
+     * Drop every pending entry tagged below `window_oldest` — input that waited in pending while the
+     * window moved past it — and report each (`'window'`).
+     * @param {number} window_oldest
+     * @private
+     */
+    #pending_trim_to_window(window_oldest) {
+        this.#pending_keep_from(window_oldest, true);
     }
 
     /**
@@ -1131,56 +1344,28 @@ export class ServerAuthoritativeServer {
      */
     #pending_fold_late_into(sim_frame) {
         const frames = this.#pending_frames;
-        let folded_any = false;
+        const count = this.#pending_count;
 
-        for (let i = 0; i < frames.length; i++) {
-            if (frames[i] >= sim_frame) continue;
-            frames[i] = sim_frame;
-            folded_any = true;
-        }
+        let oldest = Infinity;
 
-        if (folded_any) {
-            this.#pending_referenced_frames.length = 0;
-            for (const f of frames) {
-                this.#track_referenced_frame(f);
+        for (let i = 0; i < count; i++) {
+            if (frames[i] < sim_frame) {
+                frames[i] = sim_frame;
             }
+
+            if (frames[i] < oldest) oldest = frames[i];
         }
-    }
 
-    /** @private */
-    #pending_clear() {
-        this.#pending_frames.length = 0;
-        this.#pending_senders.length = 0;
-        this.#pending_type_ids.length = 0;
-        this.#pending_payloads.length = 0;
-        this.#pending_referenced_frames.length = 0;
+        this.#pending_oldest_frame = oldest;
     }
 
     /**
      * Drop pending entries with `frame <= keep_threshold`, keeping the
-     * rest. Same structural pattern as {@link __pending_trim_to_window}
-     * but with the inequality flipped — used at the end of {@link tick}
+     * rest: they have been applied. Used at the end of {@link tick}
      * to retain future-tagged inputs under `simulation_delay_ticks > 0`.
      * @private
      */
     #pending_filter_to_future(keep_threshold) {
-        let kept = 0;
-        for (let i = 0; i < this.#pending_frames.length; i++) {
-            if (this.#pending_frames[i] > keep_threshold) {
-                this.#pending_frames[kept]   = this.#pending_frames[i];
-                this.#pending_senders[kept]  = this.#pending_senders[i];
-                this.#pending_type_ids[kept] = this.#pending_type_ids[i];
-                this.#pending_payloads[kept] = this.#pending_payloads[i];
-                kept++;
-            }
-        }
-        this.#pending_frames.length   = kept;
-        this.#pending_senders.length  = kept;
-        this.#pending_type_ids.length = kept;
-        this.#pending_payloads.length = kept;
-        this.#pending_referenced_frames.length = 0;
-        for (const f of this.#pending_frames) {
-            this.#track_referenced_frame(f);
-        }
+        this.#pending_keep_from(keep_threshold + 1, false);
     }
 }

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

@@ -226,7 +226,10 @@ export class SimActionExecutor {
      *
      * Not re-entrant: calling `execute` or {@link record} from inside `affected_components`,
      * {@link authorize}, `apply`, `announce` or {@link on_component_written} is illegal (the
-     * executor is passed to actions for `slot_table` / `current_sender_id` reads only).
+     * executor is passed to actions for `slot_table` / `current_sender_id` reads only), and
+     * asserted. Unchecked, the inner action takes over the outer one's list of affected components:
+     * started from `affected_components`, the outer action's prior state is captured for the inner
+     * action's entity and a rewind no longer restores its own.
      *
      * @param {SimAction} action
      * @param {number} [sender_id] peer that originated this action.