@woosh/meep-engine 3.14.3 → 3.14.4

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

@@ -140,18 +140,40 @@ export class Replicator {
      *
      * Writes nothing if no in-scope actions are found.
      *
+     * `max_bytes` caps how many bytes this call may add. Frame groups are
+     * written whole or not at all: when the next group would cross the cap, the
+     * pack stops before it and the return value reports how far it got, so the
+     * caller can credit exactly what it sent and pick the rest up on a later
+     * pass. The one exception is a first group that does not fit by itself —
+     * that one is written anyway, because no smaller pack could ever carry the
+     * frame and dropping it would strand those actions forever.
+     *
      * @param {number} peer_id
      * @param {number} start_frame inclusive; if no frame in range is in the log, that frame is skipped
      * @param {number} end_frame inclusive
      * @param {BinaryBuffer} out_buffer
+     * @param {number} [max_bytes] byte budget for this call; unbounded by default
+     * @returns {number} the last frame this pack covers, or `start_frame - 1` if
+     *   it covers nothing. A frame that was skipped — absent from the log, or
+     *   holding nothing in scope — counts as covered: the receiver has nothing
+     *   to apply for it, so the caller may credit it.
      */
-    pack_for_peer(peer_id, start_frame, end_frame, out_buffer) {
+    pack_for_peer(peer_id, start_frame, end_frame, out_buffer, max_bytes = Number.MAX_SAFE_INTEGER) {
         assert.isNonNegativeInteger(peer_id, 'peer_id');
         assert.isNonNegativeInteger(start_frame, 'start_frame');
         assert.isNonNegativeInteger(end_frame, 'end_frame');
 
+        // Budget is measured from wherever the caller had already written to,
+        // so a caller that prefixed a packet-type byte gets it counted.
+        const budget_end = out_buffer.position + max_bytes;
+        let last_packed = start_frame - 1;
+        let wrote_any_group = false;
+
         for (let frame = start_frame; frame <= end_frame; frame++) {
-            if (!this.action_log.has_frame(frame)) continue;
+            if (!this.action_log.has_frame(frame)) {
+                last_packed = frame;
+                continue;
+            }
 
             const buffer = this.action_log.buffer_for(frame);
             const end = this.action_log.write_end_for(frame);
@@ -173,9 +195,15 @@ export class Replicator {
                 }
             }
 
-            if (in_scope_count === 0) continue;
+            if (in_scope_count === 0) {
+                last_packed = frame;
+                continue;
+            }
 
             // Second pass: write the frame header + each in-scope action's payload only.
+            // The group's encoded size is only known once written (varint frame
+            // numbers and counts), so write it and roll back if it overran.
+            const group_start = out_buffer.position;
             out_buffer.writeUintVar(frame);
             out_buffer.writeUintVar(in_scope_count);
 
@@ -184,7 +212,20 @@ export class Replicator {
                 buffer.position = rs;
                 this.#copy_action_to(buffer, out_buffer);
             }
+
+            if (wrote_any_group && out_buffer.position > budget_end) {
+                // Doesn't fit alongside what we already have. Un-write it and
+                // stop — the caller credits only up to the previous frame and
+                // this one leads the next pack.
+                out_buffer.position = group_start;
+                break;
+            }
+
+            wrote_any_group = true;
+            last_packed = frame;
         }
+
+        return last_packed;
     }
 
     /**

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

@@ -12,7 +12,7 @@
  *     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)
@@ -22,8 +22,18 @@
  * which means rewind code can walk records forward to find boundaries, then
  * iterate backward to apply prior states — no need to instantiate any actions.
  *
- * 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.
  *
@@ -60,6 +70,14 @@ export class ActionLog {
      * Close the currently-open frame.
      */
     end_frame(): void;
+    /**
+     * 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(): boolean;
     /**
      * Get the buffer for the currently-open frame for direct writing.
      *

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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH;IAoBI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;;OAIG;IACH,sCAEC;IAED;;;;OAIG;IACH,mBAFW,MAAM,QAShB;IAED;;OAEG;IACH,kBASC;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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH;IAoBI;;OAEG;IACH,qDAFW;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;KAAE,EAIlE;IAED;;;;OAIG;IACH,sCAEC;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"}

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)
@@ -24,8 +24,18 @@ import { FrameBufferRing } from "../state/FrameBufferRing.js";
  * which means rewind code can walk records forward to find boundaries, then
  * iterate backward to apply prior states — no need to instantiate any actions.
  *
- * 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 +112,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/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,24 @@ 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, so it covers nested `execute` calls made from an
+     * action's `apply` during that span. Everything else — 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}
      */

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;IA4DI;;;;;;;;;OASG;IACH,sGATW;QACV,KAAS,yBAAyB;QAClC,UAAc,YAAY;QAC1B,eAAmB,oBAAoB;QACvC,kBAAsB,8BAA8B;QACpD,UAAc,uBAAuB;QACrC,gBAAoB,CAAC,mBAAmB;KACrC,EAyFH;IAxJD;;;;;;;;;OASG;IACH,gBAFU,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,CAEP;IAEtB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,uBAFuB,MAAM,aAAa,MAAM,wBAAwB,OAAO,CAE9D;IAEjB;;;;;;;;;;;;;;;;OAgBG;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;mBA5XkB,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,25 @@ 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, so it covers nested `execute` calls made from an
+     * action's `apply` during that span. Everything else — 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,
@@ -197,6 +250,17 @@ 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');
+        // A remote sender that reaches a provenance sentinel would be recorded
+        // as local-authored or sim-derived, and a rollback replay reads the
+        // sentinel 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. 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 reserved (SENDER_DERIVED); remote peer ids must be in [0, ${MAX_PEER_ID}]`,
+            );
+        }
         assert.ok(sender_id <= 0xFF, 'sender_id must fit in a uint8');
 
         // Expose the originating sender to apply / affected_components / the
