@woosh/meep-engine 3.46.0 → 3.49.0

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

@@ -1,350 +0,0 @@
-import { assert } from "../../../../core/assert.js";
-import {
-    FRAGMENT_NACK_INITIAL_DELAY_MS,
-    FRAGMENT_NACK_MAX_ROUNDS,
-    FRAGMENT_NACK_RESEND_INTERVAL_MS,
-    MAX_CHUNKS_PER_MESSAGE,
-} from "./packet_size.js";
-
-/**
- * Per-peer reassembly buffer for fragmented packets.
- *
- * When a sender's logical payload exceeds the MTU it gets split into
- * multiple {@link NetworkPacketType.FRAGMENT} packets, each carrying a
- * `(message_id, chunk_index, total_chunks, chunk_bytes)` tuple. The
- * receiver feeds those tuples to {@link receive}; once all chunks for a
- * `message_id` have arrived, `receive` returns the reassembled bytes
- * for the upper layer to dispatch.
- *
- * Loss recovery via NACK: a partially-received message that doesn't
- * complete within `nack_initial_delay_ms` triggers a NACK back to the
- * sender listing the missing chunk indices. NACK rounds repeat at
- * `nack_resend_interval_ms` up to `nack_max_rounds`; after that the
- * receiver gives up on the message and the sender's retention ages
- * out independently. Wire the per-tick driver via {@link service}.
- *
- * Loss-of-last-resort model: if even the NACK retries fail (link is
- * dead, sender retention was evicted, etc.) the message never
- * completes and FIFO-evicts when the pending cap is hit. Upper layers
- * are still expected to tolerate occasional missing messages — NACK
- * recovers most loss, not all.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class FragmentAssembler {
-    #pending;
-    /**
-     * FIFO of message_ids in insertion order, for eviction when the
-     * pending map exceeds `max_pending_messages`.
-     * @type {number[]}
-     * @private
-     */
-    #order = [];
-
-    /**
-     * Message ids delivered recently, so a late or retransmitted chunk for one is dropped rather
-     * than opening a fresh reassembly slot. See the note in {@link receive}.
-     *
-     * Bounded by {@link #completed_order}, which spans the same window `#order` does.
-     *
-     * @type {Set<number>}
-     */
-    #completed = new Set();
-
-    /**
-     * Insertion order of {@link #completed}, for FIFO eviction.
-     * @type {number[]}
-     */
-    #completed_order = [];
-    #nack_scratch;
-    /**
-     * Scratch for message_ids to drop after a {@link service} pass.
-     * Collected during iteration so the underlying map isn't mutated
-     * mid-iteration.
-     * @type {number[]}
-     * @private
-     */
-    #drop_scratch = [];
-
-    /**
-     * @param {{
-     *   max_pending_messages?: number,
-     *   max_message_size?: number,
-     *   nack_initial_delay_ms?: number,
-     *   nack_resend_interval_ms?: number,
-     *   nack_max_rounds?: number,
-     * }} [options]
-     *   `max_pending_messages` caps the number of in-flight reassembly
-     *   slots; when full, the oldest pending message is evicted to make
-     *   room. `max_message_size` rejects reassembled messages larger than
-     *   this many bytes (defensive against a malicious peer or a wedged
-     *   sender). The `nack_*` knobs control the retransmit-request timer
-     *   driven by {@link service}.
-     */
-    constructor({
-        max_pending_messages = 8,
-        max_message_size = 65536,
-        nack_initial_delay_ms = FRAGMENT_NACK_INITIAL_DELAY_MS,
-        nack_resend_interval_ms = FRAGMENT_NACK_RESEND_INTERVAL_MS,
-        nack_max_rounds = FRAGMENT_NACK_MAX_ROUNDS,
-    } = {}) {
-        assert.isPositiveInteger(max_pending_messages, 'max_pending_messages');
-        assert.isPositiveInteger(max_message_size, 'max_message_size');
-        assert.isPositiveInteger(nack_initial_delay_ms, 'nack_initial_delay_ms');
-        assert.isPositiveInteger(nack_resend_interval_ms, 'nack_resend_interval_ms');
-        assert.isPositiveInteger(nack_max_rounds, 'nack_max_rounds');
-
-        /** @type {number} @readonly */
-        this.max_pending_messages = max_pending_messages;
-        /** @type {number} @readonly */
-        this.max_message_size = max_message_size;
-        /** @type {number} @readonly */
-        this.nack_initial_delay_ms = nack_initial_delay_ms;
-        /** @type {number} @readonly */
-        this.nack_resend_interval_ms = nack_resend_interval_ms;
-        /** @type {number} @readonly */
-        this.nack_max_rounds = nack_max_rounds;
-
-        /**
-         * Pending reassembly state per `message_id`. Each entry:
-         *   total_chunks:   uint8 — number of chunks expected
-         *   chunks:         (Uint8Array | undefined)[] — chunk_index → bytes
-         *   received_count: number of distinct chunks present
-         *   total_bytes:    sum of chunk lengths received so far
-         *   first_seen_at:  ms timestamp of the first {@link service} tick
-         *                   that observed this entry; -1 until stamped
-         *   last_nack_at:   ms timestamp of the most recent NACK emitted
-         *                   for this entry; -1 if never
-         *   nack_rounds:    number of NACKs emitted for this entry
-         * @type {Map<number, {total_chunks: number, chunks: Uint8Array[], received_count: number, total_bytes: number, first_seen_at: number, last_nack_at: number, nack_rounds: number}>}
-         * @private
-         */
-        this.#pending = new Map();
-
-        /**
-         * Reusable scratch for the missing-index list passed to the NACK
-         * callback. Sized to the wire maximum so the callback can always
-         * iterate `count` entries safely.
-         * @type {Uint8Array}
-         * @private
-         */
-        this.#nack_scratch = new Uint8Array(MAX_CHUNKS_PER_MESSAGE);
-    }
-
-    /**
-     * Process an incoming fragment. Returns the reassembled bytes when
-     * the message is complete, or null otherwise.
-     *
-     * @param {number} message_id     sender-assigned message id
-     * @param {number} chunk_index    0-based
-     * @param {number} total_chunks   expected number of chunks (>= 1)
-     * @param {Uint8Array} chunk_bytes  source byte array
-     * @param {number} chunk_offset   start offset within `chunk_bytes`
-     * @param {number} chunk_length   number of bytes from `chunk_offset` to consume
-     * @returns {Uint8Array|null}
-     */
-    receive(message_id, chunk_index, total_chunks, chunk_bytes, chunk_offset, chunk_length) {
-        assert.isNonNegativeInteger(message_id, 'message_id');
-        assert.isNonNegativeInteger(chunk_index, 'chunk_index');
-        assert.isPositiveInteger(total_chunks, 'total_chunks');
-        assert.isNonNegativeInteger(chunk_offset, 'chunk_offset');
-        assert.isNonNegativeInteger(chunk_length, 'chunk_length');
-
-        if (chunk_index >= total_chunks) {
-            // Malformed; discard silently.
-            return null;
-        }
-
-        if (this.#completed.has(message_id)) {
-            // Already delivered. Without this the chunk misses the duplicate guard below - which
-            // lives INSIDE an entry, and completion erases the entry - and opens a fresh, and
-            // therefore incomplete, reassembly slot. `service()` then NACKs the sender for chunks
-            // of a message it has already delivered, the sender's retention honours the NACK, and
-            // the message completes and is dispatched a second time: STATE_BURST straight to the
-            // application handler, INITIAL_SYNC re-applying a whole snapshot. It is the ordinary
-            // NACK/late-chunk race, not an adversarial input - `packet_size.js` sizes the delay
-            // expecting the receiver to "occasionally NACK chunks still in transit".
-            return null;
-        }
-
-        let entry = this.#pending.get(message_id);
-        if (entry === undefined) {
-            if (this.#pending.size >= this.max_pending_messages) {
-                // Evict the oldest pending message (FIFO).
-                const oldest = this.#order.shift();
-                if (oldest !== undefined) this.#pending.delete(oldest);
-            }
-            entry = {
-                total_chunks,
-                chunks: new Array(total_chunks),
-                received_count: 0,
-                total_bytes: 0,
-                first_seen_at: -1,
-                last_nack_at: -1,
-                nack_rounds: 0,
-            };
-            this.#pending.set(message_id, entry);
-            this.#order.push(message_id);
-        }
-
-        if (entry.total_chunks !== total_chunks) {
-            // Conflicting metadata across fragments for the same message_id.
-            // Drop the whole assembly — something is very wrong upstream.
-            this.#delete(message_id);
-            return null;
-        }
-
-        if (entry.chunks[chunk_index] !== undefined) {
-            // Duplicate fragment; ignore (network may have retransmitted).
-            return null;
-        }
-
-        // Defensive: refuse to allocate more memory than max_message_size for
-        // this assembly. Check incrementally so a malicious sender can't
-        // claim 255 chunks of 65 KB each.
-        if (entry.total_bytes + chunk_length > this.max_message_size) {
-            this.#delete(message_id);
-            return null;
-        }
-
-        const copy = new Uint8Array(chunk_length);
-        copy.set(chunk_bytes.subarray(chunk_offset, chunk_offset + chunk_length));
-        entry.chunks[chunk_index] = copy;
-        entry.received_count++;
-        entry.total_bytes += chunk_length;
-
-        if (entry.received_count < entry.total_chunks) return null;
-
-        // Complete — assemble.
-        const reassembled = new Uint8Array(entry.total_bytes);
-        let offset = 0;
-        for (let i = 0; i < entry.total_chunks; i++) {
-            const c = entry.chunks[i];
-            reassembled.set(c, offset);
-            offset += c.length;
-        }
-        this.#delete(message_id);
-
-        this.#remember_completed(message_id);
-
-        return reassembled;
-    }
-
-    /**
-     * Record a delivered message id, evicting the oldest when the window is full.
-     *
-     * The window is the same size as the pending one: a chunk arriving later than that many
-     * distinct messages after its own completed is beyond anything the retransmit machinery
-     * would still be holding.
-     *
-     * @param {number} message_id
-     */
-    #remember_completed(message_id) {
-        if (this.#completed.has(message_id)) {
-            return;
-        }
-
-        this.#completed.add(message_id);
-        this.#completed_order.push(message_id);
-
-        while (this.#completed_order.length > this.max_pending_messages) {
-            const oldest = this.#completed_order.shift();
-
-            this.#completed.delete(oldest);
-        }
-    }
-
-    /**
-     * Per-tick maintenance: drive NACK emission for pending messages
-     * whose initial delay has elapsed and whose resend interval has
-     * lapsed, and drop messages whose NACK budget is exhausted.
-     *
-     * On the first service tick that observes a pending entry, its
-     * arrival is timestamped (so the initial delay is measured from
-     * `now_ms` of that tick rather than from the actual wall-clock
-     * arrival of the first chunk — at typical tick rates the difference
-     * is one tick, negligible vs. the 100 ms initial delay).
-     *
-     * `on_nack` is invoked once per eligible message with
-     * `(message_id, indices, count)`: the missing chunks in index order, but
-     * never more of them than the message has delivered. The `indices` argument is a
-     * reused internal Uint8Array; only `indices[0..count)` is valid
-     * and only for the duration of the call.
-     *
-     * @param {number} now_ms
-     * @param {function(number, Uint8Array, number): void} on_nack
-     */
-    service(now_ms, on_nack) {
-        assert.isNumber(now_ms, 'now_ms');
-        assert.isFunction(on_nack, 'on_nack');
-        if (this.#pending.size === 0) return;
-
-        this.#drop_scratch.length = 0;
-
-        for (const [message_id, entry] of this.#pending) {
-            if (entry.first_seen_at < 0) {
-                entry.first_seen_at = now_ms;
-                continue;
-            }
-            if (now_ms - entry.first_seen_at < this.nack_initial_delay_ms) continue;
-            if (entry.last_nack_at >= 0
-                && now_ms - entry.last_nack_at < this.nack_resend_interval_ms) continue;
-
-            // Build the missing-chunk list, no longer than the chunks the
-            // message has delivered. `total_chunks` is the sender's claim, so
-            // it cannot bound the list by itself: one empty fragment claiming
-            // 255 chunks drew a NACK of the other 254 each round, some fifty
-            // times its own size. A message that has lost more than it has
-            // delivered is asked for the rest over the following rounds.
-            let missing_count = 0;
-            for (let i = 0; i < entry.total_chunks && missing_count < entry.received_count; i++) {
-                if (entry.chunks[i] === undefined) {
-                    this.#nack_scratch[missing_count++] = i;
-                }
-            }
-            // Defensive: a fully-received entry should have been deleted
-            // in `receive`, but a torn-down concurrent state could leave
-            // a zero-missing slot here. Skip rather than emit an empty NACK.
-            if (missing_count === 0) continue;
-
-            on_nack(message_id, this.#nack_scratch, missing_count);
-            entry.last_nack_at = now_ms;
-            entry.nack_rounds++;
-
-            if (entry.nack_rounds >= this.nack_max_rounds) {
-                this.#drop_scratch.push(message_id);
-            }
-        }
-
-        for (let i = 0; i < this.#drop_scratch.length; i++) {
-            this.#delete(this.#drop_scratch[i]);
-        }
-    }
-
-    /**
-     * Number of in-flight reassembly slots currently held.
-     * @returns {number}
-     */
-    pending_count() {
-        return this.#pending.size;
-    }
-
-    /**
-     * Drop all in-flight reassembly state. Useful on peer disconnect.
-     */
-    clear() {
-        this.#pending.clear();
-        this.#order.length = 0;
-
-        this.#completed.clear();
-        this.#completed_order.length = 0;
-    }
-
-    /** @private */
-    #delete(message_id) {
-        this.#pending.delete(message_id);
-        const idx = this.#order.indexOf(message_id);
-        if (idx >= 0) this.#order.splice(idx, 1);
-    }
-}

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

