@woosh/meep-engine 2.169.0 → 2.169.2

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

@@ -0,0 +1,84 @@
+/**
+ * A fixed-depth ring of {@link BinaryBuffer} slots, addressed by absolute frame
+ * number.
+ *
+ * Slot `frame % frame_capacity` holds that frame's bytes. Each slot remembers
+ * which absolute frame currently occupies it, so a wrapped-over frame reports
+ * as absent rather than silently handing back its successor's bytes — the one
+ * piece of bookkeeping that makes "index by modulo" safe.
+ *
+ * Exists because two classes needed exactly this and each grew its own copy:
+ * {@link ActionLog} (per-frame action records, for rollback) and
+ * {@link InputRing} (per-frame player input, for redundancy and replay). Their
+ * constructors, presence checks and both accessors were token-identical; only
+ * the *framing policy* differed, and that is what stayed with them. This class
+ * owns storage and addressing and nothing else — it has no opinion about when a
+ * frame may be opened or whether two may be open at once.
+ *
+ * Writers go through {@link open} then {@link commit}. Readers go through
+ * {@link has}, {@link buffer_for} and {@link write_end_for}. A slot is claimed
+ * by `open`, so it reads as present from that moment; its recorded length only
+ * becomes meaningful at `commit`, which is why reading a frame that is still
+ * being written yields the previous occupant's length. Owners that allow a
+ * frame to stay open across calls are responsible for saying so.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FrameBufferRing {
+    /**
+     * @param {{owner: string, frame_capacity: number, initial_buffer_size: number}} options
+     */
+    constructor({ owner, frame_capacity, initial_buffer_size }: {
+        owner: string;
+        frame_capacity: number;
+        initial_buffer_size: number;
+    });
+    /**
+     * Number of frames retained. Writing frame `f` evicts frame
+     * `f - frame_capacity`.
+     * @readonly
+     * @type {number}
+     */
+    readonly frame_capacity: number;
+    /**
+     * Claim the slot for `frame` and hand back its buffer, rewound to 0.
+     * Whatever the slot held is now unreachable.
+     *
+     * @param {number} frame absolute frame number
+     * @returns {BinaryBuffer} positioned at 0, ready to be written
+     */
+    open(frame: number): BinaryBuffer;
+    /**
+     * Record how far the writer got, fixing the frame's length for readers.
+     *
+     * @param {number} frame absolute frame number, previously passed to {@link open}
+     */
+    commit(frame: number): void;
+    /**
+     * Has this frame been written, and is it still in the ring?
+     *
+     * @param {number} frame
+     * @returns {boolean}
+     */
+    has(frame: number): boolean;
+    /**
+     * The frame's buffer, rewound to 0. Its valid byte count is
+     * {@link write_end_for}; the buffer itself is longer.
+     *
+     * @param {number} frame
+     * @returns {BinaryBuffer}
+     */
+    buffer_for(frame: number): BinaryBuffer;
+    /**
+     * Number of meaningful bytes in the frame's buffer, as of its last
+     * {@link commit}.
+     *
+     * @param {number} frame
+     * @returns {number}
+     */
+    write_end_for(frame: number): number;
+    #private;
+}
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+//# sourceMappingURL=FrameBufferRing.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"FrameBufferRing.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/state/FrameBufferRing.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAoCI;;OAEG;IACH,4DAFW;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAC,EAmB9E;IA5BD;;;;;OAKG;IACH,yBAFU,MAAM,CAED;IAwBf;;;;;;OAMG;IACH,YAHW,MAAM,GACJ,YAAY,CAcxB;IAED;;;;OAIG;IACH,cAFW,MAAM,QAQhB;IAED;;;;;OAKG;IACH,WAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,GACJ,YAAY,CAYxB;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,GACJ,MAAM,CAQlB;;CACJ;6BAtK4B,sCAAsC"}

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

