@woosh/meep-engine 3.14.5 → 3.15.0

package/src/engine/network/orchestrator/ServerAuthoritativeClient.js

@@ -1,12 +1,22 @@
 import { assert } from "../../../core/assert.js";
+import { BinaryBuffer } from "../../../core/binary/BinaryBuffer.js";
 import { Uint32Map } from "../../../core/collection/Uint32Map.js";
 import Signal from "../../../core/events/signal/Signal.js";
 import { AlwaysRelevantScope } from "../replication/ScopeFilter.js";
+import { ActionRecordCursor } from "../sim/ActionRecordCursor.js";
 import { RewindEngine } from "../sim/RewindEngine.js";
 import { InputRing } from "../state/InputRing.js";
 import { TimeDilation } from "../time/TimeDilation.js";
 import { NetworkPeer } from "./NetworkPeer.js";
 
+/**
+ * Ints per harvested record in {@link ServerAuthoritativeClient}'s replay index:
+ * action type id, sender id, and the offset of its payload.
+ *
+ * @type {number}
+ */
+const HARVEST_STRIDE = 3;
+
 /**
  * Client-side orchestrator for the predict-reconcile model.
  *
@@ -27,6 +37,19 @@ import { NetworkPeer } from "./NetworkPeer.js";
  *    {@link onReplay} handler re-executes the same SimActions the original
  *    predict path produced.
  *
+ *  - A replay also reapplies the records in the rewound window that ARRIVED
+ *    from a peer, which {@link onReplay} cannot: it re-executes this client's
+ *    own input, and the AUTH_STATE that precedes it carries one `network_id`.
+ *    Without this step a rewind about one entity discards the owner's published
+ *    state for every OTHER entity in the window — permanently, for anything
+ *    published on change rather than every frame, because nothing re-sends it
+ *    and nothing else restores it. This is the client half of the rule
+ *    `SimAction` states and `ServerAuthoritativeServer.#read_historical`
+ *    implements: a record's `sender_id` says whether it arrived, was authored,
+ *    or was derived, and a replay reapplies the first two and recomputes the
+ *    third. Here the authored half is `onReplay`'s job and the arrived half is
+ *    this one's.
+ *
  *  - A no-op short-circuit is built in: before doing the rewind+replay, the
  *    orchestrator gives the user a chance to compute what the replay WOULD
  *    produce via {@link onComputeExpected}; if that matches the current
@@ -55,6 +78,30 @@ export class ServerAuthoritativeClient {
     #expected_scratch;
     #measured_scratch;
 
+    /**
+     * Records of one log frame that arrived from a peer, indexed
+     * {@link HARVEST_STRIDE} ints apiece into {@link #harvest_payloads}. Filled
+     * by {@link #harvest_arrived} before the frame is reopened and drained by
+     * {@link #execute_harvested} once it is.
+     * @type {Int32Array}
+     */
+    #harvest_index = new Int32Array(HARVEST_STRIDE * 32);
+
+    /** @type {number} records currently described by {@link #harvest_index} */
+    #harvest_count = 0;
+
+    /**
+     * The harvested records' action payloads, back to back. A frame's bytes have
+     * to be copied out before the frame is reopened: opening it rewinds its
+     * buffer to zero and the re-execution then writes over exactly the bytes
+     * being read.
+     * @type {BinaryBuffer}
+     */
+    #harvest_payloads = new BinaryBuffer();
+
+    /** @type {ActionRecordCursor} */
+    #harvest_cursor = new ActionRecordCursor();
+
     // Counters
     /** @type {number} */
     reconcile_count = 0;
