@woosh/meep-engine 3.47.0 → 3.49.0

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

@@ -43,10 +43,19 @@ const MAX_HELD_SLICES = 256;
  *     varint:  frame_number
  *     varint:  action_count
  *     loop action_count times:
+ *       varint:  ordinal            (the record's index in the sender's log frame)
  *       uint8:   action_type_id
  *       uint32:  action_payload_len
  *       bytes:   action_payload
  * ```
+ * A record's identity on the wire is `(sender, frame_number, ordinal)`: the frame its sender tagged
+ * it for and its place among every record of that frame in the sender's log, filtered or not. The
+ * stream re-sends each unconfirmed frame every tick, and that is how a receiver tells the copies
+ * from new records — never by the payload, since two inputs alike in every byte (a held key, frame
+ * after frame) are two inputs. The ordinal is stable across re-sends because a closed frame's records
+ * are only appended to (`ActionLog.resume_frame`) or rebuilt record for record by a deterministic
+ * replay, and it survives a receiver moving the record to another frame (a late-applying host).
+ *
  * {@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
@@ -58,12 +67,12 @@ const MAX_HELD_SLICES = 256;
 export class Replicator {
     /**
      * Pre-allocated scratch for the in-scope actions of the current pack
-     * pass: `(action_type_id, payload_start, payload_len)` per action,
+     * pass: `(action_type_id, payload_start, payload_len, ordinal)` per action,
      * interleaved. Grown on demand.
      * @type {Int32Array}
      * @private
      */
-    #in_scope_actions = new Int32Array(64 * 3);
+    #in_scope_actions = new Int32Array(64 * 4);
     /**
      * Per-peer state of {@link unpack_from_peer}'s execute-on-arrival path:
      * `next_frame`, the frame after the newest applied, and `held`, later
@@ -210,18 +219,20 @@ export class Replicator {
      * does NOT touch the action log or executor — it parses the packet
      * and calls this function once per action with:
      *
-     *   `(peer_id, frame_number, action_type_id, in_buffer, payload_offset, payload_len)`
+     *   `(peer_id, frame_number, action_type_id, in_buffer, payload_offset, payload_len, ordinal)`
      *
      * The buffer is shared scratch; consumers must copy the payload bytes
      * if they need them to outlive the call. The orchestrator is then
      * responsible for executing the buffered actions in whatever order
      * the netcode model requires (e.g. rewind to oldest frame, stable-
-     * sort by sender, replay forward).
+     * sort by sender, replay forward) — and for recognising the copies the
+     * stream re-sends, by `(peer_id, frame_number, ordinal)`; this path keeps
+     * no watermark of its own.
      *
      * Leave null for "execute on arrival" semantics (the default and
      * what the loopback/single-orchestrator tests rely on).
      *
-     * @type {((peer_id: number, frame_number: number, action_type_id: number, in_buffer: BinaryBuffer, payload_offset: number, payload_len: number) => void) | null}
+     * @type {((peer_id: number, frame_number: number, action_type_id: number, in_buffer: BinaryBuffer, payload_offset: number, payload_len: number, ordinal: number) => void) | null}
      */
     on_pending_action = null;
 
@@ -316,7 +327,11 @@ export class Replicator {
             const cursor = this.#cursor;
             cursor.open(this.action_log, frame);
             let in_scope_count = 0;
+            // the record's index in the frame, counted over every record so it names the same
+            // record on every re-pack whatever this peer's filter lets through
+            let ordinal = -1;
             while (cursor.next()) {
+                ordinal++;
                 // Never send a peer its own record back. Arrived records are logged like any other,
                 // so without this a client's outbound stream carries the host's state straight
                 // back to it — harmless where ownership rejects it, and the host overwriting its own
@@ -326,12 +341,13 @@ export class Replicator {
                 // and sent back, a host would take a client-owned entity's old state from it.
                 if (cursor.sender_id === SENDER_CORRECTED) continue;
                 if (!this.#record_in_scope(cursor, peer_id)) continue;
-                if ((in_scope_count + 1) * 3 > this.#in_scope_actions.length) {
+                if ((in_scope_count + 1) * 4 > 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;
+                this.#in_scope_actions[in_scope_count * 4] = cursor.action_type_id;
+                this.#in_scope_actions[in_scope_count * 4 + 1] = cursor.payload_start;
+                this.#in_scope_actions[in_scope_count * 4 + 2] = cursor.payload_len;
+                this.#in_scope_actions[in_scope_count * 4 + 3] = ordinal;
                 in_scope_count++;
             }
 
@@ -347,15 +363,16 @@ 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.
+            // Wire format per action is (ordinal, 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 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]);
+                const payload_start = this.#in_scope_actions[i * 4 + 1];
+                const payload_len = this.#in_scope_actions[i * 4 + 2];
+                out_buffer.writeUintVar(this.#in_scope_actions[i * 4 + 3]);
+                out_buffer.writeUint8(this.#in_scope_actions[i * 4]);
                 out_buffer.writeUint32(payload_len);
                 out_buffer.writeBytes(raw_bytes, payload_start, payload_len);
             }
@@ -416,6 +433,12 @@ export class Replicator {
                     // past them (otherwise a crafted action_payload_len reads
                     // stale/out-of-bounds bytes — process crash on OOB, cross-
                     // packet leak otherwise). Real check: asserts strip in prod.
+                    // The ordinal is a varint, so it is checked for its first
+                    // byte and the fixed header after it.
+                    if (in_buffer.position >= in_buffer_end) {
+                        throw new MalformedPacketError(`Replicator.unpack_from_peer: action ordinal overruns packet (frame ${frame_number}, action ${i}/${action_count})`);
+                    }
+                    const ordinal = in_buffer.readUintVar();
                     if (in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end) {
                         throw new MalformedPacketError(`Replicator.unpack_from_peer: action header overruns packet (frame ${frame_number}, action ${i}/${action_count})`);
                     }
@@ -427,6 +450,7 @@ export class Replicator {
                     this.on_pending_action(
                         peer_id, frame_number, action_type_id,
                         in_buffer, in_buffer.position, action_payload_len,
+                        ordinal,
                     );
                     in_buffer.position += action_payload_len;
                 }
@@ -534,6 +558,10 @@ export class Replicator {
                 }
 
                 for (let i = 0; i < action_count; i++) {
+                    if (in_buffer.position >= in_buffer_end) {
+                        throw new MalformedPacketError(`Replicator.unpack_from_peer: action ordinal overruns packet (skip; frame ${frame_number}, action ${i}/${action_count})`);
+                    }
+                    in_buffer.readUintVar();                     // ordinal
                     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})`);
                     }
