@woosh/meep-engine 2.168.1 → 2.169.1

package/src/REVIEW_2026_08_06/bvh-phys-sound-net.md

@@ -0,0 +1,507 @@
+# Targeted correctness review — bvh2 / bvh8 / physics / sound / network
+
+Scope: `core/bvh2`, `core/bvh8`, and — for `engine/physics`, `engine/sound`, `engine/network` —
+the files with no adjacent `<name>.spec.js`, plus the ECS-facing bridge, the WebAudio rendering
+edge, and the transport/session boundary.
+
+Known-good areas were not re-opened (solver core, narrowphase, fluid MAC, acoustic simulator,
+seq/ack math, slot tables, bvh8 review-01 contracts, bvh2 `ebvh_sort`/`swap_nodes`).
+
+Already-reported items excluded: `FragmentAssembler.js:59` 64 KiB cap vs 302 KiB sender capacity;
+`SoundControllerSystem.js:82` log-then-dereference.
+
+---
+
+## Findings
+
+### PSN-1 AUTH_STATE reconcile gate is per-frame, not per-entity — all but one entity per frame is dropped
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/network/orchestrator/ServerAuthoritativeClient.js:332`
+- **Defect**: `#handle_auth_state` short-circuits on `if (server_frame <= this.#last_reconciled_frame) return;` — a single scalar watermark shared by *all* entities. The host emits one AUTH_STATE **per owned entity per tick**, all tagged with the same `sim_frame`, so every entity after the first is silently discarded.
+- **Failure scenario**: `NetworkSession.#on_host_tick_complete` (`NetworkSession.js:1376-1391`) loops every replicated entity owned by `peer_id` and calls `#send_auth_state_for_entity(peer_id, sim_frame, …)`. A client that owns two predicted entities (player + mount, or player + carried object) receives AUTH_STATE(frame=100, netid=A) then AUTH_STATE(frame=100, netid=B). A reconciles; B hits `100 <= 100` and returns before `slot_table.entity_for` is even consulted. B is **never** reconciled at any frame — the same thing happens on frame 101, 102, … So B's prediction drifts without bound and never converges to the server state.
+- **Fix**: Make the watermark per-`network_id`: replace `#last_reconciled_frame` with a `Map<number, number>` (or a slot-indexed `Int32Array`) keyed by `network_id`, and compare/update the entry for the incoming `network_id`.
+- **Confidence**: Confirmed
+
+### PSN-2 Client reconnect ladder: every attempt after the first throws inside `connect()` and is swallowed
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/network/NetworkSession.js:1824-1830`
+- **Defect**: `#tick_reconnect` dials a fresh transport with `this.connect(this.#remote_peer_id, new_transport)` but never tears down the *previous* attempt's binding. `NetworkPeer.connect_peer` throws `peer N already connected` (`NetworkPeer.js:451-453`) on every attempt after the first; the throw is caught and reduced to a `console.warn`. The abandoned transport is also dropped without `disconnect()`.
+- **Failure scenario**: Client on a connectionless transport (`NodeUDPTransport`, WebTransport datagrams) whose `onDisconnect` never fires on its own. Attempt 1 builds transport T1, connects, sends RESUME_HELLO — the datagram is lost. Attempt 2 (t+400 ms) builds T2, `connect()` throws (`peer 0 already connected`), warn, retry. Attempts 3-8 identical. Attempt 9 exceeds `max_attempts: 8` → `#permanently_lose_connection('reconnect_attempts_exhausted')`. **A single lost RESUME_HELLO packet permanently kills a session that is configured to tolerate 8 retries**, and 7 transports (7 UDP sockets) are created and leaked in the process. `NetworkSession.spec.js:900-914` asserts only on the `onReconnectAttempt` *signal* count, so it passes despite the connects failing.
+- **Fix**: In `#tick_reconnect`, before dialing: `this.#peer.disconnect_peer(this.#remote_peer_id)` if still bound, and call `disconnect()` on `this.#current_transport` if non-null; then `connect()`. (Equivalently, factor out the teardown half of `#on_client_transport_disconnected` and call it at the top of each attempt.)
+- **Confidence**: Confirmed
+
+### PSN-3 A failed rewind leaves the client world partially rewound, with no replay and no repair
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/network/orchestrator/ServerAuthoritativeClient.js:370-379`
+- **Defect**: `RewindEngine.rewind_to` undoes frames one at a time (`RewindEngine.js:107-109`) and `undo_frame` throws when a frame has aged out of the ring. By then the earlier frames have **already been undone in place**. `#handle_auth_state` catches the throw and `return`s — the server bytes are not applied, no forward replay runs, and `#last_reconciled_frame` has already been advanced.
+- **Failure scenario**: `frame_capacity = 32`, client at `#current_frame = 200` (log holds 169..200). A delayed AUTH_STATE for `server_frame = 150` arrives (latency spike / reorder). `rewind_to(200, 149)` successfully undoes 200 → 169, then `undo_frame(168)` throws. The catch swallows it and returns. The live world is now in **end-of-168** state — 32 frames of simulation silently reverted, nothing replayed forward. Every visible entity jumps backwards and the client continues simulating from the stale state.
+- **Fix**: Validate the whole range before mutating anything: `for (let f = this.#current_frame; f > rewind_target; f--) if (!this.action_log.has_frame(f)) { /* skip reconciliation, request STATE_BURST */ return; }` — then call `rewind_to` outside the try, so a genuine engine bug still surfaces instead of being swallowed.
+- **Confidence**: Confirmed
+
+### PSN-4 Grace-window expiry never tears down a peer that reconnected but did not resume
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/network/NetworkSession.js:1655-1664`
+- **Defect**: `connect()`'s host path for a peer already in the grace window (`NetworkSession.js:857-869`) calls `#server.connect_peer` and `#wire_peer_transport_disconnect`, but deliberately does **not** add the peer to `#connected_peers` (it waits for RESUME_HELLO). `#expire_grace_peers` only deletes the grace entry + token and fires `onPeerPermanentlyDropped` — it never calls `#server.disconnect_peer` or `#unwire_peer_transport_disconnect`.
+- **Failure scenario**: Peer 1 drops → grace. Client re-dials; `host_session.connect(1, T2)` runs. Its RESUME_HELLO is lost (or the client dies before sending one). 30 s later grace expires and the host reports the peer permanently dropped — but `NetworkPeer.#peers` still holds peer 1's `Channel` (still subscribed to T2's `onReceive`), the transport's `onDisconnect` listener is still installed, and `NetworkPeer.flush_outbound` (`NetworkPeer.js:838`) iterates `#peers`, **not** `#connected_peers`, so the host keeps packing and transmitting the full action stream to the ghost peer every tick forever. A later `connect(1, T3)` then throws `peer 1 already connected`.
+- **Fix**: In `#expire_grace_peers`, before firing the signal: `if (this.#peer.is_connected(peer_id)) this.#server.disconnect_peer(peer_id); this.#unwire_peer_transport_disconnect(peer_id); this.#peer_inbound_mark.delete(peer_id); this.#pending_initial_sync.delete(peer_id);`
+- **Confidence**: Confirmed
+
+### PSN-5 `NetworkSession.stop()` does not tear down the network
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/network/NetworkSession.js:974-988`
+- **Defect**: `stop()` is documented as "Tear down. Idempotent — safe to call from cleanup paths." It disconnects the `EntityObserver` and removes the per-entity event listeners, but leaves every `Channel` subscribed to its transport's `onReceive`, every transport `onDisconnect` listener installed (`#peer_transport_listeners` is never walked), and `#connected_peers` / `#peer_grace_state` / `#peer_session_tokens` / `#pending_initial_sync` populated.
+- **Failure scenario**: A host session with three connected peers is torn down at level transition via `stop()`; the caller then builds a new world + session. A datagram arriving on any of the three still-live transports still runs `Channel.onPayload → NetworkPeer.dispatch → replicator.unpack_from_peer → executor.execute`, mutating the **old, supposedly detached** `EntityComponentDataset` (and, for `net_mutate_component`, dereferencing entities the caller already destroyed). Peer transport disconnects likewise still mutate `#peer_grace_state` on the dead session. Worse on the restart path: `stop()` clears `#started`, and `start()` only rejects when `#started` is true (`NetworkSession.js:651`) — so `stop(); await start();` is permitted and constructs a *second* orchestrator and `NetworkPeer` while the first one's channels are still consuming from the same transports, and `#connected_peers` still holds the old peer ids, so the very first `#send_empty_ack_packet` calls `channel_for(peer_id).send(...)` on the *new* peer (which has no such peer) and throws `TypeError` out of `tick()`.
+- **Fix**: In `stop()`, iterate `#connected_peers` (and `#peer_transport_listeners`) calling `#peer.disconnect_peer(id)` + `#unwire_peer_transport_disconnect(id)`, then clear `#connected_peers`, `#peer_grace_state`, `#peer_session_tokens`, `#pending_initial_sync`, `#peer_transport_listeners`, and (client) remove `#current_transport_listener`.
+- **Confidence**: Confirmed
+
+### PSN-6 RESUME_HELLO from an already-connected peer is handled as a fresh connect, re-arming a full INITIAL_SYNC on demand
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/network/NetworkSession.js:1582-1591`
+- **Defect**: When `#peer_grace_state` has no entry, the handler's own comment acknowledges the two cases are conflated — "the peer is fully unknown **OR** they're already connected" — and treats both as a fresh peer: `#pending_initial_sync.set(transport_peer_id, 2)`. There is no check that the peer is currently in `#connected_peers`. RESUME_HELLO is only legitimate in the not-connected state.
+- **Failure scenario**: A connected (authenticated, non-malicious-looking) client sends a RESUME_HELLO packet on every tick. Each one re-arms `#pending_initial_sync`, so `#on_host_tick_complete` (`NetworkSession.js:1358-1372`) emits a **full Snapshotter dump of every replicated entity** to that peer every tick, indefinitely — a fragmented multi-hundred-kilobyte send driven by a ~24-byte inbound packet, sustained. On a populated world this saturates the host's uplink and starves every other peer's action stream.
+- **Fix**: At the top of `#on_resume_hello`, if `this.#connected_peers.has(transport_peer_id)` and there is no grace record, the peer is already live: send `RESUME_ACCEPT` (or drop the packet) and return without touching `#pending_initial_sync`.
+- **Confidence**: Confirmed
+
+### PSN-7 NACK_FRAGMENT retransmit is unbounded in count and undeduplicated
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/network/orchestrator/NetworkPeer.js:548-563`
+- **Defect**: `missing_count` is a peer-supplied uint8 read straight into the resend loop, and the listed `chunk_index` values are never deduplicated or checked against the message's actual `total_chunks` distribution. `resend_fragment_chunk` bounds each *index* (`fragment_send.js:130`), but nothing bounds the *number* of resends per NACK packet.
+- **Failure scenario**: Peer sends one NACK_FRAGMENT of 4 + 255 = 259 payload bytes naming chunk index 0 two-hundred-fifty-five times for a live retained `message_id`. The sender emits 255 fragment packets of 1191 bytes each = ~304 KB — a ~1170× amplification off one small datagram, repeatable up to `FRAGMENT_RETENTION_MAX_RETRIES` (3) per retained message and across all 16 retained slots.
+- **Fix**: Clamp the loop to the message's real chunk count (`Math.ceil(entry.length / MAX_FRAGMENT_CHUNK_BYTES)`) and skip an index already resent within this NACK (a small `Uint8Array` seen-set, or require strictly-ascending indices and drop the packet otherwise).
+- **Confidence**: Confirmed
+
+### PSN-8 `onStateBurst` `length` argument contradicts its documented contract
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/network/orchestrator/NetworkPeer.js:513`
+- **Defect**: The signal is documented (`NetworkPeer.js:356-360`) as passing "`length` … the byte count of the burst payload (**not counting the prefix**)", but `dispatch` forwards its own `length`, which is the whole packet including the leading packet-type byte.
+- **Failure scenario**: A library consumer writes the documented loop `const end = buffer.position + length;` (position is 1, just past the prefix) and iterates entities until `buffer.position >= end`. `end` is one byte too large, so after the last entity the loop runs once more and `readUintVar()` consumes a byte of the next packet's stale scratch content — producing a bogus `network_id` and, for a trailing zero byte, an entity write to slot 0.
+- **Fix**: Pass `length - 1`, or change the JSDoc to say the value is the full packet length and that the payload ends at absolute offset `length` (matching what `INITIAL_SYNC` already does).
+- **Confidence**: Confirmed
+
+### PSN-24 `NodeUDPTransport.send` hands the caller's reusable buffer straight to async `dgram.send` without copying
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/network/transport/adapters/NodeUDPTransport.js:138-139`
+- **Defect**: `Transport.send`'s contract is explicit (`Transport.js:78-84`): *"Caller may reuse `bytes` immediately after the call returns; transport implementations must copy if they need to defer delivery."* `NodeUDPTransport.send` passes `bytes.subarray(0, length)` — a live view of `Channel.#send_buffer` — directly to `this.socket.send(...)`. `dgram.send` tries `uv_udp_try_send` first, but on `UV_EAGAIN` (kernel send buffer full) it queues the request against the *same* memory; the contents must stay valid until the send callback, and Node does not copy them. `WebSocketTransport.send` has the same shape but is safe because `WebSocket.send()` is specified to enqueue a copy.
+- **Failure scenario**: `NetworkPeer.#send_to_peer` fragments a large STATE_BURST or INITIAL_SYNC: `send_fragmented` builds each chunk into the single shared `#fragment_scratch` and calls `channel.send(chunk, len)` in a tight loop; `Channel.send` copies each chunk into its single `#send_buffer` and calls `transport.send(#send_buffer, total)`. A 300 KB message is 255 back-to-back datagrams — enough to fill the default UDP send buffer, so later `uv_udp_try_send` calls return `EAGAIN` and queue. The loop then overwrites `#send_buffer` in place for the next chunk, so the queued datagrams all serialize the *later* chunk's bytes, including its fragment header. The receiver sees repeated `chunk_index` values (deduped as retransmits by `FragmentAssembler.receive:175`), `received_count` never reaches `total_chunks`, the NACK rounds exhaust, and the message is dropped — the initial sync never lands and the peer never joins.
+- **Also affected**: `WebTransportTransport.js:125,131` — `this.#writer.write(payload)` enqueues the same non-copied view into a `WritableStream`; the sink's `write` algorithm runs on a later microtask, by which time `Channel.#send_buffer` has been overwritten. (`WebSocketTransport.js:106` and `WebRTCDataChannelTransport.js:92-96` are safe: both `WebSocket.send` and `RTCDataChannel.send` are specified to copy the `BufferSource` synchronously. `LoopbackTransport` / `SimulatedTransport` copy explicitly.)
+- **Fix**: Copy in the two async adapters before handing the bytes over: `const payload = bytes.slice(0, length);` (a real copy, not `subarray`) in `NodeUDPTransport.send` and `WebTransportTransport.send`.
+- **Confidence**: Likely (the contract violation and the burst pattern are certain; whether a given send actually queues depends on kernel send-buffer / stream-backpressure state)
+
+### PSN-9 `BusGraph.setVolume` writes at time 0, so it loses to any in-flight automation
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/sopra/runtime/BusGraph.js:195`
+- **Defect**: `bus.output.gain.setValueAtTime(linear, 0)` schedules the new value at context time 0 — always in the past. Any automation event scheduled at or after `currentTime` (the `linearRampToValueAtTime` from `rampVolume`, or the `setTargetAtTime` glide from `approachVolume`) is later on the AudioParam timeline and therefore wins. The logical `bus.nominal` **is** updated, so `getVolume` reports the new value while the audible gain is unchanged.
+- **Failure scenario**: A `DuckingRule` ducks `music` while `dialogue` plays (`SopraEngine.js:392` → `approachVolume` → `setTargetAtTime(target, currentTime, attack)`). Mid-dialogue the player drags the music slider: `setBusVolume('music', 0.9)` → `nominal = 0.9`, but the param stays on the duck glide. When the dialogue ends, `#updateDuckers` (`SopraEngine.js:395`) glides back to `d.nominalDb`, the value captured *at engage* — so the player's new setting is discarded entirely and never becomes audible. Same failure with `applySnapshot(snapshot, {duration: 2})` followed by a `setBusVolume` during the 2 s blend.
+- **Fix**: `const now = this.#ctx.currentTime; bus.output.gain.cancelScheduledValues(now); bus.output.gain.setValueAtTime(linear, now);` (Optionally also have `#updateDuckers` re-read `bus.nominal` each frame while engaged so a nominal change during a duck is honoured on release.)
+- **Confidence**: Confirmed
+
+### PSN-10 `SopraEngine.setBuses` orphans the previous bus graph while it is still wired to the destination
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/sopra/SopraEngine.js:139-142`
+- **Defect**: `setBuses` replaces `this.busGraph` with a brand-new `BusGraph` but never disconnects the old one. `BusGraph.build` connects each root bus's output to `this.#destination` (`BusGraph.js:99`), so the old tree stays summed into the master destination, and every live `EventInstance` keeps its cached `#chainHead → … → panner → oldBusInput` wiring (captured in `#buildOutputChain`, `EventInstance.js:431/462/482`).
+- **Failure scenario**: A game with background music playing calls `sopra.setBuses(customBuses)` at level load (the documented way to "Replace the mixer with a new bus tree"). The music instance keeps routing through the *old* `music` bus into the *old* `master` bus into the destination — still audible, but now unreachable: `setBusVolume('music', …)`, `applySnapshot`, and every ducking rule address the new graph and have no effect on it. Calling `setBuses` again stacks a third orphaned tree.
+- **Fix**: Before replacing, walk `this.busGraph.buses` and `disconnect()` every `input` and `output` node (and any send gains), and stop/rebuild the live instances (or document `setBuses` as configure-before-play only and throw when `#activeInstances.size > 0`).
+- **Confidence**: Confirmed
+
+### PSN-11 `crossfade` performs no fade-in when the incoming event's buffers are not yet decoded
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/sopra/SopraEngine.js:217-222`
+- **Defect**: `crossfade` calls `newInstance.setGainDb(nominalDb - 60)` then `newInstance.fadeToGainDb(nominalDb, duration)`. Both are no-ops on the AudioParam when `#instanceGain` is still null — and it *is* null until `#resolve → #buildOutputChain` runs, which on the async load path happens inside a promise callback long after `playEvent` returns (`EventInstance.js:378-388`, `511`, `579`). `fadeToGainDb` still writes `#gainDb = targetDb`, so `#buildOutputChain` later initialises the gain straight to full nominal (`EventInstance.js:436`).
+- **Failure scenario**: `sopra.crossfade(currentMusic, newTrack, { duration: 3 })` where `newTrack`'s buffer has not been decoded yet — i.e. the first time that track is played, the normal case for music. Expected: 3-second fade-in. Actual: the outgoing track fades over 3 s, and the incoming track **pops in at full volume** the instant its buffer resolves.
+- **Fix**: Have `fadeToGainDb` (and `setGainDb`) record a pending ramp when `#instanceGain` is null, and replay it in `#buildOutputChain` — e.g. store `{fromDb, toDb, duration, startAfter}` and, after creating `#instanceGain`, anchor at `fromDb` and issue the `rampGain` against the remaining time.
+- **Confidence**: Confirmed
+
+### PSN-25 Audio clips of different concrete types compare and hash equal, merging distinct events into one voice-limit bucket
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/sopra/definition/clip/SwitchContainerAudioClip.js:77` (`equals`) and `:83` (`hash`); base `AbstractAudioClip.js:44` does no type check either
+- **Defect**: `AbstractAudioClip.equals` compares only `gain`/`pitch`, `ContainerAudioClip.equals` adds children, and no level in the chain checks the concrete class. `SwitchContainerAudioClip.hash()` is a byte-identical expression to `BlendContainerAudioClip.hash()` (`combine_hash(super.hash(), computeStringHash(parameter), computeHashFloat(defaultValue))` then folding children — Blend's `hash` omits `blends`). So a Switch and a Blend with the same children/parameter hash equal *and* compare equal, despite Switch playing exactly one child and Blend playing all of them.
+- **Failure scenario**: `sw = SwitchContainerAudioClip.from(kids, {parameter:'intensity', defaultValue:0})` and `bl = BlendContainerAudioClip.from(kids, {parameter:'intensity', defaultValue:0, blends:[…]})` give `sw.hash() === bl.hash()` and `sw.equals(bl) === true`. Lift to events: `EventDescription.from('weather', sw, {maxInstances:1})` and `EventDescription.from('weather', bl, {maxInstances:1})` also hash and compare equal (`EventDescription.equals` delegates straight to `rootClip.equals`). `VoiceManager.register`'s `#byEvent.getOrCompute` then files instances of the *blend* event into the *switch* event's bucket, so `makeRoom` sees `count 1 >= max 1` and steals/stops the switch event's live voice whenever the blend event is triggered — two genuinely different events share one instance-limit bucket.
+- **Fix**: Gate `AbstractAudioClip.equals` on concrete type — `if (Object.getPrototypeOf(this).constructor !== Object.getPrototypeOf(other).constructor) return false;` at the top (every subclass already chains through `super.equals`) — and fold a per-class discriminator (e.g. `computeStringHash(this.constructor.typeName)`) into `AbstractAudioClip.hash()`.
+- **Confidence**: Confirmed
+
+### PSN-26 `BlendContainerAudioClip.equals` throws when compared against a non-Blend clip
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/sopra/definition/clip/BlendContainerAudioClip.js:113`
+- **Defect**: The mirror direction of PSN-25 throws instead of returning false: `this.blends.length !== other.blends.length` dereferences `other.blends`, which is `undefined` on a `SwitchContainerAudioClip`. The three preceding short-circuit clauses (`super.equals`, `parameter`, `defaultValue`) all pass for a Switch with matching content, so execution reaches line 113. `SilenceAudioClip` / `SequenceContainerAudioClip` escape only by accident — they have no `parameter`, so clause 2 short-circuits first.
+- **Failure scenario**: With `sw`/`bl` from PSN-25, `bl.equals(sw)` throws `TypeError: Cannot read properties of undefined (reading 'length')`. In the engine this is reached whenever the Blend-rooted `EventDescription` is the one already stored in `VoiceManager.#byEvent` and the Switch-rooted one is the probe: `HashMap.get` finds the hash-matching entry (hashes are identical per PSN-25) and calls `keyEqualityFunction(record.key /* blend */, key /* switch */)`. The `TypeError` propagates out of `VoiceManager.register`/`makeRoom` and aborts the `playEvent` call — the sound never plays and the caller's frame unwinds.
+- **Fix**: The same concrete-type guard in `AbstractAudioClip.equals` (PSN-25) makes line 113 unreachable for a non-Blend `other`.
+- **Confidence**: Confirmed
+
+### PSN-27 `BlendContainerAudioClip` does not reset its parallel `blends` array in `clearChildren`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/sopra/definition/clip/BlendContainerAudioClip.js:37` (missing `clearChildren` override)
+- **Defect**: `blends` is a parallel array indexed by child index (`#blendGain` reads `blends[i]`), but `BlendContainerAudioClip` inherits `ContainerAudioClip.clearChildren()` (`ContainerAudioClip.js:42-44`), which resets only `children`. `RandomContainerAudioClip` overrides `clearChildren()` for exactly this reason (`RandomContainerAudioClip.js:53-57`, dropping `weights`); Blend does not.
+- **Failure scenario**: `const b = BlendContainerAudioClip.from([calm, storm], {parameter:'intensity', blends:[fadeOutCurve, fadeInCurve]}); b.clearChildren(); b.addChild(newLayer);` leaves `children = [newLayer]` with `blends = [fadeOutCurve, fadeInCurve]`. `planTimeline` at `intensity = 1` now evaluates `fadeOutCurve` (value 0) for `newLayer`, so `blend <= 0` and the layer is skipped entirely — the container plans zero plays and returns `duration: 0`, where the documented behaviour for a child with no blend curve is "always fully on" (gain 1). `toJSON` and the binary adapter then persist two curves for one child, so the mispairing survives a save/load round-trip.
+- **Fix**: Add `clearChildren() { super.clearChildren(); this.blends = []; }`, matching `RandomContainerAudioClip.clearChildren()`. (The binary adapter is unaffected today because it assigns `value.blends` before calling `value.clearChildren()`; reorder it to assign after, once the override exists.)
+- **Confidence**: Confirmed
+
+### PSN-28 `fadeOutAllTracks` deletes the emitter's authored tracks; `stopAllTracks` does not
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/ecs/emitter/SoundEmitterComponentContext.js:207-211` (`fadeOutAll`)
+- **Defect**: `fadeOutAll` calls `instance.fadeOutAndStop(duration)` without detaching the track↔instance bindings first. `stopAll` (lines 220-234) deliberately unbinds *before* stopping, with a comment saying exactly why: "`#onInstanceEnded` must bail out (it keys off `#instances`) so teardown doesn't fire `track.on.ended` or mutate the emitter's authored track list." The two paths differ only by a fade, yet have opposite effects on authored data.
+- **Failure scenario**: A music entity with one *looping* `SoundTrack`. The game calls `emitter.fadeOutAllTracks(2)` to duck out. Two seconds later `SopraEngine.update` crosses the instance's `#stopDeadline` → `EventInstance.stop()` → `onEnded` → `#onInstanceEnded(track, instance)` still finds `#instances.get(track) === instance`, so it fires `track.on.ended` and **removes the track from `emitter.tracks`**. `emitter.tracks.length` goes 1 → 0: the emitter can never play that music again, and serializing the entity now writes zero tracks. (`SoundEmitterSystem.spec.js:378` drives this exact path with a looping emitter but never asserts `tracks.length`, so it passes.)
+- **Fix**: In `fadeOutAll`, snapshot the entries and `#unbind(track)` (clear `track.__instance` / `track.__soundRuntime` and delete from `#instances`) for each **before** calling `instance.fadeOutAndStop(duration)` — mirroring `stopAll`.
+- **Confidence**: Confirmed
+
+### PSN-29 `SoundTrack.time` is serialized but discarded on load — a saved track always restarts from 0
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/ecs/emitter/SoundEmitterComponentContext.js:87-92` (`addTrack`)
+- **Defect**: `addTrack` calls `sopra.playEvent(description, { busId, position, oneShot })` with no `startTime` and never seeks, so the track's persisted playback cursor is silently dropped. `SoundTrack.#time` is written by `fromJSON` (`SoundTrack.js:338`) and by `SoundEmitterSerializationAdapter.js:73`, and emitted by `toJSON` (`SoundTrack.js:309`) and `SoundEmitterSerializationAdapter.js:35` — but as soon as `#bind` sets `track.__instance`, the `time` getter (`SoundTrack.js:78-80`) shadows `#time` with `instance.playhead`, so the loaded value is never read again.
+- **Failure scenario**: Save while a 3-minute looping music emitter is at `track.time === 95.2`. On load `track.time = 95.2` (instance still null, so `#time = 95.2`); then `SoundEmitterSystem.link` → `addTrack` → `EventInstance.start` sets `startedAt = now` (because `#startTime === null`) → playhead 0. The music restarts from the beginning and `track.time` immediately reports ~0 — the field round-trips through the file for no effect.
+- **Fix**: Read `track.time` *before* `#bind` and pass it through: `playEvent(description, { …, startTime: this.sopra.currentTime - time })`. The mechanism already exists and is used by `LiveEmitterSet.#promote` (`LiveEmitterSet.js:293`). (`instance.seek(time)` after binding also works but re-spawns the voices.)
+- **Confidence**: Confirmed
+
+### PSN-30 `AudioEmitter.fromJSON` defaults `sourceRadius` to 0.5 while the field initialiser is 0.05
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/ecs/audio/AudioEmitter.js:105` vs `:51`
+- **Defect**: A 10× default mismatch between the deserialization path and the class field, so a deserialized emitter is not equivalent to a constructed one.
+- **Failure scenario**: `AudioEmitter.fromJSON({ event: {...}, acoustic: true })` — any content JSON authored before, or simply without, the optional `sourceRadius` key — yields `sourceRadius === 0.5`, while `new AudioEmitter()` yields `0.05`. `AudioEmitterSystem.js:139` forwards it verbatim to `LiveEmitterSet.add` → `EventInstance.sourceRadius` → `OcclusionSolver.solve`, which offsets its probe rays by `sourceRadius`. The JSON-loaded source is treated as a 0.5 m sphere and stays partially audible behind cover exactly where the constructed one is fully occluded.
+- **Fix**: Change line 105's fallback to `0.05` to match the field (or change the field to `0.5`) — the two must agree.
+- **Confidence**: Confirmed
+
+### PSN-31 `SoundEmitter.fromJSON` defaults `attenuation` to `Linear` while the field initialiser is `Smith`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/ecs/emitter/SoundEmitter.js:344` vs `:64`
+- **Defect**: When `json.attenuation` is absent, `fromJSON`'s `else` branch assigns `SoundAttenuationFunction.Linear` (0); the field initialiser is `SoundAttenuationFunction.Smith` (2). A JSON-built emitter gets a different falloff law than a constructed one.
+- **Failure scenario**: `engine/EntityCreator.js:50` (`createSoundEmitter`) and `engine/achievements/AchievementManager.js:329` both call `SoundEmitter.fromJSON({...})` with no `attenuation` key and `isPositioned: true`; `isAttenuated` is also absent so line 332 sets the `Attenuation` flag. `soundEmitterToEventDescription.js:79` therefore builds the distance curve with `interpolate_irradiance_linear` instead of `interpolate_irradiance_smith` — every one-shot SFX entity created through those two engine helpers plays with a different distance→gain curve than the class default.
+- **Fix**: Make the `else` branch at line 344 assign `SoundAttenuationFunction.Smith` to match the field initialiser (or change the field to `Linear`).
+- **Confidence**: Confirmed
+
+### PSN-12 `SilentSoundMaterial` serializes but cannot be deserialized
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/material/concrete/json/deserializeSoundMaterialFromJSON.js:14-26`
+- **Defect**: The type switch handles `RandomSoundMaterial`, `SingleSoundMaterial` and `SoundMaterialComposition`, but not `SilentSoundMaterial` — which has a `typeName`, a `toJSON`, a `fromJSON`, and a shipped `INSTANCE` singleton, and is therefore produced by `serializeSoundMaterialToJSON`. The default branch throws.
+- **Failure scenario**: A terrain layer with no audible surface is authored/saved with `SilentSoundMaterial.INSTANCE` (the exact value `TerrainSoundMaterialSurfaceDetector.initialize` assigns for a layer with no material, `TerrainSoundMaterialSurfaceDetector.js:73`). Round-trip gives `{ type: "SilentSoundMaterial", data: {} }`. On load, `TerrainSoundMaterialSurfaceDetector.initialize` line 75 calls `deserializeSoundMaterialFromJSON` and gets `Error: Unsupported material type 'SilentSoundMaterial'`, aborting terrain sound initialisation for the whole level. Same failure for a `SoundMaterialComposition` containing a silent slot (`SoundMaterialComposition.js:49`).
+- **Fix**: Add `case SilentSoundMaterial.typeName: instance = new SilentSoundMaterial(); break;` to the switch.
+- **Confidence**: Confirmed
+
+### PSN-13 Nested `SoundMaterialComposition` corrupts its own output via a shared module-level scratch array
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/material/concrete/SoundMaterialComposition.js:10,85,101`
+- **Defect**: `computeInteractionSounds` gathers each child's output into the module-level `const temp = []` and writes its own results into the caller's `destination`. When a child is itself a `SoundMaterialComposition` — supported by `setMaterial` and by the JSON format (`deserializeSoundMaterialFromJSON` can produce one) — the recursive call receives `temp` as its `destination`, so the inner composition reads *and writes* the same array while iterating.
+- **Failure scenario**: Composition `A = [B, S3]` where `B = [S1, S2]`. `A` calls `B.computeInteractionSounds(temp, 0, …)`. Inside `B`: `S1` writes its spec to `temp[0]`; `B` clones/weights it back into `temp[0]`, offset → 1; then `S2` writes its **raw, unweighted** spec to `temp[0]`, clobbering `B`'s finished result; `B` then clones that into `temp[1]` and returns 2. `A` copies `temp[0..1]` out — so the sound that should have been S1-at-weight-w1 is emitted as S2 at full unweighted volume, and S1 disappears. The `__volume_threshold` cut is also applied against the wrong source.
+- **Fix**: Drop the module-level singleton. Either allocate a per-call array in `computeInteractionSounds`, or keep a depth-indexed pool of scratch arrays (`#scratch[depth]`) so a nested call never aliases its parent's buffer.
+- **Confidence**: Confirmed
+
+### PSN-14 `SoundControllerSystem` stop handler dereferences a missing `SoundEmitter` with no guard at all
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/ecs/SoundControllerSystem.js:86-89`
+- **Defect**: Distinct from the already-reported line 82. `stopEventHandler` does `const emitter = dataset.getComponent(entity, SoundEmitter); emitter.tracks.removeOneIf(…)` with no undefined check and no log — the start handler at least logs first.
+- **Failure scenario**: An entity carries `SoundController` and `SoundEmitter`. Game code removes the `SoundEmitter` component (e.g. muting a unit) while leaving `SoundController` attached, then the rule's `stopEvent` fires on that entity. `getComponent` returns `undefined` and the listener throws `TypeError: Cannot read properties of undefined (reading 'tracks')` out of the ECS event dispatch, aborting the remaining listeners for that event.
+- **Fix**: `if (emitter === undefined) { return; }` before the `removeOneIf`.
+- **Confidence**: Confirmed
+
+### PSN-15 `RandomSoundMaterial` with an empty `sounds` list reports one written spec but writes `undefined`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/material/concrete/RandomSoundMaterial.js:16-22`
+- **Defect**: `randomFromArray(Math.random, [])` returns `undefined` (it indexes `array[randomIntegerBetween(random, 0, -1)]`), but the method unconditionally writes it into `destination[destination_offset]` and returns `1`, violating its own contract that the return value is the number of valid specs written.
+- **Failure scenario**: A `RandomSoundMaterial` authored (or `fromJSON`'d) with `sounds: []` sits in a terrain layer. `SoundMaterialComposition.computeInteractionSounds` receives `additions = 1`, takes `const source = temp[0]` (undefined) and evaluates `source.volume * weight` → `TypeError: Cannot read properties of undefined (reading 'volume')`, killing the footstep-sound path for the whole surface.
+- **Fix**: `if (this.sounds.length === 0) { return 0; }` at the top, so the "no sound" case is reported honestly rather than as a written-but-undefined entry.
+- **Confidence**: Confirmed
+
+### PSN-16 `SoundMaterialComposition.fromJSON` default `volumeThreshold` diverges from the field initialiser
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/sound/material/concrete/SoundMaterialComposition.js:32,46`
+- **Defect**: The constructor sets `this.__volume_threshold = 0.01`; `fromJSON` destructures `volumeThreshold = 0`. A payload written before the field existed (or any hand-authored JSON that omits it) deserializes to a threshold of `0`, not the class default.
+- **Failure scenario**: `new SoundMaterialComposition().fromJSON({ materials: [m], weights: [0.001] })` yields `__volume_threshold = 0`, so a contribution with an effective volume of 0.001 — which the freshly-constructed object would have cut — is emitted. `toJSON`/`fromJSON` is therefore not the identity on the default-constructed object either: construct → `fromJSON(toJSON())` on an object whose threshold was left at the default gives 0.01 (correct), but any *older* saved file silently drops to 0.
+- **Fix**: `volumeThreshold = 0.01` in the `fromJSON` destructuring, matching the constructor.
+- **Confidence**: Confirmed
+
+### PSN-17 `ebvh_build_for_geometry_incremental` writes the BATCH index as leaf user data, so `batch_size > 1` loses all but one triangle per leaf
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/bvh2/bvh3/ebvh_build_for_geometry_incremental.js:35`
+- **Defect**: The leaf AABB is computed over `group_size` triangles starting at `index_start = i * batch_size` (lines 26-31), but the payload stored is `bvh.node_set_user_data(node_index, i)` — the *batch ordinal*, not `index_start`, and no group size is stored. Every triangle query in the package reads `COLUMN_USER_DATA` as a single triangle index and tests exactly one triangle per leaf (`ebvh_geometry_query_nearest_triangle_ray.js:119`, `ebvh_geometry_query_any_triangle_ray.js:121`). `batch_size = 1` masks the bug because then `i === index_start`.
+- **Failure scenario**: 8 triangles, `ebvh_build_for_geometry_incremental(bvh, idx, pos, 4)` → 2 leaves with user data `0` and `1`. Leaf 1's AABB covers triangles 4-7, but the ray test intersects **triangle 1** against it. A ray that hits only triangle 5 returns `false` from `ebvh_geometry_query_nearest_triangle_ray`; a ray that misses all geometry but passes through leaf 1's box while grazing triangle 1 reports a spurious hit. Triangles 2-7 are never tested at all.
+- **Fix**: Store `index_start` (not `i`) as the user data and store the group size so the leaf test can loop `[index_start, index_start + group_size)`; or remove the `batch_size` parameter and always emit one leaf per triangle, matching what every in-package consumer assumes.
+- **Confidence**: Confirmed
+
+### PSN-18 `aabb3_detailed_volume_intersection_callback_based` JSDoc parameter order does not match the signature
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/bvh2/traversal/aabb3_detailed_volume_intersection_callback_based.js:23-25`
+- **Defect**: The JSDoc declares the parameters after `z1` as `planes, plane_count, plane_mask`; the actual signature (lines 31-33) is `plane_mask, planes, plane_count`. The body forwards correctly, so only the published contract of this exported function is wrong. (The same swap is tracked for the callee in `core/geom/GEOMETRY_REVIEW_002_NAMING.md:595`; this wrapper was missed.)
+- **Failure scenario**: A consumer following the doc calls `aabb3_detailed_volume_intersection_callback_based(x0,y0,z0,x1,y1,z1, planes, 6, 0b111111, cb)`. `plane_mask` receives the `planes` array, so `plane_mask & (1 << i)` coerces to `0` and every clipping plane is skipped; `plane_count` receives the mask and `planes` receives `6`, so `planes[0]` is `undefined`. The callback receives the 8 raw box corners instead of the clipped volume — the "much tighter bounds" the function exists to produce silently degrade to the untrimmed AABB.
+- **Fix**: Reorder the three `@param` lines to `plane_mask, planes, plane_count`.
+- **Confidence**: Confirmed
+
+### PSN-22 `NodeProxy.tryAbsorbChild` runs one extra iteration at `j = -1`, absorbing `undefined` and emitting an out-of-contract leaf offset
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/bvh8/build/NodeProxy.js:208` (loop header) and `:231-233` (the second decrement)
+- **Defect**: The absorb loop decrements `j` twice when `retry_middle` is set (line 228 and line 232) but the bound `j < cluster_size` is only re-checked *after* the `j++`. On the final absorbed triangle the pair reaches `(j = -2, cluster_size = 0)`, `j++` makes it `(-1, 0)`, and `-1 < 0` is still true — so the body runs once more on `triangles[-1] === undefined`.
+- **Failure scenario**: Verified by running the shipped builders, not hypothesised. Cluster `[14, 13, 15]` in a child with the parent rejecting `14` first and accepting `15`, `13`, `14` after: `j=0 size=3 tri=14 → false` (skip middle, `retry_middle = true`), `j=2 size=3 tri=15 → true`, `j=1 size=2 tri=13 → true`, `j=0 size=1 tri=14 → true`, then **`j=-1 size=0 tri=undefined → true`**. `aabb3_from_triangle_by_index(bounds, 0, undefined, …)` produces all-NaN bounds and `tryAddPrimitive(undefined, …)` *succeeds*: the span guard `(NaN - NaN) > 23` is false and `TriangleCluster.canAccept`'s `Math.abs(existing - undefined) > 1` is false. `undefined` lands in a parent cluster and the parent's `primitive_index_low/high` become `NaN`; `cluster_size` goes to `-1`, so the now-empty child cluster fails the `cluster_size === 0` test at line 237 and is never spliced out. Downstream, `bvh8_populate_node_from_proxy` stores `node_set_base_index_triangle(node, NaN)` as `0` and, because `triangle - NaN` is `NaN`, `min_triangle_index` never updates off its sentinel `24` — so leaf slots are emitted as meta `0xF8` (offset 24, count 3). Reproduced end-to-end with ordinary geometry (50 unit right triangles at integer centres on a 3×3 grid, `seededRandom(1738)`): `metas(0) = [56, 57, 58, 248, 248, 0, 0, 0]` and `bvh8_validate_structure` reports *"node 0 slot 3: leaf triangle offset 24 > 23 collides with the internal slot encoding"*. Offset 24 aliases the internal-slot encoding, so the node points at triangles 24/25/26 instead of the real ones and the real triangles are dropped. **4 of 2000 fuzzed `bvh8_build_for_geometry` builds fail this way** (integer grids, 1e6-scale soups, and mixed-scale soups all hit it). A `NaN` `primitive_index_low` also permanently disables the ≤23-offset span guard for that node, since `NaN > 23` is always false.
+- **Fix**: Clamp `j` after the decrements — insert `if (j < -1) { j = -1; }` immediately after the `if (retry_middle) { j--; }` block (line 233). Verified: with that one line the same 2000-build fuzz drops from 4 failures to 0, and the empty cluster is then correctly spliced out by the `cluster_size === 0` branch.
+- **Confidence**: Confirmed
+
+### PSN-23 `byte()` wraps instead of clamping, so a quantized upper bound of 256 becomes 0
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/bvh8/build/byte.js:7-9`
+- **Defect**: `byte()` does `(float_value >>> 0) & 0xFF` — a wrap, not a saturating clamp. `Math.ceil((child_max - p) / e)` in the quantizer can exceed 255 by one when double rounding in `encode_bounds_e` picks an exponent one step too small; 256 wraps to 0. The same wrap turns a negative floor result into 255 on the min side.
+- **Failure scenario**: Node AABB with `p_x = -2**-53` and `x1 = 255/1024` (both exactly float32-representable): `e = 2^-10`, `(x1 - p_x) * (1/e) = 255.0000000000001`, `Math.ceil(...) = 256`, `byte(256) = 0`. Any child whose `x1` equals the node's `x1` then gets `quantized_max_x = 0` with `quantized_min_x = 0`, so `bvh8_get_node_child_bounds` decodes that child's x-range as the degenerate slab `[p_x, p_x]`. Every triangle in that child with `x > p_x` is now outside its stored child box: ray traversal culling against the quantized child AABB misses them, and `bvh8_geometry_validate` throws "violates child bounds". Both quantizer call sites are affected (`build/bvh8_from_proxy.js:211-216`, `build/BVH8Converter.js:501-506`). Reachability is low — it needs the node extent within ~1e-16 relative of `255 * 2^k`, which is why 3M random float32 pairs and 3250 fuzzed builds did not hit it — but the input above is a real float32 pair, not an impossible state.
+- **Fix**: Make `byte()` saturate: `return float_value <= 0 ? 0 : (float_value >= 255 ? 255 : (float_value >>> 0));`. Both importers (`bvh8_from_proxy.js`, `BVH8Converter.js`) want a saturating conversion, and clamping is the conservative direction for both the floor (min) and ceil (max) sides.
+- **Confidence**: Confirmed
+
+### PSN-19 `ColliderObserverSystem.unlink` re-derives the owning body from live state, leaking the BVH leaf when the derivation has changed
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/physics/ecs/ColliderObserverSystem.js:77-80`
+- **Defect**: `unlink` calls `__resolve_body_entity(ecd, entity)` — re-walking `RigidBody`-on-self → `ParentEntity` → orphan — instead of using the binding captured at attach time. `PhysicsSystem.attach_collider` records `collider._bodyId = rb._bodyId` (`PhysicsSystem.js:752`) and nothing ever reads it back. If the resolution has changed or now fails, `detach_collider` is never called, so the collider's BVH leaf and its entry in `__body_collider_lists` survive the component removal.
+- **Failure scenario**: Entity 1 = `RigidBody` + `Transform`; entity 2 = `Collider` + `Transform` + `ParentEntity(→1)`. The collider is attached: body 1 owns one list entry and BVH node `N` is live in `dynamicBvh`. Now detach the child from its parent the normal way — `ecd.removeComponentFromEntity(2, ParentEntity)` — then `ecd.removeComponentFromEntity(2, Collider)`. `unlink` runs, `__resolve_body_entity` finds neither a `RigidBody` on 2 nor a `ParentEntity`, returns `-1`, and bails at line 78. Node `N` stays in `dynamicBvh` forever: `generate_pairs` keeps producing pairs against a collider that no longer exists on any entity, and body 1 keeps colliding with a phantom. The same ordering occurs on plain entity destruction — `removeEntity` removes components in component-type-index order (`EntityComponentDataset.js:967-974`), i.e. registration order, so whether `ParentEntity` is stripped before `Collider` is incidental to how the app registered its component types, not something physics controls. A third variant: retarget `parent.entity` to a body of a different `BodyKind` before removing the collider — `detach_collider(newEntity, c)` then calls `__remove_from_broadphase` with the *new* body's kind (`PhysicsSystem.js:783`), removing node index `N` from `staticBvh` when `N` is a `dynamicBvh` node, corrupting the static tree *and* leaking the original leaf.
+- **Fix**: Resolve from the attach-time handle: in `unlink`, `if (collider._bodyId === -1) return;` then detach via that id — e.g. add `PhysicsSystem#detach_collider_by_id(collider)` that indexes `__body_collider_lists[body_id_index(collider._bodyId)]` directly, so the teardown path never depends on live dataset topology.
+- **Confidence**: Confirmed
+
+### PSN-20 `raycast` caches the shared traversal-stack pointer while invoking a user filter, and accumulates into module-level state
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/physics/queries/raycast.js:83,28-30,119`
+- **Defect**: `bvh_raycast_nearest` copies `stack.pointer` into a local (`let pointer = stack.pointer`) and never advances the global pointer during the walk (line 166 restores it to a value it never left). `SCRATCH_UINT32_TRAVERSAL_STACK`'s contract is explicit: *"Consumers that cache `pointer` into a local must not be re-entered."* But the walk invokes the caller-supplied `filter` at line 119, and `raycast`'s nearest-hit state (`acc`, `best_normal`, `cand_normal`) is module-scoped.
+- **Failure scenario**: Pass a line-of-sight filter — `(entity, collider) => system.raycast(losRay, tmpHit) === false` — or any filter that runs another BVH query (`overlap_shape`, `bvh_query_user_data_intersects_sphere`, …). The nested traversal starts its frame at `stack.pointer`, which is still the outer walk's `stack_top`, so it overwrites `stack[stack_top…]` — exactly the outer walk's pending node ids. When the outer loop resumes it pops the nested walk's leftovers as node indices, computes `node * ELEMENT_WORD_COUNT` into `bvh.__data_float32`, and tests unrelated AABBs: the ray reports a hit on a body it never crosses, or misses the true nearest surface. If the filter calls `raycast` itself, `raycast` line 200 resets `acc.best_t = max_distance` of the *inner* ray and the outer call returns the inner ray's hit and normal outright.
+- **Fix**: Keep the pointer live during the walk, the way `core/bvh2/bvh3/query/bvh_query_leaves_ray.js:38,51,79-80` does — `const stack_top = stack.pointer++; stack[stack_top] = root;` then push/pop through `stack.pointer` so a nested traversal pushes above the live frame and drains back. Additionally make `acc` / `best_normal` / `cand_normal` locals of `raycast` (or pass an explicit accumulator into `bvh_raycast_nearest`) so a re-entrant filter cannot corrupt the outer nearest-hit state.
+- **Confidence**: Confirmed
+
+### PSN-21 `Joint` has no `toJSON`/`fromJSON`, so no blueprint or entity template can contain one
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/physics/ecs/Joint.js` (class body — no `toJSON`/`fromJSON` anywhere)
+- **Defect**: Every sibling physics component implements the pair (`Collider.js:117/126`, `RigidBody.js:210/228`, `FluidObstacle.js:76/82`); `Joint` does not. The engine's generic template path calls both unconditionally.
+- **Failure scenario**: `EntityBlueprint.add()` (`EntityBlueprint.js:92`) does `this.addJSON(constructor, component.toJSON())`, so `EntityBlueprint.from([new RigidBody(), new Transform(), new Joint()])` throws `TypeError: component.toJSON is not a function`. Even a blueprint assembled via `addJSON` fails at `build()` (`EntityBlueprint.js:154`), which calls `component.fromJSON(json)` on a freshly-constructed `Joint`. A ragdoll or vehicle authored as a template therefore cannot be built at all.
+- **Fix**: Add `toJSON`/`fromJSON` covering exactly the field set `equals`/`hash` and `JointSerializationAdapter` already agree on: `entityA`, `entityB`, `localAnchorA`, `localAnchorB`, `localBasisA`, `localBasisB`, `swingTwist`, and the six-entry `dofMode` / `dofLowerLimit` / `dofUpperLimit` / `dofStiffness` / `dofDamping` / `dofMotorTargetVelocity` / `dofMotorMaxForce` arrays (excluding `dofImpulse` and the `_*` runtime handles, matching the binary adapter).
+- **Confidence**: Confirmed
+
+---
+
+## legacy sound-ECS areas traced and found correct (not findings)
+
+link/unlink signal symmetry in `SoundEmitterComponentContext` and `SpatialAudioIndex` (identical
+bound-arrow identities on both sides); the `#live` / `#emitters` / `#demoteScratch`
+iteration-vs-mutation discipline and `Math.min(budget, ranked.length)` in `LiveEmitterSet.refresh`;
+`compareByEffective` is a numeric total order; `SpatialAudioIndex` compares linear distance against
+a linear `distanceMax` on both the BVH cube and the narrowphase `distanceTo` (no squared/linear
+mixing), and `BVHQueryIntersectsSphere.from` retains the array by reference so the reused
+`#querySphere` mutation takes effect; every dB conversion (`volume2dB` → `setGainDb` → `dB2Volume`)
+and every duration (`fadeOutSeconds`, `playingSince`, `sopra.update(context.currentTime)`) is on the
+correct side of the unit boundary. Nothing reportable in `SoundTrackFlags`, `SoundEmitterFlags`,
+`SoundPanningModelType`, `loadSoundTrackAsset`, `SoundController`, `SoundListener`, or
+`SoundEmitterSystem`.
+
+---
+
+## sopra definition/serialization areas traced and found correct (not findings)
+
+Adapter write-order vs read-order (all 14 match); field completeness across
+`toJSON`/`fromJSON`/binary/field-initialiser/`clone`/`equals`/`hash` for every definition class;
+default-value agreement between the three paths; registry coverage — all 6 concrete clips and all 3
+concrete effects are registered in **both** directions in `sopraJSON.js` and
+`populateSopraSerializationRegistry.js`; effect `build()` wiring (`input`/`output` ends correct, no
+orphaned nodes); dB-vs-linear and seconds-vs-ms units throughout; timeline accumulation in
+Sequence/Switch/Blend/Random; `weightedRandomFromArray`'s weight callback.
+
+---
+
+## physics areas traced and found correct (not findings)
+
+`RigidBody`/`Collider`/`Joint` `equals`/`hash` field coverage (complete against every
+non-`_`-prefixed field, with documented exclusions); all three binary adapters' write/read order and
+defaults vs. the field initialisers, including the `>>> 0` / `| 0` signedness round-trip on
+`layer`/`mask`/`flags` and `mask = 0xFFFFFFFF|0`; `RigidBodySerializationUpgrader_0_1`'s
+1×u8 + 13×f64 + 3×u32 v0 layout against v1's `deserialize`; `solver_caches` write/read symmetry,
+sort comparators and sleep-chain rotation; `SolverBodyState` capacity/stamp/generation arithmetic
+and the grow-before-generation-roll ordering; `solve_constraints` scratch aliasing,
+`accumulate_point_block`/`invert_sym3` index arithmetic, `swing_twist_error` algebra and every row's
+sign convention; `generate_pairs` grow-and-retry plus entity-canonical A/B dedupe;
+`mesh_mesh_tet_manifold` buffer sizing and the `4 + k*7` contact layout.
+
+---
+
+## bvh2 areas traced and found correct (not findings — recorded so they are not re-walked)
+
+Implicit `(node << 1) + 1` / `last_valid_index = binary_node_count + leaf_node_count` arithmetic in
+both `bvh32_*` queries for N = 0, 1, 2, 3, 4, 5, 6, 8 leaves including the `copy_box_zero_size`
+filler nodes; `BinaryUint32BVH.build()`'s level-start computation at N = 0 and N = 1; all four
+`balance_rotate` re-wirings (child/grandchild pointers, parent back-links, re-formed-node AABB and
+height) and the fact that stale ancestor AABBs are never *read* during `bubble_up_update`;
+`insert_leaf`'s `uint32` re-bind after a reallocating `allocate_node()`; `remove_leaf` for the
+root-leaf / root-parent / interior cases; the in-place compaction in `ebvh_build_hierarchy` (the
+write cursor always trails the read cursor); the `n - 1` parent-node pool budget in both callers;
+`ebvh_nodes_sort_sah_local4` bounds; and the `result_offset` contract in every query in the package
+— no query ignores it or double-counts.
+
+---
+
+## `ServerAuthoritativeServer.authorize` status
+
+**CLOSED — no longer permissive.** `ServerAuthoritativeServer`'s constructor now unconditionally
+installs a real policy: `this.executor.authorize = make_owner_authorization({ world, identity_class,
+server_peer_id })` (`ServerAuthoritativeServer.js:130-134`), with `identity_class = NetworkIdentity`
+and `server_peer_id = -1` as constructor defaults. `SimActionExecutor.authorize` still defaults to
+`null` (`SimActionExecutor.js:155`), but that is the *low-level* primitive and is documented as
+deliberately permissive for single-peer/local-only use; the server orchestrator — the thing an
+untrusted peer talks to — is secure by default. The replay path is also safe: server-local actions
+are logged with `SENDER_LOCAL` (0xFF) and `execute` bypasses the gate for that sentinel
+(`SimActionExecutor.js:218`), so rollback replay does not reject the server's own actions.
+
+---
+
+## Unspecced file inventory
+
+Files with no adjacent `<name>.spec.js` (excluding `*.spec.js` and `prototype*.js`).
+
+### `engine/physics` — 28 files
+```
+body/SolverBodyState.js
+broadphase/generate_pairs.js
+constraint/DofMode.js
+constraint/solve_constraints.js
+contact/combine_material.js
+ecs/BodyKind.js
+ecs/ColliderFlags.js
+ecs/PhysicsEvents.js
+ecs/RigidBodyFlags.js
+ecs/RigidBodySerializationUpgrader_0_1.js
+ecs/SleepState.js
+ecs/is_sensor.js
+fluid/SliceVisualiser.js
+fluid/ecs/FluidObstacle.js
+fluid/effector/AbstractFluidEffector.js
+fluid/solver/v3_grid_compute_solid_neighbour_mask.js
+fluid/solver/v3_mac_advect_maccormack_velocity.js
+fluid/solver/v3_mac_advect_scalar.js
+fluid/solver/v3_mac_apply_vorticity_confinement.js
+fluid/solver/v3_mac_compute_divergence.js
+fluid/solver/v3_mac_subtract_pressure_gradient.js
+mls-mpm/MLS_MPM.js
+mls-mpm/testMLS_MPM.js
+narrowphase/decomposition/decompose_to_triangles.js
+narrowphase/decomposition/triangle_buffer_layout.js
+narrowphase/mesh_mesh_tet_manifold.js
+persistence/solver_caches.js
+queries/raycast.js
+```
+
+### `engine/sound` — 74 files
+```
+SoundEngine.js
+asset/SoundAssetPlaybackSpec.js
+asset/SoundAssetPlaybackSpecFlags.js
+dB2Volume.js
+volume2dB.js
+ecs/SoundController.js
+ecs/SoundControllerSystem.js
+ecs/SoundListener.js
+ecs/SoundListenerSystem.js
+ecs/emitter/SoundAttenuationFunction.js
+ecs/emitter/SoundEmitter.js
+ecs/emitter/SoundEmitterComponentContext.js
+ecs/emitter/SoundEmitterFlags.js
+ecs/emitter/SoundEmitterSerializationUpgrader_0_1.js
+ecs/emitter/SoundEmitterSerializationUpgrader_1_2.js
+ecs/emitter/SoundPanningModelType.js
+ecs/emitter/SoundTrack.js
+ecs/emitter/SoundTrackFlags.js
+ecs/emitter/loadSoundTrackAsset.js
+material/AbstractSoundMaterialDefinition.js
+material/SoundMaterialInteractionType.js
+material/concrete/RandomSoundMaterial.js
+material/concrete/SilentSoundMaterial.js
+material/concrete/SingleSoundMaterial.js
+material/concrete/SoundMaterialComposition.js
+material/concrete/json/deserializeSoundMaterialFromJSON.js
+material/detector/SoundMaterialSurfaceDetector.js
+material/detector/terrain/TerrainSoundMaterialSurfaceDetector.js
+simulation/core/AcousticMediumSerializationAdapter.js
+simulation/core/AcousticSolution.js
+simulation/core/AcousticVolumeRegion.js
+simulation/core/OccluderBody.js
+simulation/core/RayHit.js
+simulation/definition/AcousticDirectivitySerializationAdapter.js
+simulation/definition/AcousticMaterialSerializationAdapter.js
+simulation/ecs/AcousticBody.js
+simulation/ecs/AcousticBodySerializationAdapter.js
+simulation/ecs/AcousticVolume.js
+simulation/ecs/AcousticVolumeSerializationAdapter.js
+simulation/probe/AcousticProbeFieldSerializationAdapter.js
+simulation/probe/ProbeFieldPathingSolution.js
+simulation/probe/bakeProbeField.js
+simulation/probe/bakeVisibility.js
+simulation/probe/probe_sdf_grid.js
+simulation/render/reverbImpulseResponse.js
+simulation/serialization/populateAcousticSerializationRegistry.js
+sopra/asset/AssetManagerBufferProvider.js
+sopra/asset/BufferProvider.js
+sopra/asset/StubBufferProvider.js
+sopra/definition/BusDefinition.js
+sopra/definition/DuckingRule.js
+sopra/definition/MixerSnapshot.js
+sopra/definition/ParameterDefinition.js
+sopra/definition/SopraPanningModel.js
+sopra/definition/VoiceStealMode.js
+sopra/definition/clip/AbstractAudioClip.js
+sopra/definition/clip/BlendContainerAudioClip.js
+sopra/definition/clip/ContainerAudioClip.js
+sopra/definition/clip/SampleAudioClip.js
+sopra/definition/clip/SequenceContainerAudioClip.js
+sopra/definition/clip/SilenceAudioClip.js
+sopra/definition/clip/SwitchContainerAudioClip.js
+sopra/definition/effect/AbstractAudioEffect.js
+sopra/definition/effect/CompressorEffect.js
+sopra/definition/effect/EqEffect.js
+sopra/definition/effect/ReverbEffect.js
+sopra/runtime/EventInstance.js
+sopra/runtime/VoiceManager.js
+sopra/runtime/VoicePool.js
+sopra/serialization/populateSopraSerializationRegistry.js
+sopra/serialization/sopraJSON.js
+sopra/serialization/sopraSerializationHarness.js
+sopra/util/MockAudioContext.js
+sopra/util/buildAttenuationCurve.js
+```
+(`engine/sound/simulation/**` was excluded from review per the known-good list; listed here only
+for inventory completeness.)
+
+### `engine/network` — 15 files
+```
+convertPathToURL.js
+xhr.js
+core/MalformedPacketError.js
+ecs/components/NetworkIdentity.js
+orchestrator/NetworkPeer.js
+orchestrator/ServerAuthoritativeClient.js
+orchestrator/ServerAuthoritativeServer.js
+replication/ScopeFilter.js
+sim/ActionLog.js
+sim/ReplicatedComponentRegistry.js
+sim/SimAction.js
+sim/SimActionExecutor.js
+sim/SimActionRegistry.js
+transport/Transport.js
+transport/fragments/packet_size.js
+```
+
+### `core/bvh2` — files with no adjacent spec
+```
+binary/2/bvh32_query_user_data_overlaps_clipping_volume.js
+bvh3/build_triangle_morton_codes.js
+bvh3/bvh_build_from_unindexed_triangles.js
+bvh3/ebvh_build_for_geometry_incremental.js
+bvh3/ebvh_build_hierarchy.js
+bvh3/ebvh_print_to_console.js
+bvh3/query/BVHQueryAnd.js
+bvh3/query/BVHQueryAny.js
+bvh3/query/BVHQueryIntersectsAABB.js
+bvh3/query/BVHQueryIntersectsFrustum.js
+bvh3/query/BVHQueryIntersectsRay.js
+bvh3/query/BVHQueryIntersectsSphere.js
+bvh3/query/bvh_query_user_data_ray.js
+traversal/aabb3_detailed_volume_intersection_callback_based.js
+visual/BVHGeometry.js
+```
+
+### `core/bvh8` — files with no adjacent spec
+```
+bvh8_geometry_validate_indirect.js
+bvh8_node_child_surface_area.js
+bvh8_node_count_triangles.js
+bvh8_quality.js
+build/aabb3_compute_merge_cost.js
+build/aabb3_from_triangle_by_index.js
+build/bvh8_from_proxy.js
+build/byte.js
+build/encode_bounds_e.js
+```
+(`build/NodeProxy.js`, `build/TriangleCluster.js`, `build/BVH8Converter.js` and the other `build/`
+modules that do carry adjacent specs were still read, since the builder is the source of PSN-22.)