@woosh/meep-engine 2.163.11 → 2.165.0

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

@@ -1,5 +1,10 @@
 import { assert } from "../../../core/assert.js";
 import Signal from "../../../core/events/signal/Signal.js";
+import { MalformedPacketError } from "../core/MalformedPacketError.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;
 
 /**
  * Forwards action records between peers.
@@ -211,8 +216,19 @@ export class Replicator {
                 const frame_number = in_buffer.readUintVar();
                 const action_count = in_buffer.readUintVar();
                 for (let i = 0; i < action_count; i++) {
+                    // Untrusted lengths: reject a header or payload that doesn't
+                    // fit the bytes actually received before advancing the cursor
+                    // 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.
+                    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})`);
+                    }
                     const action_type_id = in_buffer.readUint8();
                     const action_payload_len = in_buffer.readUint32();
+                    if (in_buffer.position + action_payload_len > in_buffer_end) {
+                        throw new MalformedPacketError(`Replicator.unpack_from_peer: action payload of ${action_payload_len}B overruns packet (${in_buffer_end - in_buffer.position}B remain)`);
+                    }
                     this.on_pending_action(
                         peer_id, frame_number, action_type_id,
                         in_buffer, in_buffer.position, action_payload_len,
@@ -237,8 +253,14 @@ export class Replicator {
             // 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++) {
+                    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})`);
+                    }
                     in_buffer.readUint8();                       // action_type_id
                     const skip_len = in_buffer.readUint32();     // action_payload_len
+                    if (in_buffer.position + skip_len > in_buffer_end) {
+                        throw new MalformedPacketError(`Replicator.unpack_from_peer: skipped action payload of ${skip_len}B overruns packet (${in_buffer_end - in_buffer.position}B remain)`);
+                    }
                     in_buffer.position += skip_len;              // skip action payload
                 }
                 continue;
@@ -247,8 +269,14 @@ export class Replicator {
             this.action_log.begin_frame(frame_number);
             try {
                 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 (frame ${frame_number}, action ${i}/${action_count})`);
+                    }
                     const action_type_id = in_buffer.readUint8();
                     const action_payload_len = in_buffer.readUint32();
+                    if (in_buffer.position + action_payload_len > in_buffer_end) {
+                        throw new MalformedPacketError(`Replicator.unpack_from_peer: action payload of ${action_payload_len}B overruns packet (${in_buffer_end - in_buffer.position}B remain)`);
+                    }
 
                     const klass = registry.klass_for(action_type_id);
                     if (klass === undefined) {

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

@@ -95,6 +95,47 @@ export class SimActionExecutor {
      * @type {(() => void) | null}
      */
     before_execute: (() => void) | null;
+    /**
+     * Optional inbound-action authorization gate. When non-null, a
+     * REMOTE-originated action (i.e. `execute(action, sender_id)` with
+     * `sender_id !== SENDER_LOCAL`) is applied only if `authorize` returns
+     * true for EVERY local entity the action reports via
+     * `affected_components`. If any affected entity fails, the whole action
+     * is rejected: nothing is applied, nothing is logged, and
+     * {@link onActionRejected} fires.
+     *
+     * Signature: `(sender_id, entity_id, action) => boolean`.
+     *
+     * This is the server-authoritative trust gate — without it a peer can
+     * craft an action targeting an entity it does not own. The default is
+     * null (permissive) so single-peer / local-only code is unaffected;
+     * server orchestrators wire a real policy (see
+     * `make_owner_authorization`). Actions that affect no components are
+     * not gated by this entity-ownership check — a game that needs to gate
+     * those (pure event actions) should validate by action type inside the
+     * policy or the action itself, reading {@link current_sender_id}.
+     *
+     * @type {((sender_id: number, entity_id: number, action: SimAction) => boolean) | null}
+     */
+    authorize: (sender_id: number, entity_id: number, action: SimAction) => boolean;
+    /**
+     * The `sender_id` of the action currently being executed, exposed so an
+     * action's `apply` / `affected_components` (and the {@link authorize}
+     * policy) can self-validate ownership. {@link SENDER_LOCAL} between
+     * executions and for locally-originated actions.
+     *
+     * @type {number}
+     */
+    current_sender_id: number;
+    /**
+     * Fired when {@link execute} rejects a remote action that failed the
+     * {@link authorize} gate. Args: `(sender_id, action)`. Lets the
+     * orchestrator log / count / disconnect an abusive peer. The action is
+     * NOT applied or logged.
+     *
+     * @type {Signal}
+     */
+    onActionRejected: Signal;
     /**
      * Execute an action: capture prior state of affected components, apply, log.
      *
@@ -102,8 +143,12 @@ export class SimActionExecutor {
      * @param {number} [sender_id] peer that originated this action.
      *   Defaults to {@link SENDER_LOCAL} for locally-originated actions.
      *   Must be in `[0, 254]` for remote-originated actions.
+     * @returns {boolean} true if the action was applied; false if it was
+     *   rejected by the {@link authorize} gate (and therefore not applied or
+     *   logged).
      */
