@woosh/meep-engine 3.0.2 → 3.2.0

package/src/engine/sound/simulation/REFLECTION_IR_PLAN.md

@@ -1,261 +1,261 @@
-# Plan — Ray-traced reflection IR (probe-baked geometry reverb)
-
-> The keystone upgrade: replace `bakeReverb`'s single-hit mean-free-path heuristic with a true
-> ray-traced, time-binned, **per-band** reflection IR, reusing the engine's Monte-Carlo path tracer.
-> Closes the Steam-Audio *reflections* gap (early reflections + room timbre), replaces the hand-tuned
-> `DECAY_PER_METRE` constant with measured per-band RT60, and makes `scattering` / `absorption[3]` live
-> data.
->
-> **Status (2026-06-20): COMPLETE — the keystone is LANDED + committed + green.** The foundation
-> (**P1a/P1b** shape-raycast index, the **§0.5** `RowFirstTable`/`CSRGraph`/BVH data structures, the **P4
-> TLAS**) and now the reflection-IR bake itself — **P1c → P2 → P3** — are all in. `bakeReverb`'s single-hit
-> heuristic + `DECAY_PER_METRE` are gone; reverb RT60 is now *measured* per band from multi-bounce ray
-> tracing, validated against an analytic Sabine box, and rendered as a per-band decaying-noise IR.
->
-> **One deviation from this plan, for correctness:** the trace terminates by ENERGY THRESHOLD, **not**
-> Russian roulette (§1 step 5 / §4 said RR). Fixed-probability RR is the wrong estimator for acoustic
-> reflectance — a survivor at bounce *n* carries energy `(1−α)^n` but is scaled by `2^n`, so for a live
-> room (`1−α > ½`) the survivor weight grows as `(2(1−α))^n` and rare deep survivors swamp exactly the
-> late bins the RT60 slope is fitted to. Deterministic decay-to-floor is unbiased for the fit window and
-> far lower variance.
-
-The structural blueprint is **`engine/graphics/sh3/lpv/LightProbeVolumeBaker.js`** + its
-`PathTracerProbeRenderer` — a near-1:1 analogue (probe-volume baking against scene geometry via the path
-tracer). We mirror its baker ↔ probe-renderer split and `TaskGroup` orchestration; we swap the
-accumulator from SH-of-radiance to **energy-over-time per band**.
-
----
-
-## 0. What is baked vs. runtime — the source-agnostic guarantee (answers the dynamic-sources question)
-
-**The bake NEVER encodes sound sources. It encodes SPACE: (a) per-region reverberation profile and
-(b) region connectivity.** Sources are 100% runtime. There is no restriction to static/fixed sources.
-
-| Concern | Baked? | What's baked | Source / geometry dynamics |
-|---|---|---|---|
-| Direct path: occlusion, transmission, air, distance | **never** — real-time ray-trace every frame against the live `AcousticOccluderIndex` | nothing | **sources AND moving occluders fully dynamic** |
-| Reverb (reflection IR / per-band RT60) | yes, per **probe** | the SPACE's reverberation response at that point (room geometry + materials), source-agnostic | **sources fully dynamic** — any source routes into the reverb selected by the **listener's** position; geometry assumed mostly-static |
-| Pathing (corner-leakage) | yes | inter-probe **visibility graph** (the space's connectivity), source-agnostic | **sources fully dynamic** — the path source↔listener is solved at runtime from live positions; geometry static-assumed (+ live recheck below) |
-
-**Why reverb is source-agnostic** — "reverb = reflections with the source at the listener." The
-late/diffuse reverberant field of a room is approximately uniform and a property of the room (volume +
-surface absorption), not of where the source is. So one **listener-centric** reverb per probe serves
-every source in that room: `ProbeReverbRenderer` already selects by the *listener's* nearest probe, and
-all sources send into that one shared reverb bus. A source can move anywhere — it never indexes the bake.
-
-**Early reflections are the one source-position-dependent part.** The per-probe envelope bakes them
-listener-centric (correct when source ≈ listener; and when the source is far, the position-independent
-late tail dominates anyway). True per-source early reflections would be a separate real-time pass —
-deferred; the direct-path occlusion machinery already does per-source real-time work, and the late tail
-is the dominant reverb cue.
-
-**Moving objects (dynamic geometry):**
-- **Occlusion / transmission — fully live.** The occluder index is dynamic (O(1) `setTransform`), so a
-  closing door / moving platform correctly blocks the *direct* path in real-time. No bake involved.
-- **Baked reverb + baked visibility — encode bake-time geometry.** A mover that changes acoustic
-  *topology* (a door sealing a room) is not in the bake. Policy, in order of cost:
-  1. Most reverb-affecting geometry is static (walls/floors); small movers barely shift RT60 → accept.
-  2. **Pathing live recheck** (cheap, from the review): re-verify the chosen exit edge with a single
-     `anyHit` ray each frame against live geometry — a closed door re-blocks the leak instantly even
-     though the baked graph still has the edge. One ray per pathed source.
-  3. **Opt-in door variants** for big dynamic dividers (vault door, portcullis gating a whole area's
-     reverb): bake open/closed variants for the affected probes and blend on door state (Steam Audio's
-     "dynamic geometry" approach) — per set-piece, not the default.
-  4. **Re-bake affected probes** on major static-set changes (level streaming) — offline, rare.
-
-This is the standard **real-time-direct / baked-indirect** split (Steam Audio's exact model): live where
-source + geometry move, baked where it is expensive and mostly-static, with targeted live rechecks for
-the dynamic cases that matter.
-
----
-
-## 0.5 Foundation data structures (owner-directed, resolved)
-
-These replace the v1 POJO/array structures across the existing + new probe code with the engine's
-binary-backed primitives.
-
-1. **ProbeField store → `RowFirstTable`** (`core/collection/table/`), **not** `BinaryElementPool`. Probes
-   are baked **write-once** and read by integer row index, so a fixed-schema columnar binary table fits
-   exactly: one allocation, cache-friendly, no per-probe JS object. (`BinaryElementPool`'s alloc/free
-   pool semantics are for churny dynamic elements — unneeded here.) Schema via `RowFirstTableSpec`:
-   `x, y, z` (f32) · `reverbDecayLow/Mid/High` (f32, widened from the v1 scalar) · `bvhLeaf` (u32). The
-   `AcousticProbe` class becomes a thin row cursor/accessor (or is dropped for row-index access).
-
-2. **Pathing connectivity → `CSRGraph`** (`core/graph/csr/`), replacing `AcousticPathGraph.#adjacency`
-   (array-of-arrays). Baked once ⇒ CSR is the ideal static-graph form — `edge_addresses` (row pointers) +
-   `adjacency` + `edge_weights` in one buffer, with the cache-friendly `for (k=xadj[v]; k<xadj[v+1]; k++)`
-   walk that `computeExitField`/Dijkstra want. `edge_weights` is **`Float32Array`** (owner-updated — its
-   doc now cites "acoustic coupling"), so path distances go in **directly**, no quantization.
-   `bakeVisibility` builds it two-pass (count degrees → prefix-sum `edge_addresses` → fill) or via
-   `CSRGraph.fromArrays`.
-
-3. **Probe nearest → BVH + `bvh_query_user_data_nearest_to_point`** (`core/bvh2/bvh3/query/`), replacing
-   `ProbeField.nearest`'s linear scan. `ProbeField` builds a `BVH` of probe point-AABBs (leaf `user_data`
-   = row index) once after baking (the `SpatialAudioIndex` precedent); `nearest(x,y,z)` = one query →
-   row index, O(log n). This matters under the bake (`bakeVisibility` is O(probes²) nearest-style work)
-   and per-frame (`computeExitField` snaps listener + every pathed source to a probe).
-
-4. **`AcousticOccluderIndex` body → class** (replacing the `#bodies` POJO): a real `OccluderBody` holding
-   `shape, material, matrix, inverse, localAABB, worldAABB` (the triangle `blas/indices/positions` of this
-   v1 sketch are gone — §0.6 below raycasts the `shape` directly, so only meshes carry an internal BLAS).
-   `matrix` (the **forward** world transform) maps the local hit position + normal back to world space.
-
-5. **`body.inverse` mandatory — no `null` polymorphism.** `addBody`'s matrix defaults to `M4_IDENTITY`
-   and the inverse is **always** computed; `#localizeRay` always transforms (drop the `inverse === null`
-   fast-path). Uniform flow per [[feedback_uniform_flow]]. Production cost is nil — real occluder bodies
-   always carry a `Transform` matrix anyway; the identity fast-path was a test-only convenience.
-
-**Landing:** (4)+(5)+the stored forward matrix = the foundation of **P1a/P1b**. (1)+(3) = part of the
-**P2** probe refactor (the probe schema widens for per-band decay there regardless). (2) = a pathing
-refactor that can ride with P2 or land standalone first.
-
----
-
-## 0.6 Raycast shapes directly — drop the triangulation (owner-directed)
-
-The v1 `acoustic_geometry_from_shape` triangulates collider shapes (box → 12 tris, …) into mesh soup —
-counter-productive: lossy for primitives, more triangles, a per-body BLAS for a 2-tri wall. **Replace it
-with a first-class `AbstractShape3D.raycast`**, so the occluder index stores **shapes** and raycasts them
-exactly (closed-form for primitives, an internal BLAS only for meshes).
-
-**Contract:** `AbstractShape3D.raycast(hit: Float32Array, ray: Ray3) → boolean`, shape at its LOCAL
-origin (the caller localises the ray), `hit = [px, py, pz, nx, ny, nz]` (local surface point + unit
-normal). The hit distance `t` is recovered by the caller as `(hitPoint − origin)·dir` (unit dir).
-
-**It is mostly glue** — the narrowphase already factored the local math into core functions that
-`refine_ray_hit` dispatches to:
-- `SphereShape3D` → `core/geom/3d/sphere/sphere_raycast.js`
-- `BoxShape3D` → `core/geom/3d/box/box3_raycast.js`
-- `CapsuleShape3D` → `core/geom/3d/capsule/capsule_raycast.js`
-- `MeshShape3D` → an **internal lazy ebvh BLAS** (`ebvh_build_for_geometry_morton` +
-  `ebvh_geometry_query_nearest_triangle_ray` + `construct_ray_hit_from_geometry`); the normal is
-  normalised and flipped to face the incoming ray. (Owner-approved: MeshShape3D gains an internal BLAS.)
-
-`AcousticOccluderIndex` then holds `shape + material + matrix + inverse` per body; `closestHit`/`anyHit`
-localise the world ray into body space and call `shape.raycast`, transforming the hit point (by the
-forward matrix) and normal (by the rotation) back to world. **`acoustic_geometry_from_shape` is deleted**;
-`AcousticBody`/`AcousticSimulationSystem` pass the `Collider.shape` straight through. (Could later let
-the physics `refine_ray_concave` share `MeshShape3D.raycast` — out of scope.)
-
----
-
-## 1. Model — acoustic ray-tracing energy histogram
-
-From a probe (source = listener), shoot N rays over the sphere. Each ray carries a **per-band energy
-throughput** `[low, mid, high]`, init `1`. Bounce loop (modeled on `PathTracer.path_trace`):
-
-1. `index.closestHit` → `t`, world hit position + **normal** (P1a).
-2. `pathLength += t`; deposit current energy into `histogram[band][bin]`, `bin = floor(pathLength / c / binSeconds)` (`c` = speed of sound).
-3. fold absorption: `energy[band] *= (1 − material.absorption[band])`.
-4. scatter: with prob `material.scattering` → diffuse (`getBiasedNormalSample`, cosine lobe about the normal); else specular (reflect direction about the normal).
-5. `shiftForward(SELF_OCCLUSION_OFFSET · max(1,|origin|))`; Russian-roulette terminate (unbiased survivor scaling) after `min_bounce`.
-6. miss (escaped to open sky) → stop.
-
-Per probe: the per-band histogram (the **reflectogram**) → **per-band RT60** (decay slope, via Schroeder
-integration) + the early bins (room signature). This is the classic CATT/ODEON statistical method, and
-the same energy model Steam Audio's baked reflections use.
-
----
-
-## 2. Phases
-
-**P1 — Foundation (geometry-only tests).**
-- **✓ LANDED — P1a — `AbstractShape3D.raycast(hit, ray)`** (§0.6) on Sphere / Box / Capsule / Mesh — glue over the
-  narrowphase `*_raycast` core functions + an internal mesh BLAS. Engine-wide, generally useful, purely
-  additive to the shape classes. Test: known ray-vs-sphere/box/capsule/mesh hits (position + normal) and
-  misses, in the shape's local frame.
-- **✓ LANDED — P1b — `OccluderBody` class + occluder-index refactor to shapes** (§0.5 (4)(5), §0.6). Bodies hold
-  `shape + material + matrix + inverse` (inverse mandatory, identity default); `closestHit`/`anyHit`
-  localise the ray + `shape.raycast`, transform hit point (forward matrix) + normal (rotation) to world,
-  recover `t` for cross-body ordering; world-AABB broadphase from `shape.compute_bounding_box`. **Delete
-  `acoustic_geometry_from_shape`**; `AcousticBody`/`AcousticSimulationSystem` pass `Collider.shape`
-  through; `RayHit` gains world position + normal. Update the dependent specs (they currently feed
-  triangle soup). Test: occlusion/ray behaviour unchanged on shape colliders; hit normal correct.
-- **✓ LANDED — P1c — scatter + offset primitives**: `v3_reflect` (core, new) for the specular bounce;
-  the cosine-diffuse scatter reuses `getBiasedNormalSample` and the magnitude-scaled self-occlusion offset
-  reuses `Ray3.shiftForward` directly (both already existed — no wrappers needed). Tested: reflection law
-  (angle in = angle out, parallel-to-surface unchanged, unit-length preserved).
-
-**✓ LANDED — P2 — Bake core (no WebAudio).** `acoustic_trace_energy` (one ray's multi-bounce per-band
-deposit into a time-binned echogram — energy-threshold termination, not RR; see the deviation note up
-top) + `echogram_band_rt60` (Schroeder + ISO 3382 T30 slope) + `bakeReverbBands` (N rays → per-band
-RT60); `AcousticProbe` widened to `reverbDecay[3]` (scalar kept as the derived mean) + `ProbeField`
-table widened. **Sabine box gate passes** (baked cube RT60 ≈ 0.161·V/(S·α)). `bakeReverb` deleted.
-- `acoustic_trace_energy(index, origin, dir, …, histogram)` — one ray's multi-bounce energy deposit
-  (allocation-free, seeded).
-- `ReflectionProbeRenderer.bake(pos, probe)` — N rays → per-band histogram → per-band RT60 + early
-  envelope (mirrors `PathTracerProbeRenderer.bake`).
-- `AcousticReverbBaker.bake(probeField, ecd)` → `TaskGroup` (chunked over probes via `countTask`, like the
-  LPV baker; logs ms/probe).
-- **Widen `AcousticProbe`**: `reverbDecaySeconds` scalar → `reverbDecay[3]` (per-band) + optionally a short
-  early-reflection envelope; **keep the scalar derived from the bands** so the existing
-  `reverbImpulseResponse` / `ProbeReverbRenderer` path stays valid as a regression gate until the new path
-  is proven. Update `toJSON`/`fromJSON` + `bakeProbeField`.
-- **Validation gate — analytic Sabine box:** a closed box with known absorption has a known
-  RT60 (`0.161·V/(S·α)`); assert the baked late-slope matches within tolerance. Plus: per-band absorption
-  → per-band RT60 differs; open scene → ~no tail.
-
-**✓ LANDED — P3 — Render upgrade.**
-- `reverbImpulseResponse` shapes **per-band** decaying noise from `reverbDecay[3]` (each band's tail =
-  its RT60), summed → a geometry-derived IR with room *timbre*. `ProbeReverbRenderer` consumes the
-  widened probe. Test (`MockAudioContext`): IR band content reflects the per-band decays; crossfade still
-  click-safe.
-
-**P4 — Optional, measure-first (not the keystone).**
-- NEE-to-source (deposit `source→wall→listener` paths for a cleaner early-reflection IR at lower ray
-  count) — only if random-bounce variance is shown to be a problem.
-- **✓ LANDED — Body-level TLAS** over `AcousticOccluderIndex` — a dynamic BVH over the bodies' world AABBs,
-  gather via `bvh_query_user_data_ray_segment` (leaf user-data = handle, `BvhClient` refit on
-  `setTransform`). Landed early on owner request rather than waiting on the bake bench; `closestHit` /
-  `anyHit` are now O(log n + hits).
-
----
-
-## 3. Reuse map
-
-| Lifted **verbatim** (engine primitives) | Adapted / new (acoustic) |
-|---|---|
-| `getBiasedNormalSample` (cosine scatter), `construct_ray_hit_from_geometry` (hit normal), `random_point_on_sphere`, `Ray3.shiftForward` + scale-aware offset, the RR survivor-scaling pattern, `TaskGroup`/`countTask`, the baker ↔ probe-renderer split | the bounce loop (energy-time histogram vs radiance/SH), absorption-throughput fold, specular/diffuse split by `scattering`, Schroeder → RT60 reduction, per-band IR shaping |
-
-Keep the binary **`ebvh`** as the BLAS leaf (do not fork `BufferedGeometryBVH`'s inlined raycast). **Skip
-BVH8** (no CPU traversal kernel; lost to `ebvh` for 2-tri walls).
-
----
-
-## 4. Key decisions
-
-- **Dx — source-agnostic space bake (see §0).** The bake = per-region reverb profile + connectivity;
-  sources are fully runtime; reverb is selected by the *listener*; pathing is solved at runtime. Moving
-  geometry is live for occlusion, static-assumed for baked indirect, with a live path-edge `anyHit`
-  recheck + opt-in door variants. **No restriction to static sources, ever.**
-- **Statistical (energy-histogram) reverb**, one shared listener-centric IR per probe — affordable for
-  WebAudio; not per-source convolution.
-- **Per-band throughout** (collapsing to a scalar is the regression we are fixing).
-- **Unbiased & leak-free**: RR survivor scaling is mandatory; the scale-aware self-occlusion offset is
-  mandatory (a fixed epsilon silently leaks energy through walls at large world coords).
-- **Back-compat scalar path kept as the regression gate** until the per-band path validates against
-  Sabine — *correctness-first, no bandaid*.
-- **Skip wetness/humidity** (owner-agreed) and the wet-JCA physics.
-
----
-
-## 5. Testing
-
-Core (`core/` + `probe/`) is WebAudio-free → geometry-only tests, no audio mock. The Sabine box is the
-correctness gate for P2. The render (P3) uses `MockAudioContext`. Bench the bake ray cost before any
-TLAS. Run from the repo root: `npx jest --config jest.conf.json engine/sound/simulation`.
-
-## 6. Risks
-
-- **Probe-contract widening** (scalar → per-band) ripples through `AcousticProbe` serialization,
-  `bakeProbeField`, `reverbImpulseResponse`, `ProbeReverbRenderer` — hence P2 is the L item. Land P1
-  first (both S, self-contained), keep the scalar path behind the new curve.
-- **Bake cost** (rays × bounces × probes) is real but offline; `TaskGroup` chunking keeps it
-  non-blocking. Don't reach for the TLAS until the bench says so.
-- **Validation honesty**: trust the bake to replace `DECAY_PER_METRE` only after the Sabine-box RT60
-  matches analytics.
-
-## 7. Sequence
-
-P1a + P1b (S each, zero behavior change) → P2 (bake + Sabine gate) → P3 (render). P4 stays
-measured/optional.
+# Plan — Ray-traced reflection IR (probe-baked geometry reverb)
+
+> The keystone upgrade: replace `bakeReverb`'s single-hit mean-free-path heuristic with a true
+> ray-traced, time-binned, **per-band** reflection IR, reusing the engine's Monte-Carlo path tracer.
+> Closes the Steam-Audio *reflections* gap (early reflections + room timbre), replaces the hand-tuned
+> `DECAY_PER_METRE` constant with measured per-band RT60, and makes `scattering` / `absorption[3]` live
+> data.
+>
+> **Status (2026-06-20): COMPLETE — the keystone is LANDED + committed + green.** The foundation
+> (**P1a/P1b** shape-raycast index, the **§0.5** `RowFirstTable`/`CSRGraph`/BVH data structures, the **P4
+> TLAS**) and now the reflection-IR bake itself — **P1c → P2 → P3** — are all in. `bakeReverb`'s single-hit
+> heuristic + `DECAY_PER_METRE` are gone; reverb RT60 is now *measured* per band from multi-bounce ray
+> tracing, validated against an analytic Sabine box, and rendered as a per-band decaying-noise IR.
+>
+> **One deviation from this plan, for correctness:** the trace terminates by ENERGY THRESHOLD, **not**
+> Russian roulette (§1 step 5 / §4 said RR). Fixed-probability RR is the wrong estimator for acoustic
+> reflectance — a survivor at bounce *n* carries energy `(1−α)^n` but is scaled by `2^n`, so for a live
+> room (`1−α > ½`) the survivor weight grows as `(2(1−α))^n` and rare deep survivors swamp exactly the
+> late bins the RT60 slope is fitted to. Deterministic decay-to-floor is unbiased for the fit window and
+> far lower variance.
+
+The structural blueprint is **`engine/graphics/sh3/lpv/LightProbeVolumeBaker.js`** + its
+`PathTracerProbeRenderer` — a near-1:1 analogue (probe-volume baking against scene geometry via the path
+tracer). We mirror its baker ↔ probe-renderer split and `TaskGroup` orchestration; we swap the
+accumulator from SH-of-radiance to **energy-over-time per band**.
+
+---
+
+## 0. What is baked vs. runtime — the source-agnostic guarantee (answers the dynamic-sources question)
+
+**The bake NEVER encodes sound sources. It encodes SPACE: (a) per-region reverberation profile and
+(b) region connectivity.** Sources are 100% runtime. There is no restriction to static/fixed sources.
+
+| Concern | Baked? | What's baked | Source / geometry dynamics |
+|---|---|---|---|
+| Direct path: occlusion, transmission, air, distance | **never** — real-time ray-trace every frame against the live `AcousticOccluderIndex` | nothing | **sources AND moving occluders fully dynamic** |
+| Reverb (reflection IR / per-band RT60) | yes, per **probe** | the SPACE's reverberation response at that point (room geometry + materials), source-agnostic | **sources fully dynamic** — any source routes into the reverb selected by the **listener's** position; geometry assumed mostly-static |
+| Pathing (corner-leakage) | yes | inter-probe **visibility graph** (the space's connectivity), source-agnostic | **sources fully dynamic** — the path source↔listener is solved at runtime from live positions; geometry static-assumed (+ live recheck below) |
+
+**Why reverb is source-agnostic** — "reverb = reflections with the source at the listener." The
+late/diffuse reverberant field of a room is approximately uniform and a property of the room (volume +
+surface absorption), not of where the source is. So one **listener-centric** reverb per probe serves
+every source in that room: `ProbeReverbRenderer` already selects by the *listener's* nearest probe, and
+all sources send into that one shared reverb bus. A source can move anywhere — it never indexes the bake.
+
+**Early reflections are the one source-position-dependent part.** The per-probe envelope bakes them
+listener-centric (correct when source ≈ listener; and when the source is far, the position-independent
+late tail dominates anyway). True per-source early reflections would be a separate real-time pass —
+deferred; the direct-path occlusion machinery already does per-source real-time work, and the late tail
+is the dominant reverb cue.
+
+**Moving objects (dynamic geometry):**
+- **Occlusion / transmission — fully live.** The occluder index is dynamic (O(1) `setTransform`), so a
+  closing door / moving platform correctly blocks the *direct* path in real-time. No bake involved.
+- **Baked reverb + baked visibility — encode bake-time geometry.** A mover that changes acoustic
+  *topology* (a door sealing a room) is not in the bake. Policy, in order of cost:
+  1. Most reverb-affecting geometry is static (walls/floors); small movers barely shift RT60 → accept.
+  2. **Pathing live recheck** (cheap, from the review): re-verify the chosen exit edge with a single
+     `anyHit` ray each frame against live geometry — a closed door re-blocks the leak instantly even
+     though the baked graph still has the edge. One ray per pathed source.
+  3. **Opt-in door variants** for big dynamic dividers (vault door, portcullis gating a whole area's
+     reverb): bake open/closed variants for the affected probes and blend on door state (Steam Audio's
+     "dynamic geometry" approach) — per set-piece, not the default.
+  4. **Re-bake affected probes** on major static-set changes (level streaming) — offline, rare.
+
+This is the standard **real-time-direct / baked-indirect** split (Steam Audio's exact model): live where
+source + geometry move, baked where it is expensive and mostly-static, with targeted live rechecks for
+the dynamic cases that matter.
+
+---
+
+## 0.5 Foundation data structures (owner-directed, resolved)
+
+These replace the v1 POJO/array structures across the existing + new probe code with the engine's
+binary-backed primitives.
+
+1. **ProbeField store → `RowFirstTable`** (`core/collection/table/`), **not** `BinaryElementPool`. Probes
+   are baked **write-once** and read by integer row index, so a fixed-schema columnar binary table fits
+   exactly: one allocation, cache-friendly, no per-probe JS object. (`BinaryElementPool`'s alloc/free
+   pool semantics are for churny dynamic elements — unneeded here.) Schema via `RowFirstTableSpec`:
+   `x, y, z` (f32) · `reverbDecayLow/Mid/High` (f32, widened from the v1 scalar) · `bvhLeaf` (u32). The
+   `AcousticProbe` class becomes a thin row cursor/accessor (or is dropped for row-index access).
+
+2. **Pathing connectivity → `CSRGraph`** (`core/graph/csr/`), replacing `AcousticPathGraph.#adjacency`
+   (array-of-arrays). Baked once ⇒ CSR is the ideal static-graph form — `edge_addresses` (row pointers) +
+   `adjacency` + `edge_weights` in one buffer, with the cache-friendly `for (k=xadj[v]; k<xadj[v+1]; k++)`
+   walk that `computeExitField`/Dijkstra want. `edge_weights` is **`Float32Array`** (owner-updated — its
+   doc now cites "acoustic coupling"), so path distances go in **directly**, no quantization.
+   `bakeVisibility` builds it two-pass (count degrees → prefix-sum `edge_addresses` → fill) or via
+   `CSRGraph.fromArrays`.
+
+3. **Probe nearest → BVH + `bvh_query_user_data_nearest_to_point`** (`core/bvh2/bvh3/query/`), replacing
+   `ProbeField.nearest`'s linear scan. `ProbeField` builds a `BVH` of probe point-AABBs (leaf `user_data`
+   = row index) once after baking (the `SpatialAudioIndex` precedent); `nearest(x,y,z)` = one query →
+   row index, O(log n). This matters under the bake (`bakeVisibility` is O(probes²) nearest-style work)
+   and per-frame (`computeExitField` snaps listener + every pathed source to a probe).
+
+4. **`AcousticOccluderIndex` body → class** (replacing the `#bodies` POJO): a real `OccluderBody` holding
+   `shape, material, matrix, inverse, localAABB, worldAABB` (the triangle `blas/indices/positions` of this
+   v1 sketch are gone — §0.6 below raycasts the `shape` directly, so only meshes carry an internal BLAS).
+   `matrix` (the **forward** world transform) maps the local hit position + normal back to world space.
+
+5. **`body.inverse` mandatory — no `null` polymorphism.** `addBody`'s matrix defaults to `M4_IDENTITY`
+   and the inverse is **always** computed; `#localizeRay` always transforms (drop the `inverse === null`
+   fast-path). Uniform flow per [[feedback_uniform_flow]]. Production cost is nil — real occluder bodies
+   always carry a `Transform` matrix anyway; the identity fast-path was a test-only convenience.
+
+**Landing:** (4)+(5)+the stored forward matrix = the foundation of **P1a/P1b**. (1)+(3) = part of the
+**P2** probe refactor (the probe schema widens for per-band decay there regardless). (2) = a pathing
+refactor that can ride with P2 or land standalone first.
+
+---
+
+## 0.6 Raycast shapes directly — drop the triangulation (owner-directed)
+
+The v1 `acoustic_geometry_from_shape` triangulates collider shapes (box → 12 tris, …) into mesh soup —
+counter-productive: lossy for primitives, more triangles, a per-body BLAS for a 2-tri wall. **Replace it
+with a first-class `AbstractShape3D.raycast`**, so the occluder index stores **shapes** and raycasts them
+exactly (closed-form for primitives, an internal BLAS only for meshes).
+
+**Contract:** `AbstractShape3D.raycast(hit: Float32Array, ray: Ray3) → boolean`, shape at its LOCAL
+origin (the caller localises the ray), `hit = [px, py, pz, nx, ny, nz]` (local surface point + unit
+normal). The hit distance `t` is recovered by the caller as `(hitPoint − origin)·dir` (unit dir).
+
+**It is mostly glue** — the narrowphase already factored the local math into core functions that
+`refine_ray_hit` dispatches to:
+- `SphereShape3D` → `core/geom/3d/sphere/sphere_raycast.js`
+- `BoxShape3D` → `core/geom/3d/box/box3_raycast.js`
+- `CapsuleShape3D` → `core/geom/3d/capsule/capsule_raycast.js`
+- `MeshShape3D` → an **internal lazy ebvh BLAS** (`ebvh_build_for_geometry_morton` +
+  `ebvh_geometry_query_nearest_triangle_ray` + `construct_ray_hit_from_geometry`); the normal is
+  normalised and flipped to face the incoming ray. (Owner-approved: MeshShape3D gains an internal BLAS.)
+
+`AcousticOccluderIndex` then holds `shape + material + matrix + inverse` per body; `closestHit`/`anyHit`
+localise the world ray into body space and call `shape.raycast`, transforming the hit point (by the
+forward matrix) and normal (by the rotation) back to world. **`acoustic_geometry_from_shape` is deleted**;
+`AcousticBody`/`AcousticSimulationSystem` pass the `Collider.shape` straight through. (Could later let
+the physics `refine_ray_concave` share `MeshShape3D.raycast` — out of scope.)
+
+---
+
+## 1. Model — acoustic ray-tracing energy histogram
+
+From a probe (source = listener), shoot N rays over the sphere. Each ray carries a **per-band energy
+throughput** `[low, mid, high]`, init `1`. Bounce loop (modeled on `PathTracer.path_trace`):
+
+1. `index.closestHit` → `t`, world hit position + **normal** (P1a).
+2. `pathLength += t`; deposit current energy into `histogram[band][bin]`, `bin = floor(pathLength / c / binSeconds)` (`c` = speed of sound).
+3. fold absorption: `energy[band] *= (1 − material.absorption[band])`.
+4. scatter: with prob `material.scattering` → diffuse (`getBiasedNormalSample`, cosine lobe about the normal); else specular (reflect direction about the normal).
+5. `shiftForward(SELF_OCCLUSION_OFFSET · max(1,|origin|))`; Russian-roulette terminate (unbiased survivor scaling) after `min_bounce`.
+6. miss (escaped to open sky) → stop.
+
+Per probe: the per-band histogram (the **reflectogram**) → **per-band RT60** (decay slope, via Schroeder
+integration) + the early bins (room signature). This is the classic CATT/ODEON statistical method, and
+the same energy model Steam Audio's baked reflections use.
+
+---
+
+## 2. Phases
+
+**P1 — Foundation (geometry-only tests).**
+- **✓ LANDED — P1a — `AbstractShape3D.raycast(hit, ray)`** (§0.6) on Sphere / Box / Capsule / Mesh — glue over the
+  narrowphase `*_raycast` core functions + an internal mesh BLAS. Engine-wide, generally useful, purely
+  additive to the shape classes. Test: known ray-vs-sphere/box/capsule/mesh hits (position + normal) and
+  misses, in the shape's local frame.
+- **✓ LANDED — P1b — `OccluderBody` class + occluder-index refactor to shapes** (§0.5 (4)(5), §0.6). Bodies hold
+  `shape + material + matrix + inverse` (inverse mandatory, identity default); `closestHit`/`anyHit`
+  localise the ray + `shape.raycast`, transform hit point (forward matrix) + normal (rotation) to world,
+  recover `t` for cross-body ordering; world-AABB broadphase from `shape.compute_bounding_box`. **Delete
+  `acoustic_geometry_from_shape`**; `AcousticBody`/`AcousticSimulationSystem` pass `Collider.shape`
+  through; `RayHit` gains world position + normal. Update the dependent specs (they currently feed
+  triangle soup). Test: occlusion/ray behaviour unchanged on shape colliders; hit normal correct.
+- **✓ LANDED — P1c — scatter + offset primitives**: `v3_reflect` (core, new) for the specular bounce;
+  the cosine-diffuse scatter reuses `getBiasedNormalSample` and the magnitude-scaled self-occlusion offset
+  reuses `Ray3.shiftForward` directly (both already existed — no wrappers needed). Tested: reflection law
+  (angle in = angle out, parallel-to-surface unchanged, unit-length preserved).
+
+**✓ LANDED — P2 — Bake core (no WebAudio).** `acoustic_trace_energy` (one ray's multi-bounce per-band
+deposit into a time-binned echogram — energy-threshold termination, not RR; see the deviation note up
+top) + `echogram_band_rt60` (Schroeder + ISO 3382 T30 slope) + `bakeReverbBands` (N rays → per-band
+RT60); `AcousticProbe` widened to `reverbDecay[3]` (scalar kept as the derived mean) + `ProbeField`
+table widened. **Sabine box gate passes** (baked cube RT60 ≈ 0.161·V/(S·α)). `bakeReverb` deleted.
+- `acoustic_trace_energy(index, origin, dir, …, histogram)` — one ray's multi-bounce energy deposit
+  (allocation-free, seeded).
+- `ReflectionProbeRenderer.bake(pos, probe)` — N rays → per-band histogram → per-band RT60 + early
+  envelope (mirrors `PathTracerProbeRenderer.bake`).
+- `AcousticReverbBaker.bake(probeField, ecd)` → `TaskGroup` (chunked over probes via `countTask`, like the
+  LPV baker; logs ms/probe).
+- **Widen `AcousticProbe`**: `reverbDecaySeconds` scalar → `reverbDecay[3]` (per-band) + optionally a short
+  early-reflection envelope; **keep the scalar derived from the bands** so the existing
+  `reverbImpulseResponse` / `ProbeReverbRenderer` path stays valid as a regression gate until the new path
+  is proven. Update `toJSON`/`fromJSON` + `bakeProbeField`.
+- **Validation gate — analytic Sabine box:** a closed box with known absorption has a known
+  RT60 (`0.161·V/(S·α)`); assert the baked late-slope matches within tolerance. Plus: per-band absorption
+  → per-band RT60 differs; open scene → ~no tail.
+
+**✓ LANDED — P3 — Render upgrade.**
+- `reverbImpulseResponse` shapes **per-band** decaying noise from `reverbDecay[3]` (each band's tail =
+  its RT60), summed → a geometry-derived IR with room *timbre*. `ProbeReverbRenderer` consumes the
+  widened probe. Test (`MockAudioContext`): IR band content reflects the per-band decays; crossfade still
+  click-safe.
+
+**P4 — Optional, measure-first (not the keystone).**
+- NEE-to-source (deposit `source→wall→listener` paths for a cleaner early-reflection IR at lower ray
+  count) — only if random-bounce variance is shown to be a problem.
+- **✓ LANDED — Body-level TLAS** over `AcousticOccluderIndex` — a dynamic BVH over the bodies' world AABBs,
+  gather via `bvh_query_user_data_ray_segment` (leaf user-data = handle, `BvhClient` refit on
+  `setTransform`). Landed early on owner request rather than waiting on the bake bench; `closestHit` /
+  `anyHit` are now O(log n + hits).
+
+---
+
+## 3. Reuse map
+
+| Lifted **verbatim** (engine primitives) | Adapted / new (acoustic) |
+|---|---|
+| `getBiasedNormalSample` (cosine scatter), `construct_ray_hit_from_geometry` (hit normal), `random_point_on_sphere`, `Ray3.shiftForward` + scale-aware offset, the RR survivor-scaling pattern, `TaskGroup`/`countTask`, the baker ↔ probe-renderer split | the bounce loop (energy-time histogram vs radiance/SH), absorption-throughput fold, specular/diffuse split by `scattering`, Schroeder → RT60 reduction, per-band IR shaping |
+
+Keep the binary **`ebvh`** as the BLAS leaf (do not fork `BufferedGeometryBVH`'s inlined raycast). **Skip
+BVH8** (no CPU traversal kernel; lost to `ebvh` for 2-tri walls).
+
+---
+
+## 4. Key decisions
+
+- **Dx — source-agnostic space bake (see §0).** The bake = per-region reverb profile + connectivity;
+  sources are fully runtime; reverb is selected by the *listener*; pathing is solved at runtime. Moving
+  geometry is live for occlusion, static-assumed for baked indirect, with a live path-edge `anyHit`
+  recheck + opt-in door variants. **No restriction to static sources, ever.**
+- **Statistical (energy-histogram) reverb**, one shared listener-centric IR per probe — affordable for
+  WebAudio; not per-source convolution.
+- **Per-band throughout** (collapsing to a scalar is the regression we are fixing).
+- **Unbiased & leak-free**: RR survivor scaling is mandatory; the scale-aware self-occlusion offset is
+  mandatory (a fixed epsilon silently leaks energy through walls at large world coords).
+- **Back-compat scalar path kept as the regression gate** until the per-band path validates against
+  Sabine — *correctness-first, no bandaid*.
+- **Skip wetness/humidity** (owner-agreed) and the wet-JCA physics.
+
+---
+
+## 5. Testing
+
+Core (`core/` + `probe/`) is WebAudio-free → geometry-only tests, no audio mock. The Sabine box is the
+correctness gate for P2. The render (P3) uses `MockAudioContext`. Bench the bake ray cost before any
+TLAS. Run from the repo root: `npx jest --config jest.conf.json engine/sound/simulation`.
+
+## 6. Risks
+
+- **Probe-contract widening** (scalar → per-band) ripples through `AcousticProbe` serialization,
+  `bakeProbeField`, `reverbImpulseResponse`, `ProbeReverbRenderer` — hence P2 is the L item. Land P1
+  first (both S, self-contained), keep the scalar path behind the new curve.
+- **Bake cost** (rays × bounces × probes) is real but offline; `TaskGroup` chunking keeps it
+  non-blocking. Don't reach for the TLAS until the bench says so.
+- **Validation honesty**: trust the bake to replace `DECAY_PER_METRE` only after the Sabine-box RT60
+  matches analytics.
+
+## 7. Sequence
+
+P1a + P1b (S each, zero behavior change) → P2 (bake + Sabine gate) → P3 (render). P4 stays
+measured/optional.