@@ -1,103 +0,0 @@
-/**
- * Per-peer sender-side retention buffer for fragmented message bytes,
- * used to satisfy NACK retransmits from the peer's {@link FragmentAssembler}.
- *
- * Lifecycle:
- *   1. {@link retain} — called on each fragmented send; copies the source
- *      bytes into the retention so they're available to retransmit. If
- *      the per-peer slot cap is hit, the oldest retained entry is FIFO-
- *      evicted.
- *   2. {@link consume_nack} — looks up retained bytes for a NACK target
- *      and bumps the retry counter. Returns `null` if the entry is gone
- *      (aged out, evicted, or out of retry budget — in which case the
- *      entry is dropped here too).
- *   3. {@link service} — call once per tick to age out entries older
- *      than `max_age_ms`.
- *   4. {@link clear} — drop everything; call on peer disconnect.
- *
- * Memory cost: each retained entry holds a fresh copy of its source
- * payload (the upstream send buffer is a reused scratch). With the
- * default 16 slots × up-to-64 KiB cap on the receiver, worst case is
- * 1 MiB per peer; steady-state is empty because steady traffic fits in
- * one packet and bypasses fragmentation.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class FragmentRetention {
-    /**
-     * @param {{
-     *   max_messages?: number,
-     *   max_age_ms?: number,
-     *   max_retries?: number,
-     * }} [options]
-     *   `max_messages` caps simultaneously-retained messages; oldest is
-     *   FIFO-evicted on overflow. `max_age_ms` is the per-entry TTL.
-     *   `max_retries` caps how many NACK retransmit rounds a single
-     *   retained message can satisfy before being dropped.
-     */
-    constructor({ max_messages, max_age_ms, max_retries, }?: {
-        max_messages?: number;
-        max_age_ms?: number;
-        max_retries?: number;
-    });
-    /** @type {number} @readonly */
-    readonly max_messages: number;
-    /** @type {number} @readonly */
-    readonly max_age_ms: number;
-    /** @type {number} @readonly */
-    readonly max_retries: number;
-    /**
-     * Copy `payload[0..length)` into retention under `message_id`.
-     * Evicts the oldest retained entry if `max_messages` is exceeded.
-     *
-     * If a retained entry already exists for `message_id` (only legitimate
-     * cause: uint16 wrap), the old entry is dropped first so the FIFO
-     * position and retry budget restart from the new send.
-     *
-     * @param {number} message_id
-     * @param {Uint8Array} payload  source bytes (caller may overwrite after return)
-     * @param {number} length       number of bytes from `payload[0]` to copy
-     * @param {number} now_ms       monotonic timestamp for age-out
-     */
-    retain(message_id: number, payload: Uint8Array, length: number, now_ms: number): void;
-    /**
-     * Mark a NACK round for `message_id` and return the retained entry
-     * so the caller can re-emit the missing chunks. Returns `null` if
-     * no entry exists, or if the per-message retry budget is now
-     * exhausted (in which case the entry is dropped).
-     *
-     * @param {number} message_id
-     * @returns {{payload: Uint8Array, length: number}|null}
-     */
-    consume_nack(message_id: number): {
-        payload: Uint8Array;
-        length: number;
-    } | null;
-    /**
-     * Per-tick maintenance: evict any entry older than `max_age_ms`.
-     *
-     * The FIFO is in strict insertion order, so we can stop at the first
-     * still-fresh entry rather than scanning the whole map.
-     *
-     * @param {number} now_ms
-     */
-    service(now_ms: number): void;
-    /**
-     * Number of currently-retained messages.
-     * @returns {number}
-     */
-    size(): number;
-    /**
-     * Whether `message_id` is currently retained.
-     * @param {number} message_id
-     * @returns {boolean}
-     */
-    has(message_id: number): boolean;
-    /**
-     * Drop every retained entry. Use on peer disconnect.
-     */
-    clear(): void;
-    #private;
-}
-//# sourceMappingURL=FragmentRetention.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"FragmentRetention.d.ts","sourceRoot":"","sources":["../../../../../../src/engine/network/transport/fragments/FragmentRetention.js"],"names":[],"mappings":"AAOA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH;IAUI;;;;;;;;;;OAUG;IACH,yDAVW;QACV,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,UAAc,CAAC,EAAE,MAAM,CAAC;QACxB,WAAe,CAAC,EAAE,MAAM,CAAC;KACtB,EA6BH;IAdG,+BAA+B;IAC/B,uBADW,MAAM,CACe;IAChC,+BAA+B;IAC/B,qBADW,MAAM,CACW;IAC5B,+BAA+B;IAC/B,sBADW,MAAM,CACa;IAWlC;;;;;;;;;;;;OAYG;IACH,mBALW,MAAM,WACN,UAAU,UACV,MAAM,UACN,MAAM,QAuBhB;IAED;;;;;;;;OAQG;IACH,yBAHW,MAAM,GACJ;QAAC,OAAO,EAAE,UAAU,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAC,GAAC,IAAI,CAYtD;IAED;;;;;;;OAOG;IACH,gBAFW,MAAM,QAehB;IAED;;;OAGG;IACH,QAFa,MAAM,CAIlB;IAED;;;;OAIG;IACH,gBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;OAEG;IACH,cAGC;;CAQJ"}

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