-    execute(action: SimAction, sender_id?: number): void;
+    execute(action: SimAction, sender_id?: number): boolean;
     #private;
 }
+import Signal from "../../../core/events/signal/Signal.js";
 //# sourceMappingURL=SimActionExecutor.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"SimActionExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/SimActionExecutor.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,2BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAMI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EAiFH;IA9EG;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,gDAA4C;IAE5C;;;;OAIG;IACH,iCAA4B;IAE5B;;;;;;;;;;;OAWG;IACH,kBAFU,mBAAiB,IAAI,CAES;IA4BxC;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEH;IAG9B;;;;;;;OAOG;IACH,uCAJW,MAAM,QAoGhB;;CACJ"}
+{"version":3,"file":"SimActionExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/SimActionExecutor.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,2BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAMI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EA6HH;IA1HG;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,gDAA4C;IAE5C;;;;OAIG;IACH,iCAA4B;IAE5B;;;;;;;;;;;OAWG;IACH,kBAFU,mBAAiB,IAAI,CAES;IA4BxC;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEH;IAE1B;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,uBAFuB,MAAM,aAAa,MAAM,wBAAwB,OAAO,CAE1D;IAErB;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;OAOG;IACH,kBAFU,MAAM,CAEoB;IAGxC;;;;;;;;;;OAUG;IACH,uCAPW,MAAM,GAGJ,OAAO,CAwHnB;;CACJ;mBAhTkB,uCAAuC"}

package/src/engine/network/sim/SimActionExecutor.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../core/assert.js";
+import Signal from "../../../core/events/signal/Signal.js";
 
 /**
  * Sentinel sender id for actions that originated on the local peer (not
@@ -128,6 +129,50 @@ export class SimActionExecutor {
          * @type {(() => void) | null}
          */
         this.before_execute = null;
