@woosh/meep-engine 3.14.3 → 3.14.4

package/src/engine/network/NetworkSession.d.ts

@@ -367,10 +367,30 @@ export class NetworkSession {
      */
     private normalize_if_dirty;
     /**
-     * Dispatch one user-defined action. Equivalent to
-     * `peer.executor.execute(action, this.local_peer_id)` but exposed
-     * at the session level so callers don't need a reference to the
-     * executor or to know the local peer id.
+     * Dispatch one user-defined action, without needing a reference to the
+     * executor or knowledge of the local peer id.
+     *
+     * Called with a frame open — from an `onLocalSim` handler on a host, or an
+     * `onPredict` handler on a client — the action executes immediately, into
+     * that frame. Its provenance follows its context: on a host, actions a
+     * local-sim handler executes are the frame's DERIVED output, recomputed on
+     * every replay of the frame rather than replayed from the log. That is what
+     * a handler that sends every tick wants, and it is why such a handler does
+     * not accumulate copies under rollback.
+     *
+     * Called with NO frame open — between ticks, from a lobby event, a timer, a
+     * console command — a host queues the action via
+     * {@link ServerAuthoritativeServer#enqueue_action}: it applies once, on the
+     * next frame the server simulates, and is recorded as INPUT, so replays
+     * take it from the log. This is the path for a one-shot. Do NOT reach for a
+     * latched local-sim handler (`if (already_sent) return`) instead: the
+     * handler's output is derived, so the replay expects it to be re-emitted,
+     * and a latch that stops it re-emitting loses the action the first time a
+     * rollback crosses its frame.
+     *
+     * (A client outside a prediction frame has nowhere to put the action and
+     * still throws — client actions are re-derived from the InputRing during
+     * reconciliation, so they belong in an `onPredict` handler.)
      *
      * @param {SimAction} action_instance
      */

package/src/engine/network/NetworkSession.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkSession.d.ts","sourceRoot":"","sources":["../../../../src/engine/network/NetworkSession.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"NetworkSession.d.ts","sourceRoot":"","sources":["../../../../src/engine/network/NetworkSession.js"],"names":[],"mappings":"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"}

package/src/engine/network/NetworkSession.js

@@ -1151,10 +1151,30 @@ export class NetworkSession {
     }
 
     /**
-     * Dispatch one user-defined action. Equivalent to
-     * `peer.executor.execute(action, this.local_peer_id)` but exposed
-     * at the session level so callers don't need a reference to the
-     * executor or to know the local peer id.
+     * Dispatch one user-defined action, without needing a reference to the
+     * executor or knowledge of the local peer id.
+     *
+     * Called with a frame open — from an `onLocalSim` handler on a host, or an
+     * `onPredict` handler on a client — the action executes immediately, into
+     * that frame. Its provenance follows its context: on a host, actions a
+     * local-sim handler executes are the frame's DERIVED output, recomputed on
+     * every replay of the frame rather than replayed from the log. That is what
+     * a handler that sends every tick wants, and it is why such a handler does
+     * not accumulate copies under rollback.
+     *
+     * Called with NO frame open — between ticks, from a lobby event, a timer, a
+     * console command — a host queues the action via
+     * {@link ServerAuthoritativeServer#enqueue_action}: it applies once, on the
+     * next frame the server simulates, and is recorded as INPUT, so replays
+     * take it from the log. This is the path for a one-shot. Do NOT reach for a
+     * latched local-sim handler (`if (already_sent) return`) instead: the
+     * handler's output is derived, so the replay expects it to be re-emitted,
+     * and a latch that stops it re-emitting loses the action the first time a
+     * rollback crosses its frame.
+     *
+     * (A client outside a prediction frame has nowhere to put the action and
+     * still throws — client actions are re-derived from the InputRing during
+     * reconciliation, so they belong in an `onPredict` handler.)
      *
      * @param {SimAction} action_instance
      */
@@ -1163,6 +1183,10 @@ export class NetworkSession {
         if (!action_instance || action_instance.isSimAction !== true) {
             throw new Error("NetworkSession.send: argument must be a SimAction instance");
         }
+        if (this.#server !== null && !this.#peer.action_log.has_open_frame()) {
+            this.#server.enqueue_action(action_instance);
+            return;
+        }
         this.#peer.executor.execute(action_instance, this.local_peer_id);
     }
 

package/src/engine/network/orchestrator/NetworkPeer.d.ts