@@ -292,10 +356,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/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"}

package/src/engine/simulation/Ticker.js

@@ -278,7 +278,10 @@ class Ticker {
 
         this.#addLifecycleListeners();
 
-        requestAnimationFrame(animationFrameCallback);
+        //recorded, so a stop() taken before the first frame lands can cancel it. The generation guard
+        //already makes the callback a no-op, but an uncancelled frame request keeps the closures (and
+        //everything the tick listeners hold) alive until it fires
+        this.#animationFrameHandle = requestAnimationFrame(animationFrameCallback);
 
         //if we are starting while the page is already in the background, suspend right away
         const doc = globalThis.document;

package/src/engine/ui/GUIEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GUIEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/ui/GUIEngine.js"],"names":[],"mappings":";AA4BA;IACI,mBAAqB;IAErB;;;OAGG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;;OAGG;IACH,eAAc;IAEd;;;OAGG;IACH,eAFU,eAAe,eAAe,CAAC,CAEX;IAE9B;;;OAGG;IACH,UAFU,cAAc,CAEQ;IAEhC;;;OAGG;IACH,cAFU,iBAAiB,CAEyB;IAGpD;;;OAGG;IACH,QAFU,MAAM,CAEM;IAEtB,gBAOG;IAEH;;;OAGG;IACH,KAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,QAFU,cAAc,CAEuB;IAG/C;;;OAGG;IACH,cAFU,eAAa,IAAI,CAEP;IAqBpB;;;;;;OAMG;IACH,mDANW,OAAO,GAIL,MAAM,CAoClB;IAED;;;;;;OAMG;IACH,0CALW,IAAI,GAGF,eAAe,CA+D3B;IAED;;;;;;OAMG;IACH,iEALW,MAAM,GAGJ,QAAQ,GAAG,CAAC,CA0DxB;IAED;;;;OAIG;IACH,mCAJW,MAAM,gBAWhB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,gBAUhB;IAED;;;;;;;;OAQG;IACH,gEAPW,IAAI,gBA0Dd;IAED;;;;OAIG;IACH,kCAFY,eAAe,CAgB1B;IAED;;OAEG;IACH,yBAFa,eAAe,GAAC,IAAI,CAkBhC;IAED;;;OAGG;IACH,8BAKC;IAED;;;OAGG;IACH,wCAiEC;IAED,2BAYC;CACJ;iBAxgBgB,oCAAoC;gCAyBrB,4BAA4B;+BAf7B,sCAAsC;kCAFnC,yCAAyC;mBAexD,yBAAyB;sBAjBtB,kCAAkC;0BAG9B,qCAAqC;2BAPpC,oCAAoC;mBAiB5C,kBAAkB;iBAPpB,oBAAoB;gCATqB,uCAAuC"}
+{"version":3,"file":"GUIEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/ui/GUIEngine.js"],"names":[],"mappings":";AA4BA;IACI,mBAAqB;IAErB;;;OAGG;IACH,eAFU,gBAAc,IAAI,CAEP;IAErB;;;OAGG;IACH,eAAc;IAEd;;;OAGG;IACH,eAFU,eAAe,eAAe,CAAC,CAEX;IAE9B;;;OAGG;IACH,UAFU,cAAc,CAEQ;IAEhC;;;OAGG;IACH,cAFU,iBAAiB,CAEyB;IAGpD;;;OAGG;IACH,QAFU,MAAM,CAEM;IAEtB,gBAOG;IAEH;;;OAGG;IACH,KAFU,SAAS,CAEG;IAEtB;;;OAGG;IACH,QAFU,cAAc,CAEuB;IAG/C;;;OAGG;IACH,cAFU,eAAa,IAAI,CAEP;IAqBpB;;;;;;OAMG;IACH,mDANW,OAAO,GAIL,MAAM,CAoClB;IAED;;;;;;OAMG;IACH,0CALW,IAAI,GAGF,eAAe,CA+D3B;IAED;;;;;;OAMG;IACH,iEALW,MAAM,GAGJ,QAAQ,GAAG,CAAC,CA0DxB;IAED;;;;OAIG;IACH,mCAJW,MAAM,gBAWhB;IAED;;;;;OAKG;IACH,iCAJW,MAAM,gBAUhB;IAED;;;;;;;;OAQG;IACH,gEAPW,IAAI,gBA0Dd;IAED;;;;OAIG;IACH,kCAFY,eAAe,CAgB1B;IAED;;OAEG;IACH,yBAFa,eAAe,GAAC,IAAI,CAkBhC;IAED;;;OAGG;IACH,8BAKC;IAED;;;OAGG;IACH,wCAiEC;IAED,2BAkBC;CACJ;iBA9gBgB,oCAAoC;gCAyBrB,4BAA4B;+BAf7B,sCAAsC;kCAFnC,yCAAyC;mBAexD,yBAAyB;sBAjBtB,kCAAkC;0BAG9B,qCAAqC;2BAPpC,oCAAoC;mBAiB5C,kBAAkB;iBAPpB,oBAAoB;gCATqB,uCAAuC"}