+
+        /**
+         * Optional inbound-action authorization gate. When non-null, a
+         * REMOTE-originated action (i.e. `execute(action, sender_id)` with
+         * `sender_id !== SENDER_LOCAL`) is applied only if `authorize` returns
+         * true for EVERY local entity the action reports via
+         * `affected_components`. If any affected entity fails, the whole action
+         * is rejected: nothing is applied, nothing is logged, and
+         * {@link onActionRejected} fires.
+         *
+         * Signature: `(sender_id, entity_id, action) => boolean`.
+         *
+         * This is the server-authoritative trust gate — without it a peer can
+         * craft an action targeting an entity it does not own. The default is
+         * null (permissive) so single-peer / local-only code is unaffected;
+         * server orchestrators wire a real policy (see
+         * `make_owner_authorization`). Actions that affect no components are
+         * not gated by this entity-ownership check — a game that needs to gate
+         * those (pure event actions) should validate by action type inside the
+         * policy or the action itself, reading {@link current_sender_id}.
+         *
+         * @type {((sender_id: number, entity_id: number, action: SimAction) => boolean) | null}
+         */
+        this.authorize = null;
+
+        /**
+         * The `sender_id` of the action currently being executed, exposed so an
+         * action's `apply` / `affected_components` (and the {@link authorize}
+         * policy) can self-validate ownership. {@link SENDER_LOCAL} between
+         * executions and for locally-originated actions.
+         *
+         * @type {number}
+         */
+        this.current_sender_id = SENDER_LOCAL;
+
+        /**
+         * Fired when {@link execute} rejects a remote action that failed the
+         * {@link authorize} gate. Args: `(sender_id, action)`. Lets the
+         * orchestrator log / count / disconnect an abusive peer. The action is
+         * NOT applied or logged.
+         *
+         * @type {Signal}
+         */
+        this.onActionRejected = new Signal();
     }
 
     /**
@@ -137,12 +182,19 @@ export class SimActionExecutor {
      * @param {number} [sender_id] peer that originated this action.
      *   Defaults to {@link SENDER_LOCAL} for locally-originated actions.
      *   Must be in `[0, 254]` for remote-originated actions.
+     * @returns {boolean} true if the action was applied; false if it was
+     *   rejected by the {@link authorize} gate (and therefore not applied or
+     *   logged).
      */
     execute(action, sender_id = SENDER_LOCAL) {
         assert.ok(action && action.isSimAction, 'execute: action must be a SimAction');
         assert.isNonNegativeInteger(sender_id, 'sender_id');
         assert.ok(sender_id <= 0xFF, 'sender_id must fit in a uint8');
 
+        // Expose the originating sender to apply / affected_components / the
+        // authorize policy before any of them run.
+        this.current_sender_id = sender_id;
+
         if (this.before_execute !== null) {
             this.before_execute();
         }
@@ -158,6 +210,20 @@ export class SimActionExecutor {
 
         const affected_count = this.#scratch_entities.length;
 
+        // 1a. Authorization gate for remote-originated actions. A peer may only
+        // mutate entities it is authorized for; reject the whole action before
+        // any prior-bytes capture or apply otherwise. Local-originated actions
+        // (SENDER_LOCAL) are always trusted. Real runtime check — asserts strip
+        // in prod, so this must not be an assert.
+        if (this.authorize !== null && sender_id !== SENDER_LOCAL) {
+            for (let i = 0; i < affected_count; i++) {
+                if (!this.authorize(sender_id, this.#scratch_entities[i], action)) {
+                    this.onActionRejected.send2(sender_id, action);
+                    return false;
+                }
+            }
+        }
+
         // 2. Validate ALL component_type_ids up front, BEFORE any buffer
         // writes. A mid-loop throw after we'd already written the
         // prior_state_count varint and N entries would leave a partial
@@ -234,5 +300,7 @@ export class SimActionExecutor {
         buffer.position = action_len_position;
         buffer.writeUint32(action_payload_len);
         buffer.position = action_payload_end;
+
+        return true;
     }
 }

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

@@ -1 +1 @@
-{"version":3,"file":"Snapshotter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/Snapshotter.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;GAUG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;IACpD,WAAe,gBAAoB,MAAM,KAAG,IAAI,KAAG,IAAI,CAAC;CACrD,QAkDH;AAED;;;;;;;;;;;GAWG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QAqCH;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6GARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QAyCH"}
+{"version":3,"file":"Snapshotter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/Snapshotter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;GAUG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;IACpD,WAAe,gBAAoB,MAAM,KAAG,IAAI,KAAG,IAAI,CAAC;CACrD,QAkDH;AAED;;;;;;;;;;;GAWG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QA6CH;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6GARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QAgDH"}

package/src/engine/network/sim/Snapshotter.js

@@ -1,4 +1,5 @@
 import { assert } from "../../../core/assert.js";
+import { MalformedPacketError } from "../core/MalformedPacketError.js";
 
 /**
  * Initial-sync state stream generator.
@@ -109,6 +110,11 @@ export function snapshotter_apply({ buffer, buffer_end, world, slot_table, compo
     const entity_count = buffer.readUintVar();
 
     for (let i = 0; i < entity_count; i++) {
+        // Untrusted entity_count: stop creating entities once the declared
+        // stream is consumed rather than reading stale/out-of-bounds bytes.
+        if (buffer.position >= buffer_end) {
+            throw new MalformedPacketError(`snapshotter_apply: entity_count ${entity_count} overruns snapshot (entity ${i})`);
+        }
         const network_id = buffer.readUintVar();
         const component_count = buffer.readUint8();
 
@@ -118,6 +124,9 @@ export function snapshotter_apply({ buffer, buffer_end, world, slot_table, compo
         for (let j = 0; j < component_count; j++) {
             const type_id = buffer.readUint8();
             const payload_len = buffer.readUint32();
+            if (buffer.position + payload_len > buffer_end) {
+                throw new MalformedPacketError(`snapshotter_apply: component payload of ${payload_len}B overruns snapshot (network_id ${network_id})`);
+            }
 
             const klass = component_registry.class_of(type_id);
             const adapter = component_registry.adapter_for_id(type_id);
@@ -136,7 +145,7 @@ export function snapshotter_apply({ buffer, buffer_end, world, slot_table, compo
         }
 
         if (buffer.position > buffer_end) {
-            throw new Error(`snapshotter_apply: read past buffer_end at network_id ${network_id}`);
+            throw new MalformedPacketError(`snapshotter_apply: read past buffer_end at network_id ${network_id}`);
         }
     }
 }
@@ -169,6 +178,10 @@ export function snapshotter_apply_to_existing({ buffer, buffer_end, world, slot_
     const entity_count = buffer.readUintVar();
 
     for (let i = 0; i < entity_count; i++) {
+        // Untrusted entity_count: stop once the declared stream is consumed.
+        if (buffer.position >= buffer_end) {
+            throw new MalformedPacketError(`snapshotter_apply_to_existing: entity_count ${entity_count} overruns snapshot (entity ${i})`);
+        }
         const network_id = buffer.readUintVar();
         const component_count = buffer.readUint8();
 
@@ -177,6 +190,9 @@ export function snapshotter_apply_to_existing({ buffer, buffer_end, world, slot_
         for (let j = 0; j < component_count; j++) {
             const type_id = buffer.readUint8();
             const payload_len = buffer.readUint32();
+            if (buffer.position + payload_len > buffer_end) {
+                throw new MalformedPacketError(`snapshotter_apply_to_existing: component payload of ${payload_len}B overruns snapshot (network_id ${network_id})`);
+            }
 
             const klass = component_registry.class_of(type_id);
             const adapter = component_registry.adapter_for_id(type_id);
@@ -200,7 +216,7 @@ export function snapshotter_apply_to_existing({ buffer, buffer_end, world, slot_
         }
 
         if (buffer.position > buffer_end) {
-            throw new Error(`snapshotter_apply_to_existing: read past buffer_end at network_id ${network_id}`);
+            throw new MalformedPacketError(`snapshotter_apply_to_existing: read past buffer_end at network_id ${network_id}`);
         }
     }
 }

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

@@ -2,13 +2,24 @@ export class Channel {
     /**
      * @param {{
      *   transport: { send(bytes: Uint8Array, length: number): void, onReceive: Signal },
+     *   max_in_flight?: number,
      * }} options
+     *   `max_in_flight` hard-caps the number of unacked outgoing seqs. It exists
+     *   to keep the in-flight span well below the seq16 half-range (32768): once
+     *   an unacked seq falls more than half-range behind the newest sent, the
+     *   signed `seq16_distance` used for loss detection wraps and the entry can
+     *   neither be acked nor declared lost — a permanent leak (and a downstream
+     *   `seq_to_frame_end` leak in the orchestrator). Capping in-flight makes
+     *   that lap impossible. Default 1024 ≫ any realistic in-flight window
+     *   (RTT × send-rate) yet ≪ 32768. Only reached under a sustained one-way
+     *   stall, where eviction-as-lost is the correct verdict anyway.
      */
-    constructor({ transport }: {
+    constructor({ transport, max_in_flight }: {
         transport: {
             send(bytes: Uint8Array, length: number): void;
             onReceive: Signal;
         };
+        max_in_flight?: number;
     });
     /**
      * @type {{ send(bytes: Uint8Array, length: number): void, onReceive: Signal }}

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":"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"}
+{"version":3,"file":"Channel.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/Channel.js"],"names":[],"mappings":"AA6CA;IAWI;;;;;;;;;;;;;;OAcG;IACH;;wBAb8B,UAAU,UAAU,MAAM,GAAG,IAAI;uBAAa,MAAM;;wBAC7D,MAAM;OAwF1B;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,CAiDlB;IAED;;;OAGG;IACH,iBAFa,MAAM,CAIlB;IAED;;;OAGG;IACH,uBAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,mCAFW,MAAM,QAIhB;IA+ED;;;;;;;OAOG;IACH,gBAEC;;CAiBJ;mBA9UkB,uCAAuC"}

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

@@ -51,16 +51,32 @@ export class Channel {
     #send_buffer;
     #send_view;
     #lost_scratch;
+    #max_in_flight;
 
 
     /**
      * @param {{
      *   transport: { send(bytes: Uint8Array, length: number): void, onReceive: Signal },
+     *   max_in_flight?: number,
      * }} options
+     *   `max_in_flight` hard-caps the number of unacked outgoing seqs. It exists
+     *   to keep the in-flight span well below the seq16 half-range (32768): once
+     *   an unacked seq falls more than half-range behind the newest sent, the
+     *   signed `seq16_distance` used for loss detection wraps and the entry can
+     *   neither be acked nor declared lost — a permanent leak (and a downstream
+     *   `seq_to_frame_end` leak in the orchestrator). Capping in-flight makes
+     *   that lap impossible. Default 1024 ≫ any realistic in-flight window
+     *   (RTT × send-rate) yet ≪ 32768. Only reached under a sustained one-way
+     *   stall, where eviction-as-lost is the correct verdict anyway.
      */
-    constructor({ transport }) {
+    constructor({ transport, max_in_flight = 1024 }) {
         assert.ok(transport && typeof transport.send === 'function', 'transport must implement send()');
         assert.ok(transport.onReceive, 'transport must expose onReceive signal');
+        assert.isPositiveInteger(max_in_flight, 'max_in_flight');
+        assert.lessThan(max_in_flight, SEQ16_HALF_RANGE, 'max_in_flight must stay below the seq16 half-range');
+
+        /** @type {number} @private */
+        this.#max_in_flight = max_in_flight;
 
         /**
          * @type {{ send(bytes: Uint8Array, length: number): void, onReceive: Signal }}
@@ -167,6 +183,23 @@ export class Channel {
         this.transport.send(this.#send_buffer, total_size);
         this.#unacked_outgoing.add(seq);
 
+        // Enforce the in-flight bound. `#unacked_outgoing` is a Set, so its
+        // iteration order is insertion order = send order = ascending seq; the
+        // first entry is therefore the oldest unacked. When we exceed the cap
+        // (only possible under a sustained one-way stall where acks have
+        // stopped advancing the window), evict the oldest as lost. This keeps
+        // the in-flight span below the seq16 half-range so loss detection can't
+        // alias, and frees the entry (and its orchestrator-side mapping, via
+        // the onPacketLost handler) instead of leaking it. In a stall the
+        // oldest is an action-stream packet, whose loss handler does not
+        // retransmit; reliable-command retransmits are independently bounded by
+        // ReliableCommandPipeline.max_unacked (≪ this cap), so this cannot loop.
+        if (this.#unacked_outgoing.size > this.#max_in_flight) {
+            const oldest = this.#unacked_outgoing.values().next().value;
+            this.#unacked_outgoing.delete(oldest);
+            this.onPacketLost.send1(oldest);
+        }
+
         return seq;
     }
 

package/src/engine/physics/broadphase/generate_pairs.js

@@ -1,4 +1,4 @@
-import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js";
+import { bvh_query_user_data_intersects_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_aabb.js";
 import { body_id_index, pack_body_id } from "../body/BodyStorage.js";
 
 const scratch_aabb = new Float64Array(6);
@@ -81,7 +81,7 @@ export function generate_pairs(
             // queries → converges in one resize, amortised to zero).
             let n;
             for (;;) {
-                n = bvh_query_user_data_overlaps_aabb(
+                n = bvh_query_user_data_intersects_aabb(
                     candidates, 0,
                     dynamic_bvh,
                     scratch_aabb
@@ -107,7 +107,7 @@ export function generate_pairs(
 
             // Dynamic ↔ Static. Same grow-and-retry as the dynamic loop.
             for (;;) {
-                n = bvh_query_user_data_overlaps_aabb(
+                n = bvh_query_user_data_intersects_aabb(
                     candidates, 0,
                     static_bvh,
                     scratch_aabb

package/src/engine/physics/constraint/solve_constraints.js

@@ -1,6 +1,6 @@
 import { quat3_multiply } from "../../../core/geom/3d/quaternion/quat3_multiply.js";
 import { quat3_to_matrix3 } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
-import { v3_quat3_apply } from "../../../core/geom/vec3/v3_quat3_apply.js";
+import { v3_quaternion_apply } from "../../../core/geom/vec3/v3_quaternion_apply.js";
 import { body_id_index } from "../body/BodyStorage.js";
 import {
     SBS_AV_X,
@@ -590,7 +590,7 @@ export function solve_joints(joints, system, dt_sub, iters, reverse) {
 
         // World anchor A and its lever arm rA = R_A · localAnchorA.
         const la = joint.localAnchorA;
-        v3_quat3_apply(scratch_anchor, 0, la.x, la.y, la.z,
+        v3_quaternion_apply(scratch_anchor, 0, la.x, la.y, la.z,
             trA.rotation[0], trA.rotation[1], trA.rotation[2], trA.rotation[3]);
         const rAx = scratch_anchor[0], rAy = scratch_anchor[1], rAz = scratch_anchor[2];
         const anchorAx = trA.position.x + rAx;
@@ -605,7 +605,7 @@ export function solve_joints(joints, system, dt_sub, iters, reverse) {
         if (to_world) {
             anchorBx = lb.x; anchorBy = lb.y; anchorBz = lb.z;
         } else {
-            v3_quat3_apply(scratch_anchor, 0, lb.x, lb.y, lb.z,
+            v3_quaternion_apply(scratch_anchor, 0, lb.x, lb.y, lb.z,
                 trB.rotation[0], trB.rotation[1], trB.rotation[2], trB.rotation[3]);
             rBx = scratch_anchor[0]; rBy = scratch_anchor[1]; rBz = scratch_anchor[2];
             anchorBx = trB.position.x + rBx;

package/src/engine/physics/ecs/PhysicsSystem.js

@@ -1,7 +1,7 @@
 import { assert } from "../../../core/assert.js";
 import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import { BVH } from "../../../core/bvh2/bvh3/BVH.js";
-import { bvh_query_user_data_overlaps_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_overlaps_aabb.js";
+import { bvh_query_user_data_intersects_aabb } from "../../../core/bvh2/bvh3/query/bvh_query_user_data_intersects_aabb.js";
 import { returnTrue } from "../../../core/function/returnTrue.js";
 import { aabb3_transform_oriented } from "../../../core/geom/3d/aabb/aabb3_transform_oriented.js";
 import Vector3 from "../../../core/geom/Vector3.js";
@@ -582,7 +582,7 @@ export class PhysicsSystem extends System {
 
         let n;
         for (;;) {
-            n = bvh_query_user_data_overlaps_aabb(scratch_wake_candidates, 0, this.dynamicBvh, scratch_world_aabb);
+            n = bvh_query_user_data_intersects_aabb(scratch_wake_candidates, 0, this.dynamicBvh, scratch_world_aabb);
             if (n <= scratch_wake_candidates.length) break;
             // TRUE count returned, overflow writes dropped — grow and re-query.
             scratch_wake_candidates = new Uint32Array(Math.max(n, scratch_wake_candidates.length * 2));

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any, any, any, any, any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#144@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#148@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#144@#clear_field"(fluid: FluidComponent): void;
+    static "__#148@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any, any, any, any, any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#144@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#148@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any, any, any, any, any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#144@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#148@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/engine/physics/fluid/ecs/FluidSystem.d.ts

@@ -38,7 +38,7 @@ export class FluidSystem extends System<any, any, any, any, any> {
      * @param {FluidEffectorsComponent} effectors_component
      * @param {Transform} transform
      */
-    static "__#143@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
+    static "__#147@#sync_effectors_from_transform"(effectors_component: FluidEffectorsComponent, transform: Transform): void;
     /**
      * Visitor for the (FluidComponent, Transform) traversal — keeps the field's
      * grid origin locked to a cell-aligned position near the transform.
@@ -61,7 +61,7 @@ export class FluidSystem extends System<any, any, any, any, any> {
      * @param {FluidComponent} component
      * @param {Transform} transform
      */
-    static "__#143@#reanchor_field"(component: FluidComponent, transform: Transform): void;
+    static "__#147@#reanchor_field"(component: FluidComponent, transform: Transform): void;
     /**
      * Write the world-to-grid affine for a FluidComponent into `out`. Axis-aligned,
      * uniform-scale, so the matrix is sparse:
@@ -76,7 +76,7 @@ export class FluidSystem extends System<any, any, any, any, any> {
      * @param {Float32Array} out  length-16
      * @param {FluidComponent} component
      */
-    static "__#143@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
+    static "__#147@#build_world_to_grid"(out: Float32Array, component: FluidComponent): void;
     constructor();
     dependencies: (typeof FluidComponent)[];
     /**

package/src/engine/physics/inverse_kinematics/two_joint_ik.js

@@ -1,5 +1,5 @@
 import Quaternion from "../../../core/geom/Quaternion.js";
-import { v3_compute_interior_angle } from "../../../core/geom/vec3/v3_compute_interior_angle.js";
+import { v3_interior_angle } from "../../../core/geom/vec3/v3_interior_angle.js";
 import Vector3 from "../../../core/geom/Vector3.js";
 import { clamp } from "../../../core/math/clamp.js";
 
@@ -52,9 +52,9 @@ export function two_joint_ik(
     const lat = clamp(t.distanceTo(a), eps, maximum_extension);
 
     //compute current interior angles
-    const ac_ab_0 = v3_compute_interior_angle(c, a, b);
-    const ba_bc_0 = v3_compute_interior_angle(a, b, c);
-    const ac_at_0 = v3_compute_interior_angle(c, a, t);
+    const ac_ab_0 = v3_interior_angle(c, a, b);
+    const ba_bc_0 = v3_interior_angle(a, b, c);
+    const ac_at_0 = v3_interior_angle(c, a, t);
 
     // Using the cosine rule to compute desired interior angles
     const length_at_sqr = lat * lat;

package/src/engine/physics/narrowphase/box_box_manifold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AA6JA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CA8enB;AA9lBD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}
+{"version":3,"file":"box_box_manifold.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_box_manifold.js"],"names":[],"mappings":"AA2JA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,sCAvBW,MAAM,EAAE,GAAC,YAAY,MACrB,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,GACJ,OAAO,CA8enB;AA9lBD;;;GAGG;AACH,iCAFU,MAAM,CAEoD"}

package/src/engine/physics/narrowphase/box_box_manifold.js

@@ -1,6 +1,4 @@
-import {
-    line3_closest_points_segment_segment
-} from "../../../core/geom/3d/line/line3_closest_points_segment_segment.js";
+import { line3_compute_segment_segment_closest_points } from "../../../core/geom/3d/line/line3_compute_segment_segment_closest_points.js";
 import { quat3_to_matrix3 } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
 import { polygon2_clip_axis_halfplane } from "../../../core/geom/2d/polygon/polygon2_clip_axis_halfplane.js";
 import { reduce_manifold_contacts } from "./reduce_manifold_contacts.js";
@@ -89,7 +87,7 @@ const clipped_uv_out = new Float64Array(8 * 2);
 // Stride 4 per candidate: x, y, z, depth.
 const candidates = new Float64Array(8 * 4);
 
-// Output of line3_closest_points_segment_segment for the edge-cross
+// Output of line3_compute_segment_segment_closest_points for the edge-cross
 // SAT-winner path: (s, t) parameters along the two edges.
 const scratch_edge_st = new Float64Array(2);
 
@@ -250,7 +248,7 @@ export function box_box_manifold(
     //   2. Among box A's 4 parallel edges along axis i, pick the one
     //      whose corner is most in the −n direction (closest to B).
     //   3. Same for box B with +n direction.
-    //   4. `line3_closest_points_segment_segment` returns (s, t)
+    //   4. `line3_compute_segment_segment_closest_points` returns (s, t)
     //      parameters; reconstruct the world contact on each edge.
     if (best_source >= 6) {
         const ax_src = best_source - 6;
@@ -338,7 +336,7 @@ export function box_box_manifold(
         const edge_b_p2_y = corner_b_cy + edge_b_dy * edge_b_half;
         const edge_b_p2_z = corner_b_cz + edge_b_dz * edge_b_half;
 
-        line3_closest_points_segment_segment(
+        line3_compute_segment_segment_closest_points(
             scratch_edge_st,
             edge_a_p1_x, edge_a_p1_y, edge_a_p1_z, edge_a_p2_x, edge_a_p2_y, edge_a_p2_z,
             edge_b_p1_x, edge_b_p1_y, edge_b_p1_z, edge_b_p2_x, edge_b_p2_y, edge_b_p2_z

package/src/engine/physics/narrowphase/box_triangle_contact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"box_triangle_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_triangle_contact.js"],"names":[],"mappings":"AAuOA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,0CAtBW,MAAM,EAAE,GAAC,YAAY,OACrB,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CAuGnB;AApRD;;;GAGG;AACH,sCAFU,MAAM,CAEyD"}
+{"version":3,"file":"box_triangle_contact.d.ts","sourceRoot":"","sources":["../../../../../src/engine/physics/narrowphase/box_triangle_contact.js"],"names":[],"mappings":"AAqOA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,0CAtBW,MAAM,EAAE,GAAC,YAAY,OACrB,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,OACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,MACN,MAAM,GACJ,OAAO,CAuGnB;AApRD;;;GAGG;AACH,sCAFU,MAAM,CAEyD"}

package/src/engine/physics/narrowphase/box_triangle_contact.js

@@ -1,6 +1,4 @@
-import {
-    line3_closest_points_segment_segment
-} from "../../../core/geom/3d/line/line3_closest_points_segment_segment.js";
+import { line3_compute_segment_segment_closest_points } from "../../../core/geom/3d/line/line3_compute_segment_segment_closest_points.js";
 import { quat3_to_matrix3 } from "../../../core/geom/3d/quaternion/quat3_to_matrix3.js";
 import { polygon2_clip_axis_halfplane } from "../../../core/geom/2d/polygon/polygon2_clip_axis_halfplane.js";
 import { reduce_manifold_contacts } from "./reduce_manifold_contacts.js";
@@ -37,7 +35,7 @@ import { box3_projected_half_extent } from "../../../core/geom/3d/box/box3_proje
  *
  *     c. Edge-cross axis (sources 4..12) — single contact at the
  *        closest pair of points on the relevant box edge and triangle
- *        edge (via {@link line3_closest_points_segment_segment}).
+ *        edge (via {@link line3_compute_segment_segment_closest_points}).
  *
  *  3. Reduce surviving contacts to at most {@link MAX_CONTACTS} by
  *     deepest-first then perimeter expansion.
@@ -774,7 +772,7 @@ function emit_triangle_face_manifold(
  *      (the +/- of the other two box half-extents pushing to the
  *      "near" corner determined by the SAT-axis sign).
  *   2. Construct the triangle edge as the segment.
- *   3. Closest-pair via `line3_closest_points_segment_segment`.
+ *   3. Closest-pair via `line3_compute_segment_segment_closest_points`.
  *   4. Contact = midpoint, depth = best_overlap.
  */
 /**
@@ -873,7 +871,7 @@ function emit_edge_cross_contact(
     }
 
     // Closest points on the two segments.
-    line3_closest_points_segment_segment(
+    line3_compute_segment_segment_closest_points(
         closest_pair_st,
         box_p1x, box_p1y, box_p1z, box_p2x, box_p2y, box_p2z,
         tri_p1x, tri_p1y, tri_p1z, tri_p2x, tri_p2y, tri_p2z