@@ -0,0 +1,168 @@
+import { assert } from "../../../core/assert.js";
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+
+/**
+ * A fixed-depth ring of {@link BinaryBuffer} slots, addressed by absolute frame
+ * number.
+ *
+ * Slot `frame % frame_capacity` holds that frame's bytes. Each slot remembers
+ * which absolute frame currently occupies it, so a wrapped-over frame reports
+ * as absent rather than silently handing back its successor's bytes — the one
+ * piece of bookkeeping that makes "index by modulo" safe.
+ *
+ * Exists because two classes needed exactly this and each grew its own copy:
+ * {@link ActionLog} (per-frame action records, for rollback) and
+ * {@link InputRing} (per-frame player input, for redundancy and replay). Their
+ * constructors, presence checks and both accessors were token-identical; only
+ * the *framing policy* differed, and that is what stayed with them. This class
+ * owns storage and addressing and nothing else — it has no opinion about when a
+ * frame may be opened or whether two may be open at once.
+ *
+ * Writers go through {@link open} then {@link commit}. Readers go through
+ * {@link has}, {@link buffer_for} and {@link write_end_for}. A slot is claimed
+ * by `open`, so it reads as present from that moment; its recorded length only
+ * becomes meaningful at `commit`, which is why reading a frame that is still
+ * being written yields the previous occupant's length. Owners that allow a
+ * frame to stay open across calls are responsible for saying so.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class FrameBufferRing {
+    /**
+     * Name of the owning class, used only to prefix error messages so a throw
+     * points at `ActionLog.buffer_for` rather than at this shared class.
+     * @type {string}
+     */
+    #owner;
+
+    /**
+     * Per-slot buffers. Index by `frame % frame_capacity`.
+     * @type {BinaryBuffer[]}
+     */
+    #buffers;
+
+    /**
+     * Per-slot absolute frame number. `-1` means the slot has never been used.
+     * @type {Int32Array}
+     */
+    #frame_numbers;
+
+    /**
+     * Per-slot count of meaningful bytes, captured at {@link commit}. The
+     * buffer's own `position` is reused while writing, so it cannot serve as
+     * the length once a reader has moved it.
+     * @type {Int32Array}
+     */
+    #write_ends;
+
+    /**
+     * Number of frames retained. Writing frame `f` evicts frame
+     * `f - frame_capacity`.
+     * @readonly
+     * @type {number}
+     */
+    frame_capacity;
+
+    /**
+     * @param {{owner: string, frame_capacity: number, initial_buffer_size: number}} options
+     */
+    constructor({ owner, frame_capacity, initial_buffer_size }) {
+        if (!Number.isInteger(frame_capacity) || frame_capacity <= 0) {
+            throw new Error(`${owner}: frame_capacity must be a positive integer, got ${frame_capacity}`);
+        }
+
+        this.#owner = owner;
+
+        this.frame_capacity = frame_capacity;
+
+        this.#buffers = new Array(frame_capacity);
+        this.#frame_numbers = new Int32Array(frame_capacity).fill(-1);
+        this.#write_ends = new Int32Array(frame_capacity);
+
+        for (let i = 0; i < frame_capacity; i++) {
+            this.#buffers[i] = new BinaryBuffer();
+            this.#buffers[i].setCapacity(initial_buffer_size);
+        }
+    }
+
+    /**
+     * Claim the slot for `frame` and hand back its buffer, rewound to 0.
+     * Whatever the slot held is now unreachable.
+     *
+     * @param {number} frame absolute frame number
+     * @returns {BinaryBuffer} positioned at 0, ready to be written
+     */
+    open(frame) {
+        assert.isNonNegativeInteger(frame, 'frame');
+
+        const slot = frame % this.frame_capacity;
+
+        const buffer = this.#buffers[slot];
+
+        buffer.position = 0;
+
+        this.#frame_numbers[slot] = frame;
+
+        return buffer;
+    }
+
+    /**
+     * Record how far the writer got, fixing the frame's length for readers.
+     *
+     * @param {number} frame absolute frame number, previously passed to {@link open}
+     */
+    commit(frame) {
+        assert.isNonNegativeInteger(frame, 'frame');
+
+        const slot = frame % this.frame_capacity;
+
+        this.#write_ends[slot] = this.#buffers[slot].position;
+    }
+
+    /**
+     * Has this frame been written, and is it still in the ring?
+     *
+     * @param {number} frame
+     * @returns {boolean}
+     */
+    has(frame) {
+        assert.isNonNegativeInteger(frame, 'frame');
+
+        return this.#frame_numbers[frame % this.frame_capacity] === frame;
+    }
+
+    /**
+     * The frame's buffer, rewound to 0. Its valid byte count is
+     * {@link write_end_for}; the buffer itself is longer.
+     *
+     * @param {number} frame
+     * @returns {BinaryBuffer}
+     */
+    buffer_for(frame) {
+        if (!this.has(frame)) {
+            throw new Error(`${this.#owner}.buffer_for: frame ${frame} is not present in the ring`);
+        }
+
+        const buffer = this.#buffers[frame % this.frame_capacity];
+
+        buffer.position = 0;
+
+        return buffer;
+    }
+
+    /**
+     * Number of meaningful bytes in the frame's buffer, as of its last
+     * {@link commit}.
+     *
+     * @param {number} frame
+     * @returns {number}
+     */
+    write_end_for(frame) {
+        if (!this.has(frame)) {
+            throw new Error(`${this.#owner}.write_end_for: frame ${frame} is not present in the ring`);
+        }
+
+        return this.#write_ends[frame % this.frame_capacity];
+    }
+}

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