@@ -552,6 +580,12 @@ export class Replicator {
             this.action_log.resume_frame(frame_number);
             try {
                 for (let i = 0; i < action_count; i++) {
+                    if (in_buffer.position >= in_buffer_end) {
+                        throw new MalformedPacketError(`Replicator.unpack_from_peer: action ordinal overruns packet (frame ${frame_number}, action ${i}/${action_count})`);
+                    }
+                    // this path applies frames whole, behind a frame watermark: the ordinal is
+                    // for the deferred path's copy detection and is not needed here
+                    in_buffer.readUintVar();
                     if (in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end) {
                         throw new MalformedPacketError(`Replicator.unpack_from_peer: action header overruns packet (frame ${frame_number}, action ${i}/${action_count})`);
                     }

package/src/engine/network/state/RecordArrivalRing.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Which records of a sender's frames have arrived, over a window of consecutive frames.
+ *
+ * A record's identity on the action stream is the frame its sender tagged it for and its ordinal in
+ * that frame — the index of the record in the sender's log frame, counting every record there. The
+ * stream re-sends every unconfirmed frame each tick, so a receiver sees a record several times before
+ * its acknowledgement round-trips; this is how it tells the copies from new records. Nothing about the
+ * record's bytes takes part: two inputs with identical payloads tagged for different frames, or for
+ * the same frame at different ordinals, are two inputs. (Until 2026-10-15 the host compared bytes
+ * instead, and a held key — the same payload every frame — collapsed whenever its input arrived late
+ * and was folded into one frame: 56% of it applied, measured.)
+ *
+ * Slot `frame % frame_span` holds that frame's marks and remembers which frame it holds, so a frame
+ * that wrapped over reads as empty rather than as its predecessor. The caller keeps the frames it
+ * marks within `frame_span` of each other — the host accepts a record only between the oldest frame it
+ * can still rewind to and its future horizon, and that range sizes the ring — so no two live frames
+ * share a slot. Ordinals are bits in `words_per_frame` words per slot; a frame with more records than
+ * that grows every slot, once — so the caller bounds the ordinal before marking it (the host:
+ * `max_records_per_frame`), since an ordinal from the wire is whatever the peer wrote.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RecordArrivalRing {
+    /**
+     * @param {{ frame_span: number }} options how many consecutive frames the ring tells apart
+     */
+    constructor({ frame_span }: {
+        frame_span: number;
+    });
+    /**
+     * @returns {number}
+     */
+    get frame_span(): number;
+    /**
+     * Mark the record at `ordinal` of `frame` as arrived.
+     *
+     * @param {number} frame
+     * @param {number} ordinal
+     * @returns {boolean} `true` if it had not arrived before; `false` for a copy
+     */
+    mark(frame: number, ordinal: number): boolean;
+    /**
+     * Whether the record at `ordinal` of `frame` has arrived.
+     *
+     * @param {number} frame
+     * @param {number} ordinal
+     * @returns {boolean}
+     */
+    has(frame: number, ordinal: number): boolean;
+    /**
+     * Forget every frame.
+     */
+    clear(): void;
+    #private;
+}
+//# sourceMappingURL=RecordArrivalRing.d.ts.map

package/src/engine/network/state/RecordArrivalRing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecordArrivalRing.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/state/RecordArrivalRing.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAmBI;;OAEG;IACH,4BAFW;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,EAQhC;IAED;;OAEG;IACH,yBAEC;IAED;;;;;;OAMG;IACH,YAJW,MAAM,WACN,MAAM,GACJ,OAAO,CA4BnB;IAED;;;;;;OAMG;IACH,WAJW,MAAM,WACN,MAAM,GACJ,OAAO,CAanB;IAED;;OAEG;IACH,cAGC;;CAoBJ"}

package/src/engine/network/state/RecordArrivalRing.js

@@ -0,0 +1,144 @@
+import { assert } from "../../../core/assert.js";
+
+/**
+ * Which records of a sender's frames have arrived, over a window of consecutive frames.
+ *
+ * A record's identity on the action stream is the frame its sender tagged it for and its ordinal in
+ * that frame — the index of the record in the sender's log frame, counting every record there. The
+ * stream re-sends every unconfirmed frame each tick, so a receiver sees a record several times before
+ * its acknowledgement round-trips; this is how it tells the copies from new records. Nothing about the
+ * record's bytes takes part: two inputs with identical payloads tagged for different frames, or for
+ * the same frame at different ordinals, are two inputs. (Until 2026-10-15 the host compared bytes
+ * instead, and a held key — the same payload every frame — collapsed whenever its input arrived late
+ * and was folded into one frame: 56% of it applied, measured.)
+ *
+ * Slot `frame % frame_span` holds that frame's marks and remembers which frame it holds, so a frame
+ * that wrapped over reads as empty rather than as its predecessor. The caller keeps the frames it
+ * marks within `frame_span` of each other — the host accepts a record only between the oldest frame it
+ * can still rewind to and its future horizon, and that range sizes the ring — so no two live frames
+ * share a slot. Ordinals are bits in `words_per_frame` words per slot; a frame with more records than
+ * that grows every slot, once — so the caller bounds the ordinal before marking it (the host:
+ * `max_records_per_frame`), since an ordinal from the wire is whatever the peer wrote.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class RecordArrivalRing {
+    /** @type {number} */
+    #frame_span;
+
+    /**
+     * The frame each slot holds, -1 for none.
+     * @type {Int32Array}
+     */
+    #frames;
+
+    /** @type {number} */
+    #words_per_frame = 1;
+
+    /**
+     * `frame_span × words_per_frame` words; slot `s` owns `[s × words_per_frame, (s + 1) × words_per_frame)`.
+     * @type {Uint32Array}
+     */
+    #bits;
+
+    /**
+     * @param {{ frame_span: number }} options how many consecutive frames the ring tells apart
+     */
+    constructor({ frame_span }) {
+        assert.isPositiveInteger(frame_span, 'frame_span');
+
+        this.#frame_span = frame_span;
+        this.#frames = new Int32Array(frame_span).fill(-1);
+        this.#bits = new Uint32Array(frame_span);
+    }
+
+    /**
+     * @returns {number}
+     */
+    get frame_span() {
+        return this.#frame_span;
+    }
+
+    /**
+     * Mark the record at `ordinal` of `frame` as arrived.
+     *
+     * @param {number} frame
+     * @param {number} ordinal
+     * @returns {boolean} `true` if it had not arrived before; `false` for a copy
+     */
+    mark(frame, ordinal) {
+        assert.isNonNegativeInteger(frame, 'frame');
+        assert.isNonNegativeInteger(ordinal, 'ordinal');
+
+        const slot = frame % this.#frame_span;
+        const word = ordinal >>> 5;
+
+        if (word >= this.#words_per_frame) {
+            this.#grow(word + 1);
+        }
+
+        const words_per_frame = this.#words_per_frame;
+        const bits = this.#bits;
+        const base = slot * words_per_frame;
+
+        if (this.#frames[slot] !== frame) {
+            // a frame that wrapped over, or an empty slot: nothing of `frame` has arrived
+            this.#frames[slot] = frame;
+            bits.fill(0, base, base + words_per_frame);
+        }
+
+        const mask = 1 << (ordinal & 31);
+        const index = base + word;
+        if ((bits[index] & mask) !== 0) return false;
+        bits[index] |= mask;
+        return true;
+    }
+
+    /**
+     * Whether the record at `ordinal` of `frame` has arrived.
+     *
+     * @param {number} frame
+     * @param {number} ordinal
+     * @returns {boolean}
+     */
+    has(frame, ordinal) {
+        assert.isNonNegativeInteger(frame, 'frame');
+        assert.isNonNegativeInteger(ordinal, 'ordinal');
+
+        const slot = frame % this.#frame_span;
+        if (this.#frames[slot] !== frame) return false;
+
+        const word = ordinal >>> 5;
+        if (word >= this.#words_per_frame) return false;
+
+        return (this.#bits[slot * this.#words_per_frame + word] & (1 << (ordinal & 31))) !== 0;
+    }
+
+    /**
+     * Forget every frame.
+     */
+    clear() {
+        this.#frames.fill(-1);
+        this.#bits.fill(0);
+    }
+
+    /**
+     * Give every slot room for `min_words` words, keeping what is marked.
+     * @param {number} min_words
+     */
+    #grow(min_words) {
+        let words_per_frame = this.#words_per_frame;
+        while (words_per_frame < min_words) words_per_frame *= 2;
+
+        const old_words = this.#words_per_frame;
+        const old_bits = this.#bits;
+        const bits = new Uint32Array(this.#frame_span * words_per_frame);
+        for (let slot = 0; slot < this.#frame_span; slot++) {
+            bits.set(old_bits.subarray(slot * old_words, (slot + 1) * old_words), slot * words_per_frame);
+        }
+
+        this.#bits = bits;
+        this.#words_per_frame = words_per_frame;
+    }
+}