@woosh/meep-engine 3.1.0 → 3.3.0

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

@@ -1,336 +1,336 @@
-import { assert } from "../../../core/assert.js";
-import Signal from "../../../core/events/signal/Signal.js";
-import { ack_bitfield_build, ack_bitfield_for_each, } from "../core/sequence/ack_bitfield.js";
-import { seq16_advance, seq16_distance, seq16_greater_than, SEQ16_HALF_RANGE } from "../core/sequence/seq16.js";
-
-/**
- * Reliability-notification layer over a {@link Transport}.
- *
- * Adds a 9-byte header to every packet:
- * ```
- *   uint16:  outgoing_seq
- *   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).
- *
- * Channel does NOT retransmit. It surfaces:
- *   - `onPacketAcked(seq)` when a peer's ack indicates an outgoing packet arrived
- *   - `onPacketLost(seq)` when an outgoing packet falls outside the 33-seq ack
- *     window without ever being acked (peer has acked 32 newer packets, so this
- *     one is presumed lost)
- *   - `onPayload(bytes, length)` for the payload portion of received packets,
- *     with the header stripped
- *
- * Reliability-by-retransmission lives in a higher-level pipeline (separate file,
- * yet to build). Channel just provides the notification primitive.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-
-const HEADER_SIZE = 9;
-
-export class Channel {
-    #next_outgoing_seq;
-    #unacked_outgoing;
-    #latest_received_seq;
-    #received_seqs;
-    #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, 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 }}
-         */
-        this.transport = transport;
-        this.transport.onReceive.add(this.#handle_inbound, this);
-
-        /** @type {number} @private */
-        this.#next_outgoing_seq = 0;
-
-        /**
-         * Outgoing seqs waiting on ack from the peer.
-         * @type {Set<number>}
-         * @private
-         */
-        this.#unacked_outgoing = new Set();
-
-        /**
-         * Most recent seq we've received from the peer; -1 if none yet.
-         * @type {number}
-         * @private
-         */
-        this.#latest_received_seq = -1;
-
-        /**
-         * Seqs we have received. Used to build the ack bitfield piggyback.
-         * Pruned when entries fall outside the 64-seq window.
-         * @type {Set<number>}
-         * @private
-         */
-        this.#received_seqs = new Set();
-
-        /**
-         * Pre-allocated send buffer. Resized only if a payload exceeds capacity.
-         * @type {Uint8Array}
-         * @private
-         */
-        this.#send_buffer = new Uint8Array(1500);
-        /** @type {DataView} @private */
-        this.#send_view = new DataView(this.#send_buffer.buffer);
-
-        /**
-         * Scratch list for collecting "to be marked lost" outgoing seqs during
-         * an inbound handler (avoids modifying the Set while iterating).
-         * @type {number[]}
-         * @private
-         */
-        this.#lost_scratch = [];
-
-        /**
-         * Fired when an outgoing seq has been positively acknowledged by the peer.
-         * @type {Signal}
-         */
-        this.onPacketAcked = new Signal();
-
-        /**
-         * Fired when an outgoing seq has aged out of the ack window without being acked.
-         * @type {Signal}
-         */
-        this.onPacketLost = new Signal();
-
-        /**
-         * Fired when an inbound packet's payload is ready (header already stripped).
-         * Handler args: (payload: Uint8Array starting at offset 0, length: number).
-         * The Uint8Array is owned by the Channel and may be reused after the handler returns.
-         * @type {Signal}
-         */
-        this.onPayload = new Signal();
-    }
-
-    /**
-     * Wrap and send a payload. Returns the seq number assigned to it.
-     *
-     * @param {Uint8Array} payload
-     * @param {number} length payload length in bytes
-     * @returns {number} seq
-     */
-    send(payload, length) {
-        assert.isNonNegativeInteger(length, 'length');
-
-        const total_size = HEADER_SIZE + length;
-        if (total_size > this.#send_buffer.length) {
-            this.#send_buffer = new Uint8Array(Math.max(total_size, this.#send_buffer.length * 2));
-            this.#send_view = new DataView(this.#send_buffer.buffer);
-        }
-
-        const seq = this.#next_outgoing_seq;
-        this.#next_outgoing_seq = seq16_advance(seq);
-
-        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);
-        }
-
-        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;
-    }
-
-    /**
-     * Number of outgoing packets sent but not yet acked or marked lost.
-     * @returns {number}
-     */
-    unacked_count() {
-        return this.#unacked_outgoing.size;
-    }
-
-    /**
-     * Most recent seq received from the peer, or -1 if none yet.
-     * @returns {number}
-     */
-    latest_received_seq() {
-        return this.#latest_received_seq;
-    }
-
-    /**
-     * Test-only: seed the next outgoing seq number. Used to fast-forward
-     * the seq counter so the seq16 wraparound can be exercised in
-     * unit tests without sending 65k packets. Do not call from production.
-     * @param {number} seq
-     */
-    seed_outgoing_seq_for_testing(seq) {
-        this.#next_outgoing_seq = seq;
-    }
-
-    /**
-     * @param {Uint8Array} bytes
-     * @param {number} length
-     * @private
-     */
-    #handle_inbound(bytes, length) {
-        if (length < HEADER_SIZE) {
-            // Malformed: too short to contain a header. Drop silently.
-            return;
-        }
-
-        const view = new DataView(bytes.buffer, bytes.byteOffset, length);
-        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)) {
-            this.#latest_received_seq = seq;
-        }
-        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)) {
-                this.onPacketAcked.send1(acked_seq);
-            }
-        });
-
-        // Anything older than (ack_latest - 32) that is still unacked is presumed lost.
-        // Sanity: if `d` ever approaches half-range we're flying so many
-        // unacked packets that distance is about to wrap to negative and the
-        // loss-detection would silently break. Non-goal to support; assert.
-        this.#lost_scratch.length = 0;
-        for (const out_seq of this.#unacked_outgoing) {
-            const d = seq16_distance(out_seq, ack_latest);
-            assert.lessThan(d, SEQ16_HALF_RANGE / 2, `Channel: outgoing seq ${out_seq} is ${d} packets behind ack_latest ${ack_latest} — approaching seq16 half-range wraparound`);
-            if (d > 32) {
-                this.#lost_scratch.push(out_seq);
-            }
-        }
-        for (let i = 0; i < this.#lost_scratch.length; i++) {
-            const lost = this.#lost_scratch[i];
-            this.#unacked_outgoing.delete(lost);
-            this.onPacketLost.send1(lost);
-        }
-    }
-
-    /**
-     * Detach this Channel from its transport. The transport.onReceive subscription
-     * is removed so the Channel stops processing inbound bytes; the Channel's own
-     * Signals are left in place (callers usually hold no references to them after
-     * dispose, so they GC with the Channel). Required before discarding a Channel
-     * whose transport will be reused — otherwise the old Channel keeps consuming
-     * inbound packets in parallel with whatever replaces it.
-     */
-    dispose() {
-        this.transport.onReceive.remove(this.#handle_inbound, this);
-    }
-
-    /**
-     * Drop received-seq entries that are too old to matter for the next ack bitfield.
-     * Keeps a window slightly larger than the 33-seq bitfield to absorb out-of-order arrival.
-     * @private
-     */
-    #prune_received_seqs() {
-        const latest = this.#latest_received_seq;
-        if (latest < 0) return;
-        // Window: 64 seqs back. Anything farther can be dropped.
-        for (const s of this.#received_seqs) {
-            if (seq16_distance(s, latest) > 64) {
-                this.#received_seqs.delete(s);
-            }
-        }
-    }
-}
+import { assert } from "../../../core/assert.js";
+import Signal from "../../../core/events/signal/Signal.js";
+import { ack_bitfield_build, ack_bitfield_for_each, } from "../core/sequence/ack_bitfield.js";
+import { seq16_advance, seq16_distance, seq16_greater_than, SEQ16_HALF_RANGE } from "../core/sequence/seq16.js";
+
+/**
+ * Reliability-notification layer over a {@link Transport}.
+ *
+ * Adds a 9-byte header to every packet:
+ * ```
+ *   uint16:  outgoing_seq
+ *   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).
+ *
+ * Channel does NOT retransmit. It surfaces:
+ *   - `onPacketAcked(seq)` when a peer's ack indicates an outgoing packet arrived
+ *   - `onPacketLost(seq)` when an outgoing packet falls outside the 33-seq ack
+ *     window without ever being acked (peer has acked 32 newer packets, so this
+ *     one is presumed lost)
+ *   - `onPayload(bytes, length)` for the payload portion of received packets,
+ *     with the header stripped
+ *
+ * Reliability-by-retransmission lives in a higher-level pipeline (separate file,
+ * yet to build). Channel just provides the notification primitive.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+const HEADER_SIZE = 9;
+
+export class Channel {
+    #next_outgoing_seq;
+    #unacked_outgoing;
+    #latest_received_seq;
+    #received_seqs;
+    #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, 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 }}
+         */
+        this.transport = transport;
+        this.transport.onReceive.add(this.#handle_inbound, this);
+
+        /** @type {number} @private */
+        this.#next_outgoing_seq = 0;
+
+        /**
+         * Outgoing seqs waiting on ack from the peer.
+         * @type {Set<number>}
+         * @private
+         */
+        this.#unacked_outgoing = new Set();
+
+        /**
+         * Most recent seq we've received from the peer; -1 if none yet.
+         * @type {number}
+         * @private
+         */
+        this.#latest_received_seq = -1;
+
+        /**
+         * Seqs we have received. Used to build the ack bitfield piggyback.
+         * Pruned when entries fall outside the 64-seq window.
+         * @type {Set<number>}
+         * @private
+         */
+        this.#received_seqs = new Set();
+
+        /**
+         * Pre-allocated send buffer. Resized only if a payload exceeds capacity.
+         * @type {Uint8Array}
+         * @private
+         */
+        this.#send_buffer = new Uint8Array(1500);
+        /** @type {DataView} @private */
+        this.#send_view = new DataView(this.#send_buffer.buffer);
+
+        /**
+         * Scratch list for collecting "to be marked lost" outgoing seqs during
+         * an inbound handler (avoids modifying the Set while iterating).
+         * @type {number[]}
+         * @private
+         */
+        this.#lost_scratch = [];
+
+        /**
+         * Fired when an outgoing seq has been positively acknowledged by the peer.
+         * @type {Signal}
+         */
+        this.onPacketAcked = new Signal();
+
+        /**
+         * Fired when an outgoing seq has aged out of the ack window without being acked.
+         * @type {Signal}
+         */
+        this.onPacketLost = new Signal();
+
+        /**
+         * Fired when an inbound packet's payload is ready (header already stripped).
+         * Handler args: (payload: Uint8Array starting at offset 0, length: number).
+         * The Uint8Array is owned by the Channel and may be reused after the handler returns.
+         * @type {Signal}
+         */
+        this.onPayload = new Signal();
+    }
+
+    /**
+     * Wrap and send a payload. Returns the seq number assigned to it.
+     *
+     * @param {Uint8Array} payload
+     * @param {number} length payload length in bytes
+     * @returns {number} seq
+     */
+    send(payload, length) {
+        assert.isNonNegativeInteger(length, 'length');
+
+        const total_size = HEADER_SIZE + length;
+        if (total_size > this.#send_buffer.length) {
+            this.#send_buffer = new Uint8Array(Math.max(total_size, this.#send_buffer.length * 2));
+            this.#send_view = new DataView(this.#send_buffer.buffer);
+        }
+
+        const seq = this.#next_outgoing_seq;
+        this.#next_outgoing_seq = seq16_advance(seq);
+
+        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);
+        }
+
+        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;
+    }
+
+    /**
+     * Number of outgoing packets sent but not yet acked or marked lost.
+     * @returns {number}
+     */
+    unacked_count() {
+        return this.#unacked_outgoing.size;
+    }
+
+    /**
+     * Most recent seq received from the peer, or -1 if none yet.
+     * @returns {number}
+     */
+    latest_received_seq() {
+        return this.#latest_received_seq;
+    }
+
+    /**
+     * Test-only: seed the next outgoing seq number. Used to fast-forward
+     * the seq counter so the seq16 wraparound can be exercised in
+     * unit tests without sending 65k packets. Do not call from production.
+     * @param {number} seq
+     */
+    seed_outgoing_seq_for_testing(seq) {
+        this.#next_outgoing_seq = seq;
+    }
+
+    /**
+     * @param {Uint8Array} bytes
+     * @param {number} length
+     * @private
+     */
+    #handle_inbound(bytes, length) {
+        if (length < HEADER_SIZE) {
+            // Malformed: too short to contain a header. Drop silently.
+            return;
+        }
+
+        const view = new DataView(bytes.buffer, bytes.byteOffset, length);
+        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)) {
+            this.#latest_received_seq = seq;
+        }
+        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)) {
+                this.onPacketAcked.send1(acked_seq);
+            }
+        });
+
+        // Anything older than (ack_latest - 32) that is still unacked is presumed lost.
+        // Sanity: if `d` ever approaches half-range we're flying so many
+        // unacked packets that distance is about to wrap to negative and the
+        // loss-detection would silently break. Non-goal to support; assert.
+        this.#lost_scratch.length = 0;
+        for (const out_seq of this.#unacked_outgoing) {
+            const d = seq16_distance(out_seq, ack_latest);
+            assert.lessThan(d, SEQ16_HALF_RANGE / 2, `Channel: outgoing seq ${out_seq} is ${d} packets behind ack_latest ${ack_latest} — approaching seq16 half-range wraparound`);
+            if (d > 32) {
+                this.#lost_scratch.push(out_seq);
+            }
+        }
+        for (let i = 0; i < this.#lost_scratch.length; i++) {
+            const lost = this.#lost_scratch[i];
+            this.#unacked_outgoing.delete(lost);
+            this.onPacketLost.send1(lost);
+        }
+    }
+
+    /**
+     * Detach this Channel from its transport. The transport.onReceive subscription
+     * is removed so the Channel stops processing inbound bytes; the Channel's own
+     * Signals are left in place (callers usually hold no references to them after
+     * dispose, so they GC with the Channel). Required before discarding a Channel
+     * whose transport will be reused — otherwise the old Channel keeps consuming
+     * inbound packets in parallel with whatever replaces it.
+     */
+    dispose() {
+        this.transport.onReceive.remove(this.#handle_inbound, this);
+    }
+
+    /**
+     * Drop received-seq entries that are too old to matter for the next ack bitfield.
+     * Keeps a window slightly larger than the 33-seq bitfield to absorb out-of-order arrival.
+     * @private
+     */
+    #prune_received_seqs() {
+        const latest = this.#latest_received_seq;
+        if (latest < 0) return;
+        // Window: 64 seqs back. Anything farther can be dropped.
+        for (const s of this.#received_seqs) {
+            if (seq16_distance(s, latest) > 64) {
+                this.#received_seqs.delete(s);
+            }
+        }
+    }
+}