@@ -16,6 +16,9 @@
  * Distinct from {@link ActionLog} despite a similar shape: inputs are raw
  * player intent (sender side), actions are state mutations (sim side). One
  * input may produce zero or many actions when the simulation processes it.
+ * They share their storage ({@link FrameBufferRing}) but not their framing:
+ * a frame of input is written atomically here, whereas an action-log frame
+ * stays open across many writes.
  *
  * Sized to `frame_capacity` frames; oldest is overwritten on wrap.
  *
@@ -31,10 +34,11 @@ export class InputRing {
         initial_buffer_size?: number;
     });
     /**
+     * Number of frames retained before the oldest is overwritten.
      * @readonly
-     * @type {number}
+     * @returns {number}
      */
-    readonly frame_capacity: number;
+    readonly get frame_capacity(): number;
     /**
      * Write input bytes for a given frame. The callback receives the buffer
      * positioned at 0 and is expected to write input bytes via the buffer's
@@ -43,15 +47,14 @@ export class InputRing {
      *
      * Overwrites any prior data for that frame slot.
      *
-     * **Writer must not throw.** The slot's buffer has already been positioned
-     * at 0 by the time the writer runs, and the prior frame's bytes are being
-     * overwritten in-place. If the writer throws partway, the slot's metadata
-     * (frame number, length) still reflects the previous occupant while the
-     * leading bytes have been clobbered with the partial new write — a torn
-     * state that downstream readers cannot detect. A try/catch wrapper here
-     * would force a V8 deopt on the hot write path, which is a worse trade
-     * than the "writer is trusted" contract; treat any throw in a writer
-     * callback as a programming error.
+     * **Writer must not throw.** The slot has already been claimed for `frame`
+     * and rewound to 0 by the time the writer runs, and the prior frame's bytes
+     * are being overwritten in-place. If the writer throws partway, the slot
+     * reads as holding `frame` while its recorded length is still the previous
+     * occupant's — a torn state that downstream readers cannot detect. A
+     * try/catch wrapper here would force a V8 deopt on the hot write path,
+     * which is a worse trade than the "writer is trusted" contract; treat any
+     * throw in a writer callback as a programming error.
      *
      * @param {number} frame
      * @param {function(BinaryBuffer): void} writer
@@ -86,5 +89,4 @@ export class InputRing {
     for_each_in_range(start_frame: number, end_frame: number, fn: (arg0: number, arg1: BinaryBuffer, arg2: number) => void): void;
     #private;
 }
-import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 //# sourceMappingURL=InputRing.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"InputRing.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/state/InputRing.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH;IAMI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAsClE;IA/BG;;;OAGG;IACH,yBAFU,MAAM,CAEoB;IA6BxC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,aAHW,MAAM,iBACG,YAAY,KAAG,IAAI,QAWtC;IAED;;;OAGG;IACH,WAHW,MAAM,GACJ,OAAO,CAMnB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,GACJ,YAAY,CAWxB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CASlB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,aACN,MAAM,aACG,MAAM,QAAE,YAAY,QAAE,MAAM,KAAG,IAAI,QAkBtD;;CACJ;6BA3K4B,sCAAsC"}
+{"version":3,"file":"InputRing.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/state/InputRing.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH;IAMI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;;OAIG;IACH,sCAEC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,aAHW,MAAM,kCACkB,IAAI,QAQtC;IAED;;;OAGG;IACH,WAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,kBAHW,MAAM,gBAKhB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;;;;;OAOG;IACH,+BAJW,MAAM,aACN,MAAM,aACG,MAAM,4BAAgB,MAAM,KAAG,IAAI,QAmBtD;;CACJ"}

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

@@ -1,5 +1,5 @@
 import { assert } from "../../../core/assert.js";
-import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
+import { FrameBufferRing } from "./FrameBufferRing.js";
 
 /**
  * Per-player ring of input bytes, one frame per slot.
@@ -19,6 +19,9 @@ import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
  * Distinct from {@link ActionLog} despite a similar shape: inputs are raw
  * player intent (sender side), actions are state mutations (sim side). One
  * input may produce zero or many actions when the simulation processes it.
+ * They share their storage ({@link FrameBufferRing}) but not their framing:
+ * a frame of input is written atomically here, whereas an action-log frame
+ * stays open across many writes.
  *
  * Sized to `frame_capacity` frames; oldest is overwritten on wrap.
  *
@@ -26,50 +29,25 @@ import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
  * @copyright Company Named Limited (c) 2026
  */
 export class InputRing {
-    #buffers;
-    #frame_numbers;
-    #write_ends;
-
+    /**
+     * @type {FrameBufferRing}
+     */
+    #ring;
 
     /**
      * @param {{ frame_capacity: number, initial_buffer_size?: number }} options
      */
     constructor({ frame_capacity, initial_buffer_size = 64 }) {
-        if (!Number.isInteger(frame_capacity) || frame_capacity <= 0) {
-            throw new Error(`InputRing: frame_capacity must be a positive integer, got ${frame_capacity}`);
-        }
-
-        /**
-         * @readonly
-         * @type {number}
-         */
-        this.frame_capacity = frame_capacity;
-
-        /**
-         * Per-frame input buffers. Index by `frame % frame_capacity`.
-         * @type {BinaryBuffer[]}
-         * @private
-         */
-        this.#buffers = new Array(frame_capacity);
-
-        /**
-         * Per-slot absolute frame number; -1 means slot is empty.
-         * @type {Int32Array}
-         * @private
-         */
-        this.#frame_numbers = new Int32Array(frame_capacity).fill(-1);
-
-        /**
-         * Per-slot byte length of valid input data.
-         * @type {Int32Array}
-         * @private
-         */
-        this.#write_ends = new Int32Array(frame_capacity);
+        this.#ring = new FrameBufferRing({ owner: 'InputRing', frame_capacity, initial_buffer_size });
+    }
 
-        for (let i = 0; i < frame_capacity; i++) {
-            this.#buffers[i] = new BinaryBuffer();
-            this.#buffers[i].setCapacity(initial_buffer_size);
-        }
+    /**
+     * Number of frames retained before the oldest is overwritten.
+     * @readonly
+     * @returns {number}
+     */
+    get frame_capacity() {
+        return this.#ring.frame_capacity;
     }
 
     /**
@@ -80,28 +58,24 @@ export class InputRing {
      *
      * Overwrites any prior data for that frame slot.
      *
-     * **Writer must not throw.** The slot's buffer has already been positioned
-     * at 0 by the time the writer runs, and the prior frame's bytes are being
-     * overwritten in-place. If the writer throws partway, the slot's metadata
-     * (frame number, length) still reflects the previous occupant while the
-     * leading bytes have been clobbered with the partial new write — a torn
-     * state that downstream readers cannot detect. A try/catch wrapper here
-     * would force a V8 deopt on the hot write path, which is a worse trade
-     * than the "writer is trusted" contract; treat any throw in a writer
-     * callback as a programming error.
+     * **Writer must not throw.** The slot has already been claimed for `frame`
+     * and rewound to 0 by the time the writer runs, and the prior frame's bytes
+     * are being overwritten in-place. If the writer throws partway, the slot
+     * reads as holding `frame` while its recorded length is still the previous
+     * occupant's — a torn state that downstream readers cannot detect. A
+     * try/catch wrapper here would force a V8 deopt on the hot write path,
+     * which is a worse trade than the "writer is trusted" contract; treat any
+     * throw in a writer callback as a programming error.
      *
      * @param {number} frame
      * @param {function(BinaryBuffer): void} writer
      */
     write(frame, writer) {
-        assert.isNonNegativeInteger(frame, 'frame');
         assert.isFunction(writer, 'writer');
-        const slot = frame % this.frame_capacity;
-        const buffer = this.#buffers[slot];
-        buffer.position = 0;
-        writer(buffer);
-        this.#write_ends[slot] = buffer.position;
-        this.#frame_numbers[slot] = frame;
+
+        writer(this.#ring.open(frame));
+
+        this.#ring.commit(frame);
     }
 
     /**
@@ -109,9 +83,7 @@ export class InputRing {
      * @returns {boolean}
      */
     has(frame) {
-        assert.isNonNegativeInteger(frame, 'frame');
-        const slot = frame % this.frame_capacity;
-        return this.#frame_numbers[slot] === frame;
+        return this.#ring.has(frame);
     }
 
     /**
@@ -122,14 +94,7 @@ export class InputRing {
      * @returns {BinaryBuffer}
      */
     buffer_for(frame) {
-        assert.isNonNegativeInteger(frame, 'frame');
-        if (!this.has(frame)) {
-            throw new Error(`InputRing.buffer_for: frame ${frame} is not present`);
-        }
-        const slot = frame % this.frame_capacity;
-        const buffer = this.#buffers[slot];
-        buffer.position = 0;
-        return buffer;
+        return this.#ring.buffer_for(frame);
     }
 
     /**
@@ -137,12 +102,7 @@ export class InputRing {
      * @returns {number}
      */
     write_end_for(frame) {
-        assert.isNonNegativeInteger(frame, 'frame');
-        if (!this.has(frame)) {
-            throw new Error(`InputRing.write_end_for: frame ${frame} is not present`);
-        }
-        const slot = frame % this.frame_capacity;
-        return this.#write_ends[slot];
+        return this.#ring.write_end_for(frame);
     }
 
     /**
@@ -161,12 +121,13 @@ export class InputRing {
         // could possibly retain. A caller asking for `[0, current_frame]` after
         // a long disconnect would otherwise walk millions of frames just to
         // call `has()` on each — the ring only holds the last `frame_capacity`.
-        const earliest_possible = end_frame - this.frame_capacity + 1;
+        const earliest_possible = end_frame - this.#ring.frame_capacity + 1;
         const lo = start_frame < earliest_possible ? earliest_possible : start_frame;
         for (let f = lo; f <= end_frame; f++) {
-            if (this.has(f)) {
-                const buffer = this.buffer_for(f);
-                fn(f, buffer, this.write_end_for(f));
+            if (this.#ring.has(f)) {
+                const length = this.#ring.write_end_for(f);
+
+                fn(f, this.#ring.buffer_for(f), length);
             }
         }
     }

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

@@ -1 +1 @@
-{"version":3,"file":"LoopbackTransport.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/LoopbackTransport.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAyCI;;;;;OAKG;IACH,oBAHW,iBAAiB,KACjB,iBAAiB,QAO3B;IA2BD;;;;;OAKG;IACH,eAFa,MAAM,CAYlB;IAED;;;;;;OAMG;IACH,aAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;;OAKG;IACH,WAHW,MAAM,KACN,MAAM,QAWhB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;;CAoCJ;0BAhMyB,gBAAgB"}
+{"version":3,"file":"LoopbackTransport.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/LoopbackTransport.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IA6BI;;;;;OAKG;IACH,oBAHW,iBAAiB,KACjB,iBAAiB,QAO3B;IAyBD;;;;;OAKG;IACH,eAFa,MAAM,CAWlB;IAED;;;;;;OAMG;IACH,aAHW,MAAM,GACJ,MAAM,CAOlB;IAED;;;;;OAKG;IACH,WAHW,MAAM,KACN,MAAM,QAWhB;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;;CA8BJ;0BA3KyB,gBAAgB"}

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

@@ -24,7 +24,6 @@ import { Transport } from "./Transport.js";
 export class LoopbackTransport extends Transport {
     #peer;
     #in_queue;
-    #stats;
 
 
     constructor() {
@@ -49,17 +48,6 @@ export class LoopbackTransport extends Transport {
          * @private
          */
         this.#in_queue = [];
-
-        /**
-         * Stats.
-         * @private
-         */
-        this.#stats = {
-            bytes_in: 0,
-            bytes_out: 0,
-            packets_in: 0,
-            packets_out: 0,
-        };
     }
 
     /**
@@ -87,8 +75,7 @@ export class LoopbackTransport extends Transport {
         assert.isNonNegativeInteger(length, 'length');
         if (this.#peer === null) {
             // Fire-and-forget when unbound; useful for echoing tests that ignore output.
-            this.#stats.bytes_out += length;
-            this.#stats.packets_out += 1;
+            this.count_out(length);
             return;
         }
 
@@ -96,8 +83,7 @@ export class LoopbackTransport extends Transport {
         copy.set(bytes.subarray(0, length));
         this.#peer.#in_queue.push(copy);
 
-        this.#stats.bytes_out += length;
-        this.#stats.packets_out += 1;
+        this.count_out(length);
     }
 
     /**
@@ -110,8 +96,7 @@ export class LoopbackTransport extends Transport {
         let delivered = 0;
         while (this.#in_queue.length > 0) {
             const packet = this.#in_queue.shift();
-            this.#stats.bytes_in += packet.length;
-            this.#stats.packets_in += 1;
+            this.count_in(packet.length);
             this.onReceive.send2(packet, packet.length);
             delivered++;
         }
@@ -162,6 +147,13 @@ export class LoopbackTransport extends Transport {
      * also unbound so its `send()` calls don't keep accumulating into our
      * (now-undrained) inbound queue. The peer's own inbound queue is left
      * alone — the caller can still `deliver_all()` on the peer if needed.
+     *
+     * Deliberately dispatches `onDisconnect` directly rather than through the
+     * base's {@link Transport#fire_disconnect_once} latch. That latch exists to
+     * suppress a *duplicate* notification from an underlying socket closing
+     * behind a local teardown; there is no underlying socket here, so the
+     * signal a test harness drives reconnect flows with is the only one, and
+     * it has to fire on every `disconnect()`.
      */
     disconnect() {
         this.#in_queue.length = 0;
@@ -178,17 +170,4 @@ export class LoopbackTransport extends Transport {
         }
         this.onDisconnect.send1('local_disconnect');
     }
