@woosh/meep-engine 3.14.3 → 3.14.5

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

@@ -14,7 +14,7 @@ import { FrameBufferRing } from "../state/FrameBufferRing.js";
  *     uint32:  prior_payload_len
  *     bytes:   prior_payload       (adapter.serialize of the component's prior state)
  *   uint8:     action_type_id
- *   uint8:     sender_id           (peer that originated the action; local-only,
+ *   uint8:     sender_id           (provenance of the record; local-only,
  *                                   STRIPPED by Replicator before send)
  *   uint32:    action_payload_len
  *   bytes:     action_payload      (the action's own serialize output)
@@ -23,9 +23,21 @@ import { FrameBufferRing } from "../state/FrameBufferRing.js";
  * Self-describing: records can be skipped without consulting the action registry,
  * which means rewind code can walk records forward to find boundaries, then
  * iterate backward to apply prior states — no need to instantiate any actions.
+ * {@link ActionRecordCursor} is that walk; readers use it rather than parsing
+ * the layout themselves.
  *
- * Note that `sender_id` is recorded in-buffer for local rollback orchestrators
- * (stable-sort tie-breaking by sender on replay) but never crosses the wire —
+ * `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, 253]` — 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
+ *     reapplying them (see `ServerAuthoritativeServer.__read_historical`), so
+ *     the sim's output does not accumulate a copy per replay.
+ *
+ * It also gives the replay a stable sort key, so multi-client action order is
+ * deterministic across peers. It never crosses the wire —
  * {@link Replicator#pack_for_peer} strips it and the receiver derives sender
  * from the inbound packet's peer_id, so a hostile peer cannot impersonate.
  *
@@ -102,6 +114,17 @@ export class ActionLog {
         this.#current_buffer = null;
     }
 
+    /**
+     * Is a frame open for writing? {@link current_buffer} — and therefore
+     * `SimActionExecutor.execute` — throws when it is not, so a caller that can
+     * run either inside or outside a frame checks this to pick its path.
+     *
+     * @returns {boolean}
+     */
+    has_open_frame() {
+        return this.#current_frame !== -1;
+    }
+
     /**
      * Get the buffer for the currently-open frame for direct writing.
      *

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

@@ -0,0 +1,82 @@
+/**
+ * Forward cursor over the records of one closed {@link ActionLog} frame.
+ *
+ * The record layout is self-describing (see {@link ActionLog}), so any reader
+ * can walk it — and five did, each with its own copy of the header parse: the
+ * replicator's scope scan and action copy, the rewind engine's boundary pass,
+ * and the rollback server's history read and retransmission check. This is
+ * that parse in one place. {@link next} reads one record's header and exposes
+ * the layout as positions into the frame's buffer; what a reader does with the
+ * prior-state entries or the action payload is its own business.
+ *
+ * Allocation-free after construction: a reader owns one cursor and re-opens
+ * it per frame. After `next` returns true the buffer's `position` is at the
+ * END of the record, so a reader that wants the prior-state entries sets
+ * `position = prior_start` and reads `prior_count` of them; `next` seeks from
+ * `record_end` regardless of where the reader left the position.
+ *
+ * ```
+ *   cursor.open(action_log, frame);
+ *   while (cursor.next()) {
+ *       // cursor.action_type_id, cursor.sender_id,
+ *       // cursor.buffer.raw_bytes[cursor.payload_start .. + cursor.payload_len]
+ *   }
+ * ```
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ActionRecordCursor {
+    /**
+     * The open frame's buffer, positioned at {@link record_end} after each
+     * successful {@link next}.
+     * @type {BinaryBuffer|null}
+     */
+    buffer: BinaryBuffer | null;
+    /** @type {number} first byte of the current record */
+    record_start: number;
+    /** @type {number} prior-state entries in the current record */
+    prior_count: number;
+    /**
+     * First byte of the first prior-state entry. Each entry is
+     * `varint entity_id, uint8 component_type_id, uint32 len, bytes[len]`.
+     * @type {number}
+     */
+    prior_start: number;
+    /** @type {number} */
+    action_type_id: number;
+    /**
+     * The record's provenance byte: a peer id, `SENDER_LOCAL` or
+     * `SENDER_DERIVED` (see {@link SimActionExecutor}).
+     * @type {number}
+     */
+    sender_id: number;
+    /** @type {number} first byte of the action payload */
+    payload_start: number;
+    /** @type {number} */
+    payload_len: number;
+    /**
+     * One past the last byte of the current record — and so the first byte of
+     * the next, which is where {@link next} resumes. `0` before the first
+     * record.
+     * @type {number}
+     */
+    record_end: number;
+    /**
+     * Position the cursor before the first record of `frame`, which must be
+     * closed and present in the log (see {@link ActionLog#buffer_for}).
+     *
+     * @param {ActionLog} action_log
+     * @param {number} frame
+     */
+    open(action_log: ActionLog, frame: number): void;
+    /**
+     * Advance to the next record. Returns false once the frame is exhausted,
+     * leaving the fields as they were.
+     *
+     * @returns {boolean}
+     */
+    next(): boolean;
+    #private;
+}
+//# sourceMappingURL=ActionRecordCursor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ActionRecordCursor.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/ActionRecordCursor.js"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IACI;;;;OAIG;IACH,QAFU,eAAa,IAAI,CAEb;IAEd,sDAAsD;IACtD,cADW,MAAM,CACA;IAEjB,+DAA+D;IAC/D,aADW,MAAM,CACD;IAEhB;;;;OAIG;IACH,aAFU,MAAM,CAEA;IAEhB,qBAAqB;IACrB,gBADW,MAAM,CACE;IAEnB;;;;OAIG;IACH,WAFU,MAAM,CAEF;IAEd,sDAAsD;IACtD,eADW,MAAM,CACC;IAElB,qBAAqB;IACrB,aADW,MAAM,CACD;IAEhB;;;;;OAKG;IACH,YAFU,MAAM,CAED;IAKf;;;;;;OAMG;IACH,mCAFW,MAAM,QAMhB;IAED;;;;;OAKG;IACH,QAFa,OAAO,CAyBnB;;CACJ"}

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

@@ -0,0 +1,120 @@
+/**
+ * Forward cursor over the records of one closed {@link ActionLog} frame.
+ *
+ * The record layout is self-describing (see {@link ActionLog}), so any reader
+ * can walk it — and five did, each with its own copy of the header parse: the
+ * replicator's scope scan and action copy, the rewind engine's boundary pass,
+ * and the rollback server's history read and retransmission check. This is
+ * that parse in one place. {@link next} reads one record's header and exposes
+ * the layout as positions into the frame's buffer; what a reader does with the
+ * prior-state entries or the action payload is its own business.
+ *
+ * Allocation-free after construction: a reader owns one cursor and re-opens
+ * it per frame. After `next` returns true the buffer's `position` is at the
+ * END of the record, so a reader that wants the prior-state entries sets
+ * `position = prior_start` and reads `prior_count` of them; `next` seeks from
+ * `record_end` regardless of where the reader left the position.
+ *
+ * ```
+ *   cursor.open(action_log, frame);
+ *   while (cursor.next()) {
+ *       // cursor.action_type_id, cursor.sender_id,
+ *       // cursor.buffer.raw_bytes[cursor.payload_start .. + cursor.payload_len]
+ *   }
+ * ```
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class ActionRecordCursor {
+    /**
+     * The open frame's buffer, positioned at {@link record_end} after each
+     * successful {@link next}.
+     * @type {BinaryBuffer|null}
+     */
+    buffer = null;
+
+    /** @type {number} first byte of the current record */
+    record_start = 0;
+
+    /** @type {number} prior-state entries in the current record */
+    prior_count = 0;
+
+    /**
+     * First byte of the first prior-state entry. Each entry is
+     * `varint entity_id, uint8 component_type_id, uint32 len, bytes[len]`.
+     * @type {number}
+     */
+    prior_start = 0;
+
+    /** @type {number} */
+    action_type_id = 0;
+
+    /**
+     * The record's provenance byte: a peer id, `SENDER_LOCAL` or
+     * `SENDER_DERIVED` (see {@link SimActionExecutor}).
+     * @type {number}
+     */
+    sender_id = 0;
+
+    /** @type {number} first byte of the action payload */
+    payload_start = 0;
+
+    /** @type {number} */
+    payload_len = 0;
+
+    /**
+     * One past the last byte of the current record — and so the first byte of
+     * the next, which is where {@link next} resumes. `0` before the first
+     * record.
+     * @type {number}
+     */
+    record_end = 0;
+
+    /** @type {number} one past the last byte of the frame */
+    #end = 0;
+
+    /**
+     * Position the cursor before the first record of `frame`, which must be
+     * closed and present in the log (see {@link ActionLog#buffer_for}).
+     *
+     * @param {ActionLog} action_log
+     * @param {number} frame
+     */
+    open(action_log, frame) {
+        this.buffer = action_log.buffer_for(frame); // rewinds to 0
+        this.#end = action_log.write_end_for(frame);
+        this.record_end = 0;
+    }
+
+    /**
+     * Advance to the next record. Returns false once the frame is exhausted,
+     * leaving the fields as they were.
+     *
+     * @returns {boolean}
+     */
+    next() {
+        if (this.record_end >= this.#end) return false;
+
+        const buffer = this.buffer;
+        buffer.position = this.record_end;
+
+        this.record_start = buffer.position;
+        this.prior_count = buffer.readUintVar();
+        this.prior_start = buffer.position;
+        for (let i = 0; i < this.prior_count; i++) {
+            buffer.readUintVar();                   // entity_id
+            buffer.readUint8();                     // component_type_id
+            const prior_len = buffer.readUint32();
+            buffer.position += prior_len;           // prior payload
+        }
+        this.action_type_id = buffer.readUint8();
+        this.sender_id = buffer.readUint8();
+        this.payload_len = buffer.readUint32();
+        this.payload_start = buffer.position;
+        this.record_end = this.payload_start + this.payload_len;
+        buffer.position = this.record_end;
+
+        return true;
+    }
+}

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

@@ -1 +1 @@
-{"version":3,"file":"RewindEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/RewindEngine.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAQI;;;;;;OAMG;IACH,uDANW;QACV,UAAc,YAAY;QAC1B,KAAS,yBAAyB;QAClC,kBAAsB,8BAA8B;KACjD,EAiBH;IAdG;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,gDAA4C;IAGhD;;;;;OAKG;IACH,kBAFW,MAAM,QA2BhB;IAED;;;;;;;;;OASG;IACH,yBAHW,MAAM,gBACN,MAAM,QAWhB;;CAwEJ"}
+{"version":3,"file":"RewindEngine.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/RewindEngine.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;GAmBG;AACH;IAeI;;;;;;OAMG;IACH,uDANW;QACV,UAAc,YAAY;QAC1B,KAAS,yBAAyB;QAClC,kBAAsB,8BAA8B;KACjD,EAiBH;IAdG;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,8BAAkB;IAElB;;OAEG;IACH,gDAA4C;IAGhD;;;;;OAKG;IACH,kBAFW,MAAM,QA0BhB;IAED;;;;;;;;;OASG;IACH,yBAHW,MAAM,gBACN,MAAM,QAWhB;;CAiDJ"}

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

@@ -1,4 +1,5 @@
 import { assert } from "../../../core/assert.js";
+import { ActionRecordCursor } from "./ActionRecordCursor.js";
 
 /**
  * Walks the {@link ActionLog} backwards to restore prior component state.
@@ -28,6 +29,13 @@ export class RewindEngine {
      */
     #record_starts = new Int32Array(64);
 
+    /**
+     * Walks a frame's records to find where each starts.
+     * @type {ActionRecordCursor}
+     * @private
+     */
+    #cursor = new ActionRecordCursor();
+
     /**
      * @param {{
      *   action_log: ActionLog,
@@ -64,20 +72,19 @@ export class RewindEngine {
             throw new Error(`RewindEngine.undo_frame: frame ${frame} is not present in the action log`);
         }
 
-        const buffer = this.action_log.buffer_for(frame);
-        const end = this.action_log.write_end_for(frame);
-
         // 1. First pass: walk forward to find record boundaries.
+        const cursor = this.#cursor;
+        cursor.open(this.action_log, frame);
         let record_count = 0;
-        while (buffer.position < end) {
+        while (cursor.next()) {
             if (record_count >= this.#record_starts.length) {
                 this.#grow_record_starts();
             }
-            this.#record_starts[record_count++] = buffer.position;
-            this.#skip_record(buffer);
+            this.#record_starts[record_count++] = cursor.record_start;
         }
 
         // 2. Second pass: iterate records in reverse, restoring prior state.
+        const buffer = cursor.buffer;
         for (let i = record_count - 1; i >= 0; i--) {
             buffer.position = this.#record_starts[i];
             this.#restore_prior_state(buffer);
@@ -106,29 +113,6 @@ export class RewindEngine {
         }
     }
 
-    /**
-     * Walk past a single record without restoring anything. Buffer position
-     * advances to the start of the next record (or to `end` if this was the last).
-     *
-     * @param {BinaryBuffer} buffer
-     * @private
-     */
-    #skip_record(buffer) {
-        // Skip prior_state entries.
-        const prior_count = buffer.readUintVar();
-        for (let i = 0; i < prior_count; i++) {
-            buffer.readUintVar();           // entity_id
-            buffer.readUint8();             // component_type_id
-            const len = buffer.readUint32();
-            buffer.position += len;         // skip prior payload
-        }
-        // Skip action.
-        buffer.readUint8();                 // action_type_id
-        buffer.readUint8();                 // sender_id
-        const action_len = buffer.readUint32();
-        buffer.position += action_len;      // skip action payload
-    }
-
     /**
      * Read the prior_state entries of the record at the buffer's current position
      * and write them back into the live components. Buffer position advances past

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

@@ -11,6 +11,21 @@
  * deterministic consequence of the simulation, or rewind / replay /
  * replication will desync.
  *
+ * "Deterministic consequence" is a narrow licence, and it is worth being exact
+ * about what it buys. A rewind restores component state from the prior-bytes
+ * captured per action record, so a mutation made outside an action is never
+ * undone — it survives into the replayed frame and the sim must overwrite it
+ * with the same answer it produced before. That holds for a function of the
+ * frame's post-input state that fully determines what it writes (a clamp, a
+ * position solved from inputs) and fails for anything that reads the value it
+ * is about to change (`hp -= 10`, a counter, an accumulator). Those need a
+ * `SimAction`, whose prior-bytes capture makes them reversible.
+ *
+ * Going through an action does not, on its own, make a mutation replayable
+ * input: on a rollback orchestrator, a record's `sender_id` marks whether it
+ * arrived, was authored, or was derived, and only the first two are reapplied
+ * from the log. See `ServerAuthoritativeServer#onLocalSim`.
+ *
  * Wire vs local: actions reference entities by `network_id` (peer-shared);
  * `executor.slot_table.entity_for(network_id)` translates to the local id.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"SimAction.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/SimAction.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;GAkBG;AACH;IAEI;;;;OAIG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;;;;;;;OASG;IACH,mEAFa,IAAI,CAIhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,qCAHoB,MAAM,qBAAa,IAAI,qCAK1C;IAED;;;;;;OAMG;IACH,iCAFa,IAAI,CAIhB;IAED;;;;;OAKG;IACH,mCAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,cAEC;IAGL;;;;OAIG;IACH,sBAFU,OAAO,CAEc;CAP9B;;IAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH;;;;;;;iBAmGC"}
+{"version":3,"file":"SimAction.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/sim/SimAction.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH;IAEI;;;;OAIG;IACH,gBAFU,MAAM,CAEI;IAEpB;;;;;;;;;OASG;IACH,mEAFa,IAAI,CAIhB;IAED;;;;;;;;;;;;;;;;;OAiBG;IACH,qCAHoB,MAAM,qBAAa,IAAI,qCAK1C;IAED;;;;;;OAMG;IACH,iCAFa,IAAI,CAIhB;IAED;;;;;OAKG;IACH,mCAFa,IAAI,CAIhB;IAED;;;OAGG;IACH,cAEC;IAGL;;;;OAIG;IACH,sBAFU,OAAO,CAEc;CAP9B;;IAwCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsCG;IACH;;;;;;;iBAmGC"}

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

@@ -13,6 +13,21 @@ import { FunctionCompiler } from "../../../core/function/FunctionCompiler.js";
  * deterministic consequence of the simulation, or rewind / replay /
  * replication will desync.
  *
+ * "Deterministic consequence" is a narrow licence, and it is worth being exact
+ * about what it buys. A rewind restores component state from the prior-bytes
+ * captured per action record, so a mutation made outside an action is never
+ * undone — it survives into the replayed frame and the sim must overwrite it
+ * with the same answer it produced before. That holds for a function of the
+ * frame's post-input state that fully determines what it writes (a clamp, a
+ * position solved from inputs) and fails for anything that reads the value it
+ * is about to change (`hp -= 10`, a counter, an accumulator). Those need a
+ * `SimAction`, whose prior-bytes capture makes them reversible.
+ *
+ * Going through an action does not, on its own, make a mutation replayable
+ * input: on a rollback orchestrator, a record's `sender_id` marks whether it
+ * arrived, was authored, or was derived, and only the first two are reapplied
+ * from the log. See `ServerAuthoritativeServer#onLocalSim`.
+ *
  * Wire vs local: actions reference entities by `network_id` (peer-shared);
  * `executor.slot_table.entity_for(network_id)` translates to the local id.
  *

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

@@ -2,11 +2,43 @@
  * Sentinel sender id for actions that originated on the local peer (not
  * received over the wire). Used as the default `sender_id` for
  * {@link SimActionExecutor#execute} so existing single-peer code keeps
- * working. Valid peer ids must therefore be in `[0, 254]`.
+ * working.
  *
  * @type {number}
  */
 export const SENDER_LOCAL: number;
+/**
+ * Sentinel sender id recorded for actions the local simulation DERIVED from
+ * the frame's state, rather than received or authored. Written in place of
+ * the caller's `sender_id` while {@link SimActionExecutor#deriving} is set.
+ *
+ * The sender byte is the record's provenance, and provenance is what decides
+ * whether a rollback replay may reuse a record. Input — remote or locally
+ * authored — happened once and cannot be recomputed, so a replay reapplies it
+ * from the log. Derived output is a function of the frame's post-input state,
+ * which a replay recomputes anyway; reapplying the previous pass's copy on top
+ * of the recomputed one applies the effect twice. So the two are separated
+ * here, at the point of execution, where the distinction is actually known.
+ *
+ * Local-only, like `SENDER_LOCAL` — {@link Replicator#pack_for_peer} strips
+ * the byte before send, so this never reaches the wire.
+ *
+ * Both sentinels are reserved: valid peer ids are `[0, 253]`, 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
+ * and then silently vanish the first time a rollback crossed its frame.
+ *
+ * @type {number}
+ */
+export const SENDER_DERIVED: number;
+/**
+ * Largest id a remote peer may take. Above this are the two local provenance
+ * sentinels, {@link SENDER_DERIVED} and {@link SENDER_LOCAL}.
+ *
+ * @type {number}
+ */
+export const MAX_PEER_ID: number;
 /**
  * The single legitimate gateway for replicated state mutations.
  *
@@ -83,6 +115,23 @@ export class SimActionExecutor {
      * @type {((sender_id: number, entity_id: number, action: SimAction) => boolean) | null}
      */
     authorize: (sender_id: number, entity_id: number, action: SimAction) => boolean;
+    /**
+     * When true, records written by {@link execute} are stamped
+     * {@link SENDER_DERIVED} instead of the caller's `sender_id`, marking them
+     * as output the simulation recomputes rather than input it must replay.
+     *
+     * Set by a rollback orchestrator for the span in which the frame's local
+     * sim runs (see `ServerAuthoritativeServer.__replay_frame`) and cleared
+     * immediately after. Everything outside that span — arrived input,
+     * locally-authored actions — is left with its real sender.
+     *
+     * Only the RECORDED byte changes. `sender_id` still drives the
+     * {@link authorize} gate and {@link current_sender_id}, so an action that
+     * self-validates on its sender sees the truth.
+     *
+     * @type {boolean}
+     */
+    deriving: boolean;
     /**
      * @type {EntityComponentDataset}
      */
@@ -142,7 +191,7 @@ export class SimActionExecutor {
      * @param {SimAction} action
      * @param {number} [sender_id] peer that originated this action.
      *   Defaults to {@link SENDER_LOCAL} for locally-originated actions.
-     *   Must be in `[0, 254]` for remote-originated actions.
+     *   Must be in `[0, MAX_PEER_ID]` for remote-originated actions.
      * @returns {boolean} true if the action was applied; false if it was
      *   rejected by the {@link authorize} gate (and therefore not applied or
      *   logged).

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;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IAyCI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EAyFH;IArID;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEP;IAEtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,uBAFuB,MAAM,aAAa,MAAM,wBAAwB,OAAO,CAE9D;IAab;;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,CAiInB;;CACJ;mBAxTkB,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;;;;;GAKG;AACH,0BAFU,MAAM,CAEgB;AAEhC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH;IA2DI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EAyFH;IAvJD;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEP;IAEtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,uBAFuB,MAAM,aAAa,MAAM,wBAAwB,OAAO,CAE9D;IAEjB;;;;;;;;;;;;;;;OAeG;IACH,UAFU,OAAO,CAEA;IAab;;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,CAgJnB;;CACJ;mBA3XkB,uCAAuC"}

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

@@ -5,12 +5,46 @@ import Signal from "../../../core/events/signal/Signal.js";
  * Sentinel sender id for actions that originated on the local peer (not
  * received over the wire). Used as the default `sender_id` for
  * {@link SimActionExecutor#execute} so existing single-peer code keeps
- * working. Valid peer ids must therefore be in `[0, 254]`.
+ * working.
  *
  * @type {number}
  */
 export const SENDER_LOCAL = 0xFF;
 
+/**
+ * Sentinel sender id recorded for actions the local simulation DERIVED from
+ * the frame's state, rather than received or authored. Written in place of
+ * the caller's `sender_id` while {@link SimActionExecutor#deriving} is set.
+ *
+ * The sender byte is the record's provenance, and provenance is what decides
+ * whether a rollback replay may reuse a record. Input — remote or locally
+ * authored — happened once and cannot be recomputed, so a replay reapplies it
+ * from the log. Derived output is a function of the frame's post-input state,
+ * which a replay recomputes anyway; reapplying the previous pass's copy on top
+ * of the recomputed one applies the effect twice. So the two are separated
+ * here, at the point of execution, where the distinction is actually known.
+ *
+ * Local-only, like `SENDER_LOCAL` — {@link Replicator#pack_for_peer} strips
+ * the byte before send, so this never reaches the wire.
+ *
+ * Both sentinels are reserved: valid peer ids are `[0, 253]`, 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
+ * and then silently vanish the first time a rollback crossed its frame.
+ *
+ * @type {number}
+ */
+export const SENDER_DERIVED = 0xFE;
+
+/**
+ * Largest id a remote peer may take. Above this are the two local provenance
+ * sentinels, {@link SENDER_DERIVED} and {@link SENDER_LOCAL}.
+ *
+ * @type {number}
+ */
+export const MAX_PEER_ID = 0xFD;
+
 /**
  * The single legitimate gateway for replicated state mutations.
  *
@@ -75,6 +109,24 @@ export class SimActionExecutor {
      */
     authorize = null;
 
+    /**
+     * When true, records written by {@link execute} are stamped
+     * {@link SENDER_DERIVED} instead of the caller's `sender_id`, marking them
+     * as output the simulation recomputes rather than input it must replay.
+     *
+     * Set by a rollback orchestrator for the span in which the frame's local
+     * sim runs (see `ServerAuthoritativeServer.__replay_frame`) and cleared
+     * immediately after. Everything outside that span — arrived input,
+     * locally-authored actions — is left with its real sender.
+     *
+     * Only the RECORDED byte changes. `sender_id` still drives the
+     * {@link authorize} gate and {@link current_sender_id}, so an action that
+     * self-validates on its sender sees the truth.
+     *
+     * @type {boolean}
+     */
+    deriving = false;
+
     /**
      * @param {{
      *   world: EntityComponentDataset,
@@ -180,7 +232,7 @@ export class SimActionExecutor {
      * @param {SimAction} action
      * @param {number} [sender_id] peer that originated this action.
      *   Defaults to {@link SENDER_LOCAL} for locally-originated actions.
-     *   Must be in `[0, 254]` for remote-originated actions.
+     *   Must be in `[0, MAX_PEER_ID]` for remote-originated actions.
      * @returns {boolean} true if the action was applied; false if it was
      *   rejected by the {@link authorize} gate (and therefore not applied or
      *   logged).
@@ -197,7 +249,18 @@ export class SimActionExecutor {
             `execute: action class '${action.constructor.action_type_name ?? action.constructor.name}' has no wire type_id — register it (NetworkSession.defineAction, or SimActionRegistry.register) before executing it`,
         );
         assert.isNonNegativeInteger(sender_id, 'sender_id');
-        assert.ok(sender_id <= 0xFF, 'sender_id must fit in a uint8');
+        // A sender above the peer range is either the sim-derived sentinel —
+        // which a rollback replay reads back as "this record is mine to
+        // recompute", so the peer's input would apply once and then disappear
+        // on the first replay of its frame, with nothing logged — or a value
+        // that does not fit the record's one byte at all. SENDER_LOCAL itself
+        // is the caller saying "mine". Real runtime check: asserts strip in
+        // 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}] — 254 and 255 are reserved provenance markers`,
+            );
+        }
 
         // Expose the originating sender to apply / affected_components / the
         // authorize policy before any of them run.
@@ -292,10 +355,14 @@ export class SimActionExecutor {
 
         // 5. Append the action itself.
         buffer.writeUint8(action.constructor.type_id);
-        // sender_id: peer that originated this action. Local-only record; not
-        // sent over the wire (Replicator strips it during pack). Used by
-        // rollback orchestrators for stable-sort tie-breaking.
-        buffer.writeUint8(sender_id);
+        // sender_id: where this record came from. Local-only; not sent over the
+        // wire (Replicator strips it during pack). Used by rollback
+        // orchestrators for stable-sort tie-breaking, and to tell input (which
+        // a replay reapplies) from derived output (which a replay recomputes).
+        // While `deriving` is set the record is stamped SENDER_DERIVED — the
+        // originating sender is not meaningful for output the sim computed for
+        // itself, and nothing reads it back on that path.
+        buffer.writeUint8(this.deriving ? SENDER_DERIVED : sender_id);
 
         // Reserve 4 bytes for action_payload_len, write payload, then back-patch.
         const action_len_position = buffer.position;

package/src/engine/network/transport/Channel.d.ts

@@ -9,7 +9,7 @@ export class Channel {
      *   an unacked seq falls more than half-range behind the newest sent, the
      *   signed `seq16_distance` used for loss detection wraps and the entry can
      *   neither be acked nor declared lost — a permanent leak (and a downstream
-     *   `seq_to_frame_end` leak in the orchestrator). Capping in-flight makes
+     *   `seq_to_pending` leak in the orchestrator). Capping in-flight makes
      *   that lap impossible. Default 1024 ≫ any realistic in-flight window
      *   (RTT × send-rate) yet ≪ 32768. Only reached under a sustained one-way
      *   stall, where eviction-as-lost is the correct verdict anyway.

package/src/engine/network/transport/Channel.js

@@ -64,7 +64,7 @@ export class Channel {
      *   an unacked seq falls more than half-range behind the newest sent, the
      *   signed `seq16_distance` used for loss detection wraps and the entry can
      *   neither be acked nor declared lost — a permanent leak (and a downstream
-     *   `seq_to_frame_end` leak in the orchestrator). Capping in-flight makes
+     *   `seq_to_pending` leak in the orchestrator). Capping in-flight makes
      *   that lap impossible. Default 1024 ≫ any realistic in-flight window
      *   (RTT × send-rate) yet ≪ 32768. Only reached under a sustained one-way
      *   stall, where eviction-as-lost is the correct verdict anyway.

package/src/engine/physics/fluid/ecs/FluidObstacleSystem.d.ts

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#370@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#371@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#370@#clear_field"(fluid: FluidComponent): void;
+    static "__#371@#clear_field"(fluid: FluidComponent): void;
     /**
      * Mark every cell of `fluid` whose centre lies within `inflation` of the
      * posed shape as solid. Iteration is clipped to the shape's world AABB
@@ -80,7 +80,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} inflation       world-units SDF threshold
      * @param {Float64Array} point     length-3 scratch
      */
-    static "__#370@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#371@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
     /**
      * Write the obstacle's translation velocity onto every face of every cell
      * it voxelized — the moving-wall boundary condition. Runs AFTER the mask
@@ -100,7 +100,7 @@ export class FluidObstacleSystem extends System<any> {
      * @param {number} wvy
      * @param {number} wvz
      */
-    static "__#370@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#371@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
     constructor();
     dependencies: (typeof FluidObstacle)[];
     components_used: (ResourceAccessSpecification<typeof Transform> | ResourceAccessSpecification<typeof RigidBody> | ResourceAccessSpecification<typeof Collider> | ResourceAccessSpecification<typeof FluidComponent> | ResourceAccessSpecification<typeof FluidObstacle>)[];

package/src/engine/simulation/Ticker.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Ticker.d.ts","sourceRoot":"","sources":["../../../../src/engine/simulation/Ticker.js"],"names":[],"mappings":";AAIA;;;;;;;;;;;;;;GAcG;AACH;IACI;;;OAGG;IACH,gBAFU,KAAK,CAEK;IAEpB;;;;;;;;;;;;OAYG;IACH,uBAFU,OAAO,CAEY;IAkC7B;;;;OAIG;IACH,qBAAsB;IAUtB;;;;OAIG;IACH,yBAEC;IAED;;;;OAIG;IACH,yBAEC;IAuGD;;;OAGG;IACH,uBAFW,MAAM,QA8EhB;IAED,cAWC;IAED,eAaC;IAED,aAYC;;CACJ;kBAxUiB,aAAa"}
+{"version":3,"file":"Ticker.d.ts","sourceRoot":"","sources":["../../../../src/engine/simulation/Ticker.js"],"names":[],"mappings":";AAIA;;;;;;;;;;;;;;GAcG;AACH;IACI;;;OAGG;IACH,gBAFU,KAAK,CAEK;IAEpB;;;;;;;;;;;;OAYG;IACH,uBAFU,OAAO,CAEY;IAkC7B;;;;OAIG;IACH,qBAAsB;IAUtB;;;;OAIG;IACH,yBAEC;IAED;;;;OAIG;IACH,yBAEC;IAuGD;;;OAGG;IACH,uBAFW,MAAM,QAiFhB;IAED,cAWC;IAED,eAaC;IAED,aAYC;;CACJ;kBA3UiB,aAAa"}