@@ -62,6 +109,22 @@ export class ServerAuthoritativeClient {
     /** @type {number} */
     replay_frame_count = 0;
 
+    /**
+     * Records that arrived from a peer and were reapplied by a replay, over the
+     * life of this client. Zero on a client whose peers publish nothing the
+     * rewind window covers; non-zero is the fix for the discard above doing
+     * work, and is what a test can assert on rather than inferring from a value.
+     * @type {number}
+     */
+    replayed_arrived_count = 0;
+
+    /**
+     * Reconciliations abandoned because the action log no longer held the frames
+     * the rewind needed. See {@link onReconcileAbandoned}.
+     * @type {number}
+     */
+    reconcile_abandoned_count = 0;
+
     /**
      * @param {{
      *   world: EntityComponentDataset,
@@ -261,6 +324,30 @@ export class ServerAuthoritativeClient {
          */
         this.onReconcileComplete = new Signal();
 
+        /**
+         * Fires when a reconciliation is abandoned because the action log no
+         * longer holds the frames its rewind needed. Args:
+         * `(server_frame, network_id)`.
+         *
+         * This is a real loss of replicated state and not a hiccup: state a peer
+         * does not own reaches it on the action stream, and an owner that
+         * publishes on change never sends it again — so whatever that window
+         * carried for every entity other than `network_id` is gone. The server
+         * would normally back-fill via `RECOVERY_REQUEST`/`STATE_BURST`, which
+         * is request-driven, so something has to know to ask. That is what this
+         * signal is for; {@link reconcile_abandoned_count} is the same event as
+         * a counter.
+         *
+         * A client seeing this repeatedly is running further ahead of the server
+         * frame than its `frame_capacity` covers.
+         *
+         * @type {Signal}
+         */
+        this.onReconcileAbandoned = new Signal();
+
+        // One packet's worth of action payloads, grown on demand from there.
+        this.#harvest_payloads.setCapacity(1024);
+
         // Wire the AUTH_STATE handler to the algorithm above.
         this.peer.onAuthState.add((_peer_id, server_frame, network_id, buffer) => {
             this.#handle_auth_state(server_frame, network_id, buffer);
@@ -379,17 +466,51 @@ export class ServerAuthoritativeClient {
 
         // Real divergence: rewind, apply server's bytes, replay forward.
         const rewind_target = server_frame - 1;
+        let rewound = false;
         if (this.#current_frame > rewind_target) {
             try {
                 this.rewind_engine.rewind_to(this.#current_frame, rewind_target);
+                rewound = true;
             } catch (e) {
-                // The action_log probably rolled past server_frame. The
-                // server would normally back-fill us via STATE_BURST; for now
-                // skip this reconciliation.
+                /*
+                 The action_log rolled past server_frame, so the window this
+                 reconciliation needs no longer exists and skipping it is the
+                 only option left. Counted and announced rather than swallowed:
+                 what the window carried for every entity other than this one is
+                 gone for good, and an application that cannot see that happen
+                 cannot ask for the back-fill that would repair it.
+                */
+                this.reconcile_abandoned_count++;
+                this.onReconcileAbandoned.send2(server_frame, network_id);
                 return;
             }
         }
 
+        /*
+         Frame `server_frame` was just undone and is NOT replayed below: the
+         AUTH_STATE is the server's state at the END of it, so re-running this
+         client's own input for that frame would apply that input twice.
+
+         Its ARRIVED records are the other half of the frame, and the half that
+         was being dropped. The bytes below repair one `network_id`; every other
+         entity the frame touched has nothing else to restore it. They go back in
+         BEFORE those bytes, so the authoritative value still wins wherever the
+         two describe the same component.
+
+         In the ordinary owner-scoped arrangement this is the frame that matters
+         most: the owner's records for a frame land in the log at the owner's
+         frame number, which is at or below `server_frame`, so they sit at the
+         very bottom of the rewound window rather than inside the replay range.
+        */
+        if (rewound && this.#harvest_arrived(server_frame) > 0) {
+            this.action_log.begin_frame(server_frame);
+            try {
+                this.#execute_harvested();
+            } finally {
+                this.action_log.end_frame();
+            }
+        }
+
         // Apply the server's authoritative state bytes. The handler does the
         // adapter-specific deserialize.
         this.onApplyAuthState.send3(server_frame, network_id, buffer);
@@ -397,6 +518,10 @@ export class ServerAuthoritativeClient {
         // Replay forward from (server_frame + 1) through current_frame.
         let replay_count = 0;
         for (let f = server_frame + 1; f <= this.#current_frame; f++) {
+            // Harvested before `begin_frame`, which rewinds the frame's buffer
+            // over the bytes being read. Nothing to harvest if nothing was undone.
+            const arrived = rewound ? this.#harvest_arrived(f) : 0;
+
             this.action_log.begin_frame(f);
             try {
                 let input_reader = null;
@@ -405,6 +530,15 @@ export class ServerAuthoritativeClient {
                     input_reader.position = 0;
                 }
                 this.onReplay.send2(f, input_reader);
+
+                /*
+                 After the local input, which is the order the frame was written
+                 in the first time: this client's prediction was logged as it
+                 ticked the frame, and the owner's mutations for that frame
+                 arrived later. It also leaves the owner's value last, which is
+                 the one that should win where both touch a component.
+                */
+                if (arrived > 0) this.#execute_harvested();
             } finally {
                 this.action_log.end_frame();
             }
@@ -416,6 +550,115 @@ export class ServerAuthoritativeClient {
         this.onReconcileComplete.send2(server_frame, replay_count);
     }
 
+    /**
+     * Copy the records of `frame` that arrived from a peer out of the action
+     * log, ready for {@link #execute_harvested} to put back.
+     *
+     * MUST be called before `action_log.begin_frame(frame)`. Opening a frame
+     * rewinds its buffer to zero without clearing it, and the re-execution
+     * writes over exactly the bytes this reads, so the payloads are copied into
+     * {@link #harvest_payloads} rather than read in place.
+     *
+     * Provenance decides what a replay does with a record, and this client keeps
+     * a narrower set than the server does:
+     *
+     *  - a CONNECTED peer's id — it arrived from that peer, and nothing else
+     *    here reproduces it. `onApplyAuthState` covers one `network_id` and
+     *    {@link onReplay} covers this client's own input. Kept.
+     *  - `SENDER_DERIVED` — output a replay recomputes. Skipped, same as
+     *    `ServerAuthoritativeServer.#read_historical` skips it.
+     *  - `SENDER_LOCAL`, and this client's own peer id — its own input, which
+     *    {@link onReplay} reapplies from the sampled-action ledger. Skipped:
+     *    reapplying it from the log as well would apply it twice.
+     *
+     * Connectedness is the test rather than a comparison against the local peer
+     * id because it is the same question stated directly — the sender byte of an
+     * arrived record is the peer it arrived from, and a client never connects to
+     * itself, so its own records can never match.
+     *
+     * @param {number} frame
+     * @returns {number} how many records were harvested
+     * @private
+     */
+    #harvest_arrived(frame) {
+        this.#harvest_count = 0;
+        this.#harvest_payloads.position = 0;
+
+        if (!this.action_log.has_frame(frame)) return 0;
+
+        const cursor = this.#harvest_cursor;
+        cursor.open(this.action_log, frame);
+        const bytes = cursor.buffer.raw_bytes;
+
+        while (cursor.next()) {
+            if (!this.peer.is_connected(cursor.sender_id)) continue;
+
+            if ((this.#harvest_count + 1) * HARVEST_STRIDE > this.#harvest_index.length) {
+                this.#grow_harvest_index();
+            }
+
+            const i = this.#harvest_count * HARVEST_STRIDE;
+            this.#harvest_index[i] = cursor.action_type_id;
+            this.#harvest_index[i + 1] = cursor.sender_id;
+            this.#harvest_index[i + 2] = this.#harvest_payloads.position;
+            this.#harvest_count++;
+
+            this.#harvest_payloads.writeBytes(bytes, cursor.payload_start, cursor.payload_len);
+        }
+
+        return this.#harvest_count;
+    }
+
+    /**
+     * Re-execute what {@link #harvest_arrived} took, in log order, into the
+     * currently-open frame.
+     *
+     * Going back through the executor is the point rather than an implementation
+     * detail: it captures each record's prior bytes again as it applies, so the
+     * reopened frame describes what is now live and the next rewind can undo it.
+     * A record whose action class is no longer registered is skipped — the same
+     * thing `Replicator.#apply_groups` does on the way in.
+     *
+     * @private
+     */
+    #execute_harvested() {
+        const payloads = this.#harvest_payloads;
+
+        for (let record = 0; record < this.#harvest_count; record++) {
+            const i = record * HARVEST_STRIDE;
+            const type_id = this.#harvest_index[i];
+            const sender_id = this.#harvest_index[i + 1];
+            const payload_start = this.#harvest_index[i + 2];
+
+            const klass = this.action_registry.klass_for(type_id);
+            if (klass === undefined) continue;
+
+            const action = this.action_registry.acquire(klass);
+            try {
+                payloads.position = payload_start;
+                action.deserialize(payloads);
+                // `execute` returns false when an authorization policy rejects
+                // the action, in which case nothing was applied or logged — so
+                // the counter follows the return value rather than the attempt.
+                if (this.executor.execute(action, sender_id)) {
+                    this.replayed_arrived_count++;
+                }
+            } finally {
+                this.action_registry.release(action);
+            }
+        }
+    }
+
+    /**
+     * @private
+     */
+    #grow_harvest_index() {
+        const old = this.#harvest_index;
+        const next = new Int32Array(old.length * 2);
+        next.set(old);
+        this.#harvest_index = next;
+    }
+
     /**
      * Helper for the {@link onComputeExpected} handler: stash the
      * computed scalar so the orchestrator can read it. Called inside the

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

@@ -52,6 +52,24 @@ export class Replicator {
             is_entity_in_scope(peer_id: number, network_id: number): boolean;
         };
     });
+    /**
+     * Per-peer delivery accounting. Read it, log it, put it on a HUD, fail a test on it.
+     *
+     * `skipped_unapplied` is the one that matters: frames that reached this receiver and were
+     * dropped below the watermark without ever being applied. It should be zero. It is not zero
+     * when slices reorder on a sender pinned to the ring floor, which is what
+     * `max_packets_per_tick: 1` produces under jitter.
+     *
+     * `skipped_duplicate` is the healthy counterpart — the action stream's own redundancy arriving
+     * and being correctly ignored — and is expected to be large.
+     *
+     * @param {number} peer_id
+     * @returns {{skipped_unapplied: number, skipped_duplicate: number}}
+     */
+    delivery_stats(peer_id: number): {
+        skipped_unapplied: number;
+        skipped_duplicate: number;
+    };
     /**
      * Fired after each per-frame action group is fully applied via
      * {@link unpack_from_peer}. Args: `(peer_id, frame_number)`.

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;IAkFI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OA8BpF;IA/ED;;;;;;;;;;;;;OAaG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,aAAa,YAAY,kBAAkB,MAAM,eAAe,MAAM,KAAK,IAAI,CAE/H;IAmBrB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH;oCAFwC,MAAM,cAAc,MAAM,GAAG,OAAO;MAE5C;IAGpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAVW,MAAM,eACN,MAAM,aACN,MAAM,cACN,YAAY,cACZ,MAAM,GACJ,MAAM,CA4ElB;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,QAmEtE;IAyLD;;;;;;;OAOG;IACH,qBAFW,MAAM,QAKhB;;CA8CJ;mBAxlBkB,uCAAuC;6BAD7B,sCAAsC"}
+{"version":3,"file":"Replicator.d.ts","sourceRoot":"","sources":["../../../../../src/engine/network/replication/Replicator.js"],"names":[],"mappings":"AAqBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH;IA4JI;;;;;;;;OAQG;IACH;;;;;;wCAHiD,MAAM,cAAc,MAAM,GAAG,OAAO;;OA8BpF;IA/HD;;;;;;;;;;;;;OAaG;IACH,wBAHW,MAAM,GACJ;QAAC,iBAAiB,EAAE,MAAM,CAAC;QAAC,iBAAiB,EAAE,MAAM,CAAA;KAAC,CAUlE;IA0BD;;;;;;;;;;;;;OAaG;IACH,gBAFU,MAAM,CAEc;IAE9B;;;;;;;;;;;;;;;;;OAiBG;IACH,6BAFqB,MAAM,gBAAgB,MAAM,kBAAkB,MAAM,aAAa,YAAY,kBAAkB,MAAM,eAAe,MAAM,KAAK,IAAI,CAE/H;IAmBrB;;OAEG;IACH,sBAA4B;IAE5B;;OAEG;IACH,mCAAsC;IAEtC;;OAEG;IACH,4BAAwB;IAExB;;OAEG;IACH,iCAA4B;IAE5B;;;;OAIG;IACH;oCAFwC,MAAM,cAAc,MAAM,GAAG,OAAO;MAE5C;IAGpC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,uBAVW,MAAM,eACN,MAAM,aACN,MAAM,cACN,YAAY,cACZ,MAAM,GACJ,MAAM,CA4ElB;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,QAmEtE;IAiND;;;;;;;OAOG;IACH,qBAFW,MAAM,QAKhB;;CA8CJ;mBA1rBkB,uCAAuC;6BAD7B,sCAAsC"}

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

@@ -93,6 +93,80 @@ export class Replicator {
      */
     #inbound = new Map();
 
+    /**
+     * Frames that arrived and were never applied, per peer, and the ones that were.
+     *
+     * **A skipped frame is not the same thing as a lost one, and until now neither was counted.**
+     * The action stream re-sends every unconfirmed frame each tick, so a frame arrives several
+     * times before its ack round-trips and every arrival after the first is skipped — correctly,
+     * and constantly. That is the normal case and it must not be counted as loss.
+     *
+     * What must be counted is the other one: a slice that arrives *after* a newer slice has raised
+     * the watermark past it, whose frames were therefore never applied and never will be, because
+     * its channel-level ack tells the sender they were delivered and nothing re-sends them. That is
+     * the failure `fb116d3a4` fixed for the default configuration and which
+     * `max_packets_per_tick: 1` still reproduces exactly — and the thing that made it expensive to
+     * find is that it is *silent*: a missing explosion looks like a rendering bug and nothing
+     * anywhere reports a shortfall.
+     *
+     * Telling the two apart needs one bit per frame in the window. `applied` is a ring of frame
+     * numbers indexed by `frame % capacity`, holding the frame that last wrote each slot, so a
+     * skipped frame can ask "was I ever applied?" in constant time and constant memory. A frame
+     * older than the window answers "no", which is right: it is beyond recovery either way.
+     *
+     * @type {Map<number, {applied: Int32Array, skipped_unapplied: number, skipped_duplicate: number}>}
+     * @private
+     */
+    #delivery = new Map();
+
+    /**
+     * Per-peer delivery accounting. Read it, log it, put it on a HUD, fail a test on it.
+     *
+     * `skipped_unapplied` is the one that matters: frames that reached this receiver and were
+     * dropped below the watermark without ever being applied. It should be zero. It is not zero
+     * when slices reorder on a sender pinned to the ring floor, which is what
+     * `max_packets_per_tick: 1` produces under jitter.
+     *
+     * `skipped_duplicate` is the healthy counterpart — the action stream's own redundancy arriving
+     * and being correctly ignored — and is expected to be large.
+     *
+     * @param {number} peer_id
+     * @returns {{skipped_unapplied: number, skipped_duplicate: number}}
+     */
+    delivery_stats(peer_id) {
+        const d = this.#delivery.get(peer_id);
+
+        if (d === undefined) {
+            return { skipped_unapplied: 0, skipped_duplicate: 0 };
+        }
+
+        return { skipped_unapplied: d.skipped_unapplied, skipped_duplicate: d.skipped_duplicate };
+    }
+
+    /**
+     * @param {number} peer_id
+     * @returns {{applied: Int32Array, skipped_unapplied: number, skipped_duplicate: number}}
+     * @private
+     */
+    #delivery_state(peer_id) {
+        let d = this.#delivery.get(peer_id);
+
+        if (d === undefined) {
+            const capacity = this.action_log.frame_capacity;
+
+            d = {
+                // -1 is "no frame has occupied this slot"; frame numbers are non-negative
+                applied: new Int32Array(capacity).fill(-1),
+                skipped_unapplied: 0,
+                skipped_duplicate: 0
+            };
+
+            this.#delivery.set(peer_id, d);
+        }
+
+        return d;
+    }
+
     /**
      * Fired after each per-frame action group is fully applied via
      * {@link unpack_from_peer}. Args: `(peer_id, frame_number)`.
@@ -396,6 +470,25 @@ export class Replicator {
             // corrupt the action-log prior-state capture (see #inbound).
             // The read cursor must still advance past this frame's actions.
             if (frame_number < min_frame) {
+                /*
+                 Was this one already applied, or is it being lost right now?
+
+                 Both look identical here — a frame below the watermark, walked past to keep the
+                 read cursor aligned — and the difference is the whole of GAP-043's residual. The
+                 ring says which: a slot still holding this frame number means it was applied and
+                 this is the action stream's own redundancy doing its job; anything else means the
+                 watermark moved past a frame that never ran, and nothing will re-send it because
+                 its channel-level ack already told the sender it arrived.
+                */
+                const delivery = this.#delivery_state(peer_id);
+                const slot = frame_number % delivery.applied.length;
+
+                if (delivery.applied[slot] === frame_number) {
+                    delivery.skipped_duplicate++;
+                } else {
+                    delivery.skipped_unapplied++;
+                }
+
                 for (let i = 0; i < action_count; i++) {
                     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})`);
@@ -443,6 +536,11 @@ export class Replicator {
                 this.action_log.end_frame();
             }
 
+            // Record that it ran, so a later arrival of the same frame is counted as the action
+            // stream's redundancy rather than as a loss. See #delivery.
+            const delivery = this.#delivery_state(peer_id);
+            delivery.applied[frame_number % delivery.applied.length] = frame_number;
+
             // Fire AFTER end_frame so handlers see consistent state and can
             // safely query the action log for the just-applied frame.
             this.onFrameApplied.send2(peer_id, frame_number);

package/src/engine/physics/ecs/PhysicsSystem.d.ts

@@ -835,6 +835,33 @@ export class PhysicsSystem extends System<any> {
      * {@link InterpolationSystem} blends consecutive ticks from these snapshots.
      * Only awake (moving) bodies are recorded, so the log stays sparse. No-op
      * unless {@link interpolationLog} is wired.
+     *
+     * **A body created after this pass has no snapshot for the step it was born on, and renders
+     * from one snapshot for a step.** This pass runs at the end of `fixedUpdate`, and game code
+     * runs after it — that ordering is correct, the sim must read the solved poses — so a body
+     * spawned by game code is invisible to the tick it was spawned into. Its first record is the
+     * NEXT tick, and `InterpolationLog.interpolate` handles the missing half gracefully by falling
+     * back to whichever snapshot exists. That is the right primitive behaviour and it produces a
+     * bad picture: the entity is drawn at the *newer* tick for a whole frame budget, so it appears
+     * to jump a full step's travel and then hold still for one. Measured at 165 Hz by a port
+     * (GAP-036) as four frames of a rocket parked at the muzzle, reported by a player as
+     * "projectiles move with jerks".
+     *
+     * **Why this is documented rather than fixed, which is the part worth knowing.** The obvious
+     * fix — record a body's pose when it links — does not fit this log. {@link InterpolationLog} is
+     * a strictly monotonic tick ring: `begin_tick` throws while a tick is open, pages are
+     * contiguous ranges that the next page's bytes follow immediately, and `#ticks` is keyed by
+     * tick number — so re-opening the closed tick to append one body would overwrite that tick's
+     * metadata for every other body in it. The fix that does work is to move this pass out of
+     * `fixedUpdate` into a system registered after every simulation system, which is what a
+     * consumer hitting this did; that costs a second mandatory registration, which is a trade this
+     * engine has decided against elsewhere. Closing it properly means either a per-body "first
+     * tick" the blend can consult, or a log that accepts an out-of-order record.
+     *
+     * The workaround needs no engine change: put the body on the application's own timeline via a
+     * pose recorder registered last, since `__interp_restore` does not filter by `sourceId` and
+     * `PhysicsSystem` still restores the authoritative pose before it integrates.
+     *
      * @private
      */
     private __interp_record;

package/src/engine/physics/ecs/PhysicsSystem.d.ts.map

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

package/src/engine/physics/ecs/PhysicsSystem.js

@@ -1839,6 +1839,33 @@ export class PhysicsSystem extends System {
      * {@link InterpolationSystem} blends consecutive ticks from these snapshots.
      * Only awake (moving) bodies are recorded, so the log stays sparse. No-op
      * unless {@link interpolationLog} is wired.
+     *
+     * **A body created after this pass has no snapshot for the step it was born on, and renders
+     * from one snapshot for a step.** This pass runs at the end of `fixedUpdate`, and game code
+     * runs after it — that ordering is correct, the sim must read the solved poses — so a body
+     * spawned by game code is invisible to the tick it was spawned into. Its first record is the
+     * NEXT tick, and `InterpolationLog.interpolate` handles the missing half gracefully by falling
+     * back to whichever snapshot exists. That is the right primitive behaviour and it produces a
+     * bad picture: the entity is drawn at the *newer* tick for a whole frame budget, so it appears
+     * to jump a full step's travel and then hold still for one. Measured at 165 Hz by a port
+     * (GAP-036) as four frames of a rocket parked at the muzzle, reported by a player as
+     * "projectiles move with jerks".
+     *
+     * **Why this is documented rather than fixed, which is the part worth knowing.** The obvious
+     * fix — record a body's pose when it links — does not fit this log. {@link InterpolationLog} is
+     * a strictly monotonic tick ring: `begin_tick` throws while a tick is open, pages are
+     * contiguous ranges that the next page's bytes follow immediately, and `#ticks` is keyed by
+     * tick number — so re-opening the closed tick to append one body would overwrite that tick's
+     * metadata for every other body in it. The fix that does work is to move this pass out of
+     * `fixedUpdate` into a system registered after every simulation system, which is what a
+     * consumer hitting this did; that costs a second mandatory registration, which is a trade this
+     * engine has decided against elsewhere. Closing it properly means either a per-body "first
+     * tick" the blend can consult, or a log that accepts an out-of-order record.
+     *
+     * The workaround needs no engine change: put the body on the application's own timeline via a
+     * pose recorder registered last, since `__interp_restore` does not filter by `sourceId` and
+     * `PhysicsSystem` still restores the authoritative pose before it integrates.
+     *
      * @private
      */
     __interp_record() {

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

@@ -64,11 +64,11 @@ export class FluidObstacleSystem extends System<any> {
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#371@#refresh_masks"(fluid: FluidComponent): void;
+    static "__#372@#refresh_masks"(fluid: FluidComponent): void;
     /**
      * @param {FluidComponent} fluid
      */
-    static "__#371@#clear_field"(fluid: FluidComponent): void;
+    static "__#372@#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 "__#371@#voxelize"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array): void;
+    static "__#372@#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 "__#371@#stamp_wall_velocity"(fluid: FluidComponent, posed: PosedShape3D, aabb: Float64Array, inflation: number, point: Float64Array, wvx: number, wvy: number, wvz: number): void;
+    static "__#372@#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/sound/SoundEngine.d.ts

@@ -13,6 +13,30 @@ declare class SoundEngine {
     sopra: SopraEngine | null;
     context: AudioContext;
     destination: GainNode;
+    /**
+     * @param {number} value
+     */
+    set volume(arg: number);
+    /**
+     * The one master fader in the graph, and the only one worth reaching for.
+     *
+     * Everything is downstream of {@link destination}: {@link obtainSopra}
+     * passes it as the sopra bus tree's output, and a `ProbeReverbRenderer` is
+     * constructed against the same node, so the dry mix and the wet return both
+     * pass through this gain.
+     *
+     * The bus named `master` inside sopra is NOT this. The probe reverb's
+     * return joins the graph BELOW the bus tree, so `busGraph.setVolume('master', 0)`
+     * silences the dry signal and leaves the wet tail of every sound at full
+     * level — audible, and audible only in reverberant rooms.
+     *
+     * This was an `Object.defineProperties` block, which the declaration
+     * generator does not read, so `sound.volume = 0.5` was a compile error
+     * against a property that exists and works.
+     *
+     * @returns {number}
+     */
+    get volume(): number;
     /**
      * Create and own the sopra engine, built on this SoundEngine's existing AudioContext + master
      * destination (never a second context). Wired in by the sound systems, which supply an

package/src/engine/sound/SoundEngine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SoundEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/sound/SoundEngine.js"],"names":[],"mappings":";AAEA;;;;GAIG;AACH;IACI;;;;OAIG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAkBO,sBAWd;IAUF,sBAA2B;IAiB/B;;;;;;;;;;OAUG;IACH,6CAFa,WAAW,CAQvB;IAED;;;OAGG;IACH,kBAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,iBAFa,QAAQ,IAAI,CAAC,CAMzB;IAED;;;OAGG;IACH,SAFa,QAAQ,GAAG,CAAC,CAWxB;CACJ;4BAzH2B,wBAAwB"}
+{"version":3,"file":"SoundEngine.d.ts","sourceRoot":"","sources":["../../../../src/engine/sound/SoundEngine.js"],"names":[],"mappings":";AAEA;;;;GAIG;AACH;IACI;;;;OAIG;IACH,OAFU,WAAW,GAAC,IAAI,CAEb;IAkBO,sBAWd;IAUF,sBAA2B;IA4B/B;;OAEG;IACH,wBAEC;IA5BD;;;;;;;;;;;;;;;;;;OAkBG;IACH,qBAEC;IASD;;;;;;;;;;OAUG;IACH,6CAFa,WAAW,CAQvB;IAED;;;OAGG;IACH,kBAFY,MAAM,CAIjB;IAED;;;;OAIG;IACH,iBAFa,QAAQ,IAAI,CAAC,CAMzB;IAED;;;OAGG;IACH,SAFa,QAAQ,GAAG,CAAC,CAWxB;CACJ;4BA3I2B,wBAAwB"}