-
-    /**
-     * Read-only stats snapshot.
-     * @returns {{bytes_in: number, bytes_out: number, packets_in: number, packets_out: number}}
-     */
-    getStats() {
-        return {
-            bytes_in: this.#stats.bytes_in,
-            bytes_out: this.#stats.bytes_out,
-            packets_in: this.#stats.packets_in,
-            packets_out: this.#stats.packets_out,
-        };
-    }
 }

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

@@ -88,8 +88,25 @@ export class Transport {
      */
     disconnect(): void;
     /**
-     * Read-only stats snapshot. Default returns zeroes; subclasses are expected
-     * to track their own counters.
+     * Record one inbound packet of `byte_count` bytes. Subclasses call this
+     * from wherever they surface bytes on `onReceive`.
+     *
+     * @param {number} byte_count
+     * @protected
+     */
+    protected count_in(byte_count: number): void;
+    /**
+     * Record one outbound packet of `byte_count` bytes. Subclasses call this
+     * from `send`.
+     *
+     * @param {number} byte_count
+     * @protected
+     */
+    protected count_out(byte_count: number): void;
+    /**
+     * Read-only stats snapshot. Copied out so callers cannot mutate the live
+     * counters.
+     *
      * @returns {{bytes_in: number, bytes_out: number, packets_in: number, packets_out: number}}
      */
     getStats(): {
@@ -98,12 +115,35 @@ export class Transport {
         packets_in: number;
         packets_out: number;
     };
+    /**
+     * Report a lost connection through `onDisconnect`, at most once for the
+     * lifetime of this transport.
+     *
+     * Underlying APIs are not disciplined about this: an `RTCDataChannel` may
+     * raise `error` and then `close` for one failure, a dgram socket the same,
+     * and a WebSocket sometimes both. Subscribers run the reconnect ladder, so
+     * a duplicate is not a cosmetic problem.
+     *
+     * @param {string} reason implementation-specific, for diagnostics
+     * @protected
+     */
+    protected fire_disconnect_once(reason: string): void;
+    /**
+     * Suppress any future {@link fire_disconnect_once}. Called from `disconnect()`
+     * by adapters whose underlying object raises a close event of its own on
+     * the way down: a caller who explicitly tore the transport down does not
+     * expect to be notified that it went away.
+     *
+     * @protected
+     */
+    protected latch_disconnect(): void;
     /**
      * Fast type check; cheaper than `instanceof Transport` in tight loops.
      * @readonly
      * @type {boolean}
      */
     readonly isTransport: boolean;
+    #private;
 }
 import Signal from "../../../core/events/signal/Signal.js";
 //# sourceMappingURL=Transport.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"Transport.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/Transport.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAEI;;;;;;;;;;OAUG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;;OAQG;IACH,SAFU,OAAO,CAED;IAEhB;;;;;OAKG;IACH,WAFU,MAAM,CAES;IAEzB;;;;;;;;;;;OAWG;IACH,cAFU,MAAM,CAEY;IAE5B;;;;;;;;OAQG;IACH,YAJW,UAAU,UACV,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,WAFa,QAAQ,IAAI,CAAC,GAAC,IAAI,CAG9B;IAED;;OAEG;IACH,mBACC;IAED;;;;OAIG;IACH,YAFa;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAI1F;IAGL;;;;OAIG;IACH,sBAFU,OAAO,CAEc;CAP9B;mBA/GkB,uCAAuC"}
+{"version":3,"file":"Transport.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/transport/Transport.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAsBI;;;;;;;;;;OAUG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;;OAQG;IACH,SAFU,OAAO,CAED;IAEhB;;;;;OAKG;IACH,WAFU,MAAM,CAES;IAEzB;;;;;;;;;;;OAWG;IACH,cAFU,MAAM,CAEY;IAE5B;;;;;;;;OAQG;IACH,YAJW,UAAU,UACV,MAAM,GACJ,IAAI,CAIhB;IAED;;;;OAIG;IACH,WAFa,QAAQ,IAAI,CAAC,GAAC,IAAI,CAG9B;IAED;;OAEG;IACH,mBACC;IAED;;;;;;OAMG;IACH,+BAHW,MAAM,QAMhB;IAED;;;;;;OAMG;IACH,gCAHW,MAAM,QAMhB;IAED;;;;;OAKG;IACH,YAFa;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAS1F;IAED;;;;;;;;;;;OAWG;IACH,uCAHW,MAAM,QAWhB;IAED;;;;;;;OAOG;IACH,mCAEC;IAGL;;;;OAIG;IACH,sBAFU,OAAO,CAEc;;CAP9B;mBAnMkB,uCAAuC"}