@woosh/meep-engine 3.14.2 → 3.14.4

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;
     }
 
     /**

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

@@ -9,20 +9,44 @@
  *      tagged with `(client_frame, sender_id, type_id, payload_bytes)`.
  *   2. Once per server tick, `tick(current_frame)` consumes the pending log:
  *      - Rejects entries older than the action_log's rewindable window.
- *      - Determines the oldest pending frame `replay_start`.
+ *      - Determines `replay_start`: the oldest pending frame carrying an
+ *        action the log does not already hold. The action stream re-sends
+ *        every unacked frame each tick, so most of pending is copies of
+ *        already-applied records; rewinding for those would replay the
+ *        world into the state it was already in.
  *      - Rewinds the server world back to end-of-(replay_start - 1) via the
  *        action_log's prior-state captures (see {@link RewindEngine}).
  *      - Replays forward `[replay_start, current_frame]`. For each frame `f`:
  *        - Read historical actions out of `action_log[f]` BEFORE
  *          `begin_frame(f)` recycles the buffer.
  *        - Append pending entries for `f`.
+ *        - Append anything queued by {@link enqueue_action}.
  *        - Stable-sort the merged list by `sender_id` (so multi-client order
  *          is deterministic across peers — relies on per-record sender_id in
- *          the action log).
- *        - `executor.execute` each in sorted order, then run the user-
- *          supplied local sim via {@link onLocalSim}.
+ *          the action log), and `executor.execute` each in that order.
+ *        - Run the user-supplied local sim via {@link onLocalSim}.
  *      - Clear pending.
  *
+ * A frame's records have one of two provenances, and the replay treats them
+ * differently:
+ *
+ *   - **Input** — actions that arrived from a peer, and actions the server
+ *     authored via {@link enqueue_action}. Each happened once, at a point in
+ *     time nothing can recompute, so a replay reapplies it from the log.
+ *   - **Derived output** — everything {@link onLocalSim} executes. The handler
+ *     runs again on every replay of the frame, against a world that now
+ *     includes whatever late input forced the replay, so the replay recomputes
+ *     it. Reapplying the previous pass's copy as well would apply the effect
+ *     twice — and three times on the next replay, and so on, without bound.
+ *     The executor stamps these {@link SENDER_DERIVED} while the handler runs
+ *     and {@link __read_historical} drops them.
+ *
+ * Derived records are still written, and still replicate: the prior-state
+ * capture is what lets a rewind undo the local sim's effect on replicated
+ * components (so derived output need not be idempotent — only deterministic
+ * in the frame's post-input state), and the action stream carries them to
+ * clients like any other record.
+ *
  * Net effect: a client action tagged at client tick K lands on the server as
  * if applied against end-of-K-1 server state, regardless of arrival timing
  * or order. Both peers compute identical world states for identical inputs.
@@ -109,6 +133,15 @@ export class ServerAuthoritativeServer {
      * @type {number}
      */
     simulation_delay_ticks: number;
+    /**
+     * Peer id of this authoritative server, or `-1` when the session has no
+     * privileged peer. Actions from {@link enqueue_action} are tagged with
+     * it so they pass the owner-authorization gate on any entity (see
+     * {@link make_owner_authorization}), which is the documented convention
+     * for the server's own mutations.
+     * @type {number}
+     */
+    server_peer_id: number;
     /**
      * Upper bound on how far ahead of the server's own simulation a peer
      * may tag an inbound action. `frame_number` is an attacker-controlled
@@ -132,13 +165,35 @@ export class ServerAuthoritativeServer {
      */
     max_pending_total: number;
     /**
-     * Fires once per frame during the replay loop, AFTER all merged
-     * actions for that frame have been applied and BEFORE the action_log
-     * frame is closed. Use this for server-authoritative local sim
-     * (clamps, collision, AI step, etc.). The current world state
-     * reflects all inputs for this frame; the local sim should be
-     * idempotent under repeated application (because it may run many
-     * times under rollback).
+     * Fires once per execution of a frame, AFTER all input for that frame
+     * has been applied and BEFORE the action_log frame is closed. Use it
+     * for server-authoritative local sim: clamps, collision, AI step,
+     * damage resolution, spawning the effects a hit produces.
+     *
+     * **This is a derivation, not an event.** The handler runs again on
+     * every replay of the frame, and must produce the same result for the
+     * same post-input world state — it is a function OF that state, not a
+     * one-shot that happens to be called from it. Concretely:
+     *
+     *   - Decide from world state and the frame number. Both are restored
+     *     before the handler re-runs.
+     *   - Do NOT latch on handler-local flags (`if (already_fired) return`)
+     *     to make something happen once. The replay needs the handler to
+     *     re-emit; a latch makes it emit nothing, and the action is lost
+     *     the first time a rollback crosses its frame. For a genuine
+     *     one-shot — a lobby spawn, an admin command, anything decided
+     *     outside the simulation — use {@link enqueue_action}, which is
+     *     recorded as input and replayed rather than recomputed.
+     *
+     * Actions the handler executes are recorded as derived output: they
+     * replicate to clients and their prior state is captured so a rewind
+     * undoes them, but a replay recomputes them instead of reapplying the
+     * previous pass's copy. So they need not be idempotent — a handler may
+     * subtract hit points — only deterministic in the frame's post-input
+     * state. Components the handler mutates DIRECTLY, without going through
+     * an action, have no prior-state capture and are not undone by a
+     * rewind; those must additionally be idempotent, which is why a clamp
+     * is safe to write that way and `hp -= 10` is not.
      *
      * Args: `(frame_number)`.
      * @type {Signal}
@@ -215,6 +270,37 @@ export class ServerAuthoritativeServer {
      * @param {number} peer_id
      */
     send_time_dilation_feedback(peer_id: number): void;
