@woosh/meep-engine 3.14.4 → 3.14.5

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

@@ -1,11 +1,24 @@
 import { assert } from "../../../core/assert.js";
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import Signal from "../../../core/events/signal/Signal.js";
 import { MalformedPacketError } from "../core/MalformedPacketError.js";
+import { ActionRecordCursor } from "../sim/ActionRecordCursor.js";
 
 // Bytes of fixed per-action framing that always precede the variable payload:
 // uint8 action_type_id + uint32 action_payload_len.
 const ACTION_HEADER_BYTES = 5;
 
+/**
+ * Most slices {@link Replicator#unpack_from_peer} holds per peer while waiting
+ * for an earlier slice to land. A sender bursts at most `max_packets_per_tick`
+ * slices a tick and re-sends the missing one every tick, so a legitimate
+ * backlog is a burst or two; this is a backstop against a sender that never
+ * fills the gap. Beyond it the farthest slice is dropped — those frames were
+ * acked at the channel level, so the sender will credit them and not re-send
+ * them, which is a loss, and the reason the cap is generous.
+ */
+const MAX_HELD_SLICES = 256;
+
 /**
  * Forwards action records between peers.
  *
@@ -33,33 +46,52 @@ const ACTION_HEADER_BYTES = 5;
  *       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
  */
 export class Replicator {
     /**
-     * Pre-allocated scratch for record positions in the current pack pass.
-     * Each slot holds (record_start, record_end) interleaved.
-     * Grown on demand.
+     * Pre-allocated scratch for the in-scope actions of the current pack
+     * pass: `(action_type_id, payload_start, payload_len)` per action,
+     * interleaved. Grown on demand.
      * @type {Int32Array}
      * @private
      */
-    #record_bounds = new Int32Array(64 * 2);
+    #in_scope_actions = new Int32Array(64 * 3);
     /**
-     * Per-peer high-watermark of the highest frame number already applied
-     * via {@link unpack_from_peer}'s execute-on-arrival path. The action
-     * stream re-sends every unacked frame each tick (back-fill for loss
-     * tolerance), so the same frame arrives multiple times before its ack
-     * round-trips. Re-running a frame would recycle its action-log slot and
-     * re-capture prior state from the already-mutated world — corrupting the
-     * rewind baseline. Skipping frames at or below the watermark keeps each
-     * frame applied exactly once. Only used by the execute-on-arrival path;
-     * the deferred path ({@link on_pending_action}) dedups downstream.
-     * @type {Map<number, number>}
+     * Per-peer state of {@link unpack_from_peer}'s execute-on-arrival path:
+     * `next_frame`, the frame after the newest applied, and `held`, later
+     * slices of a sender's tick waiting for an earlier slice still in flight,
+     * sorted by `frame_start`.
+     *
+     * `next_frame` is what keeps each frame applied exactly once. The action
+     * stream re-sends every unconfirmed frame each tick (back-fill for loss
+     * tolerance), so a frame arrives several times before its ack round-trips,
+     * and re-running it would recycle its action-log slot and re-capture prior
+     * state from the already-mutated world — corrupting the rewind baseline.
+     * Frames below `next_frame` are skipped.
+     *
+     * One watermark is sound only because frames are applied in order. The
+     * sender may split a tick's owed range across several packets
+     * ({@link NetworkPeer#flush_outbound}), and when the first is lost the
+     * later ones land first. Applied on arrival they would put their frames
+     * ahead of the re-sent earlier ones — an absolute-state action from the
+     * older frame would then overwrite the newer, a despawn could precede its
+     * spawn — and the watermark would take them as proof of everything before,
+     * so the re-send would be skipped for good while the sender, seeing it
+     * acked, credited those frames as delivered. So a later slice is held
+     * until the slices before it have landed. Only the execute-on-arrival path
+     * keeps this; the deferred path ({@link on_pending_action}) orders and
+     * dedups downstream.
+     * @type {Map<number, {next_frame: number, held: Array<{frame_start: number, frame_end: number, buffer: BinaryBuffer, length: number}>}>}
      * @private
      */
-    #applied_through = new Map();
+    #inbound = new Map();
 
     /**
      * Fired after each per-frame action group is fully applied via
@@ -69,8 +101,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}
      */
@@ -96,6 +129,13 @@ export class Replicator {
      */
     on_pending_action = null;
 
+    /**
+     * Walks a frame's records for {@link pack_for_peer}.
+     * @type {ActionRecordCursor}
+     * @private
+     */
+    #cursor = new ActionRecordCursor();
+
     /**
      * @param {{
      *   action_log: ActionLog,
@@ -175,24 +215,20 @@ export class Replicator {
                 continue;
             }
 
-            const buffer = this.action_log.buffer_for(frame);
-            const end = this.action_log.write_end_for(frame);
-
-            // First pass: walk records, capture (start, end) for those in scope.
+            // First pass: walk the records, remembering where the action of
+            // each in-scope one sits.
+            const cursor = this.#cursor;
+            cursor.open(this.action_log, frame);
             let in_scope_count = 0;
-            while (buffer.position < end) {
-                const record_start = buffer.position;
-                const in_scope = this.#scan_record_in_scope(buffer, peer_id);
-                const record_end = buffer.position;
-
-                if (in_scope) {
-                    if ((in_scope_count + 1) * 2 > this.#record_bounds.length) {
-                        this.#grow_record_bounds();
-                    }
-                    this.#record_bounds[in_scope_count * 2] = record_start;
-                    this.#record_bounds[in_scope_count * 2 + 1] = record_end;
-                    in_scope_count++;
+            while (cursor.next()) {
+                if (!this.#record_in_scope(cursor, peer_id)) continue;
+                if ((in_scope_count + 1) * 3 > this.#in_scope_actions.length) {
+                    this.#grow_in_scope_actions();
                 }
+                this.#in_scope_actions[in_scope_count * 3] = cursor.action_type_id;
+                this.#in_scope_actions[in_scope_count * 3 + 1] = cursor.payload_start;
+                this.#in_scope_actions[in_scope_count * 3 + 2] = cursor.payload_len;
+                in_scope_count++;
             }
 
             if (in_scope_count === 0) {
@@ -207,10 +243,17 @@ export class Replicator {
             out_buffer.writeUintVar(frame);
             out_buffer.writeUintVar(in_scope_count);
 
+            // Wire format per action is (type_id, len, payload). The record's
+            // local-only sender_id byte is NOT copied: the receiver derives the
+            // sender from the packet's peer_id, and carrying it on the wire
+            // would let a hostile peer impersonate other peers' actions.
+            const raw_bytes = cursor.buffer.raw_bytes;
             for (let i = 0; i < in_scope_count; i++) {
-                const rs = this.#record_bounds[i * 2];
-                buffer.position = rs;
-                this.#copy_action_to(buffer, out_buffer);
+                const payload_start = this.#in_scope_actions[i * 3 + 1];
+                const payload_len = this.#in_scope_actions[i * 3 + 2];
+                out_buffer.writeUint8(this.#in_scope_actions[i * 3]);
+                out_buffer.writeUint32(payload_len);
+                out_buffer.writeBytes(raw_bytes, payload_start, payload_len);
             }
 
             if (wrote_any_group && out_buffer.position > budget_end) {
@@ -234,11 +277,23 @@ export class Replicator {
      * 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, in_buffer, in_buffer_end) {
+    unpack_from_peer(peer_id, in_buffer, in_buffer_end, slice = null) {
         assert.isNonNegativeInteger(peer_id, 'peer_id');
         assert.isNonNegativeInteger(in_buffer_end, 'in_buffer_end');
 
@@ -275,19 +330,72 @@ export class Replicator {
             return;
         }
 
-        const registry = this.action_registry;
+        let state = this.#inbound.get(peer_id);
+        if (state === undefined) {
+            state = { next_frame: 0, held: [] };
+            this.#inbound.set(peer_id, state);
+        }
+
+        if (slice !== null && !slice.head && slice.frame_start > state.next_frame) {
+            this.#hold_slice(peer_id, state, slice, in_buffer, in_buffer_end);
+            return;
+        }
+
+        if (slice !== null && slice.head) {
+            // Nothing before a head will be sent again. Whatever was held from
+            // before it is as complete as it will ever be, so apply it first,
+            // in order, rather than letting the head jump past it.
+            this.#apply_held_before(peer_id, state, slice.frame_start);
+        }
 
-        const applied_through = this.#applied_through.get(peer_id);
+        const last_frame = this.#apply_groups(
+            peer_id, in_buffer, in_buffer_end, state.next_frame,
+            slice !== null ? slice.frame_start : 0,
+            slice !== null ? slice.frame_end : Infinity,
+        );
+        const covered_through = slice !== null ? slice.frame_end : last_frame;
+        if (covered_through + 1 > state.next_frame) {
+            state.next_frame = covered_through + 1;
+        }
+        this.#apply_held_contiguous(peer_id, state);
+    }
+
+    /**
+     * Apply the frame groups in `[in_buffer.position, in_buffer_end)`, skipping
+     * any frame below `min_frame` — already applied, or, when `min_frame` is
+     * `Infinity`, every frame, which is how a packet is validated before it is
+     * held. A skipped group is still walked, so a malformed one throws here
+     * rather than later. A group outside `[frame_start, frame_end]`, the range
+     * the slice header declared, is malformed too: the watermark is raised to
+     * the header's end, so a frame beyond it would be applied again by the
+     * slice that genuinely carries it.
+     *
+     * @param {number} peer_id
+     * @param {BinaryBuffer} in_buffer
+     * @param {number} in_buffer_end
+     * @param {number} min_frame
+     * @param {number} frame_start
+     * @param {number} frame_end
+     * @returns {number} the highest frame number the packet carries, or -1 if none
+     * @private
+     */
+    #apply_groups(peer_id, in_buffer, in_buffer_end, min_frame, frame_start, frame_end) {
+        const registry = this.action_registry;
+        let last_frame = -1;
 
         while (in_buffer.position < in_buffer_end) {
             const frame_number = in_buffer.readUintVar();
             const action_count = in_buffer.readUintVar();
+            if (frame_number < frame_start || frame_number > frame_end) {
+                throw new MalformedPacketError(`Replicator.unpack_from_peer: frame ${frame_number} lies outside the slice [${frame_start}, ${frame_end}]`);
+            }
+            if (frame_number > last_frame) last_frame = frame_number;
 
             // Skip frames already applied from this peer — the action stream
-            // re-sends every unacked frame each tick, and re-applying would
-            // corrupt the action-log prior-state capture (see #applied_through).
+            // re-sends every unconfirmed frame each tick, and re-applying would
+            // corrupt the action-log prior-state capture (see #inbound).
             // The read cursor must still advance past this frame's actions.
-            if (applied_through !== undefined && frame_number <= applied_through) {
+            if (frame_number < min_frame) {
                 for (let i = 0; i < action_count; i++) {
                     if (in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end) {
                         throw new MalformedPacketError(`Replicator.unpack_from_peer: action header overruns packet (skip; frame ${frame_number}, action ${i}/${action_count})`);
@@ -335,44 +443,135 @@ export class Replicator {
                 this.action_log.end_frame();
             }
 
-            // Advance the per-peer watermark so subsequent back-fill resends of
-            // this frame are skipped. Frames within a packet are strictly
-            // ascending, so this only ever moves forward.
-            this.#applied_through.set(peer_id, frame_number);
-
             // Fire AFTER end_frame so handlers see consistent state and can
             // safely query the action log for the just-applied frame.
             this.onFrameApplied.send2(peer_id, frame_number);
         }
+
+        return last_frame;
     }
 
     /**
-     * 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.
+     * Keep a slice that arrived ahead of the slices before it, to be applied
+     * once they land. The bytes are copied — the inbound buffer is shared
+     * scratch — after a validation walk, so a malformed slice is rejected now,
+     * by the packet that carried it, and not during a later drain inside some
+     * other packet's handling.
+     *
+     * @param {number} peer_id
+     * @param {{next_frame: number, held: Array<{frame_start: number, frame_end: number, buffer: BinaryBuffer, length: number}>}} state
+     * @param {{frame_start: number, frame_end: number}} slice
+     * @param {BinaryBuffer} in_buffer
+     * @param {number} in_buffer_end
+     * @private
+     */
+    #hold_slice(peer_id, state, slice, in_buffer, in_buffer_end) {
+        const start = in_buffer.position;
+        this.#apply_groups(peer_id, in_buffer, in_buffer_end, Infinity, slice.frame_start, slice.frame_end);
+
+        const held = state.held;
+        let i = 0;
+        while (i < held.length && held[i].frame_start < slice.frame_start) i++;
+
+        // Slice boundaries move between ticks: the last slice of a burst grows
+        // by a frame a tick until it fills a packet, a frame that packs to
+        // nothing lets the next one in, a rollback that grows a frame pushes
+        // the next one out. So a re-send with the same start is not the same
+        // slice. Every copy was acked, and the sender credits every frame any
+        // copy covered, so a frame only one copy covers is never sent again:
+        // keep the copy that reaches further, and between equals the newer,
+        // which carries the sender's latest content for those frames.
+        const same_start = i < held.length && held[i].frame_start === slice.frame_start;
+        if (same_start && held[i].frame_end > slice.frame_end) return;
+        if (!same_start && held.length >= MAX_HELD_SLICES) {
+            // Keep the slices nearest the gap — the ones the next head is most
+            // likely to release — and drop the farthest.
+            if (i === held.length) return;
+            held.pop();
+        }
+
+        const length = in_buffer_end - start;
+        const buffer = new BinaryBuffer();
+        buffer.setCapacity(length);
+        buffer.writeBytes(in_buffer.raw_bytes, start, length);
+        const entry = { frame_start: slice.frame_start, frame_end: slice.frame_end, buffer, length };
+        if (same_start) {
+            held[i] = entry;
+        } else {
+            held.splice(i, 0, entry);
+        }
+    }
+
+    /**
+     * Apply, in order, every held slice that starts before `frame` — the start
+     * of a head, before which nothing will be sent again.
+     * @private
+     */
+    #apply_held_before(peer_id, state, frame) {
+        const held = state.held;
+        while (held.length > 0 && held[0].frame_start < frame) {
+            const h = held.shift();
+            if (h.frame_end >= state.next_frame) this.#apply_held(peer_id, state, h);
+        }
+    }
+
+    /**
+     * Apply held slices for as long as the next one starts at or before the
+     * watermark, dropping any the watermark has already passed.
+     * @private
+     */
+    #apply_held_contiguous(peer_id, state) {
+        const held = state.held;
+        while (held.length > 0) {
+            const h = held[0];
+            if (h.frame_end < state.next_frame) {
+                held.shift();
+                continue;
+            }
+            if (h.frame_start > state.next_frame) break;
+            held.shift();
+            this.#apply_held(peer_id, state, h);
+        }
+    }
+
+    /** @private */
+    #apply_held(peer_id, state, h) {
+        h.buffer.position = 0;
+        this.#apply_groups(peer_id, h.buffer, h.length, state.next_frame, h.frame_start, h.frame_end);
+        if (h.frame_end + 1 > state.next_frame) {
+            state.next_frame = h.frame_end + 1;
+        }
+    }
+
+    /**
+     * 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
      */
     forget_peer(peer_id) {
         assert.isNonNegativeInteger(peer_id, 'peer_id');
-        this.#applied_through.delete(peer_id);
+        this.#inbound.delete(peer_id);
     }
 
     /**
-     * Walk a single record from the buffer's current position, advancing past it.
-     * Returns true if any of the record's affected entities is in scope for `peer_id`,
-     * or if the record has no affected entities (event-style action — always sent).
+     * Is the record under `cursor` in scope for `peer_id` — does it touch an
+     * entity the peer should see? A record with no affected components (an
+     * event-style action) is always in scope.
      *
-     * @param {BinaryBuffer} buffer
+     * @param {ActionRecordCursor} cursor
      * @param {number} peer_id
      * @returns {boolean}
      * @private
      */
-    #scan_record_in_scope(buffer, peer_id) {
-        const prior_count = buffer.readUintVar();
+    #record_in_scope(cursor, peer_id) {
+        if (cursor.prior_count === 0) return true;
 
-        let any_in_scope = false;
-        for (let i = 0; i < prior_count; i++) {
+        const buffer = cursor.buffer;
+        buffer.position = cursor.prior_start;
+        for (let i = 0; i < cursor.prior_count; i++) {
             const entity_id = buffer.readUintVar();
             // Translate local entity_id to network_id for the scope filter, which
             // operates on peer-shared identifiers. If `network_for` returns -1,
@@ -383,64 +582,22 @@ export class Replicator {
             // safely apply.
             const network_id = this.slot_table.network_for(entity_id);
             if (network_id >= 0 && this.scope_filter.is_entity_in_scope(peer_id, network_id)) {
-                any_in_scope = true;
+                return true;
             }
             buffer.readUint8();             // component_type_id
-            const payload_len = buffer.readUint32();
-            buffer.position += payload_len; // skip prior payload
+            const prior_len = buffer.readUint32();
+            buffer.position += prior_len;   // skip prior payload
         }
-
-        // Skip the action payload too.
-        buffer.readUint8();                 // action_type_id
-        buffer.readUint8();                 // sender_id (local-only metadata, not sent)
-        const action_payload_len = buffer.readUint32();
-        buffer.position += action_payload_len;
-
-        // Event-style actions (no affected components) are always in scope.
-        return prior_count === 0 ? true : any_in_scope;
-    }
-
-    /**
-     * Buffer's current position is the start of an action record. Skip the
-     * prior_state section, then copy the action portion (type_id + len + payload)
-     * to `out_buffer`. Buffer position advances to the end of the record.
-     *
-     * @param {BinaryBuffer} buffer source action-log frame
-     * @param {BinaryBuffer} out_buffer destination packet
-     * @private
-     */
-    #copy_action_to(buffer, out_buffer) {
-        // Skip prior_state.
-        const prior_count = buffer.readUintVar();
-        for (let i = 0; i < prior_count; i++) {
-            buffer.readUintVar();           // entity_id
-            buffer.readUint8();             // component_type_id
-            const len = buffer.readUint32();
-            buffer.position += len;         // skip prior payload
-        }
-
-        // Copy action portion: type_id + len + payload. The local-only
-        // sender_id byte is STRIPPED here — over-the-wire format stays
-        // (type_id, len, payload) and the receiver derives sender from
-        // the packet's peer_id. Including sender_id on the wire would
-        // let a hostile peer impersonate other peers' actions.
-        const action_type_id = buffer.readUint8();
-        buffer.readUint8(); // sender_id — discarded, not sent on the wire
-        const action_payload_len = buffer.readUint32();
-
-        out_buffer.writeUint8(action_type_id);
-        out_buffer.writeUint32(action_payload_len);
-        out_buffer.writeBytes(buffer.raw_bytes, buffer.position, action_payload_len);
-        buffer.position += action_payload_len;
+        return false;
     }
 
     /**
      * @private
      */
-    #grow_record_bounds() {
-        const old = this.#record_bounds;
+    #grow_in_scope_actions() {
+        const old = this.#in_scope_actions;
         const next = new Int32Array(old.length * 2);
         next.set(old);
-        this.#record_bounds = next;
+        this.#in_scope_actions = next;
     }
 }

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

