@woosh/meep-engine 2.155.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/CONSTRAINT_SOLVER_BENCH_LOG.md

@@ -0,0 +1,208 @@
+# Constraint-Solver Improvements — Benchmark Log
+
+Evidence log for `CONSTRAINT_SOLVER_IMPROVEMENTS_PLAN.md`. One section per phase:
+machine/Node, baseline vs after, delta, pass/fail, and any signed rationale for a
+regression that exceeds budget.
+
+**Environment:** Node v24.15.0 · Windows · single-thread JS · benches run via
+`npx jest --config jest.conf.json -t "<name>"` (flip `test.skip`→`test`).
+All numbers are a single in-process run unless noted (per the protocol, gate on
+same-process flag A/B; absolute ms vary by machine/thermal). Tick times in ms.
+
+---
+
+## Phase 0 — Baseline (current `master` + inert flags)
+
+Flags present but all at defaults (`contactBiasSmoothBand=0`, `jointBlockSolve=false`,
+`jointSweepSymmetric=false`, `jointRelaxation=1`, `jointComplianceLin=0`) → behaviour
+identical to pre-change master. Ragdoll spec: 3/3 pass, golden bands hold, determinism
+intact.
+
+### ragdoll MICRO (1 ragdoll, 10 joints, floor+sphere, 600 ticks)
+
+| metric | mean | median | p95 | p99 | max |
+|--------|------|--------|-----|-----|-----|
+| tick (all) | 0.4505 | 0.3802 | 0.7315 | 1.3891 | 4.2801 |
+| tick (last 1s) | 0.4325 | 0.3664 | 0.8504 | 1.0324 | 1.0324 |
+
+final awake **11 / 11** (never sleeps) · final max |v|+|ω| **0.1352**
+
+### ragdoll FIELD (N=64, 704 bodies, 640 joints, 600 ticks)
+
+| metric | mean | median | p95 | p99 | max |
+|--------|------|--------|-----|-----|-----|
+| tick (all) | 33.55 | 32.68 | 46.22 | 56.10 | 62.74 |
+| tick (first 1s, settle) | 27.31 | 24.99 | 37.62 | 62.57 | 62.57 |
+| tick (last 1s, settled) | 34.67 | 33.83 | 47.28 | 52.07 | 52.07 |
+
+avg awake 704.0 / 704 · final awake **704 / 704 (asleep 0)** · residual max |v|+|ω| **0.4997**
+asleep histogram: **0.0 every second** — the pile never sleeps; steady-state cost
+(34.7ms) is *higher* than settle (27ms). **This is the gap.** Target: A2/A3 drive
+asleep ↑ and settled-window tick ↓.
+
+### settling grid (1024 shapes, A4 / sleep canary)
+
+| metric | mean | median | p95 | p99 | max |
+|--------|------|--------|-----|-----|-----|
+| tick (all) | 4.155 | 1.732 | 29.74 | 33.31 | 79.96 |
+| tick (first 1s) | 22.88 | 29.74 | 35.28 | 79.96 | 79.96 |
+| tick (last 1s, settled) | 1.464 | 1.425 | 1.794 | 2.088 | 2.088 |
+
+final awake **77 / 1024** (stacks sleep) · fall-through **0** — A4 must preserve both.
+
+### Deferred (run at phase boundaries / final sweep)
+- KEVA tower (~15 min/run) — large-island contact; run pre/post per phase, not per-commit.
+- falling tower, MeshStack, Rain, raycast — control benches; full sweep in Phase 4.
+
+---
+## Phase 1 — A4: smooth contact position bias
+
+`position_correction_bias(depth, spook_a, band)` helper; both bias sites share it;
+`contactBiasSmoothBand` (default **0**). At band=0 the math is bit-identical to the
+old hard hinge → **140/141 physics tests pass unchanged** (ragdoll spec + PhysicsSystem
+spec), determinism intact. **PASS (refactor).**
+
+A/B on the settling-grid canary (band=0.005 vs baseline, same machine):
+
+| metric | baseline | A4 on (0.005) | Δ |
+|--------|----------|---------------|---|
+| settled tick (last 1s, mean) | 1.464 | 1.535 | +4.8%* |
+| settled tick (median) | 1.425 | 1.463 | +2.7% (within 3% noise) |
+| final awake | 77/1024 | 77/1024 | — (sleep preserved) |
+| fall-through | 0 | 0 | — |
+
+\* sub-ms absolute; within run-to-run noise for this scene (grid settles below slop
+fast, so A4's band barely engages here). **PASS** — quality gates green (fall-through 0,
+sleep intact), perf within the ≤+2% budget on the median.
+
+**Decision:** A4 implemented + validated-safe; **default stays off** (`band=0`). Whether
+to default-on (and whether it helps the ragdoll residual) is judged combined with A2/A3
+in Phase 4. Knob available for tuning.
+
+### Windowed-metric baselines (A4 off — used for A2/A3 A/B)
+Bench residual metric switched from single-tick (noisy) to worst over last 1s.
+
+| scene | tick mean | tick median | tick p99 | last-1s mean | residual | asleep |
+|-------|-----------|-------------|----------|--------------|----------|--------|
+| MICRO | 0.4250 | 0.3769 | 1.1478 | — | — | 0/11 |
+| FIELD (N=64) | 31.92 | 31.68 | 46.13 | 32.27 | **0.7515** | **0/704** |
+
+(Run-to-run variance vs Phase-0 ≈ 5% — gate on same-process A/B, not cross-run absolutes.)
+
+---
+## Phase 2 — A2: block 3×3 point-solve + symmetric sweep
+
+`jointBlockSolve` + `jointSweepSymmetric` (both default **false**). Inert at default
+→ 167 joint/system tests pass unchanged. Same-process A/B on the ragdoll benches:
+
+| scene | baseline | A2 on | Δ |
+|-------|----------|-------|---|
+| MICRO tick mean | 0.4250 | 0.3669 | **−13.7%** |
+| FIELD tick mean | 31.92 | 26.81 | **−16.0%** |
+| FIELD residual (max) | 0.7515 | 0.7445 | ~0 |
+
+**A2 is a perf win, not a cost** (the block does 1 solve + ≤2 impulse applies vs 3
+axes × 2 applies, and is better-conditioned). Well under the +10% budget — it's
+negative. Residual ~unchanged (expected: A2 sharpens convergence; killing the limit
+cycle is A3's job). **PASS.**
+
+**Finding (drives A3):** A2 *enabled* against the full instrumented spec fails
+`settledSpeedMean` (2.26 > 1.8). The under-converged per-axis solve was supplying
+*incidental numerical damping*; the exact block solve removes it, leaving the
+metastable on-sphere ragdoll livelier. A2 ⇒ must pair with A3 dissipation.
+
+## Phase 3 — A3: under-relaxation (ω) [+ compliance deferred]
+
+`jointRelaxation` (default **1** = off). Applied to all three solve paths.
+A2+A3 on the canonical seed (full instrumented spec):
+
+| metric | baseline | A2+A3 (ω=0.90) | Δ |
+|--------|----------|----------------|---|
+| settled lin accel (per-pt) | 55.07 | **3.79** m/s² | −93% |
+| settled ang accel (per-pt) | 36.9 | **4.21** rad/s² | −89% |
+| settled lin speed (per-pt) | 0.73 | **0.067** m/s | −91% |
+| settled ang speed (per-pt) | 0.75 | **0.189** rad/s | −75% |
+| MICRO tick mean | 0.425 | 0.365 | −14% |
+| transient pen (static) | 0.26 | 0.38 | **+46%** (cost) |
+
+The settled residual collapses ~10–14× — the gap the whole effort targeted. With
+defaults flipped on, **all 175 non-ragdoll joint/vehicle/IK/island tests still pass**;
+only the ragdoll golden *lower* bounds trip (we improved past them).
+
+### ⚠ Complication — ω is chaotic on the metastable scene (why we did NOT burn it in)
+
+Sweeping ω on the spec (single ragdoll draped on a convex sphere):
+
+| ω | settled lin speed | verdict |
+|---|-------------------|---------|
+| 1.00 | 0.981 | livelier |
+| 0.97 | **5.81** | slid off / unsettled |
+| 0.95 | 0.437 | good |
+| 0.92 | **4.50** | slid off / unsettled |
+| 0.90 | 0.067 | great |
+| 0.75 | 3.62 | unstable |
+
+Non-monotone and **bimodal**: the ragdoll either settles on the dome or slides off,
+and tiny ω changes flip the basin. So a good ω on one seed (0.90) is **not** a robust
+global default — a neighbouring scene could land in a bad basin. Also ω<~0.8 starves
+constraint convergence → energy injection. Plus the +46% transient-penetration cost.
+
+**Decision:** Do **not** burn in ω as a default off single-seed data — that is exactly
+the brittle-default risk this plan exists to avoid. A2/A3/A4 ship as **validated opt-in
+knobs, default off (zero regression)**. Full physics suite with defaults off: **865
+pass, 0 fail.**
+
+## Phase 4 — burn-in (no flags)
+
+Directive: **no flags/toggles on the engine** — converge to one baked behaviour.
+That required deciding each change on *robust* evidence, not the canonical seed.
+
+### Monte-Carlo settled-accel **median over 150 seeds** (the decider)
+
+| config | worst-point setA median | worst-point setV median |
+|--------|-------------------------|-------------------------|
+| baseline (no A2/A3) | ~68 | ~1.23 |
+| A2 only (ω=1) | ~71 | ~1.53 |
+| A2 + ω=0.90 | **~102** | ~2.04 |
+
+The single-seed ω=0.90 win (3.8 m/s²) was **basin luck** — across the seed space ω
+*raises* the median residual, and A2 raises settled velocity ~20%. **The settled
+jitter is basin/sleep-dominated, not solver-convergence-dominated** (per-seed variance
+≫ any config difference). No convergence/relaxation lever moves the median. So:
+
+### Burn-in decision
+
+| change | verdict | action |
+|--------|---------|--------|
+| **A2** (block 3×3 point-solve + symmetric sweep) | robust **−9–16%** joint-solve time, exact ball-socket, mass-ratio-robust; residual-neutral in median | **BAKED as the single code path** (no flag) |
+| **A3** (ω under-relaxation) | median-*worse*, chaotic/bimodal, +46% transient pen | **REMOVED** (disproven bandaid) |
+| **A4** (contact bias smoothing) | neutral, benefit unproven; baking would churn contact determinism for no measured gain | **REVERTED** to original hard hinge |
+
+All flags/config fields removed (`jointBlockSolve`, `jointSweepSymmetric`,
+`jointRelaxation`, `contactBiasSmoothBand`). Solver has one path. Final:
+
+| scene | pre (baseline) | post (A2 baked) | Δ |
+|-------|----------------|-----------------|---|
+| MICRO tick mean | 0.425 | 0.388 | −9% |
+| FIELD tick mean | 31.92 | 28.65 | −10% |
+| FIELD residual / asleep | 0.75 / 0 | 0.74 / 0 | neutral |
+
+Re-baselined one golden band: `settledSpeedMean` 1.8→2.9 hi (A2's honest liveliness;
+documented in the spec). Full physics suite: **865 pass / 0 fail.**
+
+### The jitter goal is NOT closed — and the data says why
+
+A2 is a perf+correctness win but does **not** reduce the settled jitter (it slightly
+raises it — removing the per-axis solve's incidental damping). The Monte-Carlo proves
+the residual is basin/sleep-dominated. **The real lever is island sleep, not the
+solver:** an *aggregate-energy + hysteresis* sleep criterion (plan item **B**) lets an
+over-constrained island deactivate once its *total* energy is low, instead of requiring
+every body under the per-body gate continuously (which the limit cycle never satisfies).
+Recommended next step. Beyond that, **A1** (reduced-coordinate articulation) removes the
+maximal-coordinate joint residual at the source.
+
+**Net of this effort:** a faster, more correct joint solver (shipped, no flags) + a
+rigorous, evidenced redirection of the jitter goal to the lever that can actually move
+it (sleep), instead of a brittle solver knob that looked good on one seed.
+
+