@@ -50,14 +50,29 @@ export const ResumeRejectReason: Readonly<{
      */
     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.
+ *
+ * @typedef {{frame_end: number, unacked: number, abandoned: boolean}} PendingAck
+ * @property {number} frame_end  last frame in the packed range `[start, frame_end]`
+ * @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.
@@ -262,6 +277,17 @@ export class NetworkPeer {
      * @returns {number}
      */
     inbound_count(peer_id: number): number;
+    /**
+     * 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: number): number;
     /**
      * Direct access to a peer's channel (for sending acks-only packets, raw payloads, etc.).
      * @param {number} peer_id
@@ -280,8 +306,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.
@@ -299,8 +325,9 @@ 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`, bounded to one channel packet. Empty packs
+     * (no in-scope actions) are not sent. Clears the per-tick changed-entity
+     * set after recording.
      *
      * @param {number} current_frame
      */
@@ -421,6 +448,20 @@ export class NetworkPeer {
     send_reliable_command(peer_id: number, payload: Uint8Array, length: number): number;
     #private;
 }
+/**
+ * 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.
+ */
+export type PendingAck = {
+    frame_end: number;
+    unacked: number;
+    abandoned: boolean;
+};
 import { ReplicatedComponentRegistry } from "../sim/ReplicatedComponentRegistry.js";
 import { SimActionRegistry } from "../sim/SimActionRegistry.js";
 import { ReplicationSlotTable } from "../state/ReplicationSlotTable.js";

package/src/engine/network/orchestrator/NetworkPeer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NetworkPeer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/NetworkPeer.js"],"names":[],"mappings":"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"}
+{"version":3,"file":"NetworkPeer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/NetworkPeer.js"],"names":[],"mappings":"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"}

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";
@@ -168,14 +168,30 @@ 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.
+ *
+ * @typedef {{frame_end: number, unacked: number, abandoned: boolean}} PendingAck
+ * @property {number} frame_end  last frame in the packed range `[start, frame_end]`
+ * @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 +238,16 @@ 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 = [];
+
     /**
      * @param {{
      *   world: EntityComponentDataset,
@@ -317,8 +343,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, on_payload, on_acked }
+         * @type {Map<number, { channel: Channel, transport: Object, seq_to_pending: Map<number, PendingAck>, on_payload: Function, on_acked: Function }>}
          * @private
          */
         this.#peers = new Map();
@@ -463,12 +489,21 @@ 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 seq_to_pending = new Map();
         const fragment_assembler = new FragmentAssembler();
         const fragment_retention = new FragmentRetention();
         const reliable_pipeline = new ReliableCommandPipeline({
@@ -639,22 +674,42 @@ export class NetworkPeer {
             }
         };
 
-        // Ack: advance Baseline to the highest acked frame_end for this peer.
+        // Ack: advance Baseline to the record's frame_end — but only once every
+        // seq that send 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.
         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.baseline.set_acked(peer_id, pending.frame_end);
             }
         };
 
         // 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 +743,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,
             on_payload: payload_handler, on_acked, on_lost, on_nack,
             fragment_assembler, fragment_retention,
             reliable_pipeline,
@@ -764,6 +819,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 +867,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 +905,9 @@ 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`, bounded to one channel packet. Empty packs
+     * (no in-scope actions) are not sent. Clears the per-tick changed-entity
+     * set after recording.
      *
      * @param {number} current_frame
      */
@@ -853,15 +924,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 +947,81 @@ 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);
+            // Bound the pack to a single channel packet.
+            //
+            // A fragmented action stream is confirmed only if EVERY fragment
+            // survives, so letting the pack grow 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.
+            //
+            // Bounded, the back-fill degrades into "catch up by a packet each
+            // tick": every send occupies one seq, so any packet that lands
+            // advances the baseline, and a peer behind by more than one packet
+            // converges instead of spiralling. 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
+            // above, 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.
+            const packed_through = this.replicator.pack_for_peer(
+                peer_id, start, current_frame, this.#send_buffer,
+                MAX_CHANNEL_PAYLOAD_BYTES - this.#send_buffer.position,
+            );
             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);
+            this.#send_to_peer(conn, this.#send_buffer.raw_bytes, length, this.#sent_seqs);
+
+            // One record shared by every seq the send produced. Frames
+            // [start, 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 the next 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.
+            const seq_count = this.#sent_seqs.length;
+            const pending = { frame_end: packed_through, unacked: seq_count, abandoned: false };
+            for (let i = 0; i < seq_count; i++) {
+                conn.seq_to_pending.set(this.#sent_seqs[i], pending);
+            }
         }
 
         // Reset the per-tick changed-entity set so the next tick starts clean.
@@ -910,24 +1033,31 @@ export class NetworkPeer {
      * 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 +1065,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;
     }
 
     /**