@@ -21,6 +21,8 @@
  * Self-describing: records can be skipped without consulting the action registry,
  * which means rewind code can walk records forward to find boundaries, then
  * iterate backward to apply prior states — no need to instantiate any actions.
+ * {@link ActionRecordCursor} is that walk; readers use it rather than parsing
+ * the layout themselves.
  *
  * `sender_id` says where the record came from, which is what a rollback replay
  * needs in order to decide what to do with it:

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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"}
+{"version":3,"file":"ActionLog.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/ActionLog.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;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

@@ -23,6 +23,8 @@ import { FrameBufferRing } from "../state/FrameBufferRing.js";
  * Self-describing: records can be skipped without consulting the action registry,
  * which means rewind code can walk records forward to find boundaries, then
  * iterate backward to apply prior states — no need to instantiate any actions.
+ * {@link ActionRecordCursor} is that walk; readers use it rather than parsing
+ * the layout themselves.
  *
  * `sender_id` says where the record came from, which is what a rollback replay
  * needs in order to decide what to do with it:

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

@@ -0,0 +1,82 @@
+/**
+ * Forward cursor over the records of one closed {@link ActionLog} frame.
+ *
+ * The record layout is self-describing (see {@link ActionLog}), so any reader
+ * can walk it — and five did, each with its own copy of the header parse: the
+ * replicator's scope scan and action copy, the rewind engine's boundary pass,
+ * and the rollback server's history read and retransmission check. This is
+ * that parse in one place. {@link next} reads one record's header and exposes
+ * the layout as positions into the frame's buffer; what a reader does with the
+ * prior-state entries or the action payload is its own business.
+ *
+ * Allocation-free after construction: a reader owns one cursor and re-opens
+ * it per frame. After `next` returns true the buffer's `position` is at the
+ * END of the record, so a reader that wants the prior-state entries sets
+ * `position = prior_start` and reads `prior_count` of them; `next` seeks from
+ * `record_end` regardless of where the reader left the position.
+ *
+ * ```
+ *   cursor.open(action_log, frame);
+ *   while (cursor.next()) {
+ *       // cursor.action_type_id, cursor.sender_id,
+ *       // cursor.buffer.raw_bytes[cursor.payload_start .. + cursor.payload_len]
+ *   }
+ * ```
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ActionRecordCursor {
+    /**
+     * The open frame's buffer, positioned at {@link record_end} after each
+     * successful {@link next}.
+     * @type {BinaryBuffer|null}
+     */
+    buffer: BinaryBuffer | null;
+    /** @type {number} first byte of the current record */
+    record_start: number;
+    /** @type {number} prior-state entries in the current record */
+    prior_count: number;
+    /**
+     * First byte of the first prior-state entry. Each entry is
+     * `varint entity_id, uint8 component_type_id, uint32 len, bytes[len]`.
+     * @type {number}
+     */
+    prior_start: number;
+    /** @type {number} */
+    action_type_id: number;
+    /**
+     * The record's provenance byte: a peer id, `SENDER_LOCAL` or
+     * `SENDER_DERIVED` (see {@link SimActionExecutor}).
+     * @type {number}
+     */
+    sender_id: number;
+    /** @type {number} first byte of the action payload */
+    payload_start: number;
+    /** @type {number} */
+    payload_len: number;
+    /**
+     * One past the last byte of the current record — and so the first byte of
+     * the next, which is where {@link next} resumes. `0` before the first
+     * record.
+     * @type {number}
+     */
+    record_end: number;
+    /**
+     * Position the cursor before the first record of `frame`, which must be
+     * closed and present in the log (see {@link ActionLog#buffer_for}).
+     *
+     * @param {ActionLog} action_log
+     * @param {number} frame
+     */
+    open(action_log: ActionLog, frame: number): void;
+    /**
+     * Advance to the next record. Returns false once the frame is exhausted,
+     * leaving the fields as they were.
+     *
+     * @returns {boolean}
+     */
+    next(): boolean;
+    #private;
+}
+//# sourceMappingURL=ActionRecordCursor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ActionRecordCursor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/ActionRecordCursor.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACI;;;;OAIG;IACH,QAFU,eAAa,IAAI,CAEb;IAEd,sDAAsD;IACtD,cADW,MAAM,CACA;IAEjB,+DAA+D;IAC/D,aADW,MAAM,CACD;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB,qBAAqB;IACrB,gBADW,MAAM,CACE;IAEnB;;;;OAIG;IACH,WAFU,MAAM,CAEF;IAEd,sDAAsD;IACtD,eADW,MAAM,CACC;IAElB,qBAAqB;IACrB,aADW,MAAM,CACD;IAEhB;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAKf;;;;;;OAMG;IACH,mCAFW,MAAM,QAMhB;IAED;;;;;OAKG;IACH,QAFa,OAAO,CAyBnB;;CACJ"}