@@ -1,191 +0,0 @@
-import { assert } from "../../../../core/assert.js";
-import {
-    FRAGMENT_RETENTION_MAX_AGE_MS,
-    FRAGMENT_RETENTION_MAX_MESSAGES,
-    FRAGMENT_RETENTION_MAX_RETRIES,
-} from "./packet_size.js";
-
-/**
- * Per-peer sender-side retention buffer for fragmented message bytes,
- * used to satisfy NACK retransmits from the peer's {@link FragmentAssembler}.
- *
- * Lifecycle:
- *   1. {@link retain} — called on each fragmented send; copies the source
- *      bytes into the retention so they're available to retransmit. If
- *      the per-peer slot cap is hit, the oldest retained entry is FIFO-
- *      evicted.
- *   2. {@link consume_nack} — looks up retained bytes for a NACK target
- *      and bumps the retry counter. Returns `null` if the entry is gone
- *      (aged out, evicted, or out of retry budget — in which case the
- *      entry is dropped here too).
- *   3. {@link service} — call once per tick to age out entries older
- *      than `max_age_ms`.
- *   4. {@link clear} — drop everything; call on peer disconnect.
- *
- * Memory cost: each retained entry holds a fresh copy of its source
- * payload (the upstream send buffer is a reused scratch). With the
- * default 16 slots × up-to-64 KiB cap on the receiver, worst case is
- * 1 MiB per peer; steady-state is empty because steady traffic fits in
- * one packet and bypasses fragmentation.
- *
- * @author Alex Goldring
- * @copyright Company Named Limited (c) 2026
- */
-export class FragmentRetention {
-    #entries;
-    /**
-     * FIFO of message_ids in insertion order, for eviction on
-     * overflow and for monotonic age-out.
-     * @type {number[]}
-     * @private
-     */
-    #order = [];
-
-    /**
-     * @param {{
-     *   max_messages?: number,
-     *   max_age_ms?: number,
-     *   max_retries?: number,
-     * }} [options]
-     *   `max_messages` caps simultaneously-retained messages; oldest is
-     *   FIFO-evicted on overflow. `max_age_ms` is the per-entry TTL.
-     *   `max_retries` caps how many NACK retransmit rounds a single
-     *   retained message can satisfy before being dropped.
-     */
-    constructor({
-        max_messages = FRAGMENT_RETENTION_MAX_MESSAGES,
-        max_age_ms = FRAGMENT_RETENTION_MAX_AGE_MS,
-        max_retries = FRAGMENT_RETENTION_MAX_RETRIES,
-    } = {}) {
-        assert.isPositiveInteger(max_messages, 'max_messages');
-        assert.isPositiveInteger(max_age_ms, 'max_age_ms');
-        assert.isNonNegativeInteger(max_retries, 'max_retries');
-
-        /** @type {number} @readonly */
-        this.max_messages = max_messages;
-        /** @type {number} @readonly */
-        this.max_age_ms = max_age_ms;
-        /** @type {number} @readonly */
-        this.max_retries = max_retries;
-
-        /**
-         * message_id → retained entry. `payload` is a fresh copy
-         * (independent of the caller's send buffer).
-         * @type {Map<number, {payload: Uint8Array, length: number, sent_at: number, retries: number}>}
-         * @private
-         */
-        this.#entries = new Map();
-    }
-
-    /**
-     * Copy `payload[0..length)` into retention under `message_id`.
-     * Evicts the oldest retained entry if `max_messages` is exceeded.
-     *
-     * If a retained entry already exists for `message_id` (only legitimate
-     * cause: uint16 wrap), the old entry is dropped first so the FIFO
-     * position and retry budget restart from the new send.
-     *
-     * @param {number} message_id
-     * @param {Uint8Array} payload  source bytes (caller may overwrite after return)
-     * @param {number} length       number of bytes from `payload[0]` to copy
-     * @param {number} now_ms       monotonic timestamp for age-out
-     */
-    retain(message_id, payload, length, now_ms) {
-        assert.isNonNegativeInteger(message_id, 'message_id');
-        assert.isNonNegativeInteger(length, 'length');
-        assert.isNumber(now_ms, 'now_ms');
-
-        if (this.#entries.has(message_id)) {
-            this.#delete(message_id);
-        }
-        if (this.#entries.size >= this.max_messages) {
-            const oldest = this.#order.shift();
-            if (oldest !== undefined) this.#entries.delete(oldest);
-        }
-        const copy = new Uint8Array(length);
-        copy.set(payload.subarray(0, length));
-        this.#entries.set(message_id, {
-            payload: copy,
-            length,
-            sent_at: now_ms,
-            retries: 0,
-        });
-        this.#order.push(message_id);
-    }
-
-    /**
-     * Mark a NACK round for `message_id` and return the retained entry
-     * so the caller can re-emit the missing chunks. Returns `null` if
-     * no entry exists, or if the per-message retry budget is now
-     * exhausted (in which case the entry is dropped).
-     *
-     * @param {number} message_id
-     * @returns {{payload: Uint8Array, length: number}|null}
-     */
-    consume_nack(message_id) {
-        assert.isNonNegativeInteger(message_id, 'message_id');
-        const entry = this.#entries.get(message_id);
-        if (entry === undefined) return null;
-        entry.retries++;
-        if (entry.retries > this.max_retries) {
-            this.#delete(message_id);
-            return null;
-        }
-        return entry;
-    }
-
-    /**
-     * Per-tick maintenance: evict any entry older than `max_age_ms`.
-     *
-     * The FIFO is in strict insertion order, so we can stop at the first
-     * still-fresh entry rather than scanning the whole map.
-     *
-     * @param {number} now_ms
-     */
-    service(now_ms) {
-        assert.isNumber(now_ms, 'now_ms');
-        while (this.#order.length > 0) {
-            const id = this.#order[0];
-            const entry = this.#entries.get(id);
-            if (entry === undefined) {
-                this.#order.shift();
-                continue;
-            }
-            if (now_ms - entry.sent_at < this.max_age_ms) break;
-            this.#order.shift();
-            this.#entries.delete(id);
-        }
-    }
-
-    /**
-     * Number of currently-retained messages.
-     * @returns {number}
-     */
-    size() {
-        return this.#entries.size;
-    }
-
-    /**
-     * Whether `message_id` is currently retained.
-     * @param {number} message_id
-     * @returns {boolean}
-     */
-    has(message_id) {
-        return this.#entries.has(message_id);
-    }
-
-    /**
-     * Drop every retained entry. Use on peer disconnect.
-     */
-    clear() {
-        this.#entries.clear();
-        this.#order.length = 0;
-    }
-
-    /** @private */
-    #delete(message_id) {
-        this.#entries.delete(message_id);
-        const idx = this.#order.indexOf(message_id);
-        if (idx >= 0) this.#order.splice(idx, 1);
-    }
-}