package/src/engine/ui/GUIEngine.js

@@ -506,6 +506,12 @@ class GUIEngine {
     }
 
     shutdown() {
+        // startup() armed this loop, so shutdown() is what has to disarm it. Left running it keeps
+        // animating views against a GUI that has been torn down, and its frame/timer chain outlives
+        // the host it belonged to - under a test environment that means calling
+        // requestAnimationFrame after the environment that provided it is gone.
+        this.ticker.stop();
+
         this.windows.reset();
         this.entityManager = null;
 

package/src/shade/playground/particle_system/README.md

@@ -0,0 +1,98 @@
+# GPU particle system — playground
+
+The whole GPU particle path running in a real scene: emitters, the VM, the alive/dead lists and the
+billboard renderer, driven end to end by the GPU with no renderer, no assets and no `Renderer`
+dependency. It moved here from `renderer/particles/prototypeParticleSystem.js`, which had no page to
+open it with.
+
+## Running it
+
+```bash
+npm run dev --workspace @woosh/meep-engine
+```
+
+then open <http://localhost:5173/src/shade/playground/particle_system/index.html>.
+
+It has to be `http://localhost` rather than `file://`: WebGPU needs a secure context, and module
+imports from `file://` are blocked by CORS anyway. The page imports nothing but meep's own relative
+ESM, so any static server rooted at the repo also serves it.
+
+**It needs immediate data**, and refuses to start without it. Emit, simulate and build-indirect each
+carry their per-dispatch state (`u_dt`, `u_time`, `u_frame`, and for emit the request count and the
+pool capacity) as an immediate block rather than as a transient uniform buffer, so an adapter whose
+WGSL lacks the `immediate` address space cannot build any of the three. The refusal names the byte
+counts. Chrome/Edge 113+ with immediates; Claude Code's in-app browser pane is **not** one — it
+reports no adapter at all today, and no `immediate_address_space` in `wgslLanguageFeatures`.
+
+## What is on screen
+
+Four emitters sharing one 32k pool, chosen so each renderer path is visible at once:
+
+| emitter | blend | projection | what it is there to show |
+|---|---|---|---|
+| fire | additive | billboard | `fire_effect()` straight out of `particle_prototype.js`, at the foot of the pillar |
+| smoke | alpha | billboard, soft-depth | a rising column that fades where it meets the pillar rather than cutting into it |
+| sparks | additive | **stretched** | short-lived, gravity-fed, stretched along velocity — the one non-billboard projection |
+| dust | alpha | billboard, soft-depth | a wide slow drift, so the ground plane and the low wall both get a soft intersection |
+
+Ground plane and three boxes are drawn first into a reverse-Z `depth32float` buffer. The billboard
+pass loads that colour target and depth-tests against the same buffer read-only, so particles are
+**occluded** by the boxes and the soft-depth emitters sample the depth they were occluded by.
+
+Things worth looking at:
+
+- particles disappearing behind the pillar as the camera orbits — that is the depth test,
+- smoke and dust softening where they touch a surface instead of showing a hard intersection line —
+  that is `PARTICLE_FLAG_SOFT_DEPTH` and the reverse-Z linearisation,
+- sparks leaning into their own velocity — `EMITTER_PROJECTION.STRETCHED`,
+- both blend modes in **one** draw with one pipeline: `particle_premultiply` picks per particle, so
+  there is no additive pass and no alpha pass.
+
+The overlay shows fps and, every 30 frames, the alive count, the free-list length and the two
+indirect arg buffers. Those are read back **to look at**. Nothing on the CPU sizes a pass.
+
+## The property the page exists to demonstrate
+
+The frame is GPU-driven end to end. `shader_particle_build_indirect` writes both the simulate
+dispatch args and the billboard draw args on the GPU; the next frame's simulate runs through
+`dispatchWorkgroupsIndirect` and this frame's draw through `drawIndirect`. The host's only sizing
+decision is how many *new* particles to spawn, which is a per-emitter rate times `dt` and has
+nothing to do with how many are already alive.
+
+Sizing either from a CPU readback instead would be a correctness bug rather than a latency one: a
+stale count that is too small leaves the tail of the alive list unsimulated, so those slots are
+never freed, and one that is too large re-simulates entries past the end, pushing a dead slot onto
+the free list twice — it is then popped twice and two live particles share one record.
+
+## Verifying it
+
+`particle_scene.js` holds the scene with every reference to the page removed, so
+`particle_scene.spec.js` can encode the same frames against `SoftwareGPUDevice`:
+
+```bash
+npx vitest run src/shade/playground/particle_system/particle_scene.spec.js
+```
+
+That mock runs no shaders, so the spec asserts nothing about what a pass computed. What it does
+assert is that the frame is legal and wired the way the design requires — pass order and
+attachments, the alive lists ping-ponging so no frame reads the list it appends to, the immediate
+blocks written before every dispatch that declares them, and simulate and the draw both taking their
+counts from the indirect buffers. Any WebGPU validation failure anywhere in the frame arrives as an
+uncaptured error, which every test fails on.
+
+The picture is the browser's job; the spec cannot see it.
+
+### Stepping frames by hand
+
+Add `?debug` to the URL. `requestAnimationFrame` is then not used at all, and `window.__step(n)`
+runs exactly `n` frames and returns the frame counter — which is what makes the loop drivable in a
+hidden or headless tab, where rAF is suspended. `window.__stats` carries the last counters snapshot.
+
+## What this page does not cover
+
+Depth sorting. `EMITTER_FLAG.SORT` and the bucketed depth sort in `particles/sort/` (histogram →
+csdldf scan → scatter) are not wired in here: the billboard pass draws the alive list directly, so
+alpha-blended emitters are in emission order rather than back-to-front. The two soft-depth emitters are faint and diffuse enough that it
+does not read as wrong, which is exactly why it should not be taken as evidence that sorting works.
+Lighting is the unlit hook, too — `chunk_particle_lighting_unlit`, not the shading-chunk-backed one
+the renderer feature swaps in.