+    /**
+     * Author a server-side action, to be applied on the next simulated frame.
+     *
+     * This is the supported path for a mutation the simulation cannot
+     * recompute — a spawn triggered by a lobby event, an admin command, a
+     * scripted trigger — as opposed to {@link onLocalSim}, which derives a
+     * frame's output from its state and is re-run on every replay.
+     *
+     * The action is serialized immediately (so the caller may reuse or discard
+     * the instance) and applied exactly once, on the next frame {@link tick}
+     * simulates for the first time, merged into that frame's input and ordered
+     * with it by sender. From then on it is ordinary history: replayed from the
+     * log like any other input, and never re-queued.
+     *
+     * Callable at any time EXCEPT from inside {@link onLocalSim}, which throws:
+     * that handler re-runs on every replay of its frame, so it would queue a
+     * fresh copy each time. (`executor.execute` is the opposite — it requires
+     * an open action_log frame, so it only works from inside the handler.)
+     *
+     * Recorded with {@link server_peer_id} as the sender when the session has
+     * one, so it passes the owner-authorization gate on any entity; with
+     * {@link SENDER_LOCAL} otherwise, which bypasses the gate.
+     *
+     * @param {SimAction} action
+     */
+    enqueue_action(action: SimAction): void;
+    /**
+     * Number of locally-authored actions waiting for the next simulated frame.
+     * @returns {number}
+     */
+    queued_local_action_count(): number;
     /**
      * Drive the rollback flow for one tick.
      *

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

@@ -1 +1 @@
-{"version":3,"file":"ServerAuthoritativeServer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/ServerAuthoritativeServer.js"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH;IA6BI;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uOApBW;QACV,KAAS,yBAAyB;QAClC,eAAmB,8BAA8B;QACjD,qBAAyB,EAAE,UAAU,CAAC;QACtC,cAAkB,EAAE,UAAU,CAAC;QAC/B,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,sBAA0B,CAAC,EAAE,MAAM,CAAC;KACjC,EAyLH;IA3MD;;;;;OAKG;IACH,mBAFU,MAAM,CAEO;IAwCnB,0BAA0B;IAC1B,MADW,WAAW,CASpB;IAEF,qCAAqC;IACrC,8BAAkB;IAClB,gCAAgC;IAChC,4BAAkC;IAclC,mCAAmC;IACnC,iCAAsC;IACtC,wBAAwB;IACxB,sBAAsC;IACtC,gCAAgC;IAChC,mCAAgD;IAChD,0CAA0C;IAC1C,gDAAsD;IAEtD,2BAA2B;IAC3B,eADW,YAAY,CAKrB;IAEF;;;;;;OAMG;IACH,6BAFU,MAAM,CAEqB;IAErC;;;;OAIG;IACH,wBAFU,MAAM,CAEoC;IAEpD;;;;;;;;;OASG;IACH,yBAFU,MAAM,CAEsC;IAEtD;;;;;;;;;OASG;IACH,mBAFU,MAAM,CAE0B;IA4B1C;;;;;;;;;;;OAWG;IACH,YAFU,MAAM,CAEc;IAE9B;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;;;;;;OAWG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;;;;OAOG;IACH,wBAFU,MAAM,CAE0B;IAG9C;;;;;;;OAOG;IACH,sBAHW,MAAM,aACN,MAAM,QAIhB;IAED;;;OAGG;IACH,yBAFW,MAAM,QAIhB;IAED;;;;;;;;OAQG;IACH,yBALW,MAAM,gBACN,MAAM,cACN,MAAM,kBACA,YAAY,KAAK,IAAI,QAIrC;IAED;;;;OAIG;IACH,qBAFW,MAAM,6CAIhB;IAED;;;;;;;;OAQG;IACH,qCAFW,MAAM,QAIhB;IAED;;;;;;;;;;;;OAYG;IACH,oBAFW,MAAM,QA2ChB;IAED;;;;;;;;OAQG;IACH,+BAHW,MAAM,GACJ,MAAM,CAOlB;IA2GD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CA0HJ;4BAvnB2B,kBAAkB;6BADjB,wBAAwB;mBANlC,uCAAuC;6BAH7B,sCAAsC"}
+{"version":3,"file":"ServerAuthoritativeServer.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/orchestrator/ServerAuthoritativeServer.js"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiEG;AACH;IAwCI;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,uOApBW;QACV,KAAS,yBAAyB;QAClC,eAAmB,8BAA8B;QACjD,qBAAyB,EAAE,UAAU,CAAC;QACtC,cAAkB,EAAE,UAAU,CAAC;QAC/B,YAAgB,CAAC,EAAE,MAAM,CAAC;QAC1B,cAAkB,CAAC,EAAE,MAAM,CAAC;QAC5B,mBAAuB,CAAC,EAAE,MAAM,CAAC;QACjC,sBAA0B,CAAC,EAAE,MAAM,CAAC;KACjC,EA4NH;IA9OD;;;;;OAKG;IACH,mBAFU,MAAM,CAEO;IAwCnB,0BAA0B;IAC1B,MADW,WAAW,CASpB;IAEF,qCAAqC;IACrC,8BAAkB;IAClB,gCAAgC;IAChC,4BAAkC;IAclC,mCAAmC;IACnC,iCAAsC;IACtC,wBAAwB;IACxB,sBAAsC;IACtC,gCAAgC;IAChC,mCAAgD;IAChD,0CAA0C;IAC1C,gDAAsD;IAEtD,2BAA2B;IAC3B,eADW,YAAY,CAKrB;IAEF;;;;;;OAMG;IACH,6BAFU,MAAM,CAEqB;IAErC;;;;OAIG;IACH,wBAFU,MAAM,CAEoC;IAEpD;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEoB;IAEpC;;;;;;;;;OASG;IACH,yBAFU,MAAM,CAEsC;IAEtD;;;;;;;;;OASG;IACH,mBAFU,MAAM,CAE0B;IA+B1C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,YAFU,MAAM,CAEc;IAE9B;;;;;;;OAOG;IACH,gBAFU,MAAM,CAEkB;IAElC;;;;;;;;;;;OAWG;IACH,UAFU,MAAM,CAEY;IAE5B;;;;;;;OAOG;IACH,wBAFU,MAAM,CAE0B;IAG9C;;;;;;;OAOG;IACH,sBAHW,MAAM,aACN,MAAM,QAIhB;IAED;;;OAGG;IACH,yBAFW,MAAM,QAIhB;IAED;;;;;;;;OAQG;IACH,yBALW,MAAM,gBACN,MAAM,cACN,MAAM,kBACA,YAAY,KAAK,IAAI,QAIrC;IAED;;;;OAIG;IACH,qBAFW,MAAM,6CAIhB;IAED;;;;;;;;OAQG;IACH,qCAFW,MAAM,QAIhB;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,wCA8BC;IAED;;;OAGG;IACH,6BAFa,MAAM,CAIlB;IAED;;;;;;;;;;;;OAYG;IACH,oBAFW,MAAM,QAiEhB;IAED;;;;;;;;OAQG;IACH,+BAHW,MAAM,GACJ,MAAM,CAOlB;IAuOD;;;;OAIG;IACH,yBAFa,MAAM,CAIlB;;CA0HJ;4BAh5B2B,kBAAkB;6BAFjB,wBAAwB;mBANlC,uCAAuC;6BAH7B,sCAAsC"}