@woosh/meep-engine 3.46.0 → 3.49.0

package/src/engine/network/replication/Replicator.d.ts

@@ -21,10 +21,19 @@
  *     varint:  frame_number
  *     varint:  action_count
  *     loop action_count times:
+ *       varint:  ordinal            (the record's index in the sender's log frame)
  *       uint8:   action_type_id
  *       uint32:  action_payload_len
  *       bytes:   action_payload
  * ```
+ * A record's identity on the wire is `(sender, frame_number, ordinal)`: the frame its sender tagged
+ * it for and its place among every record of that frame in the sender's log, filtered or not. The
+ * stream re-sends each unconfirmed frame every tick, and that is how a receiver tells the copies
+ * from new records — never by the payload, since two inputs alike in every byte (a held key, frame
+ * after frame) are two inputs. The ordinal is stable across re-sends because a closed frame's records
+ * are only appended to (`ActionLog.resume_frame`) or rebuilt record for record by a deterministic
+ * replay, and it survives a receiver moving the record to another frame (a late-applying host).
+ *
  * {@link NetworkPeer} prefixes each packet of this with a slice header — the
  * frame range the packet covers and whether it is the first of the sender's
  * tick — which it parses itself and hands to {@link unpack_from_peer} as
@@ -99,20 +108,22 @@ export class Replicator {
      * does NOT touch the action log or executor — it parses the packet
      * and calls this function once per action with:
      *
-     *   `(peer_id, frame_number, action_type_id, in_buffer, payload_offset, payload_len)`
+     *   `(peer_id, frame_number, action_type_id, in_buffer, payload_offset, payload_len, ordinal)`
      *
      * The buffer is shared scratch; consumers must copy the payload bytes
      * if they need them to outlive the call. The orchestrator is then
      * responsible for executing the buffered actions in whatever order
      * the netcode model requires (e.g. rewind to oldest frame, stable-
-     * sort by sender, replay forward).
+     * sort by sender, replay forward) — and for recognising the copies the
+     * stream re-sends, by `(peer_id, frame_number, ordinal)`; this path keeps
+     * no watermark of its own.
      *
      * Leave null for "execute on arrival" semantics (the default and
      * what the loopback/single-orchestrator tests rely on).
      *
-     * @type {((peer_id: number, frame_number: number, action_type_id: number, in_buffer: BinaryBuffer, payload_offset: number, payload_len: number) => void) | null}
+     * @type {((peer_id: number, frame_number: number, action_type_id: number, in_buffer: BinaryBuffer, payload_offset: number, payload_len: number, ordinal: number) => void) | null}
      */
-    on_pending_action: ((peer_id: number, frame_number: number, action_type_id: number, in_buffer: BinaryBuffer, payload_offset: number, payload_len: number) => void) | null;
+    on_pending_action: ((peer_id: number, frame_number: number, action_type_id: number, in_buffer: BinaryBuffer, payload_offset: number, payload_len: number, ordinal: number) => void) | null;
     /**
      * @type {ActionLog}
      */

package/src/engine/network/replication/Replicator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IAiLI;;;;;;;;OAQG;IACH,iFARW;QACV,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,QAAY,oBAAoB;QAChC,UAAc,uBAAuB;QACrC,YAAgB,EAAE;YAAE,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CAAC;KACpF,EA6BH;IA5ID;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,wBAHW,MAAM,GACJ;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC,CAc1F;IA2BD;;;;;;;;;;;;;OAaG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;OAiBG;IACH,mBAFU,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAEvI;IAmBrB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH,cAFU;QAAE,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAE9C;IAGpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAVW,MAAM,eACN,MAAM,aACN,MAAM,cACN,YAAY,cACZ,MAAM,GACJ,MAAM,CAiFlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,0BALW,MAAM,aACN,YAAY,iBACZ,MAAM,UACN;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC,GAAC,IAAI,QAoEtE;IAmRD;;;;;;;OAOG;IACH,qBAFW,MAAM,QAKhB;;CA8CJ;mBAvxBkB,uCAAuC;6BAD7B,sCAAsC"}
+{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAsBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH;IAmLI;;;;;;;;OAQG;IACH,iFARW;QACV,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,QAAY,oBAAoB;QAChC,UAAc,uBAAuB;QACrC,YAAgB,EAAE;YAAE,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;SAAE,CAAC;KACpF,EA6BH;IA9ID;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,wBAHW,MAAM,GACJ;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAC,CAc1F;IA2BD;;;;;;;;;;;;;OAaG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,mBAFU,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC,GAAG,IAAI,CAExJ;IAmBrB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH,cAFU;QAAE,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAE9C;IAGpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAVW,MAAM,eACN,MAAM,aACN,MAAM,cACN,YAAY,cACZ,MAAM,GACJ,MAAM,CA0FlB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,0BALW,MAAM,aACN,YAAY,iBACZ,MAAM,UACN;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAC,GAAC,IAAI,QA2EtE;IA+RD;;;;;;;OAOG;IACH,qBAFW,MAAM,QAKhB;;CA8CJ;mBA/zBkB,uCAAuC;6BAD7B,sCAAsC"}

package/src/engine/network/replication/Replicator.js

@@ -3,6 +3,7 @@ import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import Signal from "../../../core/events/signal/Signal.js";
 import { MalformedPacketError } from "../core/MalformedPacketError.js";
 import { ActionRecordCursor } from "../sim/ActionRecordCursor.js";
+import { SENDER_CORRECTED } from "../sim/SimActionExecutor.js";
 
 // Bytes of fixed per-action framing that always precede the variable payload:
 // uint8 action_type_id + uint32 action_payload_len.
@@ -42,10 +43,19 @@ const MAX_HELD_SLICES = 256;
  *     varint:  frame_number
  *     varint:  action_count
  *     loop action_count times:
+ *       varint:  ordinal            (the record's index in the sender's log frame)
  *       uint8:   action_type_id
  *       uint32:  action_payload_len
  *       bytes:   action_payload
  * ```
