@woosh/meep-engine 3.2.0 → 3.4.0

package/src/DUPLICATION_AUDIT_2026_08_07/F_sound.md

@@ -1,102 +1,110 @@
-# Domain F — engine/sound (legacy + sopra + acoustic simulation)
-
-All paths relative to `H:/git/moh/app/src/mir-engine/meep/src/`. Every finding below was verified by
-opening the cited files.
-
-## Findings
-
-| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
-|---|---|---|---|---|---|---|---|
-| 1 | HIGH | "Is this segment clear of occluders?" shadow-ray test written **3×**, each with its own module-static `Ray3` | `engine/sound/simulation/probe/probe_edge_visible.js:20` `probe_edge_visible`; `engine/sound/simulation/probe/probe_refine_connectivity.js:168` `segment_clear`; `engine/sound/simulation/probe/AcousticProbeField.js:328-345` (filter arrow in `nearestVisibleIndex`) | Brief C sim=0.75. All three do: zero-length ⇒ visible; `inv = 1/d`; `setOrigin/setDirection/tMax = d`; `!index.anyHit(RAY)`. `probe_refine_connectivity.js:167` comment literally says *"mirrors probe_edge_visible"*. `probe_edge_visible.js:8-9` claims it is *"the one visibility test shared by the offline bake and the runtime recheck, so they agree exactly"* — a claim the other two sites falsify | UNJUSTIFIED | `engine/sound/simulation/core/segment_clear.js` — `segment_clear(index, ax,ay,az, bx,by,bz)` with ONE scratch ray; `probe_edge_visible` becomes a 4-line probe-index wrapper; `nearestVisibleIndex`'s filter calls it directly | S / low |
-| 2 | HIGH | Undirected edge-list → CSR (degree count → prefix sum → fill via write cursor) written twice; plus a hand-rolled sorted-row `isNeighbour` binary search | `engine/sound/simulation/probe/bakeVisibility.js:109-141` (weighted, → `CSRGraph.fromArrays`); `engine/sound/simulation/probe/probe_visibility_augment.js:50-70` (unweighted + per-row `.sort()`), with `isNeighbour` at `:167-182` | Both consume the same `{a,b}` edge arrays produced by stages A–D of the same bake. `core/graph/csr/` has `CSRGraph`, `csr_graph_find_edge`, `csr_graph_build_distance_field`, `csr_graph_find_shortest_path` — but **no builder**, so every caller re-derives one | PROMOTION | `core/graph/csr/csr_graph_from_undirected_edge_list.js(vertex_count, a, b, weights?, {sorted_rows})`; `isNeighbour` → `csr_graph_find_edge !== -1` (give the core one a sorted-row fast path) | M / low |
-| 3 | HIGH | Listener resolution + `sopra.update(currentTime)` duplicated in two ECS systems that share ONE `SopraEngine` | `engine/sound/ecs/emitter/SoundEmitterSystem.js:137-158` `update`; `engine/sound/ecs/audio/AudioEmitterSystem.js:246-315` `update` | Both do `ecd.getAnyComponent(SoundListener)` → `getComponent(entity, Transform)` → `sopra.setListener(pos)` → `sopra.update(this.webAudioContext.currentTime)`. The engine is shared (`SoundEngine.obtainSopra`, `SoundEngine.js:82-88`), and BOTH class docs state coexistence is the design (`SoundEngine.js:76-78`, `AudioEmitterSystem.js:35-36`). Co-registering them double-runs `SopraEngine.update` (`sopra/SopraEngine.js:340-351`: snapshot + iterate all active instances + `#updateDuckers`). Harmless-but-wasted today because `EventInstance.#evaluate` guards on `entry.voice === null`; the copy-pasted "missing Transform" tolerance comment has already diverged (AudioEmitterSystem additionally skips `liveSet.refresh`) | UNJUSTIFIED | One owner for the tick: a `SopraTickSystem` (or fold listener-resolve + tick into `SoundListenerSystem`, which already owns the `SoundListener`+`Transform` pair). Emitter systems then only push emitter state | M / medium |
-| 4 | HIGH | The container child-hash fold is copy-pasted into all 4 concrete containers instead of living on the base that owns `children` — and has already diverged | `engine/sound/sopra/definition/clip/SequenceContainerAudioClip.js:26-35`; `RandomContainerAudioClip.js:130-144`; `SwitchContainerAudioClip.js:83-96`; `BlendContainerAudioClip.js:126-139` (all `hash()`) | Brief A [70×2] + E. `ContainerAudioClip` owns `children` and DOES implement the parallel `equals()` fold (`ContainerAudioClip.js:80-99`) but has no `hash()`. Divergence already present: `BlendContainerAudioClip.hash()` folds `parameter`+`defaultValue` but **not** `blends`, though `equals()` compares them (`:117-121`) and the adapter serializes them — two blend containers differing only in curves hash identically. `EventDescription` polyphony buckets are keyed by event content, so clip hashes are load-bearing | UNJUSTIFIED | `ContainerAudioClip.hash()` = `super.hash()` folded with each child's `hash()`; each subclass folds only its own fields on top (and Blend adds `blends`) | S / low |
-| 5 | MEDIUM | `AnimationCurve` binary keyframe codec hand-written twice | `engine/sound/sopra/definition/EventDescriptionSerializationAdapter.js:24-33` + `:55-64`; `engine/sound/sopra/definition/clip/BlendContainerAudioClipSerializationAdapter.js:20-33` + `:52-66` | Both carry the same excuse comment: *"AnimationCurve has no binary adapter of its own"*. Identical wire format (`uintVar` count, then `time/value/inTangent/outTangent` float32s). A payload change (wrap modes, tangent packing) must land in both or one silently mis-reads | PROMOTION | `engine/animation/curve/AnimationCurveSerializationAdapter.js` (or a `serialize_animation_curve` / `deserialize_animation_curve` pair beside `AnimationCurve.js`), registered so `this.objectAdapter` handles it | S / low |
-| 6 | MEDIUM | 3-band decaying-noise IR synthesis kernel duplicated | `engine/sound/simulation/render/reverbImpulseResponse.js:26` `reverbImpulseResponse` (kernel `:33-72`); `engine/sound/simulation/render/foaReverbImpulseResponse.js:33` `foaReverbImpulseResponse` (kernel `:41-96`) | Brief E (4-line window). Identical: bin-length derivation from `decayBands × sampleRate`, one-pole coefficients `a = 1 − e^(−2πf/fs)`, the energy-preserving `low/mid/high` split, and the three `Math.pow(1 − i/len, decayPower)` envelopes. Only the write-out differs (omni sum vs direction-weighted B-format). Retuning the crossover or envelope must land in both | UNJUSTIFIED (the shared part is a per-buffer producer, not a per-sample call) | A `write_band_tails(outLow, outMid, outHigh, length, lenLow, lenMid, lenHigh, decayPower, sampleRate, random)` both consume; scalar sums, FOA weights by direction | M / medium (numeric output must stay bit-identical — the specs pin it) |
-| 7 | MEDIUM | A **third** decaying-noise IR generator, unseeded | `engine/sound/sopra/definition/effect/ReverbEffect.js:45-66` `build` | Brief F `raw_math_random`: `data[i] = (Math.random() * 2 - 1) * Math.pow(1 - t, this.decayPower)` — the single-band case of finding 6. `reverbImpulseResponse.js:18` documents *"with three equal bands this reduces to the plain scalar tail"*, i.e. it already subsumes this. Divergence with teeth: the acoustic path is explicitly seeded (`ProbeReverbRenderer.js:97`, `FoaProbeReverbRenderer.js:161` → `seededRandom(1)`), so a sopra bus reverb is the only non-reproducible IR in the engine | UNJUSTIFIED | `ReverbEffect.build` → `reverbImpulseResponse(ctx, [d,d,d], this.decayPower, this.#random)` with a seeded RNG field | S / low |
-| 8 | MEDIUM | Probe-reverb renderer scaffolding duplicated, with a divergent re-bake trigger | `engine/sound/simulation/render/ProbeReverbRenderer.js:108-136` (ctor) + `:192-230` `setBands`; `engine/sound/simulation/render/FoaProbeReverbRenderer.js:172-236` (ctor) + `:296-333` `#rebake` | Same double-buffered convolver bank, same `#active` flip, same `rampGain(..., FADE_EPSILON, crossfadeSeconds, ctx)` crossfade, same `max(bands) >= minDecay` audibility gate, same `setProbeField`/`input`/`output` surface. But the scalar re-bakes on per-band hysteresis (`changeThreshold`, `:198-208`) while the FOA re-bakes on nearest-probe-index change plus a `#dirty` force-flag (`:123-131`, `:257-260`) that the scalar **lacks** — a `setProbeField` swap between two fields whose bands agree at the listener leaves the scalar renderer's IR stale | UNJUSTIFIED for the crossfade/gate scaffolding (JUSTIFIED for the differing WebAudio graph shape) | Extract an N-channel `ConvolverCrossfadeBank` (build, `swapTo(buffers[])`, `mute()`) both renderers own; give both the same `#dirty` semantics | M / medium |
-| 9 | MEDIUM | "Randomly orient a Fibonacci sample set" written twice, bypassing `random_point_on_sphere` | `engine/sound/simulation/core/OcclusionSolver.js:43-51` (in `solve`); `engine/sound/simulation/probe/bakeReverbBands.js:69-74` | Identical four lines: `z = 2·random()−1`, `azimuth = 2π·random()`, `ring = sqrt(max(0, 1−z²))`, then `v3_orthonormal_matrix_from_normal(ROTATION, 0, ring·cos, ring·sin, z)`. `core/geom/random/random_point_on_sphere.js` already produces the uniform direction | UNJUSTIFIED | `core/geom/random/random_orthonormal_basis(out9, out_offset, random)` beside `v3_orthonormal_matrix_from_normal`; at minimum call `random_point_on_sphere` for the direction | S / low |
-| 10 | MEDIUM | Canonical undirected edge key `min·n + max` written **4×** (and decoded in a 5th place) | `engine/sound/simulation/probe/ProbeVisibilityRecheck.js:72-75` `#edgeId` (decode at `:112-113`); `engine/sound/simulation/probe/probe_densify_portals.js:141-143` `edgeKey`; `engine/sound/simulation/probe/probe_visibility_bridge_components.js:84-86` (inline `rlo·n + rhi`); `engine/sound/simulation/probe/probe_visibility_augment.js:147` (inline `u·n + v`, correctness relies on the caller's `u<v` canonicalisation at `:96`) | A bug-prone invariant (must use the probe count as the radix AND canonicalise the pair) replicated across four modules of one bake pipeline; changing the radix (e.g. for >65k probes packing) silently breaks the ones you miss | UNJUSTIFIED | `engine/sound/simulation/probe/probe_edge_key.js` — `probe_edge_key(a, b, n)` + `probe_edge_decode(key, n, out2)` | S / low |
-| 11 | MEDIUM | `SoundControllerSystem` ≡ `AnimationControllerSystem` — the whole "component.rules → per-entity event-listener registration + teardown" ECS lifecycle | `engine/sound/ecs/SoundControllerSystem.js:49-101` `link` / `:103-113` `unlink`; `engine/graphics/ecs/animation/AnimationControllerSystem.js:18-62` `link` / `:64-72` `unlink` | Brief A [59×2] (`unlink` is token-identical) + E. Both hold `this.removers = []`, build `callbacks = this.removers[entity] = []`, register `{name, handler}` pairs for `rule.startEvent`/`rule.stopEvent` via `dataset.addEntityEventListener`, and tear down identically. Only the two handler bodies differ | UNJUSTIFIED (cross-domain, reported here per instructions) | A typed `EntityEventRuleBinding` value (owns the `{name, handler}` list, `bind(dataset, entity, name, handler)` / `release(dataset, entity)`) that both systems compose — no string-keyed registry involved | S / low |
-| 11b | LOW | `randomFromArray` re-derived inline | `engine/sound/ecs/SoundControllerSystem.js:13-24` `pickTackFromRule` | Brief F `raw_math_random`: `Math.floor(Math.random() * tracks.length)`. `core/math/random/randomFromArray.js` exists and is used correctly two directories away in `engine/sound/material/concrete/RandomSoundMaterial.js:17` | UNJUSTIFIED | `randomFromArray(Math.random, rule.tracks)` | XS / none |
-| 12 | MEDIUM | Emitter → `sopra.playEvent(...)` option mapping duplicated; drives a 9-positional-argument API | `engine/sound/ecs/audio/AudioEmitterSystem.js:209-233` `#play`; `engine/sound/ecs/audio/LiveEmitterSet.js:281-323` `#promote` (fed by `LiveEmitterSet.add` at `:158-163`, called with 9 positional args at `AudioEmitterSystem.js:139`) | Both derive `oneShot = !event.rootClip.loops()`, build the same `{busId, position, oneShot, acoustic, pathing, sourceRadius, orientation, directivity}` bag, then re-apply `setGainDb`. `LiveEmitterSet`'s record type (`:77`) is a hand-mirrored copy of that bag. Every new per-source acoustic property (`orientation`, `directivity` were the last two) must be threaded through the record, the 9-arg `add` signature, `#promote`, AND `#play` | UNJUSTIFIED | One typed `AudioEmitterPlaySpec` built from `(emitter, transform, acousticSim)`; `LiveEmitterSet.add(entity, spec)` stores it, `#promote` and `#play` both hand it to `playEvent` | M / low |
-| 13 | MEDIUM | Three hand-written "dynamic BVH of handle-addressed objects" wrappers inside one domain | `engine/sound/simulation/core/AcousticOccluderIndex.js:40-122`; `engine/sound/simulation/core/AcousticRegionIndex.js:23-134`; `engine/sound/ecs/audio/SpatialAudioIndex.js:24-138` | Identical skeleton in all three: `#bvh = new BVH()`, a parallel `BvhClient` store, retire-a-slot-by-null, a `#fitLeaf(client, x)` that ends in `client.resize(x0…z1)`, a reused `#candidates` gather buffer, and a query that maps returned handles back to user objects. Only the leaf-bounds policy and the refit trigger (reactive `onChanged` / per-frame `refit()` / explicit `setTransform`) differ | UNJUSTIFIED | `core/bvh2/bvh3/BvhObjectIndex.js` — typed container holding `T[]` + clients, with `computeBounds(out, item)` supplied by the owner; the three sound indices become thin policy classes | M / medium |
-| 13b | LOW | AABB union re-derived | `engine/sound/simulation/core/AcousticOccluderIndex.js:252-279` `computeWorldBounds` | Hand-written 6-component min/max fold; `core/geom/3d/aabb/aabb3_array_combine.js` does exactly this | UNJUSTIFIED | `aabb3_array_combine` | XS / none |
-| 14 | MEDIUM | Trilinear sampling of a Float32Array 3D scalar grid re-implemented | `engine/sound/simulation/probe/probe_sdf_grid.js:104-122` `grid_sample_trilinear` (+ `clampInt` at `:181-183`) | `engine/graphics/texture/3d/scs3d_sample_linear.js:15` is the same function: same `z·(rx·ry) + y·rx + x` layout, same edge clamping, same trilinear blend. `SingleChannelSampler3D` is the matching container. `probe_sdf_grid.js:1` already imports `clamp` yet still hand-rolls `clampInt` | UNJUSTIFIED | Back `SdfGrid` with `SingleChannelSampler3D` and call `scs3d_sample_linear`; delete `clampInt` | S / low |
-| 15 | LOW | `{type: ctor.typeName, data: x.toJSON()}` wrapper written 3× with two different `constructor` lookups | `engine/sound/material/concrete/json/serializeSoundMaterialToJSON.js:1-6` (`material.constructor.typeName`); `engine/sound/sopra/serialization/sopraJSON.js:22-27` `serializeAudioClipToJSON` and `:68-73` `serializeAudioEffectToJSON` (`Object.getPrototypeOf(x).constructor.typeName`) | Brief A [70×2], C sim=1. The **switch-based deserializers** (`deserializeSoundMaterialFromJSON.js:12`, `sopraJSON.js:33`, `sopraJSON.js:79`) are **JUSTIFIED** — the alternative in core (`core/json/abstractJSONDeserializer.js`) is precisely the string-keyed `Map<string, fn>` registry the house rules reject, and `sopraJSON.js:11-16` documents deliberate call-time class binding to survive an import cycle. Only the three one-line serializers are gratuitous, and they disagree on how to reach the constructor | UNJUSTIFIED (serializers only) | One `type_tagged_to_json(value)` helper (typed, no registry); pick one constructor lookup | XS / none |
-| 16 | LOW | `dB2Volume` re-derived inline in a file that already imports it | `engine/sound/sopra/runtime/EventInstance.js:33-35` `dbTiltToGain` → `Math.pow(10, -excessDb / 20)`; `dB2Volume` imported at `:2` | Called 4× per acoustic instance per frame (`:542-543`, `:561-562`) — not per-sample, so no inlining justification | UNJUSTIFIED | `excessDb <= 0 ? 1 : dB2Volume(-excessDb)` | XS / none |
-| 17 | LOW | `BusGraph` repeats the same lookup-or-throw preamble 6× | `engine/sound/sopra/runtime/BusGraph.js:143` `getInput`, `:159` `getOutput`, `:173` `getVolume`, `:187` `setVolume`, `:214` `rampVolume`, `:232` `approachVolume` | Six copies of `const bus = this.buses.get(id); if (bus === undefined) { throw new Error(\`sopra: no bus '${id}'\`); }` — ~30 lines | UNJUSTIFIED | A `#bus(id)` private that does the lookup + throw | XS / none |
-| 18 | LOW / PROMOTION | The `setFlag`/`clearFlag`/`writeFlag`/`getFlag` quad, byte-identical in **35 files** | In this domain: `engine/sound/ecs/emitter/SoundEmitter.js:156-189`; `engine/sound/ecs/emitter/SoundTrack.js:138-171`; `engine/sound/asset/SoundAssetPlaybackSpec.js`; `engine/ecs/speaker/Voice.js:13-46` | Brief E (30-file window). `grep -l "clearFlag(flag) {"` returns 35 files spanning core/, engine/ecs, graphics, physics, sound, view | PROMOTION (codebase-wide, not sound-specific — flagged for the cross-domain roll-up, not for a sound-local fix) | A `FlagCarrier` base (or a shared `flags_set/clear/write/read` quartet on the flat `flags` word); JS single inheritance makes the base awkward where a class already extends, so the function quartet is the safer shape | L / medium |
-| 19 | LOW | Well-conditioned perpendicular-axis construction re-derived | `engine/sound/simulation/probe/probe_detect_portals.js:170-184` `throatIsAperture` | Hand-rolls "cross with world-up, swap reference if `|ey| > 0.9`, normalize". `core/geom/vec3/v3_orthonormal_matrix_from_normal.js` builds exactly this stable basis and is already used twice in this same package (`OcclusionSolver.js:48`, `bakeReverbBands.js:74`) | UNJUSTIFIED | `v3_orthonormal_matrix_from_normal` and read the tangent column | XS / low |
-| 20 | LOW | Vector normalize written by hand, inconsistently with the same file | `engine/sound/simulation/AcousticSimulator.js:598-621` `#directivityGainToward` (`Math.sqrt(dx*dx+dy*dy+dz*dz)` at `:605`) vs `:454, :455, :459, :460` in `#applyPath` (`Math.hypot`) | Brief F `inline_length3`. Cold path (once per non-omni source per frame). `v3_length` / `v3_normalize_array` exist; the file already imports `line3_compute_segment_closest_point_t` from the same family | UNJUSTIFIED (cold) | `v3_length`, or at least pick one of `Math.hypot`/`sqrt` within the file | XS / none |
-| 21 | LOW / PROMOTION | Union-find connected components over probe connectivity written twice | `engine/sound/simulation/probe/probe_visibility_bridge_components.js:35-39` (from an `{a,b}` edge list); `engine/sound/simulation/probe/probe_refine_connectivity.js:50-56` (from a `CSRGraph`) | Both then use `uf_find(parent, i) === uf_find(parent, j)` as the same-component predicate. `core/graph/graph_compute_disconnected_clusters.js` exists but only for the object-graph `Graph`, not `CSRGraph` | PROMOTION | `core/graph/csr/csr_graph_connected_components(parent, graph)` beside `csr_graph_build_distance_field`; the edge-list variant folds into finding 2's builder | S / low |
-
-## Strangler-migration debt
-
-Context, not a defect list. Legacy-vs-sopra parallelism is the deliberate migration shape; what matters is
-where the seam has stalled and where a fix would have to land twice.
-
-| Legacy | sopra / native counterpart | Is legacy still wired? | Note |
-|---|---|---|---|
-| `ecs/emitter/SoundEmitterSystem` + `SoundEmitterComponentContext` | `ecs/audio/AudioEmitterSystem` + `AudioEmitter` + `LiveEmitterSet` | **YES** — `mir-engine/model/game/makeMirEngineConfig.js:182` | The seam is genuinely healthy here: legacy is a *translator* (`sopra/legacy/soundEmitterToEventDescription.js`) onto sopra, not a second renderer. Conversely `AudioEmitter*` has **zero** consumers outside `engine/sound/` — the new path is unused in the game |
-| `ecs/SoundControllerSystem` | none — its own JSDoc names a *"forthcoming `AudioEventTrigger`"* (`SoundControllerSystem.js:27-30`) | **YES** — `makeMirEngineConfig.js:183` | `@deprecated` and still registered with no replacement in the tree. Findings 11/11b live here |
-| `material/**` (`AbstractSoundMaterialDefinition`, `Single`/`Random`/`Composition`, `json/`) | sopra clips — `SwitchContainerAudioClip.js:11` *"Supersedes the dormant material/ surface-switch concept"*; `BlendContainerAudioClip.js:13` *"Supersedes the dormant material/ composition concept"* | **NO** — grep finds zero references outside `engine/sound/material/` (only a doc mention in `sopraJSON.js:13`) | Dead but public surface (meep is a library). Origin of the JSON copies in finding 15 |
-| `SoundEmitterChannels` (`effects`/`music`/`ambient`) | sopra `SopraDefaultBus` + `BusDefinition` | **YES** — 7 app files import it (UnitMaker, StoryManager, WorldEventManager, …) | Already proxied 1:1: `SoundEmitterSystem.get/setChannelVolume` (`:91-102`) forwards to `sopra.get/setBusVolume` |
-| `ecs/SoundListenerSystem` (WebAudio `AudioListener` pose) | `sopra.setListener(position)` inside the emitter systems | **YES** — `makeMirEngineConfig.js:184` | THREE readers of the same `SoundListener`→`Transform` relation. sopra's listener is position-only; the WebAudio listener also carries orientation. See finding 3 |
-| `ProbeReverbRenderer` (scalar) | `FoaProbeReverbRenderer` (directional/B-format) | scalar is what `configureAcousticSimulation.js:31` documents; FOA is referenced only by `prototypeAcousticSolver.js:515` + its spec | Neither is deprecated; both live. Findings 6/8 mean an IR or crossfade fix must land in both |
-| `ecs/emitter/SoundPanningModelType` | `sopra/definition/SopraPanningModel` | **YES** — translated by `soundEmitterToEventDescription.js:57-61` | Identical 2-value enums; translation is one ternary. Fine |
-| `SoundAttenuationFunction` + `core/math/physics/irradiance/interpolate_irradiance_*` | authored `AnimationCurve` via `sopra/util/buildAttenuationCurve.js` | **YES** | This is the *good* seam: the legacy falloffs are REUSED to sample the new curve rather than reimplemented. Called out as a model, not debt |
-
-## Dismissed leads
-
-- Brief A/C `makePhysicsGroundResolver` / `recomputeMove` / `bindMoveKey` / `buildInputBindings` / `logHelp` (`engine/control/first-person/prototype_first_person_controller.js` ⟷ `engine/sound/simulation/prototypeAcousticSolver.js`) — both sites are `prototype*.js` harnesses, out of scope. **One line as instructed:** a real shared debug fly/walk camera *with* a physics ground resolver would be worth promoting to `engine/control/`, since it is now copied verbatim for every new subsystem demo.
-- `DuckingRuleSerializationAdapter` / `CompressorEffectSerializationAdapter` / `ParameterDefinitionSerializationAdapter` `serialize`+`deserialize` (brief A [50×3] and [45×3]) — read all three: different field names and types (`writeUTF8String`+3×float32+float32 / 5×float32 / string+3×float32+uint8), zero shared logic. Exactly the per-class shape boilerplate the house rules bless.
-- `SequenceContainerAudioClipSerializationAdapter.deserialize` ⟷ `SwitchContainerAudioClipSerializationAdapter.deserialize` (brief C sim=0.781) — same verdict; Switch additionally reads `parameter`/`defaultValue`.
-- The container adapters' repeated `gain`/`pitch` writes and children loop (brief E) — wire order is per-class protocol; hoisting it into a base couples four independent binary formats. Deliberate.
-- `MixerSnapshotSerializationAdapter` bus-entry codec vs `BusDefinitionSerializationAdapter` sends codec — structurally identical (`string` + `float32` pairs), semantically distinct record types. Shape only.
-- `engine/ecs/speaker/Voice.js` vs `engine/sound/sopra/runtime/Voice.js` (brief G) — pure name collision. The first is a speech-bubble ECS component (flags only, `Voice.serializable = false`); the second is a WebAudio `AudioBufferSourceNode` holder. No shared logic beyond the flag quad (finding 18). The `speaker/` package has no importers, but meep is a library — not a defect.
-- `echogram_band_rt60.js:49` `10 * Math.log10(edc / total)` — **energy** dB, deliberately not `volume2dB`'s amplitude `20·log10`. Correct as written.
-- Brief F `inline_lerp` in `probe_sdf_grid.js:118-121` — the innermost trilinear blend; folds into finding 14 anyway. `AcousticSimulator.js:453, :458` and `probe_detect_portals.js:94, :109` are 3-component point-on-segment evaluations, not scalar `lerp` calls.
-- Brief F `inline_length3`, the remaining ~14 hits — hot per-ray / per-edge / per-candidate-pair loops (`OcclusionSolver.js:79` per ray, `bakeVisibility.js:106` per graph edge, `probe_visibility_augment.js:92,108,111` per 2-ring chord). Inlining is the right call there; only the cold `AcousticSimulator` site (finding 20) is worth changing.
-- Brief F `epsilon_compare` `ProbeReverbRenderer.js:198-200` — a tunable re-bake hysteresis (`changeThreshold = 0.1 s`), not float-tolerance equality. `epsilonEquals` would be semantically wrong.
-- Brief F `binary_search_inline` `probe_visibility_augment.js:171` — folded into finding 2.
-- `EventInstance.js:47-92` `build3BandCrossover` / `set3BandGains` / `disconnect3Band` — already correctly factored and shared by BOTH the direct and corner-leak paths (`:457`, `:476`). No duplication; a model for finding 8.
-- `ProbeFieldPathingSolution.js:62` correctly delegates to `csr_graph_build_distance_field`, and `AcousticProbeField.shortestPath:519` to `csr_graph_find_shortest_path`. **No Dijkstra / graph-search duplication in `simulation/`** — the probe pathing is a clean `core/graph` consumer.
-- No hand-rolled biquad coefficient math, equal-power panning law, or crossfade curve anywhere in the domain — WebAudio nodes (`createBiquadFilter`, `PannerNode`, `linearRampToValueAtTime`) do all of it. The one filter-adjacent formula, the one-pole coefficient `1 − e^(−2πf/fs)`, is finding 6.
-- The 3-band value classes (`AcousticMedium`, `AcousticMaterial`, `AcousticSolution`, `AcousticSourceState`) unroll their 3-element copies by hand in `equals`/`clone`/`hash`/`toJSON` — typed, explicit, per-field. Consistent with "typed over magic"; not duplication of *logic*.
-
-## Notes — why duplication accumulates here
-
-1. **Three generations coexist in one package.** `material/` (dead, superseded), `ecs/emitter/` (legacy, wired,
-   now a translator), and `sopra/` + `ecs/audio/` (new, unwired outside the engine). Each generation
-   re-solved the same problems — polymorphic type-tagged JSON, weighted random selection, composition
-   with per-child weights — because the previous one was not being deleted. The three JSON dispatchers
-   (finding 15) and the material-vs-clip parallel hierarchy are the visible residue.
-
-2. **The migration seam stalled at the game boundary, not inside the engine.** Inside `engine/sound/`
-   the strangler is genuinely done — sopra is the single renderer and legacy is a translator. But
-   `makeMirEngineConfig.js` still registers the three legacy systems and nothing registers
-   `AudioEmitterSystem`, so the new path's code has no production caller keeping it honest. That is
-   what let finding 3 (two systems each owning the sopra tick) and finding 12 (two copies of the
-   play-options mapping) survive: only one of each pair actually runs.
-
-3. **`core/graph/csr/` ships consumers but no producer.** It has Dijkstra, distance fields, and edge
-   lookup, but no `from_edge_list` builder — so the probe bake writes its own twice (finding 2), and the
-   companions it also needs (connected components, canonical edge key) got written locally 2–4× each
-   (findings 10, 21). One missing primitive generated four findings.
-
-4. **Ray-scratch locality beats reuse.** Every module that casts a shadow ray declares its own
-   module-static `Ray3` and inlines the normalize-and-set sequence (finding 1). The pattern is
-   allocation-free by construction, which makes the copy feel cheap, but it means the "one shared
-   visibility test" the code documents does not actually exist.
-
-5. **Per-sample DSP genuinely justifies inlining — but the justification got over-applied.** The IR
-   synthesis kernels (findings 6, 7) share far more than the inner loop: window sizing, filter
-   coefficients, and envelope shape are all per-*bake* work that could be shared without a per-sample
-   call. The `EventInstance` crossover helpers show the team already knows how to draw that line
-   correctly; the reverb bakers just predate it.
-
-6. **The base class stops one level short.** `AbstractAudioClip` folds `gain`/`pitch` into `hash()`, and
-   `ContainerAudioClip` folds `children` into `equals()` — but not into `hash()`. Four subclasses filled
-   the gap by copy-paste, and one of them (Blend) has already drifted (finding 4). The same shape
-   appears in the container adapters, where the base clip fields are re-written per subclass.
+# Domain F — engine/sound (legacy + sopra + acoustic simulation)
+
+All paths relative to `H:/git/moh/app/src/mir-engine/meep/src/`. Every finding below was verified by
+opening the cited files.
+
+## Findings
+
+| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
+|---|---|---|---|---|---|---|---|
+| 1 | HIGH | "Is this segment clear of occluders?" shadow-ray test written **3×**, each with its own module-static `Ray3` | `engine/sound/simulation/probe/probe_edge_visible.js:20` `probe_edge_visible`; `engine/sound/simulation/probe/probe_refine_connectivity.js:168` `segment_clear`; `engine/sound/simulation/probe/AcousticProbeField.js:328-345` (filter arrow in `nearestVisibleIndex`) | Brief C sim=0.75. All three do: zero-length ⇒ visible; `inv = 1/d`; `setOrigin/setDirection/tMax = d`; `!index.anyHit(RAY)`. `probe_refine_connectivity.js:167` comment literally says *"mirrors probe_edge_visible"*. `probe_edge_visible.js:8-9` claims it is *"the one visibility test shared by the offline bake and the runtime recheck, so they agree exactly"* — a claim the other two sites falsify | UNJUSTIFIED | `engine/sound/simulation/core/segment_clear.js` — `segment_clear(index, ax,ay,az, bx,by,bz)` with ONE scratch ray; `probe_edge_visible` becomes a 4-line probe-index wrapper; `nearestVisibleIndex`'s filter calls it directly | S / low |
+| 2 | HIGH | Undirected edge-list → CSR (degree count → prefix sum → fill via write cursor) written twice; plus a hand-rolled sorted-row `isNeighbour` binary search | `engine/sound/simulation/probe/bakeVisibility.js:109-141` (weighted, → `CSRGraph.fromArrays`); `engine/sound/simulation/probe/probe_visibility_augment.js:50-70` (unweighted + per-row `.sort()`), with `isNeighbour` at `:167-182` | Both consume the same `{a,b}` edge arrays produced by stages A–D of the same bake. `core/graph/csr/` has `CSRGraph`, `csr_graph_find_edge`, `csr_graph_build_distance_field`, `csr_graph_find_shortest_path` — but **no builder**, so every caller re-derives one | PROMOTION | `core/graph/csr/csr_graph_from_undirected_edge_list.js(vertex_count, a, b, weights?, {sorted_rows})`; `isNeighbour` → `csr_graph_find_edge !== -1` (give the core one a sorted-row fast path) | M / low |
+| 3 | HIGH | Listener resolution + `sopra.update(currentTime)` duplicated in two ECS systems that share ONE `SopraEngine` | `engine/sound/ecs/emitter/SoundEmitterSystem.js:137-158` `update`; `engine/sound/ecs/audio/AudioEmitterSystem.js:246-315` `update` | Both do `ecd.getAnyComponent(SoundListener)` → `getComponent(entity, Transform)` → `sopra.setListener(pos)` → `sopra.update(this.webAudioContext.currentTime)`. The engine is shared (`SoundEngine.obtainSopra`, `SoundEngine.js:82-88`), and BOTH class docs state coexistence is the design (`SoundEngine.js:76-78`, `AudioEmitterSystem.js:35-36`). Co-registering them double-runs `SopraEngine.update` (`sopra/SopraEngine.js:340-351`: snapshot + iterate all active instances + `#updateDuckers`). Harmless-but-wasted today because `EventInstance.#evaluate` guards on `entry.voice === null`; the copy-pasted "missing Transform" tolerance comment has already diverged (AudioEmitterSystem additionally skips `liveSet.refresh`) | UNJUSTIFIED | One owner for the tick: a `SopraTickSystem` (or fold listener-resolve + tick into `SoundListenerSystem`, which already owns the `SoundListener`+`Transform` pair). Emitter systems then only push emitter state | M / medium |
+| 4 | HIGH | The container child-hash fold is copy-pasted into all 4 concrete containers instead of living on the base that owns `children` — and has already diverged | `engine/sound/sopra/definition/clip/SequenceContainerAudioClip.js:26-35`; `RandomContainerAudioClip.js:130-144`; `SwitchContainerAudioClip.js:83-96`; `BlendContainerAudioClip.js:126-139` (all `hash()`) | Brief A [70×2] + E. `ContainerAudioClip` owns `children` and DOES implement the parallel `equals()` fold (`ContainerAudioClip.js:80-99`) but has no `hash()`. Divergence already present: `BlendContainerAudioClip.hash()` folds `parameter`+`defaultValue` but **not** `blends`, though `equals()` compares them (`:117-121`) and the adapter serializes them — two blend containers differing only in curves hash identically. `EventDescription` polyphony buckets are keyed by event content, so clip hashes are load-bearing | UNJUSTIFIED | `ContainerAudioClip.hash()` = `super.hash()` folded with each child's `hash()`; each subclass folds only its own fields on top (and Blend adds `blends`) | S / low |
+| 5 | MEDIUM | `AnimationCurve` binary keyframe codec hand-written twice | `engine/sound/sopra/definition/EventDescriptionSerializationAdapter.js:24-33` + `:55-64`; `engine/sound/sopra/definition/clip/BlendContainerAudioClipSerializationAdapter.js:20-33` + `:52-66` | Both carry the same excuse comment: *"AnimationCurve has no binary adapter of its own"*. Identical wire format (`uintVar` count, then `time/value/inTangent/outTangent` float32s). A payload change (wrap modes, tangent packing) must land in both or one silently mis-reads | PROMOTION | `engine/animation/curve/AnimationCurveSerializationAdapter.js` (or a `serialize_animation_curve` / `deserialize_animation_curve` pair beside `AnimationCurve.js`), registered so `this.objectAdapter` handles it | S / low |
+| 6 | MEDIUM | 3-band decaying-noise IR synthesis kernel duplicated | `engine/sound/simulation/render/reverbImpulseResponse.js:26` `reverbImpulseResponse` (kernel `:33-72`); `engine/sound/simulation/render/foaReverbImpulseResponse.js:33` `foaReverbImpulseResponse` (kernel `:41-96`) | Brief E (4-line window). Identical: bin-length derivation from `decayBands × sampleRate`, one-pole coefficients `a = 1 − e^(−2πf/fs)`, the energy-preserving `low/mid/high` split, and the three `Math.pow(1 − i/len, decayPower)` envelopes. Only the write-out differs (omni sum vs direction-weighted B-format). Retuning the crossover or envelope must land in both | UNJUSTIFIED (the shared part is a per-buffer producer, not a per-sample call) | A `write_band_tails(outLow, outMid, outHigh, length, lenLow, lenMid, lenHigh, decayPower, sampleRate, random)` both consume; scalar sums, FOA weights by direction | M / medium (numeric output must stay bit-identical — the specs pin it) |
+| 7 | MEDIUM | A **third** decaying-noise IR generator, unseeded | `engine/sound/sopra/definition/effect/ReverbEffect.js:45-66` `build` | Brief F `raw_math_random`: `data[i] = (Math.random() * 2 - 1) * Math.pow(1 - t, this.decayPower)` — the single-band case of finding 6. `reverbImpulseResponse.js:18` documents *"with three equal bands this reduces to the plain scalar tail"*, i.e. it already subsumes this. Divergence with teeth: the acoustic path is explicitly seeded (`ProbeReverbRenderer.js:97`, `FoaProbeReverbRenderer.js:161` → `seededRandom(1)`), so a sopra bus reverb is the only non-reproducible IR in the engine | UNJUSTIFIED | `ReverbEffect.build` → `reverbImpulseResponse(ctx, [d,d,d], this.decayPower, this.#random)` with a seeded RNG field | S / low |
+| 8 | MEDIUM | Probe-reverb renderer scaffolding duplicated, with a divergent re-bake trigger | `engine/sound/simulation/render/ProbeReverbRenderer.js:108-136` (ctor) + `:192-230` `setBands`; `engine/sound/simulation/render/FoaProbeReverbRenderer.js:172-236` (ctor) + `:296-333` `#rebake` | Same double-buffered convolver bank, same `#active` flip, same `rampGain(..., FADE_EPSILON, crossfadeSeconds, ctx)` crossfade, same `max(bands) >= minDecay` audibility gate, same `setProbeField`/`input`/`output` surface. But the scalar re-bakes on per-band hysteresis (`changeThreshold`, `:198-208`) while the FOA re-bakes on nearest-probe-index change plus a `#dirty` force-flag (`:123-131`, `:257-260`) that the scalar **lacks** — a `setProbeField` swap between two fields whose bands agree at the listener leaves the scalar renderer's IR stale | UNJUSTIFIED for the crossfade/gate scaffolding (JUSTIFIED for the differing WebAudio graph shape) | Extract an N-channel `ConvolverCrossfadeBank` (build, `swapTo(buffers[])`, `mute()`) both renderers own; give both the same `#dirty` semantics | M / medium |
+| 9 | MEDIUM | "Randomly orient a Fibonacci sample set" written twice, bypassing `random_point_on_sphere` | `engine/sound/simulation/core/OcclusionSolver.js:43-51` (in `solve`); `engine/sound/simulation/probe/bakeReverbBands.js:69-74` | Identical four lines: `z = 2·random()−1`, `azimuth = 2π·random()`, `ring = sqrt(max(0, 1−z²))`, then `v3_orthonormal_matrix_from_normal(ROTATION, 0, ring·cos, ring·sin, z)`. `core/geom/random/random_point_on_sphere.js` already produces the uniform direction | UNJUSTIFIED | `core/geom/random/random_orthonormal_basis(out9, out_offset, random)` beside `v3_orthonormal_matrix_from_normal`; at minimum call `random_point_on_sphere` for the direction | S / low |
+| 10 | MEDIUM | Canonical undirected edge key `min·n + max` written **4×** (and decoded in a 5th place) | `engine/sound/simulation/probe/ProbeVisibilityRecheck.js:72-75` `#edgeId` (decode at `:112-113`); `engine/sound/simulation/probe/probe_densify_portals.js:141-143` `edgeKey`; `engine/sound/simulation/probe/probe_visibility_bridge_components.js:84-86` (inline `rlo·n + rhi`); `engine/sound/simulation/probe/probe_visibility_augment.js:147` (inline `u·n + v`, correctness relies on the caller's `u<v` canonicalisation at `:96`) | A bug-prone invariant (must use the probe count as the radix AND canonicalise the pair) replicated across four modules of one bake pipeline; changing the radix (e.g. for >65k probes packing) silently breaks the ones you miss | UNJUSTIFIED | `engine/sound/simulation/probe/probe_edge_key.js` — `probe_edge_key(a, b, n)` + `probe_edge_decode(key, n, out2)` | S / low |
+| 11 | MEDIUM | `SoundControllerSystem` ≡ `AnimationControllerSystem` — the whole "component.rules → per-entity event-listener registration + teardown" ECS lifecycle | `engine/sound/ecs/SoundControllerSystem.js:49-101` `link` / `:103-113` `unlink`; `engine/graphics/ecs/animation/AnimationControllerSystem.js:18-62` `link` / `:64-72` `unlink` | Brief A [59×2] (`unlink` is token-identical) + E. Both hold `this.removers = []`, build `callbacks = this.removers[entity] = []`, register `{name, handler}` pairs for `rule.startEvent`/`rule.stopEvent` via `dataset.addEntityEventListener`, and tear down identically. Only the two handler bodies differ | UNJUSTIFIED (cross-domain, reported here per instructions) | A typed `EntityEventRuleBinding` value (owns the `{name, handler}` list, `bind(dataset, entity, name, handler)` / `release(dataset, entity)`) that both systems compose — no string-keyed registry involved | S / low |
+| 11b | LOW | `randomFromArray` re-derived inline | `engine/sound/ecs/SoundControllerSystem.js:13-24` `pickTackFromRule` | Brief F `raw_math_random`: `Math.floor(Math.random() * tracks.length)`. `core/math/random/randomFromArray.js` exists and is used correctly two directories away in `engine/sound/material/concrete/RandomSoundMaterial.js:17` | UNJUSTIFIED | `randomFromArray(Math.random, rule.tracks)` | XS / none |
+| 12 | MEDIUM | Emitter → `sopra.playEvent(...)` option mapping duplicated; drives a 9-positional-argument API | `engine/sound/ecs/audio/AudioEmitterSystem.js:209-233` `#play`; `engine/sound/ecs/audio/LiveEmitterSet.js:281-323` `#promote` (fed by `LiveEmitterSet.add` at `:158-163`, called with 9 positional args at `AudioEmitterSystem.js:139`) | Both derive `oneShot = !event.rootClip.loops()`, build the same `{busId, position, oneShot, acoustic, pathing, sourceRadius, orientation, directivity}` bag, then re-apply `setGainDb`. `LiveEmitterSet`'s record type (`:77`) is a hand-mirrored copy of that bag. Every new per-source acoustic property (`orientation`, `directivity` were the last two) must be threaded through the record, the 9-arg `add` signature, `#promote`, AND `#play` | UNJUSTIFIED | One typed `AudioEmitterPlaySpec` built from `(emitter, transform, acousticSim)`; `LiveEmitterSet.add(entity, spec)` stores it, `#promote` and `#play` both hand it to `playEvent` | M / low |
+| 13 | MEDIUM | Three hand-written "dynamic BVH of handle-addressed objects" wrappers inside one domain | `engine/sound/simulation/core/AcousticOccluderIndex.js:40-122`; `engine/sound/simulation/core/AcousticRegionIndex.js:23-134`; `engine/sound/ecs/audio/SpatialAudioIndex.js:24-138` | Identical skeleton in all three: `#bvh = new BVH()`, a parallel `BvhClient` store, retire-a-slot-by-null, a `#fitLeaf(client, x)` that ends in `client.resize(x0…z1)`, a reused `#candidates` gather buffer, and a query that maps returned handles back to user objects. Only the leaf-bounds policy and the refit trigger (reactive `onChanged` / per-frame `refit()` / explicit `setTransform`) differ | UNJUSTIFIED | `core/bvh2/bvh3/BvhObjectIndex.js` — typed container holding `T[]` + clients, with `computeBounds(out, item)` supplied by the owner; the three sound indices become thin policy classes | M / medium |
+| 13b | LOW | AABB union re-derived | `engine/sound/simulation/core/AcousticOccluderIndex.js:252-279` `computeWorldBounds` | Hand-written 6-component min/max fold; `core/geom/3d/aabb/aabb3_array_combine.js` does exactly this | UNJUSTIFIED | `aabb3_array_combine` | XS / none |
+| 14 | MEDIUM | Trilinear sampling of a Float32Array 3D scalar grid re-implemented | `engine/sound/simulation/probe/probe_sdf_grid.js:104-122` `grid_sample_trilinear` (+ `clampInt` at `:181-183`) | `engine/graphics/texture/3d/scs3d_sample_linear.js:15` is the same function: same `z·(rx·ry) + y·rx + x` layout, same edge clamping, same trilinear blend. `SingleChannelSampler3D` is the matching container. `probe_sdf_grid.js:1` already imports `clamp` yet still hand-rolls `clampInt` | UNJUSTIFIED | Back `SdfGrid` with `SingleChannelSampler3D` and call `scs3d_sample_linear`; delete `clampInt` | S / low |
+| 15 | LOW | `{type: ctor.typeName, data: x.toJSON()}` wrapper written 3× with two different `constructor` lookups | `engine/sound/material/concrete/json/serializeSoundMaterialToJSON.js:1-6` (`material.constructor.typeName`); `engine/sound/sopra/serialization/sopraJSON.js:22-27` `serializeAudioClipToJSON` and `:68-73` `serializeAudioEffectToJSON` (`Object.getPrototypeOf(x).constructor.typeName`) | Brief A [70×2], C sim=1. The **switch-based deserializers** (`deserializeSoundMaterialFromJSON.js:12`, `sopraJSON.js:33`, `sopraJSON.js:79`) are **JUSTIFIED** — the alternative in core (`core/json/abstractJSONDeserializer.js`) is precisely the string-keyed `Map<string, fn>` registry the house rules reject, and `sopraJSON.js:11-16` documents deliberate call-time class binding to survive an import cycle. Only the three one-line serializers are gratuitous, and they disagree on how to reach the constructor | UNJUSTIFIED (serializers only) | One `type_tagged_to_json(value)` helper (typed, no registry); pick one constructor lookup | XS / none |
+| 16 | LOW | `dB2Volume` re-derived inline in a file that already imports it | `engine/sound/sopra/runtime/EventInstance.js:33-35` `dbTiltToGain` → `Math.pow(10, -excessDb / 20)`; `dB2Volume` imported at `:2` | Called 4× per acoustic instance per frame (`:542-543`, `:561-562`) — not per-sample, so no inlining justification | UNJUSTIFIED | `excessDb <= 0 ? 1 : dB2Volume(-excessDb)` | XS / none |
+| 17 | LOW | `BusGraph` repeats the same lookup-or-throw preamble 6× | `engine/sound/sopra/runtime/BusGraph.js:143` `getInput`, `:159` `getOutput`, `:173` `getVolume`, `:187` `setVolume`, `:214` `rampVolume`, `:232` `approachVolume` | Six copies of `const bus = this.buses.get(id); if (bus === undefined) { throw new Error(\`sopra: no bus '${id}'\`); }` — ~30 lines | UNJUSTIFIED | A `#bus(id)` private that does the lookup + throw | XS / none |
+| 18 | LOW / PROMOTION | The `setFlag`/`clearFlag`/`writeFlag`/`getFlag` quad, byte-identical in **35 files** | In this domain: `engine/sound/ecs/emitter/SoundEmitter.js:156-189`; `engine/sound/ecs/emitter/SoundTrack.js:138-171`; `engine/sound/asset/SoundAssetPlaybackSpec.js`; `engine/ecs/speaker/Voice.js:13-46` | Brief E (30-file window). `grep -l "clearFlag(flag) {"` returns 35 files spanning core/, engine/ecs, graphics, physics, sound, view | PROMOTION (codebase-wide, not sound-specific — flagged for the cross-domain roll-up, not for a sound-local fix) | A `FlagCarrier` base (or a shared `flags_set/clear/write/read` quartet on the flat `flags` word); JS single inheritance makes the base awkward where a class already extends, so the function quartet is the safer shape | L / medium |
+| 19 | LOW | Well-conditioned perpendicular-axis construction re-derived | `engine/sound/simulation/probe/probe_detect_portals.js:170-184` `throatIsAperture` | Hand-rolls "cross with world-up, swap reference if `|ey| > 0.9`, normalize". `core/geom/vec3/v3_orthonormal_matrix_from_normal.js` builds exactly this stable basis and is already used twice in this same package (`OcclusionSolver.js:48`, `bakeReverbBands.js:74`) | UNJUSTIFIED | `v3_orthonormal_matrix_from_normal` and read the tangent column | XS / low |
+| 20 | LOW | Vector normalize written by hand, inconsistently with the same file | `engine/sound/simulation/AcousticSimulator.js:598-621` `#directivityGainToward` (`Math.sqrt(dx*dx+dy*dy+dz*dz)` at `:605`) vs `:454, :455, :459, :460` in `#applyPath` (`Math.hypot`) | Brief F `inline_length3`. Cold path (once per non-omni source per frame). `v3_length` / `v3_normalize_array` exist; the file already imports `line3_compute_segment_closest_point_t` from the same family | UNJUSTIFIED (cold) | `v3_length`, or at least pick one of `Math.hypot`/`sqrt` within the file | XS / none |
+| 21 | LOW / PROMOTION | Union-find connected components over probe connectivity written twice | `engine/sound/simulation/probe/probe_visibility_bridge_components.js:35-39` (from an `{a,b}` edge list); `engine/sound/simulation/probe/probe_refine_connectivity.js:50-56` (from a `CSRGraph`) | Both then use `uf_find(parent, i) === uf_find(parent, j)` as the same-component predicate. `core/graph/graph_compute_disconnected_clusters.js` exists but only for the object-graph `Graph`, not `CSRGraph` | PROMOTION | `core/graph/csr/csr_graph_connected_components(parent, graph)` beside `csr_graph_build_distance_field`; the edge-list variant folds into finding 2's builder | S / low |
+
+## Strangler-migration debt
+
+Context, not a defect list. Legacy-vs-sopra parallelism was the deliberate migration shape; what mattered is
+where the seam had stalled and where a fix would have to land twice.
+
+> **Resolved on the meep side (2026-08-27).** The legacy behavioural path is deleted: no
+> `SoundEmitterSystem`, `SoundEmitterComponentContext`, `SoundControllerSystem` or `SoundEmitterChannels`.
+> `SoundEmitter`/`SoundTrack`/`SoundController` survive only as frozen readers under `sopra/legacy/`, kept
+> registered so old saves still deserialize, and `convertLegacySoundComponents` turns what they carry into
+> `AudioEmitter` / `AudioEventTrigger`. `AudioEventTrigger` now exists. The "is legacy still wired?" column
+> below describes the state before that; the game repo has not been ported yet. See
+> `engine/sound/SOUND_EMITTER_RETIREMENT_PLAN.md`.
+
+| Legacy | sopra / native counterpart | Is legacy still wired? | Note |
+|---|---|---|---|
+| `ecs/emitter/SoundEmitterSystem` + `SoundEmitterComponentContext` | `ecs/audio/AudioEmitterSystem` + `AudioEmitter` + `LiveEmitterSet` | **YES** — `mir-engine/model/game/makeMirEngineConfig.js:182` | The seam is genuinely healthy here: legacy is a *translator* (`sopra/legacy/soundEmitterToEventDescription.js`) onto sopra, not a second renderer. Conversely `AudioEmitter*` has **zero** consumers outside `engine/sound/` — the new path is unused in the game |
+| `ecs/SoundControllerSystem` | `ecs/trigger/AudioEventTrigger` + `AudioEventTriggerSystem` | deleted in meep; still registered in the game | Was `@deprecated` with no replacement in the tree; the replacement now exists and the system is gone. Findings 11/11b died with it |
+| `material/**` (`AbstractSoundMaterialDefinition`, `Single`/`Random`/`Composition`, `json/`) | sopra clips — `SwitchContainerAudioClip.js:11` *"Supersedes the dormant material/ surface-switch concept"*; `BlendContainerAudioClip.js:13` *"Supersedes the dormant material/ composition concept"* | **NO** — grep finds zero references outside `engine/sound/material/` (only a doc mention in `sopraJSON.js:13`) | Dead but public surface (meep is a library). Origin of the JSON copies in finding 15 |
+| `SoundEmitterChannels` (`effects`/`music`/`ambient`) | sopra `SopraDefaultBus` + `BusDefinition` | deleted in meep; 7 app files still import it | The ids are identical, and the `get/setChannelVolume` proxies it carried were 1-line forwards to `sopra.get/setBusVolume`, so the app ports by swapping the import and reaching the buses directly |
+| `ecs/SoundListenerSystem` (WebAudio `AudioListener` pose) | `sopra.setListener(position)` inside the emitter systems | **YES** — `makeMirEngineConfig.js:184` | THREE readers of the same `SoundListener`→`Transform` relation. sopra's listener is position-only; the WebAudio listener also carries orientation. See finding 3 |
+| `ProbeReverbRenderer` (scalar) | `FoaProbeReverbRenderer` (directional/B-format) | scalar is what `configureAcousticSimulation.js:31` documents; FOA is referenced only by `prototypeAcousticSolver.js:515` + its spec | Neither is deprecated; both live. Findings 6/8 mean an IR or crossfade fix must land in both |
+| `ecs/emitter/SoundPanningModelType` | `sopra/definition/SopraPanningModel` | **YES** — translated by `soundEmitterToEventDescription.js:57-61` | Identical 2-value enums; translation is one ternary. Fine |
+| `SoundAttenuationFunction` + `core/math/physics/irradiance/interpolate_irradiance_*` | authored `AnimationCurve` via `sopra/util/buildAttenuationCurve.js` | **YES** | This is the *good* seam: the legacy falloffs are REUSED to sample the new curve rather than reimplemented. Called out as a model, not debt |
+
+## Dismissed leads
+
+- Brief A/C `makePhysicsGroundResolver` / `recomputeMove` / `bindMoveKey` / `buildInputBindings` / `logHelp` (`engine/control/first-person/prototype_first_person_controller.js` ⟷ `engine/sound/simulation/prototypeAcousticSolver.js`) — both sites are `prototype*.js` harnesses, out of scope. **One line as instructed:** a real shared debug fly/walk camera *with* a physics ground resolver would be worth promoting to `engine/control/`, since it is now copied verbatim for every new subsystem demo.
+- `DuckingRuleSerializationAdapter` / `CompressorEffectSerializationAdapter` / `ParameterDefinitionSerializationAdapter` `serialize`+`deserialize` (brief A [50×3] and [45×3]) — read all three: different field names and types (`writeUTF8String`+3×float32+float32 / 5×float32 / string+3×float32+uint8), zero shared logic. Exactly the per-class shape boilerplate the house rules bless.
+- `SequenceContainerAudioClipSerializationAdapter.deserialize` ⟷ `SwitchContainerAudioClipSerializationAdapter.deserialize` (brief C sim=0.781) — same verdict; Switch additionally reads `parameter`/`defaultValue`.
+- The container adapters' repeated `gain`/`pitch` writes and children loop (brief E) — wire order is per-class protocol; hoisting it into a base couples four independent binary formats. Deliberate.
+- `MixerSnapshotSerializationAdapter` bus-entry codec vs `BusDefinitionSerializationAdapter` sends codec — structurally identical (`string` + `float32` pairs), semantically distinct record types. Shape only.
+- `engine/ecs/speaker/Voice.js` vs `engine/sound/sopra/runtime/Voice.js` (brief G) — pure name collision. The first is a speech-bubble ECS component (flags only, `Voice.serializable = false`); the second is a WebAudio `AudioBufferSourceNode` holder. No shared logic beyond the flag quad (finding 18). The `speaker/` package has no importers, but meep is a library — not a defect.
+- `echogram_band_rt60.js:49` `10 * Math.log10(edc / total)` — **energy** dB, deliberately not `volume2dB`'s amplitude `20·log10`. Correct as written.
+- Brief F `inline_lerp` in `probe_sdf_grid.js:118-121` — the innermost trilinear blend; folds into finding 14 anyway. `AcousticSimulator.js:453, :458` and `probe_detect_portals.js:94, :109` are 3-component point-on-segment evaluations, not scalar `lerp` calls.
+- Brief F `inline_length3`, the remaining ~14 hits — hot per-ray / per-edge / per-candidate-pair loops (`OcclusionSolver.js:79` per ray, `bakeVisibility.js:106` per graph edge, `probe_visibility_augment.js:92,108,111` per 2-ring chord). Inlining is the right call there; only the cold `AcousticSimulator` site (finding 20) is worth changing.
+- Brief F `epsilon_compare` `ProbeReverbRenderer.js:198-200` — a tunable re-bake hysteresis (`changeThreshold = 0.1 s`), not float-tolerance equality. `epsilonEquals` would be semantically wrong.
+- Brief F `binary_search_inline` `probe_visibility_augment.js:171` — folded into finding 2.
+- `EventInstance.js:47-92` `build3BandCrossover` / `set3BandGains` / `disconnect3Band` — already correctly factored and shared by BOTH the direct and corner-leak paths (`:457`, `:476`). No duplication; a model for finding 8.
+- `ProbeFieldPathingSolution.js:62` correctly delegates to `csr_graph_build_distance_field`, and `AcousticProbeField.shortestPath:519` to `csr_graph_find_shortest_path`. **No Dijkstra / graph-search duplication in `simulation/`** — the probe pathing is a clean `core/graph` consumer.
+- No hand-rolled biquad coefficient math, equal-power panning law, or crossfade curve anywhere in the domain — WebAudio nodes (`createBiquadFilter`, `PannerNode`, `linearRampToValueAtTime`) do all of it. The one filter-adjacent formula, the one-pole coefficient `1 − e^(−2πf/fs)`, is finding 6.
+- The 3-band value classes (`AcousticMedium`, `AcousticMaterial`, `AcousticSolution`, `AcousticSourceState`) unroll their 3-element copies by hand in `equals`/`clone`/`hash`/`toJSON` — typed, explicit, per-field. Consistent with "typed over magic"; not duplication of *logic*.
+
+## Notes — why duplication accumulates here
+
+1. **Three generations coexist in one package.** `material/` (dead, superseded), `ecs/emitter/` (legacy, wired,
+   now a translator), and `sopra/` + `ecs/audio/` (new, unwired outside the engine). Each generation
+   re-solved the same problems — polymorphic type-tagged JSON, weighted random selection, composition
+   with per-child weights — because the previous one was not being deleted. The three JSON dispatchers
+   (finding 15) and the material-vs-clip parallel hierarchy are the visible residue.
+
+2. **The migration seam stalled at the game boundary, not inside the engine.** Inside `engine/sound/`
+   the strangler is genuinely done — sopra is the single renderer and legacy is a translator. But
+   `makeMirEngineConfig.js` still registers the three legacy systems and nothing registers
+   `AudioEmitterSystem`, so the new path's code has no production caller keeping it honest. That is
+   what let finding 3 (two systems each owning the sopra tick) and finding 12 (two copies of the
+   play-options mapping) survive: only one of each pair actually runs.
+
+3. **`core/graph/csr/` ships consumers but no producer.** It has Dijkstra, distance fields, and edge
+   lookup, but no `from_edge_list` builder — so the probe bake writes its own twice (finding 2), and the
+   companions it also needs (connected components, canonical edge key) got written locally 2–4× each
+   (findings 10, 21). One missing primitive generated four findings.
+
+4. **Ray-scratch locality beats reuse.** Every module that casts a shadow ray declares its own
+   module-static `Ray3` and inlines the normalize-and-set sequence (finding 1). The pattern is
+   allocation-free by construction, which makes the copy feel cheap, but it means the "one shared
+   visibility test" the code documents does not actually exist.
+
+5. **Per-sample DSP genuinely justifies inlining — but the justification got over-applied.** The IR
+   synthesis kernels (findings 6, 7) share far more than the inner loop: window sizing, filter
+   coefficients, and envelope shape are all per-*bake* work that could be shared without a per-sample
+   call. The `EventInstance` crossover helpers show the team already knows how to draw that line
+   correctly; the reverb bakers just predate it.
+
+6. **The base class stops one level short.** `AbstractAudioClip` folds `gain`/`pitch` into `hash()`, and
+   `ContainerAudioClip` folds `children` into `equals()` — but not into `hash()`. Four subclasses filled
+   the gap by copy-paste, and one of them (Blend) has already drifted (finding 4). The same shape
+   appears in the container adapters, where the base clip fields are re-written per subclass.

package/src/avif/encoder_worker.js

@@ -8,21 +8,11 @@ import avifEncoderFactory from './codec/enc/avif_enc.js';
 import { initEmscriptenModule } from './utils.js';
 import { defaultOptions } from './meta.js';
 import { to_half_float_uint16 } from '../core/binary/to_half_float_uint16.js';
+import { linear_to_PQ } from '../core/color/PQ/linear_to_PQ.js';
+import { PQ_SDR_WHITE_LINEAR } from '../core/color/PQ/PQ_constants.js';
 
 const AVIF_DEFAULT_SPEED = 5;
 
-// PQ OETF (SMPTE ST 2084). Input: linear light normalized so 1.0 = 10000 nits. Output: PQ signal in [0,1].
-const PQ_M1 = 0.1593017578125;
-const PQ_M2 = 78.84375;
-const PQ_C1 = 0.8359375;
-const PQ_C2 = 18.8515625;
-const PQ_C3 = 18.6875;
-
-function linear_to_pq(x) {
-    const xp = Math.pow(Math.max(x, 0), PQ_M1);
-    return Math.pow((PQ_C1 + PQ_C2 * xp) / (1.0 + PQ_C3 * xp), PQ_M2);
-}
-
 const AvifSubsample = {
     YUV400: 0,
     YUV420: 1,
@@ -30,10 +20,6 @@ const AvifSubsample = {
     YUV444: 3,
 };
 
-// PQ tone mapping: 1.0 linear = SDR reference white = ~203 nits per BT.2408
-const SDR_WHITE_NITS = 203;
-const PQ_MAX_NITS = 10000;
-
 let encoder_promise = null;
 
 function get_encoder() {
@@ -103,8 +89,9 @@ function rgba_float16_to_pq_uint16(f16_view, width, height) {
     for (let i = 0; i < f16_view.length; i += 4) {
         for (let c = 0; c < 3; c++) {
             const linear = Math.max(f16_view[i + c], 0);
-            const normalized = linear * SDR_WHITE_NITS / PQ_MAX_NITS;
-            const pq = linear_to_pq(normalized);
+            // Engine linear is normalized to SDR reference white; PQ's is normalized to its own
+            // 10000-nit peak, so cross over before encoding.
+            const pq = linear_to_PQ(linear * PQ_SDR_WHITE_LINEAR);
             out[i + c] = Math.round(pq * 4095);
         }
         // alpha: linear 0..1 mapped directly to 0..4095

package/src/core/bvh2/bvh3/ebvh_build_hierarchy_radix.d.ts

@@ -1,3 +1,57 @@
+/**
+ * Karras 2012 — "Maximizing Parallelism in the Construction of BVHs, Octrees, and k-d Trees".
+ *
+ * For a sorted array of N Morton codes, build a binary radix tree of N-1 internal
+ * nodes and N leaves. Each internal node corresponds to the longest common prefix
+ * of a contiguous range of Morton codes; its split point is where the first bit
+ * after that prefix flips from 0 to 1.
+ *
+ * The caller must pre-allocate:
+ *   - `leaf_count` leaf nodes in `bvh`, each with its AABB and user-data set;
+ *     their IDs are passed in `leaf_nodes`, sorted by `sorted_morton_codes`.
+ *   - `leaf_count - 1` internal nodes (when `leaf_count >= 2`); their IDs are
+ *     passed in `internal_nodes`, in arbitrary order.
+ *
+ * The returned root index is wired into the tree; internal-node bounds and
+ * heights are filled in by a bottom-up refit after structural construction.
+ *
+ * @see "Thinking Parallel, Part III: Tree Construction on the GPU", 2012 by Tero Karras
+ */
+/**
+ * Compute the position of the first bit where the codes at `first` and `last`
+ * differ in their longest-common-prefix sense — i.e. the split point for the
+ * range [first, last]. Returns an index `s` such that all codes in [first, s]
+ * share more leading bits with the firstCode than codes in [s+1, last] do.
+ *
+ * @param {number[]|Uint32Array} sortedMortonCodes
+ * @param {number} first
+ * @param {number} last
+ * @return {number}
+ */
+/**
+ * Karras longest-common-prefix length between the codes at indices `i` and `j`, with the standard
+ * index tiebreaker: identical Morton codes are disambiguated by their (distinct) indices, so a node's
+ * range never collapses to a degenerate single element. Returns -1 for `j` outside [0, n-1] (the
+ * canonical Karras "out of range" sentinel).
+ *
+ * @param {number[]|Uint32Array} codes
+ * @param {number} n number of codes
+ * @param {number} i
+ * @param {number} j
+ * @return {number}
+ */
+export function delta(codes: number[] | Uint32Array, n: number, i: number, j: number): number;
+export function find_split(sortedMortonCodes: any, n: any, first: any, last: any): any;
+/**
+ * Determine the [first, last] code range covered by internal node `idx`.
+ *
+ * @see https://github.com/mbartling/cuda-bvh/blob/7f2f98d9d29956c3559632e59104ba66f31f80b8/kernels/bvh.cu#L276
+ * @param {number[]|Uint32Array} output 2-element output [first, last]
+ * @param {number[]|Uint32Array} sortedMortonCodes
+ * @param {number} leaf_count
+ * @param {number} idx
+ */
+export function determineRange(output: number[] | Uint32Array, sortedMortonCodes: number[] | Uint32Array, leaf_count: number, idx: number): void;
 /**
  * Build a binary radix tree over the given leaves and Morton codes.
  *

package/src/core/bvh2/bvh3/ebvh_build_hierarchy_radix.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ebvh_build_hierarchy_radix.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh2/bvh3/ebvh_build_hierarchy_radix.js"],"names":[],"mappings":"AAkMA;;;;;;;;;;;;;;;;GAgBG;AACH,iEAbW,MAAM,EAAE,GAAC,WAAW,uBAGpB,MAAM,EAAE,GAAC,WAAW,cAEpB,MAAM,kBAGN,MAAM,EAAE,GAAC,WAAW,GAGlB,MAAM,CAiElB"}
+{"version":3,"file":"ebvh_build_hierarchy_radix.d.ts","sourceRoot":"","sources":["../../../../../src/core/bvh2/bvh3/ebvh_build_hierarchy_radix.js"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;GAkBG;AASH;;;;;;;;;;GAUG;AACH;;;;;;;;;;;GAWG;AACH,6BANW,MAAM,EAAE,GAAC,WAAW,KACpB,MAAM,KACN,MAAM,KACN,MAAM,GACL,MAAM,CAgBjB;AAED,uFA2BC;AAED;;;;;;;;GAQG;AACH,uCALW,MAAM,EAAE,GAAC,WAAW,qBACpB,MAAM,EAAE,GAAC,WAAW,cACpB,MAAM,OACN,MAAM,QAmDhB;AA6CD;;;;;;;;;;;;;;;;GAgBG;AACH,iEAbW,MAAM,EAAE,GAAC,WAAW,uBAGpB,MAAM,EAAE,GAAC,WAAW,cAEpB,MAAM,kBAGN,MAAM,EAAE,GAAC,WAAW,GAGlB,MAAM,CAiElB"}

package/src/core/bvh2/bvh3/ebvh_build_hierarchy_radix.js

@@ -21,6 +21,13 @@ import { NULL_NODE } from "./BVH.js";
  * @see "Thinking Parallel, Part III: Tree Construction on the GPU", 2012 by Tero Karras
  */
 
+/*
+ * `delta`, `determineRange` and `find_split` are exported for one reason: the GPU builder's
+ * emission kernel is a transliteration of them, and its WGSL is executed against these exact
+ * functions on the WGSL emulator rather than against a second copy of the rules that could drift
+ * from this one. They are not part of the builder's interface — `ebvh_build_hierarchy_radix` is.
+ */
+
 /**
  * Compute the position of the first bit where the codes at `first` and `last`
  * differ in their longest-common-prefix sense — i.e. the split point for the
@@ -44,7 +51,7 @@ import { NULL_NODE } from "./BVH.js";
  * @param {number} j
  * @return {number}
  */
-function delta(codes, n, i, j) {
+export function delta(codes, n, i, j) {
     if (j < 0 || j >= n) {
         return -1;
     }
@@ -60,7 +67,7 @@ function delta(codes, n, i, j) {
     return Math.clz32(ci ^ cj);
 }
 
-function find_split(sortedMortonCodes, n, first, last) {
+export function find_split(sortedMortonCodes, n, first, last) {
     // NOTE: do not special-case identical Morton codes with a midpoint split. delta() breaks ties by index, so
     // the binary search below finds a split that is consistent with determineRange's index-based ranges. A
     // midpoint shortcut returns a different split, which makes a parent and its child both claim the same leaf
@@ -98,7 +105,7 @@ function find_split(sortedMortonCodes, n, first, last) {
  * @param {number} leaf_count
  * @param {number} idx
  */
-function determineRange(output, sortedMortonCodes, leaf_count, idx) {
+export function determineRange(output, sortedMortonCodes, leaf_count, idx) {
     // For the root (idx === 0) the range is unambiguously [0, leaf_count - 1].
     // We short-circuit so callers don't have to special-case it.
     if (idx === 0) {

package/src/core/color/PQ/PQ_constants.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Coefficients of the SMPTE ST 2084 (a.k.a. "PQ", Perceptual Quantizer) transfer function.
+ *
+ * Every value is exact in binary floating point -- each is a small integer over a power of two, as the
+ * standard specifies them -- so the OETF and the EOTF built from these are exact inverses to within the
+ * rounding of `Math.pow` alone.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+/** @type {number} 2610 / 16384 */
+export const PQ_M1: number;
+/** @type {number} 2523 / 32 */
+export const PQ_M2: number;
+/** @type {number} 3424 / 4096 */
+export const PQ_C1: number;
+/** @type {number} 2413 / 128 */
+export const PQ_C2: number;
+/** @type {number} 2392 / 128 */
+export const PQ_C3: number;
+/**
+ * Peak luminance of the PQ signal range, in nits. A linear value of `1.0` in PQ's own normalization is
+ * this bright -- which is why {@link linear_to_PQ} and {@link PQ_to_linear} work in that normalization
+ * and not in any renderer's.
+ * @type {number}
+ */
+export const PQ_MAX_NITS: number;
+/**
+ * Luminance of SDR reference white, in nits, per ITU-R BT.2408. This is the engine's `1.0`, and it is
+ * NOT PQ's `1.0`: converting between the two scales is the caller's job and needs
+ * {@link PQ_SDR_WHITE_LINEAR} in one direction or its reciprocal in the other.
+ * @type {number}
+ */
+export const SDR_WHITE_NITS: number;
+/**
+ * SDR reference white expressed in PQ's linear normalization, i.e. `SDR_WHITE_NITS / PQ_MAX_NITS`.
+ *
+ * Multiply an engine-normalized linear value by this before {@link linear_to_PQ}; divide by it after
+ * {@link PQ_to_linear} to come back.
+ * @type {number}
+ */
+export const PQ_SDR_WHITE_LINEAR: number;
+//# sourceMappingURL=PQ_constants.d.ts.map

package/src/core/color/PQ/PQ_constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PQ_constants.d.ts","sourceRoot":"","sources":["../../../../../src/core/color/PQ/PQ_constants.js"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,kCAAkC;AAClC,oBADW,MAAM,CACoB;AAErC,+BAA+B;AAC/B,oBADW,MAAM,CACa;AAE9B,iCAAiC;AACjC,oBADW,MAAM,CACc;AAE/B,gCAAgC;AAChC,oBADW,MAAM,CACe;AAEhC,gCAAgC;AAChC,oBADW,MAAM,CACY;AAE7B;;;;;GAKG;AACH,0BAFU,MAAM,CAEiB;AAEjC;;;;;GAKG;AACH,6BAFU,MAAM,CAEkB;AAElC;;;;;;GAMG;AACH,kCAFU,MAAM,CAEgD"}

package/src/core/color/PQ/PQ_constants.js

@@ -0,0 +1,50 @@
+/**
+ * Coefficients of the SMPTE ST 2084 (a.k.a. "PQ", Perceptual Quantizer) transfer function.
+ *
+ * Every value is exact in binary floating point -- each is a small integer over a power of two, as the
+ * standard specifies them -- so the OETF and the EOTF built from these are exact inverses to within the
+ * rounding of `Math.pow` alone.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+
+/** @type {number} 2610 / 16384 */
+export const PQ_M1 = 0.1593017578125;
+
+/** @type {number} 2523 / 32 */
+export const PQ_M2 = 78.84375;
+
+/** @type {number} 3424 / 4096 */
+export const PQ_C1 = 0.8359375;
+
+/** @type {number} 2413 / 128 */
+export const PQ_C2 = 18.8515625;
+
+/** @type {number} 2392 / 128 */
+export const PQ_C3 = 18.6875;
+
+/**
+ * Peak luminance of the PQ signal range, in nits. A linear value of `1.0` in PQ's own normalization is
+ * this bright -- which is why {@link linear_to_PQ} and {@link PQ_to_linear} work in that normalization
+ * and not in any renderer's.
+ * @type {number}
+ */
+export const PQ_MAX_NITS = 10000;
+
+/**
+ * Luminance of SDR reference white, in nits, per ITU-R BT.2408. This is the engine's `1.0`, and it is
+ * NOT PQ's `1.0`: converting between the two scales is the caller's job and needs
+ * {@link PQ_SDR_WHITE_LINEAR} in one direction or its reciprocal in the other.
+ * @type {number}
+ */
+export const SDR_WHITE_NITS = 203;
+
+/**
+ * SDR reference white expressed in PQ's linear normalization, i.e. `SDR_WHITE_NITS / PQ_MAX_NITS`.
+ *
+ * Multiply an engine-normalized linear value by this before {@link linear_to_PQ}; divide by it after
+ * {@link PQ_to_linear} to come back.
+ * @type {number}
+ */
+export const PQ_SDR_WHITE_LINEAR = SDR_WHITE_NITS / PQ_MAX_NITS;

package/src/core/color/PQ/PQ_to_linear.d.ts

@@ -0,0 +1,24 @@
+/**
+ * SMPTE ST 2084 EOTF: decode a PQ signal back to linear light. Exact inverse of {@link linear_to_PQ}.
+ *
+ * NORMALIZATION: the result is in PQ's own scale, where `1.0` is {@link PQ_MAX_NITS} (10000 nits) --
+ * not the engine's, where `1.0` is {@link SDR_WHITE_NITS} (203 nits). Divide by
+ * {@link PQ_SDR_WHITE_LINEAR} to land back in engine units:
+ *
+ * ```js
+ * const engine_linear = PQ_to_linear(pq) / PQ_SDR_WHITE_LINEAR;
+ * ```
+ *
+ * The numerator is clamped at `0` so that signals below `linear_to_PQ(0)` -- which the standard's
+ * curve never produces, but quantization and interpolation both do -- decode to black instead of
+ * `NaN` from a negative base under a fractional exponent.
+ *
+ * @param {number} pq PQ signal, in `[0, 1]`
+ * @returns {number} linear light, `1.0` = 10000 nits
+ * @see linear_to_PQ
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export function PQ_to_linear(pq: number): number;
+//# sourceMappingURL=PQ_to_linear.d.ts.map