@woosh/meep-engine 2.156.0 → 2.157.0

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

@@ -595,12 +595,22 @@ export class NetworkPeer {
             }
         };
 
+        // Loss: a packet that aged out of the ack window without being acked
+        // leaves a dead seq→frame_end entry. The baseline must NOT advance (the
+        // frame was never confirmed; back-fill resends it under a fresh seq), but
+        // the stale mapping should be reclaimed — otherwise lost-packet entries
+        // accumulate across the session until the seq value is reused on wrap.
+        const on_lost = (seq) => {
+            seq_to_frame_end.delete(seq);
+        };
+
         channel.onPayload.add(dispatch);
         channel.onPacketAcked.add(on_acked);
+        channel.onPacketLost.add(on_lost);
 
         this.#peers.set(peer_id, {
             channel, transport, seq_to_frame_end,
-            on_payload: dispatch, on_acked, on_nack,
+            on_payload: dispatch, on_acked, on_lost, on_nack,
             fragment_assembler, fragment_retention,
             reliable_pipeline,
         });
@@ -617,6 +627,7 @@ export class NetworkPeer {
 
         conn.channel.onPayload.remove(conn.on_payload);
         conn.channel.onPacketAcked.remove(conn.on_acked);
+        conn.channel.onPacketLost.remove(conn.on_lost);
         // Drop the channel's subscription on the transport. Required for the
         // common case of reusing the same transport on a subsequent reconnect:
         // without this, the orphaned channel keeps consuming inbound packets
@@ -636,6 +647,9 @@ export class NetworkPeer {
 
         this.#peers.delete(peer_id);
         this.baseline.forget(peer_id);
+        // Drop the replicator's apply watermark for this peer so a reconnect
+        // (or id reuse) isn't deduped against the previous connection's frames.
+        this.replicator.forget_peer(peer_id);
     }
 
     /**

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

@@ -128,6 +128,14 @@ export class Replicator {
      * @param {number} in_buffer_end byte position to stop reading at
      */
     unpack_from_peer(peer_id: number, in_buffer: BinaryBuffer, in_buffer_end: number): 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.
+     *
+     * @param {number} peer_id
+     */
+    forget_peer(peer_id: number): void;
     #private;
 }
 import Signal from "../../../core/events/signal/Signal.js";

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":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAII;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OA0EpF;IAtEG;;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;IAWhC;;;;;;;;;;;;OAYG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,2CAA2C,MAAM,eAAe,MAAM,KAAK,IAAI,CAE3H;IAGjC;;;;;;;;;;OAUG;IACH,uBALW,MAAM,eACN,MAAM,aACN,MAAM,kCA2ChB;IAED;;;;;;;;;OASG;IACH,0BAJW,MAAM,0CAEN,MAAM,QAiEhB;;CAuFJ;mBA5UkB,uCAAuC"}
+{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH;IAKI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OAyFpF;IArFG;;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;IA0BhC;;;;;;;;;;;;OAYG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,2CAA2C,MAAM,eAAe,MAAM,KAAK,IAAI,CAE3H;IAGjC;;;;;;;;;;OAUG;IACH,uBALW,MAAM,eACN,MAAM,aACN,MAAM,kCA2ChB;IAED;;;;;;;;;OASG;IACH,0BAJW,MAAM,0CAEN,MAAM,QAqFhB;IAED;;;;;;OAMG;IACH,qBAFW,MAAM,QAKhB;;CAuFJ;mBA5XkB,uCAAuC"}

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

@@ -34,6 +34,7 @@ import Signal from "../../../core/events/signal/Signal.js";
  */
 export class Replicator {
     #record_bounds;
+    #applied_through;
 
 
     /**
@@ -82,6 +83,21 @@ export class Replicator {
          */
         this.#record_bounds = new Int32Array(64 * 2);
 
+        /**
+         * 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>}
+         * @private
+         */
+        this.#applied_through = new Map();
+
         /**
          * Fired after each per-frame action group is fully applied via
          * {@link unpack_from_peer}. Args: `(peer_id, frame_number)`.
@@ -209,10 +225,25 @@ export class Replicator {
 
         const registry = this.action_registry;
 
+        const applied_through = this.#applied_through.get(peer_id);
+
         while (in_buffer.position < in_buffer_end) {
             const frame_number = in_buffer.readUintVar();
             const action_count = in_buffer.readUintVar();
 
+            // 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).
+            // The read cursor must still advance past this frame's actions.
+            if (applied_through !== undefined && frame_number <= applied_through) {
+                for (let i = 0; i < action_count; i++) {
+                    in_buffer.readUint8();                       // action_type_id
+                    const skip_len = in_buffer.readUint32();     // action_payload_len
+                    in_buffer.position += skip_len;              // skip action payload
+                }
+                continue;
+            }
+
             this.action_log.begin_frame(frame_number);
             try {
                 for (let i = 0; i < action_count; i++) {
@@ -240,12 +271,29 @@ 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);
         }
     }
 
+    /**
+     * 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.
+     *
+     * @param {number} peer_id
+     */
+    forget_peer(peer_id) {
+        assert.isNonNegativeInteger(peer_id, 'peer_id');
+        this.#applied_through.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`,

package/src/engine/network/transport/Channel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Channel.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/Channel.js"],"names":[],"mappings":"AAoCA;IAUI;;;;OAIG;IACH;;wBAH8B,UAAU,UAAU,MAAM,GAAG,IAAI;uBAAa,MAAM;;OA0EjF;IAnEG;;OAEG;IACH;oBAFwB,UAAU,UAAU,MAAM,GAAG,IAAI;mBAAa,MAAM;MAElD;IA6C1B;;;OAGG;IACH,eAFU,MAAM,CAEiB;IAEjC;;;OAGG;IACH,cAFU,MAAM,CAEgB;IAEhC;;;;;OAKG;IACH,WAFU,MAAM,CAEa;IAGjC;;;;;;OAMG;IACH,cAJW,UAAU,UACV,MAAM,GACJ,MAAM,CA8BlB;IAED;;;OAGG;IACH,iBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,uBAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,mCAFW,MAAM,QAIhB;IAwDD;;;;;;;OAOG;IACH,gBAEC;;CAiBJ;mBA3QkB,uCAAuC"}
+{"version":3,"file":"Channel.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/Channel.js"],"names":[],"mappings":"AA6CA;IAUI;;;;OAIG;IACH;;wBAH8B,UAAU,UAAU,MAAM,GAAG,IAAI;uBAAa,MAAM;;OA0EjF;IAnEG;;OAEG;IACH;oBAFwB,UAAU,UAAU,MAAM,GAAG,IAAI;mBAAa,MAAM;MAElD;IA6C1B;;;OAGG;IACH,eAFU,MAAM,CAEiB;IAEjC;;;OAGG;IACH,cAFU,MAAM,CAEgB;IAEhC;;;;;OAKG;IACH,WAFU,MAAM,CAEa;IAGjC;;;;;;OAMG;IACH,cAJW,UAAU,UACV,MAAM,GACJ,MAAM,CAgClB;IAED;;;OAGG;IACH,iBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,uBAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,mCAFW,MAAM,QAIhB;IA+ED;;;;;;;OAOG;IACH,gBAEC;;CAiBJ;mBA7SkB,uCAAuC"}

package/src/engine/network/transport/Channel.js

@@ -6,13 +6,22 @@ import { seq16_advance, seq16_distance, seq16_greater_than, SEQ16_HALF_RANGE } f
 /**
  * Reliability-notification layer over a {@link Transport}.
  *
- * Adds an 8-byte header to every packet:
+ * Adds a 9-byte header to every packet:
  * ```
  *   uint16:  outgoing_seq
- *   uint16:  ack_latest    (most recent seq received from peer, or 0 if none)
+ *   uint16:  ack_latest    (most recent seq received from peer; 0 when ack_present=0)
  *   uint32:  ack_bitfield  (the previous 32 seqs: bit i set => latest-1-i was received)
+ *   uint8:   ack_present   (1 if this packet carries ack info; 0 if the sender has
+ *                           received nothing yet)
  * ```
  *
+ * The `ack_present` flag exists because a sender that has received nothing would
+ * otherwise emit `(ack_latest=0, ack_bitfield=0)`, which is wire-indistinguishable
+ * from "I have received exactly seq 0" and would spuriously ack the peer's
+ * outstanding seq 0 — silently breaking the action-stream back-fill and the
+ * reliable-command retransmit for that seq. The receiver skips all ack/loss
+ * processing when `ack_present` is 0.
+ *
  * The header gives positive acknowledgement of up to 33 packets per inbound
  * packet — robust enough that a single dropped ack-bearing packet typically
  * doesn't matter (a later one carries the same info).
@@ -32,7 +41,7 @@ import { seq16_advance, seq16_distance, seq16_greater_than, SEQ16_HALF_RANGE } f
  * @copyright Company Named Limited (c) 2026
  */
 
-const HEADER_SIZE = 8;
+const HEADER_SIZE = 9;
 
 export class Channel {
     #next_outgoing_seq;
@@ -141,14 +150,16 @@ export class Channel {
         const seq = this.#next_outgoing_seq;
         this.#next_outgoing_seq = seq16_advance(seq);
 
-        const ack_latest = this.#latest_received_seq < 0 ? 0 : this.#latest_received_seq;
-        const ack_bitfield = this.#latest_received_seq < 0
-            ? 0
-            : ack_bitfield_build(this.#latest_received_seq, s => this.#received_seqs.has(s));
+        const has_received = this.#latest_received_seq >= 0;
+        const ack_latest = has_received ? this.#latest_received_seq : 0;
+        const ack_bitfield = has_received
+            ? ack_bitfield_build(this.#latest_received_seq, s => this.#received_seqs.has(s))
+            : 0;
 
         this.#send_view.setUint16(0, seq, true);
         this.#send_view.setUint16(2, ack_latest, true);
         this.#send_view.setUint32(4, ack_bitfield, true);
+        this.#send_view.setUint8(8, has_received ? 1 : 0);
         if (length > 0) {
             this.#send_buffer.set(payload.subarray(0, length), HEADER_SIZE);
         }
@@ -200,6 +211,7 @@ export class Channel {
         const seq = view.getUint16(0, true);
         const ack_latest = view.getUint16(2, true);
         const ack_bitfield = view.getUint32(4, true);
+        const ack_present = view.getUint8(8);
 
         // Record receipt of this seq.
         if (this.#latest_received_seq < 0 || seq16_greater_than(seq, this.#latest_received_seq)) {
@@ -208,6 +220,33 @@ export class Channel {
         this.#received_seqs.add(seq);
         this.#prune_received_seqs();
 
+        // Process acks/loss only when the peer actually carries ack info. A peer
+        // that has received nothing sends ack_present=0 with (ack_latest=0,
+        // ack_bitfield=0); reading that as an ack would spuriously confirm our
+        // seq 0 (see the seq-0 ambiguity note in the class header).
+        if (ack_present === 1) {
+            this.#process_acks(ack_latest, ack_bitfield);
+        }
+
+        // Strip header and surface the payload.
+        const payload_length = length - HEADER_SIZE;
+        const payload = bytes.subarray(HEADER_SIZE, HEADER_SIZE + payload_length);
+        this.onPayload.send2(payload, payload_length);
+    }
+
+    /**
+     * Apply the ack header of an inbound packet: fire `onPacketAcked` for each
+     * newly-acknowledged outgoing seq, and `onPacketLost` for any unacked seq
+     * that has aged out of the 33-seq ack window. Only invoked when the inbound
+     * header sets `ack_present` (the peer has received at least one packet from
+     * us), so `ack_latest` is a genuine acknowledgement rather than the
+     * "nothing received yet" sentinel.
+     *
+     * @param {number} ack_latest
+     * @param {number} ack_bitfield
+     * @private
+     */
+    #process_acks(ack_latest, ack_bitfield) {
         // Mark each acknowledged outgoing seq.
         ack_bitfield_for_each(ack_latest, ack_bitfield, acked_seq => {
             if (this.#unacked_outgoing.delete(acked_seq)) {
@@ -232,11 +271,6 @@ export class Channel {
             this.#unacked_outgoing.delete(lost);
             this.onPacketLost.send1(lost);
         }
-
-        // Strip header and surface the payload.
-        const payload_length = length - HEADER_SIZE;
-        const payload = bytes.subarray(HEADER_SIZE, HEADER_SIZE + payload_length);
-        this.onPayload.send2(payload, payload_length);
     }
 
     /**

package/src/engine/network/transport/ReliableCommandPipeline.d.ts

@@ -1,3 +1,19 @@
+/**
+ * Largest reliable-command payload that fits in a single channel packet.
+ *
+ * A command's wire form is `uint8 packet_type + uintVar logical_seq + payload`.
+ * The pipeline sends it through {@link Channel#send} directly — it does NOT
+ * fragment — so the whole thing must fit one channel packet
+ * ({@link MAX_CHANNEL_PAYLOAD_BYTES}). We reserve 11 bytes for the framing:
+ * 1 packet-type byte + up to 10 bytes of `uintVar` for `logical_seq` (its
+ * worst case; `logical_seq` grows over the session, so we budget the maximum
+ * rather than the current value). Sending a larger payload on a UDP-style
+ * transport would emit an over-MTU datagram that the network silently drops;
+ * we reject it loudly instead.
+ *
+ * @type {number}
+ */
+export const MAX_RELIABLE_COMMAND_PAYLOAD_BYTES: number;
 /**
  * Reliable, at-least-once delivery layer over a {@link Channel}.
  *

package/src/engine/network/transport/ReliableCommandPipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ReliableCommandPipeline.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/ReliableCommandPipeline.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH;IAUI;;;;;;;;OAQG;IACH,uFARW;QACV,OAAW,EAAE,OAAO,cAAc,EAAE,OAAO,CAAC;QAC5C,WAAe,EAAE,MAAM,CAAC;QACxB,WAAe,CAAC,EAAE,MAAM,CAAC;QACzB,oBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,WAAe,CAAC,EAAE,MAAM,CAAC;KACtB,EAoGH;IApFG,6CAA6C;IAC7C,SADW,OAAO,cAAc,EAAE,OAAO,CACnB;IACtB,+BAA+B;IAC/B,sBADW,MAAM,CACa;IAC9B,+BAA+B;IAC/B,sBADW,MAAM,CACa;IAC9B,+BAA+B;IAC/B,+BADW,MAAM,CAC+B;IAChD;;;;;;;OAOG;IACH,sBAFU,MAAM,CAEc;IA4C9B;;;;;;OAMG;IACH,WAFU,MAAM,CAEa;IAE7B;;;;;;;OAOG;IACH,oBAFU,MAAM,CAEsB;IAS1C;;;;;;;;OAQG;IACH,cAJW,UAAU,UACV,MAAM,GACJ,MAAM,CAoBlB;IAED;;;;;;;;OAQG;IACH,oBAJW,YAAY,gBACZ,MAAM,QAqBhB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,gBAMC;;CAsCJ;mBAhSkB,uCAAuC;6BAD7B,sCAAsC"}
+{"version":3,"file":"ReliableCommandPipeline.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/ReliableCommandPipeline.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;GAcG;AACH,iDAFU,MAAM,CAEiE;AAEjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH;IAUI;;;;;;;;OAQG;IACH,uFARW;QACV,OAAW,EAAE,OAAO,cAAc,EAAE,OAAO,CAAC;QAC5C,WAAe,EAAE,MAAM,CAAC;QACxB,WAAe,CAAC,EAAE,MAAM,CAAC;QACzB,oBAAwB,CAAC,EAAE,MAAM,CAAC;QAClC,WAAe,CAAC,EAAE,MAAM,CAAC;KACtB,EAoGH;IApFG,6CAA6C;IAC7C,SADW,OAAO,cAAc,EAAE,OAAO,CACnB;IACtB,+BAA+B;IAC/B,sBADW,MAAM,CACa;IAC9B,+BAA+B;IAC/B,sBADW,MAAM,CACa;IAC9B,+BAA+B;IAC/B,+BADW,MAAM,CAC+B;IAChD;;;;;;;OAOG;IACH,sBAFU,MAAM,CAEc;IA4C9B;;;;;;OAMG;IACH,WAFU,MAAM,CAEa;IAE7B;;;;;;;OAOG;IACH,oBAFU,MAAM,CAEsB;IAS1C;;;;;;;;OAQG;IACH,cAJW,UAAU,UACV,MAAM,GACJ,MAAM,CA+BlB;IAED;;;;;;;;OAQG;IACH,oBAJW,YAAY,gBACZ,MAAM,QAqBhB;IAED;;;;OAIG;IACH,iBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,gBAMC;;CAsCJ;mBA7TkB,uCAAuC;6BAD7B,sCAAsC"}

package/src/engine/network/transport/ReliableCommandPipeline.js

@@ -1,6 +1,24 @@
 import { assert } from "../../../core/assert.js";
 import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import Signal from "../../../core/events/signal/Signal.js";
+import { MAX_CHANNEL_PAYLOAD_BYTES } from "./fragments/packet_size.js";
+
+/**
+ * Largest reliable-command payload that fits in a single channel packet.
+ *
+ * A command's wire form is `uint8 packet_type + uintVar logical_seq + payload`.
+ * The pipeline sends it through {@link Channel#send} directly — it does NOT
+ * fragment — so the whole thing must fit one channel packet
+ * ({@link MAX_CHANNEL_PAYLOAD_BYTES}). We reserve 11 bytes for the framing:
+ * 1 packet-type byte + up to 10 bytes of `uintVar` for `logical_seq` (its
+ * worst case; `logical_seq` grows over the session, so we budget the maximum
+ * rather than the current value). Sending a larger payload on a UDP-style
+ * transport would emit an over-MTU datagram that the network silently drops;
+ * we reject it loudly instead.
+ *
+ * @type {number}
+ */
+export const MAX_RELIABLE_COMMAND_PAYLOAD_BYTES = MAX_CHANNEL_PAYLOAD_BYTES - 11;
 
 /**
  * Reliable, at-least-once delivery layer over a {@link Channel}.
@@ -184,6 +202,17 @@ export class ReliableCommandPipeline {
      */
     send(payload, length) {
         assert.isNonNegativeInteger(length, 'length');
+        if (length > MAX_RELIABLE_COMMAND_PAYLOAD_BYTES) {
+            // The pipeline does not fragment; an over-MTU command would be sent
+            // as one oversized datagram that UDP-style transports silently drop.
+            // Fail loudly so the caller chunks at the application layer (or uses
+            // a stream transport) rather than losing the message on the wire.
+            throw new Error(
+                `ReliableCommandPipeline.send: payload of ${length} bytes exceeds the ` +
+                `${MAX_RELIABLE_COMMAND_PAYLOAD_BYTES}-byte single-packet limit; this layer does not ` +
+                `fragment — chunk the message at the application layer or send it over a stream transport`
+            );
+        }
         if (this.#unacked.size >= this.max_unacked) {
             throw new Error(
                 `ReliableCommandPipeline.send: ${this.#unacked.size} commands unacked ` +

package/src/engine/network/transport/adapters/NodeUDPTransport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeUDPTransport.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/adapters/NodeUDPTransport.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH;IASI;;;;;;OAMG;IACH,kDANW;QACV,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAU,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;KAC5C,EA4DH;IArDG,0CAA0C;IAC1C,QADW,OAAO,YAAY,EAAE,MAAM,CACJ;IAsDtC;;;;OAIG;IACH,oBAHW,MAAM,QACN,MAAM,QAMhB;IAED;;;;OAIG;IACH,qBAFa;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAC,IAAI,CAQhD;IAmBD;;;;;OAKG;IACH,WAFa,QAAQ,IAAI,CAAC,CA0BzB;;CAsCJ;0BA3MyB,iBAAiB"}
+{"version":3,"file":"NodeUDPTransport.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/adapters/NodeUDPTransport.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;GAeG;AACH;IASI;;;;;;OAMG;IACH,kDANW;QACV,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,SAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAU,CAAC,EAAE;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAE,CAAC;KAC5C,EAkEH;IA3DG,0CAA0C;IAC1C,QADW,OAAO,YAAY,EAAE,MAAM,CACJ;IA4DtC;;;;OAIG;IACH,oBAHW,MAAM,QACN,MAAM,QAMhB;IAED;;;;OAIG;IACH,qBAFa;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAC,GAAC,IAAI,CAQhD;IAmBD;;;;;OAKG;IACH,WAFa,QAAQ,IAAI,CAAC,CA0BzB;;CAsCJ;0BAjNyB,iBAAiB"}

package/src/engine/network/transport/adapters/NodeUDPTransport.js

@@ -60,7 +60,13 @@ export class NodeUDPTransport extends Transport {
 
         /** @private */
         this.#on_message = (msg, rinfo) => {
-            // If we don't have a remote yet, latch onto the first sender (server pattern).
+            // If we don't have a remote yet, latch onto the first sender (server
+            // pattern). This binds the adapter to exactly ONE peer — a single
+            // instance must never be shared across clients. A server with many
+            // clients demultiplexes by source address:port at a higher layer and
+            // owns one NodeUDPTransport per client (see the class doc); packets
+            // from any other source would otherwise be misattributed to the
+            // latched remote.
             if (this.#remote === null) {
                 this.#remote = { address: rinfo.address, port: rinfo.port };
             }

package/src/engine/network/transport/fragments/packet_size.d.ts

@@ -13,12 +13,12 @@
  *
  * Header overhead breakdown for a fragment packet, from the transport's
  * point of view:
- *   - {@link Channel} adds 8 bytes (seq + ack_latest + ack_bitfield).
+ *   - {@link Channel} adds 9 bytes (seq + ack_latest + ack_bitfield + ack_present).
  *   - The FRAGMENT packet type byte = 1 byte.
  *   - Fragment header (message_id uint16 + chunk_index uint8 + total_chunks
  *     uint8) = 4 bytes.
- * Total overhead per fragment = 13 bytes; payload capacity per fragment =
- * 1200 - 13 = 1187 bytes.
+ * Total overhead per fragment = 14 bytes; payload capacity per fragment =
+ * 1200 - 14 = 1186 bytes.
  *
  * For a logical message that fits in a single packet (no fragmentation
  * needed), only the Channel header overhead applies — the payload starts
@@ -29,8 +29,8 @@
  */
 /** Target transport MTU. */
 export const MTU_BYTES: 1200;
-/** Channel layer's per-packet header size. */
-export const CHANNEL_HEADER_BYTES: 8;
+/** Channel layer's per-packet header size. Must match {@link Channel}'s HEADER_SIZE. */
+export const CHANNEL_HEADER_BYTES: 9;
 /**
  * Bytes the Channel reserves for the actual payload (no fragmentation):
  * MTU minus the channel header.

package/src/engine/network/transport/fragments/packet_size.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"packet_size.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/fragments/packet_size.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,4BAA4B;AAC5B,6BAA8B;AAE9B,8CAA8C;AAC9C,qCAAsC;AAEtC;;;GAGG;AACH,+CAA0E;AAE1E;;;;;;GAMG;AACH,sCAAuC;AAEvC,2DAA2D;AAC3D,8CAA0F;AAE1F,4FAA4F;AAC5F,yCAA0C;AAE1C,+EAA+E;AAC/E,+CAA2F;AAE3F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,gDAAiD;AACjD,kDAAmD;AACnD,yCAA0C;AAE1C;;;;;;;;;;GAUG;AACH,iDAAkD;AAClD,iDAAkD;AAClD,+CAAgD"}
+{"version":3,"file":"packet_size.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/fragments/packet_size.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,4BAA4B;AAC5B,6BAA8B;AAE9B,wFAAwF;AACxF,qCAAsC;AAEtC;;;GAGG;AACH,+CAA0E;AAE1E;;;;;;GAMG;AACH,sCAAuC;AAEvC,2DAA2D;AAC3D,8CAA0F;AAE1F,4FAA4F;AAC5F,yCAA0C;AAE1C,+EAA+E;AAC/E,+CAA2F;AAE3F;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,gDAAiD;AACjD,kDAAmD;AACnD,yCAA0C;AAE1C;;;;;;;;;;GAUG;AACH,iDAAkD;AAClD,iDAAkD;AAClD,+CAAgD"}

package/src/engine/network/transport/fragments/packet_size.js

@@ -13,12 +13,12 @@
  *
  * Header overhead breakdown for a fragment packet, from the transport's
  * point of view:
- *   - {@link Channel} adds 8 bytes (seq + ack_latest + ack_bitfield).
+ *   - {@link Channel} adds 9 bytes (seq + ack_latest + ack_bitfield + ack_present).
  *   - The FRAGMENT packet type byte = 1 byte.
  *   - Fragment header (message_id uint16 + chunk_index uint8 + total_chunks
  *     uint8) = 4 bytes.
- * Total overhead per fragment = 13 bytes; payload capacity per fragment =
- * 1200 - 13 = 1187 bytes.
+ * Total overhead per fragment = 14 bytes; payload capacity per fragment =
+ * 1200 - 14 = 1186 bytes.
  *
  * For a logical message that fits in a single packet (no fragmentation
  * needed), only the Channel header overhead applies — the payload starts
@@ -31,8 +31,8 @@
 /** Target transport MTU. */
 export const MTU_BYTES = 1200;
 
-/** Channel layer's per-packet header size. */
-export const CHANNEL_HEADER_BYTES = 8;
+/** Channel layer's per-packet header size. Must match {@link Channel}'s HEADER_SIZE. */
+export const CHANNEL_HEADER_BYTES = 9;
 
 /**
  * Bytes the Channel reserves for the actual payload (no fragmentation):

package/src/engine/physics/BULLET_REVIEW.md

@@ -125,7 +125,7 @@ position* + slack — same idea, slightly different constants.
 ### 1.4 Island structure
 
 meep's `IslandBuilder` is union-find with deterministic union-by-min-index +
-path halving (`island/union_find.js:65-76`), producing CSR-style output sorted
+path halving (`core/collection/union-find/union_find.js:65-76`), producing CSR-style output sorted
 ascending within and across islands. Static / kinematic bodies are **constraint
 anchors only** — they do not enlarge islands, so two disjoint piles on the
 same floor remain separate islands. This is identical to Bullet's

package/src/engine/physics/JOLT_REVIEW.md

@@ -254,7 +254,7 @@ maintained).
 
 | | meep `island/IslandBuilder.js` + `union_find.js` | Jolt `IslandBuilder.cpp` |
 |---|---|---|
-| Build algorithm | Union-find over awake bodies + touched non-sensor manifolds; path halving + union by min-index (`island/union_find.js:45-76`) | Union-find via `BodyLink::mLinkedTo` atomic; linked-to-lowest-index |
+| Build algorithm | Union-find over awake bodies + touched non-sensor manifolds; path halving + union by min-index (`core/collection/union-find/union_find.js:45-76`) | Union-find via `BodyLink::mLinkedTo` atomic; linked-to-lowest-index |
 | Output | CSR-style: `body_data` + `body_offsets`, `contact_data` + `contact_offsets`; both sorted ascending within islands | CSR-style: `BodyID *mBodyIslands` + `mBodyIslandEnds`, similar for constraints |
 | Anchors | Static/Kinematic bodies are anchors only — do not merge islands (`island/IslandBuilder.js:172`) | Same |
 | Determinism | Union by min-index + sort guarantees stable output across runs (PLAN.md determinism contract) | Atomic union may have ordering races in MT mode |
@@ -849,7 +849,7 @@ custom code paths.
 
 - **Heap implementation duplication** (`BodyStorage` / `ManifoldStore`)
   — one shared `core/collection/IntMinHeap.js` (small).
-- **PosedShape** (`narrowphase/PosedShape.js`) is fine but only used by
+- **PosedShape3D** (`core/geom/3d/shape/PosedShape3D.js`) is fine but only used by
   GJK/EPA paths; the comment-noted concave dispatch builds two of them
   for the inverted convention. A single canonical "shape under pose"
   abstraction used everywhere (broadphase, narrowphase, queries) would