+ * A record's identity on the wire is `(sender, frame_number, ordinal)`: the frame its sender tagged
+ * it for and its place among every record of that frame in the sender's log, filtered or not. The
+ * stream re-sends each unconfirmed frame every tick, and that is how a receiver tells the copies
+ * from new records — never by the payload, since two inputs alike in every byte (a held key, frame
+ * after frame) are two inputs. The ordinal is stable across re-sends because a closed frame's records
+ * are only appended to (`ActionLog.resume_frame`) or rebuilt record for record by a deterministic
+ * replay, and it survives a receiver moving the record to another frame (a late-applying host).
+ *
  * {@link NetworkPeer} prefixes each packet of this with a slice header — the
  * frame range the packet covers and whether it is the first of the sender's
  * tick — which it parses itself and hands to {@link unpack_from_peer} as
@@ -57,12 +67,12 @@ const MAX_HELD_SLICES = 256;
 export class Replicator {
     /**
      * Pre-allocated scratch for the in-scope actions of the current pack
-     * pass: `(action_type_id, payload_start, payload_len)` per action,
+     * pass: `(action_type_id, payload_start, payload_len, ordinal)` per action,
      * interleaved. Grown on demand.
      * @type {Int32Array}
      * @private
      */
-    #in_scope_actions = new Int32Array(64 * 3);
+    #in_scope_actions = new Int32Array(64 * 4);
     /**
      * Per-peer state of {@link unpack_from_peer}'s execute-on-arrival path:
      * `next_frame`, the frame after the newest applied, and `held`, later
@@ -209,18 +219,20 @@ export class Replicator {
      * does NOT touch the action log or executor — it parses the packet
      * and calls this function once per action with:
      *
-     *   `(peer_id, frame_number, action_type_id, in_buffer, payload_offset, payload_len)`
+     *   `(peer_id, frame_number, action_type_id, in_buffer, payload_offset, payload_len, ordinal)`
      *
      * The buffer is shared scratch; consumers must copy the payload bytes
      * if they need them to outlive the call. The orchestrator is then
      * responsible for executing the buffered actions in whatever order
      * the netcode model requires (e.g. rewind to oldest frame, stable-
-     * sort by sender, replay forward).
+     * sort by sender, replay forward) — and for recognising the copies the
+     * stream re-sends, by `(peer_id, frame_number, ordinal)`; this path keeps
+     * no watermark of its own.
      *
      * Leave null for "execute on arrival" semantics (the default and
      * what the loopback/single-orchestrator tests rely on).
      *
-     * @type {((peer_id: number, frame_number: number, action_type_id: number, in_buffer: BinaryBuffer, payload_offset: number, payload_len: number) => void) | null}
+     * @type {((peer_id: number, frame_number: number, action_type_id: number, in_buffer: BinaryBuffer, payload_offset: number, payload_len: number, ordinal: number) => void) | null}
      */
     on_pending_action = null;
 
@@ -315,19 +327,27 @@ export class Replicator {
             const cursor = this.#cursor;
             cursor.open(this.action_log, frame);
             let in_scope_count = 0;
+            // the record's index in the frame, counted over every record so it names the same
+            // record on every re-pack whatever this peer's filter lets through
+            let ordinal = -1;
             while (cursor.next()) {
+                ordinal++;
                 // Never send a peer its own record back. Arrived records are logged like any other,
                 // so without this a client's outbound stream carries the host's state straight
                 // back to it — harmless where ownership rejects it, and the host overwriting its own
                 // simulation with a stale copy of itself where the entity belongs to the client.
                 if (cursor.sender_id === peer_id) continue;
+                // Nor anyone a correction: it is the server's word about this peer's own world,
+                // and sent back, a host would take a client-owned entity's old state from it.
+                if (cursor.sender_id === SENDER_CORRECTED) continue;
                 if (!this.#record_in_scope(cursor, peer_id)) continue;
-                if ((in_scope_count + 1) * 3 > this.#in_scope_actions.length) {
+                if ((in_scope_count + 1) * 4 > this.#in_scope_actions.length) {
                     this.#grow_in_scope_actions();
                 }
-                this.#in_scope_actions[in_scope_count * 3] = cursor.action_type_id;
-                this.#in_scope_actions[in_scope_count * 3 + 1] = cursor.payload_start;
-                this.#in_scope_actions[in_scope_count * 3 + 2] = cursor.payload_len;
+                this.#in_scope_actions[in_scope_count * 4] = cursor.action_type_id;
+                this.#in_scope_actions[in_scope_count * 4 + 1] = cursor.payload_start;
+                this.#in_scope_actions[in_scope_count * 4 + 2] = cursor.payload_len;
+                this.#in_scope_actions[in_scope_count * 4 + 3] = ordinal;
                 in_scope_count++;
             }
 
@@ -343,15 +363,16 @@ export class Replicator {
             out_buffer.writeUintVar(frame);
             out_buffer.writeUintVar(in_scope_count);
 
-            // Wire format per action is (type_id, len, payload). The record's
-            // local-only sender_id byte is NOT copied: the receiver derives the
-            // sender from the packet's peer_id, and carrying it on the wire
-            // would let a hostile peer impersonate other peers' actions.
+            // Wire format per action is (ordinal, type_id, len, payload). The
+            // record's local-only sender_id byte is NOT copied: the receiver
+            // derives the sender from the packet's peer_id, and carrying it on
+            // the wire would let a hostile peer impersonate other peers' actions.
             const raw_bytes = cursor.buffer.raw_bytes;
             for (let i = 0; i < in_scope_count; i++) {
-                const payload_start = this.#in_scope_actions[i * 3 + 1];
-                const payload_len = this.#in_scope_actions[i * 3 + 2];
-                out_buffer.writeUint8(this.#in_scope_actions[i * 3]);
+                const payload_start = this.#in_scope_actions[i * 4 + 1];
+                const payload_len = this.#in_scope_actions[i * 4 + 2];
+                out_buffer.writeUintVar(this.#in_scope_actions[i * 4 + 3]);
+                out_buffer.writeUint8(this.#in_scope_actions[i * 4]);
                 out_buffer.writeUint32(payload_len);
                 out_buffer.writeBytes(raw_bytes, payload_start, payload_len);
             }
@@ -412,6 +433,12 @@ export class Replicator {
                     // past them (otherwise a crafted action_payload_len reads
                     // stale/out-of-bounds bytes — process crash on OOB, cross-
                     // packet leak otherwise). Real check: asserts strip in prod.
+                    // The ordinal is a varint, so it is checked for its first
+                    // byte and the fixed header after it.
+                    if (in_buffer.position >= in_buffer_end) {
+                        throw new MalformedPacketError(`Replicator.unpack_from_peer: action ordinal overruns packet (frame ${frame_number}, action ${i}/${action_count})`);
+                    }
+                    const ordinal = in_buffer.readUintVar();
                     if (in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end) {
                         throw new MalformedPacketError(`Replicator.unpack_from_peer: action header overruns packet (frame ${frame_number}, action ${i}/${action_count})`);
                     }
@@ -423,6 +450,7 @@ export class Replicator {
                     this.on_pending_action(
                         peer_id, frame_number, action_type_id,
                         in_buffer, in_buffer.position, action_payload_len,
+                        ordinal,
                     );
                     in_buffer.position += action_payload_len;
                 }
@@ -530,6 +558,10 @@ export class Replicator {
                 }
 
                 for (let i = 0; i < action_count; i++) {
+                    if (in_buffer.position >= in_buffer_end) {
+                        throw new MalformedPacketError(`Replicator.unpack_from_peer: action ordinal overruns packet (skip; frame ${frame_number}, action ${i}/${action_count})`);
+                    }
+                    in_buffer.readUintVar();                     // ordinal
                     if (in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end) {
                         throw new MalformedPacketError(`Replicator.unpack_from_peer: action header overruns packet (skip; frame ${frame_number}, action ${i}/${action_count})`);
                     }
@@ -543,9 +575,17 @@ export class Replicator {
                 continue;
             }
 
-            this.action_log.begin_frame(frame_number);
+            // After what the frame already holds: on a client this frame is usually one it has
+            // already predicted, and its own records are what a rewind undoes.
+            this.action_log.resume_frame(frame_number);
             try {
                 for (let i = 0; i < action_count; i++) {
+                    if (in_buffer.position >= in_buffer_end) {
+                        throw new MalformedPacketError(`Replicator.unpack_from_peer: action ordinal overruns packet (frame ${frame_number}, action ${i}/${action_count})`);
+                    }
+                    // this path applies frames whole, behind a frame watermark: the ordinal is
+                    // for the deferred path's copy detection and is not needed here
+                    in_buffer.readUintVar();
                     if (in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end) {
                         throw new MalformedPacketError(`Replicator.unpack_from_peer: action header overruns packet (frame ${frame_number}, action ${i}/${action_count})`);
                     }

package/src/engine/network/sim/ActionLog.d.ts

@@ -27,7 +27,7 @@
  * `sender_id` says where the record came from, which is what a rollback replay
  * needs in order to decide what to do with it:
  *
- *   - a peer id `[0, 252]` — arrived from that peer;
+ *   - a peer id `[0, 251]` — arrived from that peer;
  *   - `SENDER_LOCAL` (255) — authored on this peer;
  *   - `SENDER_DERIVED` (254) — computed by this peer's simulation from the
  *     frame's own state. A replay of the frame recomputes these rather than
@@ -35,7 +35,11 @@
  *     the sim's output does not accumulate a copy per replay;
  *   - `SENDER_RECORDED` (253) — recorded, not executed: what this peer's world
  *     became, for the peers (see `SimActionExecutor.record`). A replay carries
- *     these over unchanged.
+ *     these over unchanged;
+ *   - `SENDER_CORRECTED` (252) — a server's correction of one entity on a
+ *     predicting client (see `SimActionExecutor.begin_correction`): prior state
+ *     and the server's bytes, no action. A replay applies it again, last in its
+ *     frame, and it is never packed for any peer.
  *
  * It also gives the replay a stable sort key, so multi-client action order is
  * deterministic across peers. It never crosses the wire —
@@ -70,6 +74,29 @@ export class ActionLog {
      * @param {number} frame absolute frame number
      */
     begin_frame(frame: number): void;
+    /**
+     * Open a frame for writing after the records it already holds, rather than over them. A frame
+     * the ring does not hold is opened empty, as {@link begin_frame} opens it.
+     *
+     * For a writer adding to a frame someone else wrote: records arriving from a peer for a frame
+     * this peer has already simulated. Opened with {@link begin_frame} instead, they would erase
+     * this peer's own records for the frame — and with them the prior state a rewind needs to undo
+     * that input, so a replay would apply it a second time, and the outbound stream, which packs
+     * from this log, would lose it before the peer it was for had confirmed it.
+     *
+     * @param {number} frame absolute frame number
+     */
+    resume_frame(frame: number): void;
+    /**
+     * Drop every record the log holds, keeping each frame it holds present and empty.
+     *
+     * For when the world the records were written against is replaced wholesale, and the frame
+     * numbers they were written under with it: their prior state belongs to that world, so a rewind
+     * that walked them would put it back into this one. Present rather than absent, because a frame
+     * the new world never ran — skipped by the seek that came with it — is one in which nothing was
+     * done, and a rewind crossing it has nothing to undo; an absent frame would make it abandon.
+     */
+    empty_frames(): void;
     /**
      * Close the currently-open frame.
      */
@@ -100,9 +127,9 @@ export class ActionLog {
      * The buffer's `position` will be set to 0 and its valid byte length is `write_end_for(frame)`.
      *
      * **Only valid for frames that have been closed via {@link end_frame}.** While a
-     * frame is open, its slot's recorded length still holds the previous
-     * occupant's — `buffer_for`/`write_end_for` would return mismatched
-     * buffer-contents-vs-length and any reader would walk garbage.
+     * frame is open, its slot's recorded length is what was last committed — 0 for a
+     * frame opened by {@link begin_frame}, the old end for one opened by
+     * {@link resume_frame} — so a reader sees none of what is being written.
      *
      * @param {number} frame
      * @returns {BinaryBuffer}

package/src/engine/network/sim/ActionLog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionLog.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/ActionLog.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH;IAoBI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAShB;IAED;;OAEG;IACH,kBASC;IAED;;;;;;OAMG;IACH,kBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,+BAMC;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,kBAHW,MAAM,gBAKhB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;;CACJ"}
+{"version":3,"file":"ActionLog.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/ActionLog.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH;IAoBI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;OAGG;IACH,6BAEC;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAShB;IAED;;;;;;;;;;;OAWG;IACH,oBAFW,MAAM,QAShB;IAED;;;;;;;;OAQG;IACH,qBAMC;IAED;;OAEG;IACH,kBASC;IAED;;;;;;OAMG;IACH,kBAFa,OAAO,CAInB;IAED;;;;OAIG;IACH,+BAMC;IAED;;;;;OAKG;IACH,iBAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;;;;;;OAWG;IACH,kBAHW,MAAM,gBAKhB;IAED;;;;OAIG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;;CACJ"}

package/src/engine/network/sim/ActionLog.js

@@ -29,7 +29,7 @@ import { FrameBufferRing } from "../state/FrameBufferRing.js";
  * `sender_id` says where the record came from, which is what a rollback replay
  * needs in order to decide what to do with it:
  *
- *   - a peer id `[0, 252]` — arrived from that peer;
+ *   - a peer id `[0, 251]` — arrived from that peer;
  *   - `SENDER_LOCAL` (255) — authored on this peer;
  *   - `SENDER_DERIVED` (254) — computed by this peer's simulation from the
  *     frame's own state. A replay of the frame recomputes these rather than
@@ -37,7 +37,11 @@ import { FrameBufferRing } from "../state/FrameBufferRing.js";
  *     the sim's output does not accumulate a copy per replay;
  *   - `SENDER_RECORDED` (253) — recorded, not executed: what this peer's world
  *     became, for the peers (see `SimActionExecutor.record`). A replay carries
- *     these over unchanged.
+ *     these over unchanged;
+ *   - `SENDER_CORRECTED` (252) — a server's correction of one entity on a
+ *     predicting client (see `SimActionExecutor.begin_correction`): prior state
+ *     and the server's bytes, no action. A replay applies it again, last in its
+ *     frame, and it is never packed for any peer.
  *
  * It also gives the replay a stable sort key, so multi-client action order is
  * deterministic across peers. It never crosses the wire —
@@ -102,6 +106,44 @@ export class ActionLog {
         this.#current_frame = frame;
     }
 
+    /**
+     * Open a frame for writing after the records it already holds, rather than over them. A frame
+     * the ring does not hold is opened empty, as {@link begin_frame} opens it.
+     *
+     * For a writer adding to a frame someone else wrote: records arriving from a peer for a frame
+     * this peer has already simulated. Opened with {@link begin_frame} instead, they would erase
+     * this peer's own records for the frame — and with them the prior state a rewind needs to undo
+     * that input, so a replay would apply it a second time, and the outbound stream, which packs
+     * from this log, would lose it before the peer it was for had confirmed it.
+     *
+     * @param {number} frame absolute frame number
+     */
+    resume_frame(frame) {
+        if (this.#current_frame !== -1) {
+            throw new Error(`ActionLog.resume_frame: previous frame ${this.#current_frame} still open; call end_frame first`);
+        }
+
+        this.#current_buffer = this.#ring.resume(frame);
+        this.#current_frame = frame;
+    }
+
+    /**
+     * Drop every record the log holds, keeping each frame it holds present and empty.
+     *
+     * For when the world the records were written against is replaced wholesale, and the frame
+     * numbers they were written under with it: their prior state belongs to that world, so a rewind
+     * that walked them would put it back into this one. Present rather than absent, because a frame
+     * the new world never ran — skipped by the seek that came with it — is one in which nothing was
+     * done, and a rewind crossing it has nothing to undo; an absent frame would make it abandon.
+     */
+    empty_frames() {
+        if (this.#current_frame !== -1) {
+            throw new Error(`ActionLog.empty_frames: frame ${this.#current_frame} is open; call end_frame first`);
+        }
+
+        this.#ring.empty();
+    }
+
     /**
      * Close the currently-open frame.
      */
@@ -155,9 +197,9 @@ export class ActionLog {
      * The buffer's `position` will be set to 0 and its valid byte length is `write_end_for(frame)`.
      *
      * **Only valid for frames that have been closed via {@link end_frame}.** While a
-     * frame is open, its slot's recorded length still holds the previous
-     * occupant's — `buffer_for`/`write_end_for` would return mismatched
-     * buffer-contents-vs-length and any reader would walk garbage.
+     * frame is open, its slot's recorded length is what was last committed — 0 for a
+     * frame opened by {@link begin_frame}, the old end for one opened by
+     * {@link resume_frame} — so a reader sees none of what is being written.
      *
      * @param {number} frame
      * @returns {BinaryBuffer}

package/src/engine/network/sim/SimActionExecutor.d.ts

@@ -23,7 +23,7 @@ export const SENDER_LOCAL: number;
  * Local-only, like `SENDER_LOCAL` — {@link Replicator#pack_for_peer} strips
  * the byte before send, so this never reaches the wire.
  *
- * The sentinels are reserved: valid peer ids are `[0, 252]`, enforced by
+ * The sentinels are reserved: valid peer ids are `[0, 251]`, enforced by
  * {@link SimActionExecutor#execute} and at {@link NetworkPeer#connect_peer}.
  * A peer allowed to take 254 would have its records read back as the local
  * sim's own output and dropped from every replay — its input would apply once
@@ -44,9 +44,24 @@ export const SENDER_DERIVED: number;
  * @type {number}
  */
 export const SENDER_RECORDED: number;
+/**
+ * Sentinel sender id for a server's correction written into a predicting client's log (see
+ * {@link SimActionExecutor#begin_correction}): the server's state for one entity at the end of a
+ * frame, put over this client's prediction of it.
+ *
+ * Its prior state is what makes the correction undoable, so a rewind across its frame takes the
+ * entity back to the prediction underneath. It has no action: a rollback replay applies it again,
+ * last in its frame, from the bytes it carries. It is never sent — the client's log is its outbound
+ * stream, and a host would take a client-owned entity's old state from it. Local-only, like the
+ * other sentinels.
+ *
+ * @type {number}
+ */
+export const SENDER_CORRECTED: number;
 /**
  * Largest id a remote peer may take. Above this are the local provenance sentinels,
- * {@link SENDER_RECORDED}, {@link SENDER_DERIVED} and {@link SENDER_LOCAL}.
+ * {@link SENDER_CORRECTED}, {@link SENDER_RECORDED}, {@link SENDER_DERIVED} and
+ * {@link SENDER_LOCAL}.
  *
  * @type {number}
  */
@@ -242,6 +257,31 @@ export class SimActionExecutor {
      * @param {SimAction} action
      */
     record(action: SimAction): void;
+    /**
+     * Open a {@link SENDER_CORRECTED} record in the open frame: capture the prior state of every
+     * replicated component `entity_id` has, as {@link execute} captures an action's, so a rewind
+     * across the frame puts it back. The caller then overwrites the entity with the server's state
+     * and closes the record with {@link end_correction} — also when that overwrite throws, or the
+     * frame is left holding half a record.
+     *
+     * Every replicated component, because a correction is the server's whole state for the entity
+     * and the executor cannot know which of them the caller's deserialize writes.
+     *
+     * No authorization, no {@link before_execute}, no announcement: the caller writes, not this.
+     *
+     * @param {number} entity_id
+     */
+    begin_correction(entity_id: number): void;
+    /**
+     * Close the record {@link begin_correction} opened, carrying `length` bytes of `bytes` from
+     * `offset` — what a replay needs to apply the correction again. The record has no action: its
+     * action type byte is 0 and means nothing, and readers go by its sender.
+     *
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} length
+     */
+    end_correction(bytes: Uint8Array, offset: number, length: number): void;
     #private;
 }
 import Signal from "../../../core/events/signal/Signal.js";

package/src/engine/network/sim/SimActionExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SimActionExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/SimActionExecutor.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,2BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,6BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH,8BAFU,MAAM,CAEoB;AAEpC;;;;;GAKG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAqEI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EAyFH;IAjKD;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEP;IAEtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAFU,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,WAAW,KAAK,OAAO,CAAC,GAAG,IAAI,CAEtE;IAEjB;;;;;;;;;;;;;;;OAeG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,sBAFU,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,UAAU,KAAK,IAAI,CAAC,GAAG,IAAI,CAE7C;IAaxB;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,gDAA4C;IAE5C;;;;OAIG;IACH,iCAA4B;IAE5B;;;;;;;;;;;OAWG;IACH,kBAFU,mBAAiB,IAAI,CAES;IA4BxC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;OAOG;IACH,kBAFU,MAAM,CAEoB;IAGxC;;;;;;;;;;OAUG;IACH,uCAPW,MAAM,GAGJ,OAAO,CA0KnB;IAkCD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gCAwCC;;CACJ;mBA7gBkB,uCAAuC"}
+{"version":3,"file":"SimActionExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/SimActionExecutor.js"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,2BAFU,MAAM,CAEiB;AAEjC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,6BAFU,MAAM,CAEmB;AAEnC;;;;;;;;;;GAUG;AACH,8BAFU,MAAM,CAEoB;AAEpC;;;;;;;;;;;;GAYG;AACH,+BAFU,MAAM,CAEqB;AAErC;;;;;;GAMG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA2EI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EAyFH;IAjKD;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEP;IAEtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,WAFU,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,WAAW,KAAK,OAAO,CAAC,GAAG,IAAI,CAEtE;IAEjB;;;;;;;;;;;;;;;OAeG;IACH,UAFU,OAAO,CAEA;IAEjB;;;;;;;OAOG;IACH,sBAFU,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,UAAU,KAAK,IAAI,CAAC,GAAG,IAAI,CAE7C;IAaxB;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,gDAA4C;IAE5C;;;;OAIG;IACH,iCAA4B;IAE5B;;;;;;;;;;;OAWG;IACH,kBAFU,mBAAiB,IAAI,CAES;IA4BxC;;;;;;;OAOG;IACH,mBAFU,MAAM,CAEqB;IAErC;;;;;;;OAOG;IACH,kBAFU,MAAM,CAEoB;IAGxC;;;;;;;;;;OAUG;IACH,uCAPW,MAAM,GAGJ,OAAO,CA0KnB;IAkCD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,gCAwCC;IAED;;;;;;;;;;;;;OAaG;IACH,4BAFW,MAAM,QAqChB;IAED;;;;;;;;OAQG;IACH,sBAJW,UAAU,UACV,MAAM,UACN,MAAM,QAchB;;CACJ;mBA7mBkB,uCAAuC"}

package/src/engine/network/sim/SimActionExecutor.js

@@ -27,7 +27,7 @@ export const SENDER_LOCAL = 0xFF;
  * Local-only, like `SENDER_LOCAL` — {@link Replicator#pack_for_peer} strips
  * the byte before send, so this never reaches the wire.
  *
- * The sentinels are reserved: valid peer ids are `[0, 252]`, enforced by
+ * The sentinels are reserved: valid peer ids are `[0, 251]`, enforced by
  * {@link SimActionExecutor#execute} and at {@link NetworkPeer#connect_peer}.
  * A peer allowed to take 254 would have its records read back as the local
  * sim's own output and dropped from every replay — its input would apply once
@@ -50,13 +50,29 @@ export const SENDER_DERIVED = 0xFE;
  */
 export const SENDER_RECORDED = 0xFD;
 
+/**
+ * Sentinel sender id for a server's correction written into a predicting client's log (see
+ * {@link SimActionExecutor#begin_correction}): the server's state for one entity at the end of a
+ * frame, put over this client's prediction of it.
+ *
+ * Its prior state is what makes the correction undoable, so a rewind across its frame takes the
+ * entity back to the prediction underneath. It has no action: a rollback replay applies it again,
+ * last in its frame, from the bytes it carries. It is never sent — the client's log is its outbound
+ * stream, and a host would take a client-owned entity's old state from it. Local-only, like the
+ * other sentinels.
+ *
+ * @type {number}
+ */
+export const SENDER_CORRECTED = 0xFC;
+
 /**
  * Largest id a remote peer may take. Above this are the local provenance sentinels,
- * {@link SENDER_RECORDED}, {@link SENDER_DERIVED} and {@link SENDER_LOCAL}.
+ * {@link SENDER_CORRECTED}, {@link SENDER_RECORDED}, {@link SENDER_DERIVED} and
+ * {@link SENDER_LOCAL}.
  *
  * @type {number}
  */
-export const MAX_PEER_ID = 0xFC;
+export const MAX_PEER_ID = 0xFB;
 
 /**
  * The single legitimate gateway for replicated state mutations.
@@ -86,6 +102,12 @@ export class SimActionExecutor {
     #scratch_classes;
     #collect_cb;
 
+    /**
+     * Between {@link begin_correction} and {@link end_correction}.
+     * @type {boolean}
+     */
+    #correction_open = false;
+
     /**
      * Optional hook fired at the top of {@link execute}, before
      * prior-bytes capture. Higher-level orchestrators install this
@@ -281,7 +303,7 @@ export class SimActionExecutor {
         // prod, and silent input loss is not something to ship behind one.
         if (sender_id > MAX_PEER_ID && sender_id !== SENDER_LOCAL) {
             throw new Error(
-                `SimActionExecutor.execute: sender_id ${sender_id} is not a peer id; remote peer ids must be in [0, ${MAX_PEER_ID}] — 253, 254 and 255 are reserved provenance markers`,
+                `SimActionExecutor.execute: sender_id ${sender_id} is not a peer id; remote peer ids must be in [0, ${MAX_PEER_ID}] — 252 to 255 are reserved provenance markers`,
             );
         }
 
@@ -524,4 +546,78 @@ export class SimActionExecutor {
         buffer.writeUint32(action_payload_end - action_payload_start);
         buffer.position = action_payload_end;
     }
+
+    /**
+     * Open a {@link SENDER_CORRECTED} record in the open frame: capture the prior state of every
+     * replicated component `entity_id` has, as {@link execute} captures an action's, so a rewind
+     * across the frame puts it back. The caller then overwrites the entity with the server's state
+     * and closes the record with {@link end_correction} — also when that overwrite throws, or the
+     * frame is left holding half a record.
+     *
+     * Every replicated component, because a correction is the server's whole state for the entity
+     * and the executor cannot know which of them the caller's deserialize writes.
+     *
+     * No authorization, no {@link before_execute}, no announcement: the caller writes, not this.
+     *
+     * @param {number} entity_id
+     */
+    begin_correction(entity_id) {
+        assert.isNonNegativeInteger(entity_id, 'entity_id');
+        assert.equal(this.#correction_open, false, 'begin_correction: a correction is already open');
+
+        const buffer = this.action_log.current_buffer();
+        const registry = this.component_registry;
+        const world = this.world;
+        const type_count = registry.type_count();
+
+        let count = 0;
+        for (let type_id = 0; type_id < type_count; type_id++) {
+            if (world.getComponent(entity_id, registry.class_of(type_id)) !== undefined) count++;
+        }
+
+        buffer.writeUintVar(count);
+
+        for (let type_id = 0; type_id < type_count; type_id++) {
+            const component = world.getComponent(entity_id, registry.class_of(type_id));
+            if (component === undefined) continue;
+
+            buffer.writeUintVar(entity_id);
+            buffer.writeUint8(type_id);
+
+            const len_position = buffer.position;
+            buffer.writeUint32(0); // placeholder
+            const payload_start = buffer.position;
+            registry.adapter_for_id(type_id).serialize(buffer, component);
+            const payload_end = buffer.position;
+
+            buffer.position = len_position;
+            buffer.writeUint32(payload_end - payload_start);
+            buffer.position = payload_end;
+        }
+
+        this.#correction_open = true;
+    }
+
+    /**
+     * Close the record {@link begin_correction} opened, carrying `length` bytes of `bytes` from
+     * `offset` — what a replay needs to apply the correction again. The record has no action: its
+     * action type byte is 0 and means nothing, and readers go by its sender.
+     *
+     * @param {Uint8Array} bytes
+     * @param {number} offset
+     * @param {number} length
+     */
+    end_correction(bytes, offset, length) {
+        assert.equal(this.#correction_open, true, 'end_correction: no correction is open');
+        assert.isNonNegativeInteger(length, 'length');
+
+        const buffer = this.action_log.current_buffer();
+
+        buffer.writeUint8(0);
+        buffer.writeUint8(SENDER_CORRECTED);
+        buffer.writeUint32(length);
+        buffer.writeBytes(bytes, offset, length);
+
+        this.#correction_open = false;
+    }
 }

package/src/engine/network/sim/Snapshotter.d.ts

@@ -46,6 +46,18 @@ export function snapshotter_emit({ buffer, world, slot_table, component_registry
     component_registry: ReplicatedComponentRegistry;
     entity_iter: (arg0: (arg0: number) => void) => void;
 }): void;
+/**
+ * Write one entity's record — network id, then each replicated component it has — in the format
+ * {@link snapshotter_emit} writes per entity. Allocates nothing: a page builder calls it once per
+ * entity it fits.
+ *
+ * @param {BinaryBuffer} buffer
+ * @param {EntityComponentDataset} world
+ * @param {ReplicationSlotTable} slot_table
+ * @param {ReplicatedComponentRegistry} component_registry
+ * @param {number} entity_id must be registered in the slot table
+ */
+export function snapshotter_write_entity(buffer: BinaryBuffer, world: EntityComponentDataset, slot_table: ReplicationSlotTable, component_registry: ReplicatedComponentRegistry, entity_id: number): void;
 /**
  * Apply a snapshot stream to a (typically empty) world, creating each entity
  * and attaching components.

package/src/engine/network/sim/Snapshotter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Snapshotter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/Snapshotter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;GAUG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;IACpD,WAAe,gBAAoB,MAAM,KAAG,IAAI,KAAG,IAAI,CAAC;CACrD,QAkDH;AAED;;;;;;;;;;;GAWG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QA6CH;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6GARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QAgDH"}
+{"version":3,"file":"Snapshotter.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/Snapshotter.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH;;;;;;;;;;GAUG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;IACpD,WAAe,gBAAoB,MAAM,KAAG,IAAI,KAAG,IAAI,CAAC;CACrD,QAkDH;AAED;;;;;;;;;;GAUG;AACH,4LAFW,MAAM,QAgChB;AAED;;;;;;;;;;;GAWG;AACH,iGARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QA6CH;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,6GARW;IACV,MAAU,eAAe;IACzB,UAAc,EAAE,MAAM,CAAC;IACvB,KAAS,yBAAyB;IAClC,UAAc,uBAAuB;IACrC,kBAAsB,8BAA8B;CACjD,QAgDH"}