@woosh/meep-engine 3.14.3 → 3.14.5

package/src/engine/network/orchestrator/NetworkPeer.js

@@ -7,7 +7,7 @@ import { Replicator } from "../replication/Replicator.js";
 import { AlwaysRelevantScope } from "../replication/ScopeFilter.js";
 import { ActionLog } from "../sim/ActionLog.js";
 import { ReplicatedComponentRegistry } from "../sim/ReplicatedComponentRegistry.js";
-import { SimActionExecutor } from "../sim/SimActionExecutor.js";
+import { MAX_PEER_ID, SimActionExecutor } from "../sim/SimActionExecutor.js";
 import { SimActionRegistry } from "../sim/SimActionRegistry.js";
 import { snapshotter_emit } from "../sim/Snapshotter.js";
 import { Baseline } from "../state/Baseline.js";
@@ -27,6 +27,19 @@ import { ReliableCommandPipeline } from "../transport/ReliableCommandPipeline.js
 const DISCONNECT_TEXT_ENCODER = new TextEncoder();
 const DISCONNECT_TEXT_DECODER = new TextDecoder();
 
+// ACTION_STREAM slice header, after the packet-type byte: uint32 frame_start,
+// uint32 frame_end, uint8 head. See NetworkPacketType.ACTION_STREAM.
+const ACTION_STREAM_SLICE_HEADER_BYTES = 9;
+
+// Widest slice a header may claim. A slice covers frames from the pack start
+// to the last frame packed, so it never spans more than the sender's action
+// log holds — a ring of tens or hundreds of frames. The receiver raises its
+// apply watermark to a head's frame_end, so a header claiming 2^32 frames
+// would have it skip every frame the sender ever sends after; that is a
+// sender bug or a sender lying about its own stream, and either is dropped as
+// malformed rather than obeyed.
+const MAX_ACTION_STREAM_SLICE_FRAMES = 65536;
+
 /**
  * Wire packet types. The first byte of every NetworkPeer-routed payload picks
  * the dispatch path. New types can be added without breaking the action stream
@@ -36,6 +49,20 @@ const DISCONNECT_TEXT_DECODER = new TextDecoder();
  * @enum {number}
  */
 export const NetworkPacketType = {
+    /**
+     * A slice of the action stream. Wire layout (after this type byte):
+     *
+     *   uint32  frame_start   first frame the slice covers
+     *   uint32  frame_end     last frame the slice covers
+     *   uint8   head          1 if this is the first slice of the sender's tick
+     *   bytes   groups        {@link Replicator} wire format
+     *
+     * A tick may send several slices, and the receiver applies them in frame
+     * order: a slice that is not a head and starts past what the receiver has
+     * applied is held until the slices before it land. A head's start is the
+     * earliest frame the sender will send again, so it is applied at once.
+     * A packet of just the type byte carries nothing and is ignored.
+     */
     ACTION_STREAM: 0,
     RECOVERY_REQUEST: 1,
     STATE_BURST: 2,
@@ -168,14 +195,40 @@ export const ResumeRejectReason = Object.freeze({
     NoSessionToken: 5,
 });
 
+/**
+ * One outbound action-stream send, awaiting confirmation.
+ *
+ * A send occupies one transport seq when it fits the MTU and N consecutive
+ * seqs when it has to be fragmented. All of those seqs map to the SAME record:
+ * the receiver reassembles a fragmented message all-or-nothing, so the frame
+ * range is confirmed only when `unacked` reaches zero without `abandoned`
+ * having been set by a loss along the way.
+ *
+ * A tick may make several sends to one peer, each carrying the next slice of
+ * the owed range (see {@link NetworkPeer#flush_outbound}). They confirm
+ * independently, and the baseline advances only through slices confirmed in
+ * order — a later slice landing says nothing about an earlier one still in
+ * flight. `head` marks the first slice of a tick, whose start is the pack
+ * start itself; see {@link NetworkPeer#__credit_confirmed}.
+ *
+ * @typedef {{frame_start: number, frame_end: number, head: boolean, unacked: number, abandoned: boolean}} PendingAck
+ * @property {number} frame_start first frame in the packed range
+ * @property {number} frame_end   last frame in the packed range
+ * @property {boolean} head       this send began at the pack start, so nothing
+ *   sendable lies before it and its confirmation credits outright
+ * @property {number} unacked     seqs of this send not yet acked or declared lost
+ * @property {boolean} abandoned  at least one seq was declared lost, so the
+ *   message is forfeit and must never advance the baseline
+ */
+
 /**
  * Per-tick orchestrator that wires the action infrastructure to one or more
  * peers over a Transport.
  *
  * Holds a single world (`EntityComponentDataset`) plus the action machinery
  * (executor, replicator, action log). For each connected peer it owns a
- * `Channel` and a `seq → frame_end` map so that ack notifications advance the
- * `Baseline.last_acked(peer_id)` watermark.
+ * `Channel` and a `seq` → {@link PendingAck} map so that ack notifications
+ * advance the `Baseline.last_acked(peer_id)` watermark.
  *
  * Use as both server (many connected peers) and client (one peer = the server).
  * The asymmetry is in *who* connects — the orchestrator itself is symmetric.
@@ -222,6 +275,25 @@ export class NetworkPeer {
      */
     #malformed_packets_dropped = 0;
 
+    /**
+     * Scratch list of the transport seqs one send produced — one entry for a
+     * single-packet send, one per fragment for a fragmented one. Reused across
+     * sends so the common path allocates nothing; only valid until the next
+     * `__send_to_peer` call.
+     * @type {number[]}
+     * @private
+     */
+    #sent_seqs = [];
+
+    /**
+     * Scratch for the slice header of the ACTION_STREAM packet being
+     * dispatched, handed to `Replicator.unpack_from_peer`, which copies what
+     * it keeps. Only valid for the duration of that call.
+     * @type {{frame_start: number, frame_end: number, head: boolean}}
+     * @private
+     */
+    #slice = { frame_start: 0, frame_end: 0, head: false };
+
     /**
      * @param {{
      *   world: EntityComponentDataset,
@@ -233,6 +305,7 @@ export class NetworkPeer {
      *   initial_buffer_size?: number,
      *   mutation_ledger?: MutationLedger|null,
      *   changed_set_capacity?: number,
+     *   max_packets_per_tick?: number,
      * }} options
      */
     constructor({
@@ -245,11 +318,13 @@ export class NetworkPeer {
         initial_buffer_size = 1024,
         mutation_ledger = null,
         changed_set_capacity = 256,
+        max_packets_per_tick = 8,
     }) {
         assert.ok(world && typeof world.createEntity === 'function', 'world must be an EntityComponentDataset');
         assert.ok(binary_registry, 'binary_registry required');
         assert.isFunction(replicated_components.forEach, 'replicated_components must be iterable');
         assert.isFunction(action_classes.forEach, 'action_classes must be iterable');
+        assert.isPositiveInteger(max_packets_per_tick, 'max_packets_per_tick');
 
         /** @type {EntityComponentDataset} */
         this.world = world;
@@ -272,6 +347,33 @@ export class NetworkPeer {
         /** @type {ActionLog} */
         this.action_log = new ActionLog({ frame_capacity, initial_buffer_size });
 
+        /**
+         * Most action-stream packets {@link flush_outbound} may send one peer
+         * in a tick. Each carries the next slice of what the peer is owed and
+         * is confirmed on its own, so this caps how fast a peer that has
+         * fallen behind catches up: a slice is re-sent every tick until its ack
+         * returns, so a peer is confirmed at most this many packets of frames
+         * per round trip, against the one frame per tick the simulation
+         * produces. One packet a tick keeps up only while a round trip's frames
+         * fit one packet; past that the owed range grows until it meets the
+         * ring floor and frames are lost.
+         *
+         * It is also the bandwidth ceiling under catch-up — this many MTUs per
+         * tick per peer — and it has to stay inside the channel's ack window.
+         * A peer's ack header covers its latest 33 seqs, so with a peer that
+         * replies once a tick, `33 / max_packets_per_tick` consecutive lost
+         * replies leave a delivered packet outside the window and it is
+         * declared lost: a wasted re-send rather than a defect, since the
+         * receiver skips frames it has already applied. Eight tolerates three
+         * such losses in a row (one tick in sixteen at 50% loss, one in ten
+         * thousand at 10%), and lets a 60 Hz stream at 100 ms RTT carry a full
+         * packet of actions per frame. Lower it for peers that reply less often
+         * than every tick.
+         *
+         * @type {number}
+         */
+        this.max_packets_per_tick = max_packets_per_tick;
+
         /**
          * Optional per-tick mutation tracker. When a `MutationLedger` is supplied,
          * this peer records each tick's affected network IDs into a fresh
@@ -317,8 +419,8 @@ export class NetworkPeer {
         this.baseline = new Baseline();
 
         /**
-         * peer_id → { channel, transport, seq_to_frame_end, on_payload, on_acked }
-         * @type {Map<number, { channel: Channel, transport: Object, seq_to_frame_end: Map<number, number>, on_payload: Function, on_acked: Function }>}
+         * peer_id → { channel, transport, seq_to_pending, confirmed, on_payload, on_acked }
+         * @type {Map<number, { channel: Channel, transport: Object, seq_to_pending: Map<number, PendingAck>, confirmed: Int32Array, on_payload: Function, on_acked: Function }>}
          * @private
          */
         this.#peers = new Map();
@@ -463,13 +565,38 @@ export class NetworkPeer {
      */
     connect_peer(peer_id, transport) {
         assert.isNonNegativeInteger(peer_id, 'peer_id');
+        // The action log records a peer's id as the provenance of its actions,
+        // in one byte whose top two values are reserved for locally-authored
+        // and sim-derived records. A peer holding one of those would have its
+        // input read back as the local sim's own output and dropped by the
+        // first rollback replay of its frame, so refuse the connection rather
+        // than lose its input later. Real runtime check — asserts strip in prod.
+        if (peer_id > MAX_PEER_ID) {
+            throw new Error(`NetworkPeer.connect_peer: peer id ${peer_id} is out of range; must be in [0, ${MAX_PEER_ID}] — 254 and 255 are reserved provenance markers in the action log`);
+        }
         if (this.#peers.has(peer_id)) {
             throw new Error(`NetworkPeer.connect_peer: peer ${peer_id} already connected`);
         }
 
         const channel = new Channel({ transport });
-        const seq_to_frame_end = new Map();
-        const fragment_assembler = new FragmentAssembler();
+        const seq_to_pending = new Map();
+        // Frames this peer has confirmed that the baseline has not reached yet,
+        // because a slice before them is still in flight. A ring indexed by
+        // frame modulo capacity holding the frame number — see
+        // __credit_confirmed.
+        const confirmed = new Int32Array(this.action_log.frame_capacity).fill(-1);
+        // The reassembly window is sized from the burst. A frame too big for
+        // one packet goes out as a fragmented slice, and a tick may send
+        // `max_packets_per_tick` of them; jitter that holds a message's later
+        // fragments behind the next ticks' first fragments leaves that many
+        // partial messages per tick in flight at once. The assembler evicts
+        // the oldest partial when its window is full, both fragments of the
+        // evicted message are still acked, and the sender credits the slice —
+        // a silent loss. Four ticks of burst keeps the window ahead of any
+        // jitter the NACK timer would not already have caught.
+        const fragment_assembler = new FragmentAssembler({
+            max_pending_messages: Math.max(8, 4 * this.max_packets_per_tick),
+        });
         const fragment_retention = new FragmentRetention();
         const reliable_pipeline = new ReliableCommandPipeline({
             channel,
@@ -513,11 +640,25 @@ export class NetworkPeer {
             const packet_type = this.#recv_buffer.readUint8();
 
             switch (packet_type) {
-                case NetworkPacketType.ACTION_STREAM:
-                    // The Replicator opens a frame on the action log per packet
-                    // (one per sender frame).
-                    this.replicator.unpack_from_peer(peer_id, this.#recv_buffer, length);
+                case NetworkPacketType.ACTION_STREAM: {
+                    // Just the type byte: an empty stream, nothing to apply.
+                    if (length === 1) break;
+                    if (length < 1 + ACTION_STREAM_SLICE_HEADER_BYTES) {
+                        throw new MalformedPacketError(`NetworkPeer.dispatch: ACTION_STREAM truncated before its slice header`);
+                    }
+                    const slice = this.#slice;
+                    slice.frame_start = this.#recv_buffer.readUint32();
+                    slice.frame_end = this.#recv_buffer.readUint32();
+                    slice.head = this.#recv_buffer.readUint8() !== 0;
+                    if (slice.frame_end < slice.frame_start
+                        || slice.frame_end - slice.frame_start >= MAX_ACTION_STREAM_SLICE_FRAMES) {
+                        throw new MalformedPacketError(`NetworkPeer.dispatch: ACTION_STREAM slice [${slice.frame_start}, ${slice.frame_end}] is inverted or wider than any action log`);
+                    }
+                    // The Replicator opens a frame on the action log per group
+                    // (one per sender frame), applying slices in frame order.
+                    this.replicator.unpack_from_peer(peer_id, this.#recv_buffer, length, slice);
                     break;
+                }
                 case NetworkPacketType.RECOVERY_REQUEST: {
                     const start_tick = this.#recv_buffer.readUintVar();
                     const end_tick = this.#recv_buffer.readUintVar();
@@ -639,22 +780,43 @@ export class NetworkPeer {
             }
         };
 
-        // Ack: advance Baseline to the highest acked frame_end for this peer.
+        // Ack: a send is confirmed once every seq it went out under has been
+        // acked. For a single-packet send that is the one seq. For a
+        // fragmented send it is all N fragments, because the receiver applies
+        // nothing until it has reassembled the whole message; advancing on the
+        // first fragment's ack would retire a frame range the receiver never
+        // saw, from the only mechanism that could still re-send it. What a
+        // confirmed send credits to the baseline is decided in order, by
+        // __credit_confirmed.
         const on_acked = (seq) => {
-            const frame_end = seq_to_frame_end.get(seq);
-            if (frame_end !== undefined) {
-                this.baseline.set_acked(peer_id, frame_end);
-                seq_to_frame_end.delete(seq);
+            const pending = seq_to_pending.get(seq);
+            if (pending === undefined) return;
+            seq_to_pending.delete(seq);
+            pending.unacked--;
+            if (pending.unacked === 0 && !pending.abandoned) {
+                this.#credit_confirmed(peer_id, confirmed, pending);
             }
         };
 
         // Loss: a packet that aged out of the ack window without being acked
-        // leaves a dead seq→frame_end entry. The baseline must NOT advance (the
-        // frame was never confirmed; back-fill resends it under a fresh seq), but
-        // the stale mapping should be reclaimed — otherwise lost-packet entries
-        // accumulate across the session until the seq value is reused on wrap.
+        // leaves a dead seq→record entry. The baseline must NOT advance (the
+        // frame range was never confirmed; the back-fill re-sends it under a
+        // fresh seq), and the record is marked abandoned so that siblings
+        // acking afterwards cannot complete it — one lost fragment forfeits the
+        // whole message. The mapping is reclaimed either way, otherwise
+        // lost-packet entries accumulate across the session until the seq value
+        // is reused on wrap.
+        //
+        // Every outstanding seq is resolved by Channel as exactly one of acked
+        // or lost — via the ack bitfield, the 33-seq window age-out, or the
+        // max_in_flight eviction — so no record can be stranded by a seq that
+        // never reports.
         const on_lost = (seq) => {
-            seq_to_frame_end.delete(seq);
+            const pending = seq_to_pending.get(seq);
+            if (pending === undefined) return;
+            seq_to_pending.delete(seq);
+            pending.unacked--;
+            pending.abandoned = true;
         };
 
         // Untrusted-input boundary. A structurally-malformed or truncated
@@ -688,7 +850,7 @@ export class NetworkPeer {
         channel.onPacketLost.add(on_lost);
 
         this.#peers.set(peer_id, {
-            channel, transport, seq_to_frame_end,
+            channel, transport, seq_to_pending, confirmed,
             on_payload: payload_handler, on_acked, on_lost, on_nack,
             fragment_assembler, fragment_retention,
             reliable_pipeline,
@@ -764,6 +926,21 @@ export class NetworkPeer {
         return conn === undefined ? 0 : conn.inbound_count;
     }
 
+    /**
+     * Number of outbound action-stream seqs for `peer_id` still awaiting an
+     * ack-or-lost verdict. Returns 0 for an unknown peer.
+     *
+     * Diagnostics: this is bounded by the channel's in-flight window and must
+     * fall back to 0 once a stream of acks has resolved everything sent. A
+     * value that only grows is a leak in the ack accounting.
+     * @param {number} peer_id
+     * @returns {number}
+     */
+    pending_ack_count(peer_id) {
+        const conn = this.#peers.get(peer_id);
+        return conn === undefined ? 0 : conn.seq_to_pending.size;
+    }
+
     /**
      * Direct access to a peer's channel (for sending acks-only packets, raw payloads, etc.).
      * @param {number} peer_id
@@ -797,8 +974,8 @@ export class NetworkPeer {
     /**
      * Close the current tick and send pending action records to every peer.
      * For each peer, packs frames `[Baseline.last_acked(peer) + 1, current_frame]`
-     * and sends via the channel; records the seq→frame_end mapping so the next
-     * ack from that peer advances the baseline.
+     * and sends via the channel; records the seqs the send went out under so
+     * that acks for all of them advance the baseline.
      *
      * If a {@link MutationLedger} was supplied at construction, this tick's
      * accumulated changed-entity set is also compacted into the ledger.
@@ -835,8 +1012,10 @@ export class NetworkPeer {
      * by the caller. Records the tick's accumulated mutations into the
      * MutationLedger (if configured), then packs frames
      * `[last_acked+1, current_frame]` for each peer via
-     * `Replicator.pack_for_peer`. Empty packs (no in-scope actions) are
-     * not sent. Clears the per-tick changed-entity set after recording.
+     * `Replicator.pack_for_peer` into up to {@link max_packets_per_tick}
+     * channel packets, each the next slice of that range. Empty packs (no
+     * in-scope actions) are not sent. Clears the per-tick changed-entity set
+     * after recording.
      *
      * @param {number} current_frame
      */
@@ -853,15 +1032,14 @@ export class NetworkPeer {
 
         for (const [peer_id, conn] of this.#peers) {
             const last_acked = this.baseline.last_acked(peer_id);
-            // Pack-range start.
+            // Pack-range start: whichever is newer of "catch up since you
+            // last confirmed receipt" and "the oldest frame the log still
+            // holds."
             //
-            // For peers with at least one acked frame, this is just
-            // last_acked+1 — the standard "catch up since you last
-            // confirmed receipt."
-            //
-            // For freshly-connected peers (no ack yet), we cover the
-            // action_log's full ring: max(0, current_frame -
-            // frame_capacity + 1). Two competing constraints:
+            // last_acked+1 is the ordinary catch-up point. A freshly-
+            // connected peer has no ack, so its -1+1 falls through to the
+            // ring floor and it covers the log's full content. Two competing
+            // constraints shaped that floor:
             //
             //   - Don't pack `current_frame` only: under any non-zero
             //     latency, A's actions tagged at frame X land on the
@@ -877,28 +1055,120 @@ export class NetworkPeer {
             //
             // `current_frame - frame_capacity + 1` is the oldest frame
             // the ring could still hold, so we naturally cap at the
-            // ring's actual content. Actions referencing entities the
-            // peer's slot_table doesn't yet know about silently no-op
-            // (Replicator translates via network_for → -1; SimAction
-            // apply hits the `if (local < 0) return` guard). For first-
-            // connect scenarios the app is still expected to send a
-            // state-burst seed; this just makes the action-stream
-            // bootstrap work in addition to that.
-            const start = last_acked < 0
-                ? Math.max(0, current_frame - this.action_log.frame_capacity + 1)
-                : last_acked + 1;
+            // ring's actual content.
+            //
+            // The floor binds acked peers too, not just fresh ones: a peer
+            // that acked once and then stopped leaves last_acked pinned while
+            // current_frame runs on, and without the floor the loop walks
+            // every frame since that ack to emit at most a ring's worth —
+            // work that grows without bound the longer the peer stays quiet.
+            // Skipping those frames costs nothing, because they are already
+            // gone from the log and can never be sent whatever the ack says;
+            // `pack_for_peer` credits them as covered the moment it reaches
+            // them anyway, so the frame this pack confirms is the same
+            // either way.
+            //
+            // Actions referencing entities the peer's slot_table doesn't yet
+            // know about silently no-op (Replicator translates via
+            // network_for → -1; SimAction apply hits the `if (local < 0)
+            // return` guard). For first-connect scenarios the app is still
+            // expected to send a state-burst seed; this just makes the
+            // action-stream bootstrap work in addition to that.
+            const start = Math.max(
+                last_acked + 1,
+                current_frame - this.action_log.frame_capacity + 1,
+                0,
+            );
             if (start > current_frame) continue;
 
-            this.#send_buffer.position = 0;
-            // Packet-type prefix.
-            this.#send_buffer.writeUint8(NetworkPacketType.ACTION_STREAM);
-            this.replicator.pack_for_peer(peer_id, start, current_frame, this.#send_buffer);
-            const length = this.#send_buffer.position;
-            // Just the prefix → no in-scope actions to send.
-            if (length === 1) continue;
-
-            const seq = this.#send_to_peer(conn, this.#send_buffer.raw_bytes, length);
-            conn.seq_to_frame_end.set(seq, current_frame);
+            // Up to `max_packets_per_tick` sends, each bounded to one channel
+            // packet and each taking the next slice of the owed range.
+            //
+            // Bounding a send to one packet is load-bearing. A fragmented
+            // action stream is confirmed only if EVERY fragment survives, so a
+            // send that grows with the owed range is self-defeating under
+            // loss: one lost fragment pins the baseline, which widens the next
+            // pack, which raises the fragment count N, which drops
+            // P(all arrive) = (1-p)^N geometrically — the range then widens
+            // faster than it drains and delivery collapses. Split into whole
+            // packets instead, each slice is confirmed on its own and a loss
+            // forfeits one slice, not the tick.
+            //
+            // Sending more than one is what keeps the stream up with the
+            // simulation. A slice is re-sent every tick until its ack returns,
+            // so the baseline moves by at most a tick's worth of slices per
+            // round trip, while the sim produces a frame per tick. One packet
+            // a tick therefore keeps up only while a round trip's frames fit
+            // one packet; past that the owed range grows until it meets the
+            // ring floor, a ring of frames is lost crossing it, and everything
+            // after arrives a ring late — on a link that loses nothing. The
+            // pack is oldest-owed-first, which is what the range order already
+            // gives.
+            //
+            // The budget is what is left of one payload after the prefix and
+            // the slice header, read from the buffer rather than written as a
+            // constant: `pack_for_peer` measures its budget from the current
+            // position, so a hard-coded allowance would have to be edited in
+            // step with every byte added here, and getting that wrong puts
+            // each full pack one byte over the limit and quietly fragments it
+            // again.
+            let from = start;
+            for (let n = 0; n < this.max_packets_per_tick && from <= current_frame; n++) {
+                this.#send_buffer.position = 0;
+                // Packet-type prefix, then the slice header: the range this
+                // packet covers and whether it is the tick's first, which is
+                // what lets the receiver apply slices in frame order (see
+                // Replicator.unpack_from_peer). frame_end is back-patched once
+                // the pack has decided how far it got.
+                this.#send_buffer.writeUint8(NetworkPacketType.ACTION_STREAM);
+                this.#send_buffer.writeUint32(from);
+                const frame_end_position = this.#send_buffer.position;
+                this.#send_buffer.writeUint32(0);
+                this.#send_buffer.writeUint8(n === 0 ? 1 : 0);
+                const packed_through = this.replicator.pack_for_peer(
+                    peer_id, from, current_frame, this.#send_buffer,
+                    MAX_CHANNEL_PAYLOAD_BYTES - this.#send_buffer.position,
+                );
+                const length = this.#send_buffer.position;
+                // Just the prefix and header → nothing in scope left to send
+                // this peer.
+                if (length === 1 + ACTION_STREAM_SLICE_HEADER_BYTES) break;
+                this.#send_buffer.position = frame_end_position;
+                this.#send_buffer.writeUint32(packed_through);
+                this.#send_buffer.position = length;
+
+                this.#send_to_peer(conn, this.#send_buffer.raw_bytes, length, this.#sent_seqs);
+
+                // One record shared by every seq the send produced. Frames
+                // [from, packed_through] are confirmed only when all of those
+                // seqs ack; a loss on any of them abandons the record and
+                // leaves the range owed, so a later tick's pack picks it up
+                // again.
+                //
+                // frame_end is what the pack actually held, NOT current_frame:
+                // the budget may have stopped it short, and crediting frames
+                // that were left out of the packet would retire them from the
+                // back-fill unsent — the same defect as crediting a whole
+                // message to its first fragment, one layer up.
+                //
+                // Only the first slice starts at the pack start. The rest start
+                // where the previous slice stopped, and their confirmation is
+                // held until everything before them is confirmed too — see
+                // __credit_confirmed.
+                const seq_count = this.#sent_seqs.length;
+                const pending = {
+                    frame_start: from,
+                    frame_end: packed_through,
+                    head: n === 0,
+                    unacked: seq_count,
+                    abandoned: false,
+                };
+                for (let i = 0; i < seq_count; i++) {
+                    conn.seq_to_pending.set(this.#sent_seqs[i], pending);
+                }
+
+                from = packed_through + 1;
+            }
         }
 
         // Reset the per-tick changed-entity set so the next tick starts clean.
@@ -906,28 +1176,84 @@ export class NetworkPeer {
         if (this.#changed_entities !== null) this.#changed_entities.clear();
     }
 
+    /**
+     * A send has been confirmed in full — every seq it went out under acked,
+     * none lost — so the receiver has applied every frame it carried. Record
+     * those frames, then advance the peer's baseline as far as the frames
+     * confirmed so far run contiguously.
+     *
+     * The order matters because a tick may send several slices and they
+     * confirm independently. A later slice landing while an earlier one is
+     * still in flight must not credit the earlier one's frames: they are
+     * still owed, and crediting them would retire them from the back-fill
+     * unsent. So a slice is credited only once the baseline has reached the
+     * frame before it. The exception is the head of a tick's burst. Its start
+     * IS the pack start — `last_acked + 1` or the ring floor, whichever is
+     * newer — so nothing sendable lies before it and its confirmation credits
+     * outright. That is also how the baseline gets past frames the ring has
+     * already retired, which no ack could ever confirm.
+     *
+     * `confirmed` is a ring indexed by frame modulo capacity that stores the
+     * frame number, so a slot whose frame has since been overwritten reads as
+     * unconfirmed rather than as its successor (the {@link FrameBufferRing}
+     * trick). A mark can only be overwritten by a frame a full ring later,
+     * and a frame that far behind is below the ring floor — no longer owed,
+     * and no longer needed to advance the baseline, which a head crosses it
+     * with.
+     *
+     * @param {number} peer_id
+     * @param {Int32Array} confirmed the peer's confirmed-frame ring
+     * @param {PendingAck} pending the record that just drained
+     * @private
+     */
+    #credit_confirmed(peer_id, confirmed, pending) {
+        const capacity = confirmed.length;
+        for (let f = pending.frame_start; f <= pending.frame_end; f++) {
+            confirmed[f % capacity] = f;
+        }
+
+        const before = this.baseline.last_acked(peer_id);
+        let last_acked = before;
+        if (pending.head && pending.frame_end > last_acked) {
+            last_acked = pending.frame_end;
+        }
+        while (confirmed[(last_acked + 1) % capacity] === last_acked + 1) {
+            last_acked++;
+        }
+        if (last_acked > before) {
+            this.baseline.set_acked(peer_id, last_acked);
+        }
+    }
+
     /**
      * Send a logical payload to a connected peer, fragmenting transparently
      * if it exceeds the channel's single-packet capacity.
      *
-     * Returns the seq of the FIRST transport packet emitted. For non-
-     * fragmented sends that's the only packet; for fragmented sends, that
-     * seq is what callers should record in `seq_to_frame_end` — when it
-     * acks, the first fragment arrived, which is a sufficient signal that
-     * the message is in flight. Fragments either all arrive (and the
-     * receiver reassembles) or the message is lost; the action-stream's
-     * back-fill mechanism naturally recovers from the latter on subsequent
-     * sends.
+     * Fragments either all arrive (and the receiver reassembles) or the
+     * message is lost — there is no partial delivery, and the receiver never
+     * applies a message it could not reassemble.
+     *
+     * A caller that ties delivery state to the ack must therefore wait on
+     * EVERY seq the send produced, not just the first. The action stream's
+     * back-fill does recover a lost message, but only for as long as the
+     * frames stay owed: crediting the range to the first fragment's ack
+     * retires it from the back-fill, and a message whose later fragments were
+     * dropped is then never re-sent and never applied. Pass `seqs_out` to
+     * collect the seqs; {@link NetworkPeer#flush_outbound} does exactly that.
      *
      * @param {object} conn  entry from __peers
      * @param {Uint8Array} payload  starts with the packet-type byte
      * @param {number} length
-     * @returns {number} seq of the first packet sent
+     * @param {number[]} [seqs_out]  when given, cleared and then filled with the
+     *   seq of every transport packet emitted, in send order
      * @private
      */
-    #send_to_peer(conn, payload, length) {
+    #send_to_peer(conn, payload, length, seqs_out = null) {
+        if (seqs_out !== null) seqs_out.length = 0;
         if (length <= MAX_CHANNEL_PAYLOAD_BYTES) {
-            return conn.channel.send(payload, length);
+            const seq = conn.channel.send(payload, length);
+            if (seqs_out !== null) seqs_out.push(seq);
+            return;
         }
         const message_id = this.#next_fragment_message_id;
         this.#next_fragment_message_id = seq16_advance(this.#next_fragment_message_id);
@@ -935,16 +1261,14 @@ export class NetworkPeer {
         // Copy happens inside retain(); `payload` is the orchestrator's
         // shared send buffer and will be overwritten by the next call.
         conn.fragment_retention.retain(message_id, payload, length, performance.now());
-        let first_seq = -1;
         send_fragmented(
             payload, length, message_id,
             NetworkPacketType.FRAGMENT, this.#fragment_scratch,
             (chunk_bytes, chunk_length) => {
                 const seq = conn.channel.send(chunk_bytes, chunk_length);
-                if (first_seq < 0) first_seq = seq;
+                if (seqs_out !== null) seqs_out.push(seq);
             },
         );
-        return first_seq;
     }
 
     /**