@woosh/meep-engine 3.1.0 → 3.3.0

package/src/DUPLICATION_AUDIT_2026_08_07/E_physics.md

@@ -1,69 +1,69 @@
-# Domain E — engine/physics
-
-Scope: `engine/physics/**` (+ `engine/ecs/ik/*` where the task named it). Every finding below was verified by opening the cited files. `*.spec.js`, `prototype*.js`, `test*.js` excluded.
-
-The mechanical brief was thin and its three "A. token-identical" hits turned out to be the *least* interesting things in the domain (two are explicitly, correctly justified). The real duplication here is semantic re-derivation, and it clusters in four places: (1) the fluid solver's collocated-vs-MAC twin kernel families, (2) the narrowphase contact-emission epilogues, (3) the two solvers (contacts / constraints) which independently implement the same impulse application, (4) core primitives that return *parameters* where every single caller wants *points*.
-
-## Findings
-
-| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
-|---|---|---|---|---|---|---|---|
-| 1 | HIGH | **Solver impulse application written twice, verbatim.** `Δv = P·invM; Δω = Iw⁻¹·(r×P)` with the identical `invM===0` guard, identical sign folding, identical `world_inverse_inertia_apply_raw` argument order and identical AV write-back. | `engine/physics/constraint/solve_constraints.js:250` `apply_impulse(ss, base, invM, rx,ry,rz, Px,Py,Pz, sign)` ⟷ `engine/physics/solver/solve_contacts.js:401` `apply_impulse_to_body(ss, base, invM, rx,ry,rz, Px,Py,Pz, sign, scratch_inertia)` | Bodies are line-for-line identical (15 statements each). The *only* difference is that the contacts version takes `scratch_inertia` as an 11th parameter where the constraints version closes over a module-static one. Both call the same kernel with the same operand order. | UNJUSTIFIED | Promote one copy to `engine/physics/solver/apply_impulse_to_body.js` (next to `friction_cone.js`) with the explicit `scratch` parameter; both solvers import it. Keep the parameter form — it is already the more explicit of the two. | Low effort. **Determinism: LOW risk** — identical operand order means bit-identical output; `determinism.spec.js` is the gate. This is the single most load-bearing routine in the step (per-row × per-iteration), so re-measure the rain/KEVA benches: a cross-module call here must stay inlined. |
-| 2 | HIGH | **SAT minimum-overlap magnitude computed three ways, one of which diverges.** Same invariant ("how far along this axis must I push to separate?"), three independent expressions. | `engine/physics/narrowphase/box_box_manifold.js:135` `overlap = (rA + rB) - dist`; `engine/physics/narrowphase/box_triangle_contact.js:209-211` `overlap = min(bmax - tmin, tmax - bmin)`; `engine/physics/narrowphase/convex_convex_manifold.js:261` `overlap = Math.min(maxA,maxB) - Math.max(minA,minB)` | The first two are the minimum-translation (push-out) distance and agree. The third is the *interval intersection length*, which is smaller whenever one projection interval contains the other (A=[0,10], B=[4,5] → push-out 5, intersection 1). SAT then picks the axis by minimum overlap, so an understated value makes a containment axis *more* likely to win and be reported as the depth. `convex_convex_manifold` is documented as being for "the SMALL convex pieces of a decomposed mesh" — exactly where a thin piece is contained in a fat one. The three sites also carry three different degeneracy tests (`PARALLEL_EPS_SQR` absolute in two files, `PARALLEL_EPS_REL * ref2` relative in the third) and only two of three have the `TIE_REL/TIE_ABS` deadband. | UNJUSTIFIED (and needs a correctness decision before unification) | Extract `sat_track_min_overlap(state, ux,uy,uz, minA,maxA, minB,maxB, kind, sign_ref)` covering: normalise-and-reject, separation test, push-out overlap, deadband tie-break, centre-delta sign orientation. Each caller keeps its own *projection* (box half-extent vs 3 vertices vs vertex loop) — that part is legitimately shape-specific. | Medium effort. **Determinism: HIGH risk** and behaviour-changing: fixing `convex_convex`'s formula changes chosen axes on containment configs. Do it test-first against `convex_convex_manifold`'s own suite, then the determinism gate. |
-| 3 | HIGH | **Whole collocated advection family shadows the MAC family and has zero callers.** `FluidSimulator` uses only the `v3_mac_*` kernels (imports at `engine/physics/fluid/FluidSimulator.js:6-11`). | Zero non-spec importers: `v3_grid_advect_sl_velocity.js`, `v3_grid_apply_advection_forward.js`, `v3_grid_apply_scalar_advection.js`, `v3_grid_advect_maccormack_scalar.js`, `v3_grid_advect_maccormack_velocity.js` (≈555 LOC) | Verified by importer count across `engine/` and `app/` (spec files excluded). Each is a collocated-grid re-implementation of an algorithm the MAC file next to it also implements (SL trace, MacCormack forward/backward/correct, Selle limiter, solid pass-through). A fix in the MAC limiter or the solid handling silently misses five files. | UNJUSTIFIED (as duplication) — but **NOT dead code**: meep is a library, these are public surface. | Do not delete. Collapse the *internal* redundancy first (findings 4 and 5), then leave the collocated family as thin, correct, exported kernels. Add a one-line "the simulator uses the MAC family; this is the collocated variant" note to each so the next reviewer does not re-derive this. | Low effort for 4/5; the family itself stays. Determinism: none (unreferenced by the sim). |
-| 4 | MEDIUM | **MacCormack pass 1 re-implements the SL kernel that sits in the same directory.** The MAC file does this correctly (calls the SL kernel); the grid file does not. | `engine/physics/fluid/solver/v3_grid_advect_maccormack_scalar.js:66-82` (pass 1) ⟷ `v3_grid_apply_scalar_advection.js:38-58`; `v3_grid_advect_maccormack_velocity.js:73-94` (pass 1) ⟷ `v3_grid_advect_sl_velocity.js:69-96` | Both pairs are statement-for-statement identical: same solid pass-through, same `s = x - vel[c]*dt`, same sampler call. Contrast `v3_mac_advect_scalar.js:146`, which *does* call `v3_mac_advect_sl_scalar(fwd, ...)` for its forward pass — proving the delegation is viable and this is an oversight, not a design choice. | UNJUSTIFIED | Replace each pass-1 loop with the call to its SL sibling, exactly as the MAC scalar file already does. | Low effort. **Determinism: LOW** — identical arithmetic and identical loop order; the only change is a function boundary. |
-| 5 | MEDIUM | **`v3_grid_apply_advection_forward` is a slower copy of `v3_grid_advect_sl_velocity`, and says so in its own docstring.** | `engine/physics/fluid/solver/v3_grid_apply_advection_forward.js:32` ⟷ `v3_grid_advect_sl_velocity.js:38` | The docstring at `v3_grid_apply_advection_forward.js:16` states: it "is exactly `v3_grid_advect_sl_velocity(outputs, inputs, inputs...)`". The body differs only by issuing three separate `scs3d_sample_linear` calls instead of one fused `scs3d_sample_linear3` — i.e. it recomputes the trilinear corner indices and weights three times per cell. MinHash flagged the pair at 0.813. | UNJUSTIFIED | Keep the export (public surface, meaningful name); make the body a one-line delegation to `v3_grid_advect_sl_velocity`. | Low effort. **Determinism: MEDIUM** — the fused 3-channel sampler may associate weights differently from three scalar samples. Diff numerically before/after; `quality.spec.js` is the fluid gate. |
-| 6 | MEDIUM | **Selle monotone limiter written four times, twice under the same name `limit8` with different signatures in the same directory.** | `engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.js:155` `limit8(value, data, c0..c7)`; `v3_mac_advect_maccormack_velocity.js:293` `limit8(value, data, lx,ly,lz, dim_x,dim_y,dim_z, row, slice)`; hand-inlined at `v3_grid_advect_maccormack_scalar.js:107-132`; hand-inlined **with solid masking** at `v3_mac_advect_scalar.js:191-232` | The two named `limit8`s are different functions with the same name two files apart — a genuine reader hazard, and invisible to the mechanical pass because neither is exported (brief §G is empty). The grid-scalar inline is a *byte-level* match for the MAC-velocity `limit8` signature (`limit8(corrected, source, x-vx, y-vy, z-vz, res_x,res_y,res_z, res_x, slice_size)` reproduces it exactly). The MAC-scalar inline is a genuine superset (skips solid corners, `Infinity` init, fallback to the forward value). | UNJUSTIFIED for 3 of 4 | Extract two files: `v3_limit8_lattice.js` (position-form, absorbs the MAC-velocity version, the grid-scalar inline and — via a precomputed-index overload or by the caller passing the position — the grid-velocity version) and `v3_limit8_lattice_masked.js` for the solid-aware variant. Do **not** merge masked and unmasked behind a flag (uniform-control-flow rule). | Low-medium effort. **Determinism: LOW** for the unmasked merge (identical comparison order). These are per-cell kernels over the whole grid, so verify the extracted call stays inlined — the bodies are branchy but loop-free, which is the inlinable shape. |
-| 7 | MEDIUM | **Vorticity confinement: the MAC kernel collocates to cell centres and then re-derives the collocated kernel's two passes verbatim.** | `engine/physics/fluid/solver/v3_grid_apply_vorticity_confinement.js:78-130` (pass 1 curl+\|ω\|, pass 2 N×ω) ⟷ `v3_mac_apply_vorticity_confinement.js:98-164` (pass 2, pass 3) | The MAC file's pass 1 (lines 70-90) averages faces into `scratch_cu/cv/cw` cell-centred arrays; its passes 2 and 3 are then character-identical to the grid file's passes 1 and 2 — same central-difference curl expressions, same `scratch_wmag` fill, same `magnitude_floor = 1e-10`, same `s = epsilon_dt / g_len`, same `N × ω` cross. Only the final deposit differs (cell write vs `0.5 *` scatter to two faces per axis). ≈60 lines. | UNJUSTIFIED | Extract `v3_grid_compute_vorticity(scratch_wx,wy,wz,wmag, vel_x,vel_y,vel_z, res, solid)` and `v3_grid_compute_confinement_force(out3, scratch_*, c, res_x, cell_slice, epsilon_dt)`; the MAC kernel calls both and keeps only its collocate-in / scatter-out ends. | Medium effort. **Determinism: LOW** (same expressions, same order). Per-cell whole-grid kernel — measure; the force helper writing 3 floats to a module-static may cost vs the current fully-inlined form. |
-| 8 | MEDIUM | **Two-bone and one-bone IK solvers share a ~75-line terrain-probe + influence prologue verbatim.** | `engine/ecs/ik/TwoBoneInverseKinematicsSolver.js:76-151` (`solve`) ⟷ `engine/ecs/ik/OneBoneSurfaceAlignmentSolver.js:74-151` (`solve`) | Identical: the ray direction from parent→bone, the primary `terrain.raycastFirstSync`, the early return, the secondary cast back along the contact normal from the bone + normal, the second early return, `constraint.offset * <scale>` → `v3_displace_in_direction`, the `delta_contact_c_*` triple, `v3_dot` side test, `v3_length`, the `dot_contact_side < 0 ? 1 : 1 - clamp01(constraint.distance.normalizeValue(inverseLerp(0, <scale>, d)))` influence, and the `influence <= 0` bail. Only two things differ and both are plain inputs: the ray origin (parent bone world position vs root bone A world position) and the length scale (`boneWorldScale.length() * 1/√3` vs limb length A→B→C). The mechanical brief missed this entirely because its path filter was `^engine/physics/`. | UNJUSTIFIED | Extract `ik_probe_surface_influence(contact_out, terrain, origin_xyz, direction_xyz, effector_xyz, length_scale, constraint) -> number` returning influence (0 = no contact / no influence) and leaving the contact in the supplied `SurfacePoint3`. Both solvers keep only their own post-influence rotation math, which is genuinely different. | Low-medium effort. No determinism exposure (animation-side, not the physics step). Note: the task hypothesis "two competing two-bone IK solvers" is **false** — `TwoBoneInverseKinematicsSolver` *imports* `two_joint_ik` (line 11). The real duplication is this sibling prologue. |
-| 9 | MEDIUM | **Closest-point-pair → contact epilogue written five times.** Given two witness points and two radii, produce (unit normal B→A, depth, witness on A, witness on B) with a degenerate-distance tie-break. | `engine/physics/narrowphase/sphere_sphere_contact.js:27-51`; `sphere_triangle_contact.js:99-141`; `capsule_contacts.js:89-116` (`capsule_sphere_contact`); `capsule_contacts.js:158-197` (`capsule_capsule_contact`); `capsule_contacts.js:293-324` (`capsule_capsule_multi_contacts` inner loop) | All five: `d = pa - pb`, `dist_sqr`, `sum = ra + rb`, `if (dist_sqr >= sum*sum) return false`, `dist = sqrt`, `if (dist > 0) normalize else <tie-break>`, `out[3] = sum - dist`, `out[4..6] = pa - n*ra`, `out[7..9] = pb + n*rb`. The tie-break direction is the only real variation: `(1,0,0)` at two sites, segment-centre delta at one, body-centre delta at two — i.e. it is an *input*, not a mode. | UNJUSTIFIED | `narrowphase/emit_pair_contact.js`: `emit_pair_contact(out, pax,pay,paz, pbx,pby,pbz, ra, rb, fbx,fby,fbz) -> boolean`, fallback direction always supplied by the caller (no null-sentinel). `sphere_sphere_contact` writes only lanes 0-3 today and would need to keep that shorter contract or gain witness lanes — check its callers first. | Low-medium effort. Per-contact hot path but not per-cell; a leaf function of this size is a normal V8 inline candidate. **Determinism: LOW** (identical order), but the tie-break unification changes `capsule_sphere_contact`'s `(1,0,0)` if you "improve" it — don't; pass `(1,0,0)` explicitly. |
-| 10 | MEDIUM | **Cap-endpoint contact append + spatial dedup written twice, with the same magic constant.** | `engine/physics/narrowphase/capsule_contacts.js:582-619` (endpoint loop inside `capsule_box_multi_contacts`) ⟷ `capsule_triangle_contact.js:360-395` (`try_endpoint_contact`) | Both: run a sphere-vs-X query at a cap centre, unpack the 10-float `(n, depth, A, B)` scratch, loop `k < count` comparing the capsule-side world position against every already-emitted contact, reject below `DEDUPE_DIST_SQR`, then write the `(A, B, n, depth)` stride-10 record. `DEDUPE_DIST_SQR = 1e-6` is declared independently in both files (`capsule_contacts.js:510`, `capsule_triangle_contact.js:64`) with near-identical justifying comments, and both files independently declare a stride-10 constant (`CAPSULE_BOX_CONTACT_STRIDE`, `CAPSULE_TRIANGLE_CONTACT_STRIDE`). | UNJUSTIFIED | `narrowphase/append_deduped_contact.js`: `append_deduped_contact(out, count, scratch10) -> number`, with `DEDUPE_DIST_SQR` and the stride-10 candidate layout defined once (the layout is already shared by three files — put it next to `decomposition/triangle_buffer_layout.js`). | Low effort. **Determinism: LOW.** Real payoff is the single definition of the tolerance: today a tuning change to one leaves the other. |
-| 11 | MEDIUM | **Reference-face manifold emission epilogue written three times.** Project each clipped point, reject non-penetrating, push `(x,y,z,depth)` candidates, `reduce_manifold_contacts`, then per kept point project onto the reference plane and swap A/B by `ref_is_A`. | `engine/physics/narrowphase/convex_convex_manifold.js:596-622` (`emit_face_manifold`); `box_box_manifold.js:578-670`; `box_triangle_contact.js:455-497` (`emit_box_face_manifold`) | All three build a stride-4 (or 7) candidate array, call `reduce_manifold_contacts(cand, n, stride, MAX_CONTACTS, depth_lane)`, then run the identical "ref-side witness = point − ref_out · dist_to_plane" projection and the identical `if (ref_is_A) {A=proj,B=pt} else {A=pt,B=proj}` swap into `4 + k*CONTACT_STRIDE`. A previous review already lifted the *reduction* out of these three (see the "Each previously carried its own byte-identical copy" note at `reduce_manifold_contacts.js:14-18`) — this is the un-lifted residue of the same block. | UNJUSTIFIED | Finish the extraction the previous review started: `emit_reference_face_manifold(out, cand, n, stride, ref_is_A, r0x,r0y,r0z, rmx,rmy,rmz)` doing reduce + project + swap + write. The *clipping* stays per-shape. | Medium effort. **Determinism: LOW** if the projection expression is copied verbatim. The three sites use different candidate strides (4 and 7), so the stride stays a parameter — `reduce_manifold_contacts` already set that precedent. |
-| 12 | MEDIUM | **A general 2D half-plane Sutherland–Hodgman clipper exists in core, unused, while narrowphase ships its own.** | `core/geom/2d/polygon/polygon2_clip_halfplane.js:20` (exported, spec'd, **zero consumers**) ⟷ `engine/physics/narrowphase/box_triangle_contact.js:110` `clip_against_half_plane_uv` | Same algorithm: walk edges, evaluate a signed side function at both endpoints, emit the start point if inside, emit the crossing at `t = sa/(sa-sb)`. The core version parameterises the line by point+direction and tests `cross(dir, P-e)`; the physics version by point+normal and tests `(P-e)·n` — algebraically the same half-plane with `n = perp(dir)`. Note `box_box_manifold.js:3` and `box_triangle_contact.js:3` *already* import the sibling `polygon2_clip_axis_halfplane` from core, so the boundary crossing is established practice. | UNJUSTIFIED | `box_triangle_contact` imports `polygon2_clip_halfplane` and converts its normal to a direction (or add a normal-form export next to it). | Low effort. **Determinism: MEDIUM** — the core version carries `POINT_EPS = 1e-9` inside/outside slack; the physics version uses exact `<= 0`. That changes the surviving vertex count on boundary-coincident points, hence the manifold. Diff on the box-triangle suite before adopting. |
-| 13 | MEDIUM | **Effector face-lattice splat scaffolding written six times (3 axes × 2 effectors).** | `engine/physics/fluid/effector/ImpulseFluidEffector.js:105-132, 134-161, 163-191` ⟷ `WakeFluidEffector.js:249-273, 275-298, 300-~330` | Each block: derive the per-lattice index range as `max(0, floor(box_min [+0.5 on own axis]))` … `min(res_axis [−1 off-axis], ceil(box_max [+0.5]))`, triple loop, compute the lattice offset (`sx*res_y` / `res_x*(res_y+1)` / `res_x*res_y`), evaluate a falloff weight at the face position (offset −0.5 on the own axis), `continue` on zero weight, `continue` on `pin[f] !== 0`, accumulate `v[f] += impulse_axis * w`. The only per-block variation is the weight function — and `WakeFluidEffector` already proves this can be a callback (`tube_weight` closure at line 230). | UNJUSTIFIED | `fluid/effector/mac_splat_axis.js`: `mac_splat_axis(velocity, pin, axis, res_x,res_y,res_z, box6, deposit, weight_fn)`. The two effectors then differ only in their weight function and box, which is the actual content. | Medium effort. **Determinism: LOW.** Perf: this is a *bounded* splat (influence radius), not a whole-grid kernel, and the Wake path already pays a closure call per face — so the reuse-over-micro-opt rule applies cleanly here. |
-| 14 | PROMOTION | **`tri3_closest_point_barycentric` returns barycentrics; all 12 callers immediately reconstruct the world point.** The missing primitive is `tri3_closest_point`. | Physics: `sphere_triangle_contact.js:89-96`; `capsule_triangle_contact.js:186-191`, `:210-215`, `:234-239`; `compute_penetration.js:331-335`. Core/graphics (context): `core/geom/3d/shape/Triangle3D.js:169-175` and `:212-…`; `core/geom/3d/topology/struct/binary/query/bt_mesh_find_nearest_face.js:131-137`; `core/geom/3d/shape/MeshShape3D.js:439`, `:491`; `core/geom/3d/shape/ConvexHullShape3D.js:254`, `:285`; `engine/graphics/geometry/buffered/query/bvh32_geometry_nearest.js:203`; `.../query_bvh_geometry_nearest.js:164` | Every site writes the same four lines: `const c = 1 - a - b; qx = a*ax + b*bx + c*cx; qy = …; qz = …`. Several then compute the same `d = p - q; d_sqr` follow-up. This is the block the brief flagged as shared between `Triangle3D.js:162`, `capsule_triangle_contact.js:181`, `bt_mesh_find_nearest_face.js` and the two BVH nearest queries. | PROMOTION | Add `core/geom/3d/triangle/tri3_closest_point.js` — `tri3_closest_point(out, out_offset, px,py,pz, ax..cz)` writing the world point (wrapping the barycentric version) — and `tri3_point_distance_sqr(...)` for the distance-only callers. Keep the barycentric export (public surface; a few callers genuinely want the weights). | Low effort per site, 12 sites. **Determinism: LOW** if the reconstruction expression is copied verbatim (`a*ax + b*bx + c*cx` in that order — `bt_mesh_find_nearest_face.js:135` writes `ax*wa + bx*wb + cx*wc`, which is the same order of operands; check each before converting). |
-| 15 | PROMOTION | **`line3_compute_segment_segment_closest_points` returns `(s, t)`; all four physics callers immediately lerp both segments.** | `engine/physics/narrowphase/capsule_contacts.js:142-156`; `capsule_triangle_contact.js:105-117` (`test_edge`); `convex_convex_manifold.js:501-516` (`emit_edge_pair_contact`); `box_triangle_contact.js:874-885` (`emit_edge_cross_contact`) | All four: call the core function into a length-2 scratch, then six `p = a0 + (a1 - a0) * s` lines. This is the bulk of the brief's 39 `inline_lerp` hits in narrowphase. `core/geom/3d/line/` already contains a differently-named `line3_closest_points_segment_segment.js` — worth checking whether *it* is the point-returning variant that was never adopted. | PROMOTION | Add `line3_segment_segment_closest_point_pair(out6, a0x..a1z, b0x..b1z)` writing both world points (and returning the squared distance, which three of the four sites compute next anyway). | Low effort. **Determinism: LOW** — the lerp form `a + (b-a)*t` is used identically at all four sites; preserve it exactly (do not "improve" to `(1-t)*a + t*b`). |
-| 16 | LOW/MEDIUM | **Two hash-combine conventions coexist inside `engine/physics`, producing different values for the same inputs.** | Hand-rolled `h = (h*31 + x) | 0`, seeded with the first field: `engine/physics/ecs/Collider.js:157`, `RigidBody.js:279`, `Joint.js:442`. Canonical `combine_hash(...)`: `engine/physics/fluid/effector/GlobalFluidEffector.js:182`, `ImpulseFluidEffector.js:228`. A third variant `h = ((h<<5) - h) + v; h \|= 0` seeded with `n`: `engine/physics/fluid/ecs/FluidEffectorsComponent.js:77` | `core/collection/array/combine_hash.js` → `computeIntegerArrayHash` → `computeStridedIntegerArrayHash` is the canonical fold: `hash = length`, then `hash = ((hash<<5) - hash) + (v >>> 0)`, returning **uint32**. `(h<<5)-h` and `h*31` are the same multiply; the divergences are the seed (`length` vs first field) and the output signedness (`>>> 0` vs `\| 0`). Three conventions in one package. | UNJUSTIFIED as a *convention* split; the hand-rolled fold itself is JUSTIFIED (`combine_hash(...args)` allocates a rest-array per call — `RigidBody.hash()` folds 12 fields and runs during dirty-checking) | Do **not** route the ECS components through `combine_hash`. Instead add a non-allocating `hash_combine_step(h, v)`-style primitive next to `computeStridedIntegerArrayHash` and have all three physics families use it, so the seed and signedness are decided once. Then `FluidEffectorsComponent` and the two effectors stop being a third and fourth answer. | Low effort. No determinism exposure (hashes are change-detection, not simulation state) — but do check nothing persists these values across versions before changing seed/signedness. |
-| 17 | LOW/MEDIUM | **`solve_constraints` re-derives `angular_effective_mass_raw`, which was extracted for exactly this purpose.** | `engine/physics/constraint/solve_constraints.js:191-204` `axis_effective_mass` ⟷ `engine/physics/inertia/world_inverse_inertia.js:102` `angular_effective_mass_raw` | The core of `axis_effective_mass` is `cx,cy,cz = r × d; world_inverse_inertia_apply_raw(scratch, …, cx,cy,cz); k += cx*s[0] + cy*s[1] + cz*s[2]` — character-for-character the body of `angular_effective_mass_raw`. That kernel's own docstring (lines 80-84) says it is "The shared kernel behind the contact/joint solver's SoA path and the raycast-vehicle's component path — each previously inlined the cross product + apply_raw + dot themselves." `solve_contacts.js:526` and `RaycastVehicle.js:54` adopted it; `solve_constraints.js` was missed. | UNJUSTIFIED (incomplete prior extraction) | `axis_effective_mass` becomes `invM === 0 ? 0 : invM + angular_effective_mass_raw(iix,iiy,iiz, qx,qy,qz,qw, rx,ry,rz, dx,dy,dz, scratch_inertia)`, keeping the existing zero-inertia short-circuit. | Low effort. **Determinism: LOW** — identical operand order by construction. Note `angular_axis_effective_mass` at `solve_constraints.js:146` is genuinely different (`a·Iw⁻¹·a`, no lever arm) and should be left alone. |
-| 18 | LOW/MEDIUM | **EPA→MPR fallback + MTV sign-validation + normalise written three times.** | `engine/physics/narrowphase/narrowphase_step.js:1128-1138` and `:1245-1255` (concave-triangle path and general convex fallback, same file) ⟷ `engine/physics/queries/shape_cast.js:394-408` (MPR-only variant) | The two `narrowphase_step` copies are identical: `gjk_epa_penetration` → `pen_depth > 0 && Number.isFinite(pen_depth)` → scale unit axis by depth, else `mpr()` → `depth = Math.sqrt(ex*ex+ey*ey+ez*ez)` → `!(depth > 0) \|\| !Number.isFinite(depth)` bail. All three then dot the MTV against a centre-delta reference, flip on negative, and emit `-e * (1/depth)` as the B→A normal (`shape_cast.js:401-407` even says "same pattern as `narrowphase_step`'s EPA path"). | UNJUSTIFIED for the two same-file copies | `narrowphase/resolve_penetration_mtv.js`: `resolve_penetration_mtv(out4, posed_a, posed_b, ref_x, ref_y, ref_z) -> boolean` writing unit normal + depth. `shape_cast` keeps its MPR-only path (it deliberately skips EPA — documented at `shape_cast.js:361-366` — so folding it in would need a mode flag; leave it). | Low effort for the two `narrowphase_step` copies. **Determinism: LOW.** Do not unify the third site — that would need the sentinel-parameter shape the house rules forbid. |
-| 19 | LOW | **The `(p + 0.5) \| 0` + clamp + solid-lookup convention is written six times.** | `engine/physics/fluid/solver/v3_mac_clip_trace.js:83` `point_in_solid`; `v3_mac_advect_scalar.js:23` `end_in_solid`; `v3_mac_advect_maccormack_velocity.js:23` `end_in_solid`; inline ×3 at `v3_mac_advect_sl_velocity.js:112-118`, `:155-161`, `:200-206` | The two `end_in_solid` copies are byte-identical (brief §A, 120 tokens ×3 with `point_in_solid`). | **JUSTIFIED — with one exception.** `v3_mac_clip_trace.js:25-29` carries an explicit, measured performance contract: the loop in `v3_mac_clip_trace` blocks V8 inlining and "a per-face call costs several times the entire surrounding advection body (measured 8.6× on the SL kernel)", so hot kernels must inline the fluid test. The three inline copies in `v3_mac_advect_sl_velocity` are unambiguously correct. **But** the two `end_in_solid` *functions* are already function calls — the perf argument that justifies inlining does not justify a private copy of a loop-free leaf. | Export `point_in_solid` from `v3_mac_clip_trace.js` and have the two advect kernels import it instead of redeclaring it; leave the three genuine inline expansions alone. | Low effort, **but measure first** — that is the whole point of the contract comment. If the imported leaf does not inline as well as the module-local one, revert and instead cross-reference the copies in a comment. Determinism: none (integer indexing). |
-| 20 | LOW | **Unnormalised triangle face normal (`(B−A) × (C−A)`) inline-derived at five physics sites.** | `engine/physics/narrowphase/sphere_triangle_contact.js:73-78`; `capsule_triangle_contact.js:162-166` and `:320-325`; `refine_ray_concave.js:142-146`; `compute_penetration.js:263-271` | Same three cross-product lines each time, three of the five followed by the same `mag = sqrt(...)`, degeneracy bail, `1/mag` normalise. Context: `core/geom/3d/triangle/` already offers **three** names for this — `compute_triangle_normal.js`, `tri3_compute_normal.js`, `v3_compute_triangle_normal.js` — which is likely why nobody reaches for one. | UNJUSTIFIED, but low value | Pick the canonical core name (a domain-A decision) and use it. Worth doing only as part of that consolidation, not on its own. | Low effort. **Determinism: LOW** if operand order matches. Per-triangle in a concave dispatch loop — inlining is defensible here; this is a readability finding, not a perf one. |
-| 21 | LOW | **"Perpendicular axis pair from an axis index" written three times.** | `engine/physics/narrowphase/box_box_manifold.js:417-432`; `box_triangle_contact.js:835-842`; and again in `box_triangle_contact.js`'s `emit_box_face_manifold` (half-extent selection at `:441-442` region) | Identical `if (idx===0){u=1;v=2}else if(idx===1){u=2;v=0}else{u=0;v=1}` plus the identical `half_u = u===0 ? hx : (u===1 ? hy : hz)` ternary chain. | UNJUSTIFIED, low value | Two module-static `Uint8Array` lookup tables (`PERP_U = [1,2,0]`, `PERP_V = [2,0,1]`) in a shared `narrowphase/box_axis_tables.js`, plus a 3-float half-extent read. Typed constants, no string keys. | Trivial effort, **determinism: none** (integer selection only). |
-| 22 | LOW | **World→grid direction transform and uniform-scale extraction re-derived across the fluid effectors.** | Direction transform `m[0]*x + m[4]*y + m[8]*z` (etc.): `GlobalFluidEffector.js:99-101` and `:117-119`, `ImpulseFluidEffector.js:75-77`. Uniform scale `sqrt(m[0]²+m[1]²+m[2]²)`: `ImpulseFluidEffector.js:88`, `WakeFluidEffector.js:172` | `core/geom/vec3/` has `v3_matrix4_multiply` (point, with perspective divide) and `v3_matrix4_rotate_unit` (direction, **but it normalises the output**) — neither fits, because the effectors need the *unnormalised* linear part so world units/s² become grid units/s². So the re-derivation is caused by a genuine gap in the core surface. `v3_matrix4_rotate.js` is just a deprecated re-export of `v3_matrix4_rotate_unit`. | PROMOTION | Add `core/geom/vec3/v3_matrix4_transform_direction.js` (linear part, no normalise, no divide) and `m4_uniform_scale.js`. Three and two sites respectively. | Trivial effort. **Determinism: LOW.** Cold code (once per effector per frame), so this is a pure clarity/gap-closing win. |
-
-## Dismissed leads
-
-- **"Two competing two-bone IK solvers"** (`engine/ecs/ik/TwoBoneInverseKinematicsSolver.js` vs `engine/physics/inverse_kinematics/two_joint_ik.js`) — not duplicates. The former *imports and calls* the latter at `TwoBoneInverseKinematicsSolver.js:11,157`; it is the ECS/terrain wrapper, `two_joint_ik` is the pure analytic core. Correctly factored. The real finding in that pair of files is #8.
-- **FABRIK vs `two_joint_ik`** — `engine/physics/inverse_kinematics/fabrik/fabrik3d_solve_primitive.js` is an iterative N-joint positional solver; `two_joint_ik` is an analytic 2-joint rotational solver on a different data model (Vector3/Quaternion objects vs flat Float32Array). No shared body. FABRIK has no internal callers, but meep is a library.
-- **`GlobalFluidEffector.equals`/`hash` vs `ImpulseFluidEffector.equals`/`hash`** (brief §A, 118 and 71 tokens) — same *shape*, different *fields* (`drag`/`force`/`wind` vs `radius`/`position`/`force`). Unifying needs a field-list registry, i.e. exactly the string-keyed metaprogramming the house rules forbid. Correctly written out per class.
-- **`v3_grid_patch_edges_uniform` vs `v3_grid_patch_edges_constant`** (brief §C, 0.75) — genuinely different operations (replicate the adjacent valid slab vs write a constant), and the constant version exploits `fill` contiguity the replication version cannot. Shared surface is a ~10-line dispatch preamble whose `|shift| >= res` branches *differ* (return vs full fill). Not worth unifying.
-- **`v3_grid_compute_divergence` vs `v3_mac_compute_divergence`** — different discretisations (central differences with one-sided boundary handling on collocated cells vs exact face differences on the staggered lattice). Different algorithms, not a copy. Same for the two `subtract_pressure_gradient` kernels.
-- **`Collider.setFlag/clearFlag/getFlag/writeFlag` vs `RigidBody.*`** (brief §E) — the same four one-line bodies appear in **32** engine classes. A codebase-wide idiom over a `this.flags` int, no shared state, one line each; a base class would impose an inheritance constraint on unrelated component hierarchies. Not a physics finding.
-- **`reduce_manifold_contacts`** — already extracted by a previous review; `reduce_manifold_contacts.js:14-18` documents that box_box, convex_convex, box_triangle and the dispatcher "each previously carried its own byte-identical copy". `box_triangle_contact.js:146 reduce_contacts` is a 1-line binding, not a copy. Do not re-flag.
-- **`mls-mpm` vs `fluid`** — `MLS_MPM.js` is 2D with quadratic B-spline P2G/G2P weights; the fluid stack is 3D trilinear on a MAC lattice. No shared indexing or weight code. It is also plainly a prototype (`Math.random()` at `:388-389`, per-step array allocation in `advance`, a `testMLS_MPM.js` harness beside it). No reuse opportunity.
-- **"Second broadphase / AABB tree inside physics"** — none. `engine/physics/broadphase/generate_pairs.js:1` queries `core/bvh2`, and `compute_fat_world_aabb.js:1` uses `core/geom/3d/aabb/aabb3_transform_oriented`. Clean.
-- **`solve_contacts.js:458 apply_impulse_to_pseudo` vs `:401 apply_impulse_to_body`** — same math, but the destination is a different buffer with a different stride and split lin/ang lanes. Unifying needs `(dst, lin_offset, ang_offset)` threading through the hottest routine in the solver for one caller's benefit. Borderline; folded into finding #1 only if that extraction happens anyway.
-- **`SBS_AV_X/SBS_INV_I_X` block shared by `solve_constraints.js` and `solve_contacts.js`** (brief §E) — that is an import list of shared lane constants from `body/SolverBodyState.js`. Correct reuse, not duplication.
-- **`convex_convex_manifold.js:243` vs `box_box_manifold.js:117` vs `box_triangle_contact.js:182` — the *projection* halves of `test_axis`** — legitimately shape-specific (symmetric half-extent projection vs three explicit vertex dots vs a vertex-buffer min/max loop). Only the tracking half is duplicated; that is finding #2.
-- **The `g_bb_*` / `g_bt_*` / `g_ct_*` module-static accumulator idiom** appearing in three narrowphase files — each carries a comment explaining it replaced a per-call closure allocation ("D3"). Same *technique*, different state. Correct as-is.
-
-## Notes
-
-**Why duplication accumulates here, structurally:**
-
-1. **Twin kernel families.** The fluid solver carries a full collocated (`v3_grid_*`) and a full staggered-MAC (`v3_mac_*`) implementation of advection. The MAC family superseded the collocated one (memory: "MAC staggered, exact projection; MacCormack velocity default") but the collocated family stayed as library surface — so every algorithm in it (SL trace, MacCormack, Selle limiter, solid pass-through) now exists twice, and the two copies have already begun to drift (findings 4, 5, 6, 7). This is the largest single source of duplication in the domain by line count.
-
-2. **Core primitives that return parameters, not points.** `tri3_closest_point_barycentric` returns `(α, β)` and `line3_compute_segment_segment_closest_points` returns `(s, t)`. Sixteen call sites across physics, core and graphics then write the same reconstruction arithmetic. This is the highest-leverage class of finding (#14, #15) because the fix is additive — two new core functions, no behaviour change, and the existing exports stay.
-
-3. **Partial prior extractions.** Three separate extractions were done and each missed one site: `reduce_manifold_contacts` left the surrounding emit epilogue behind (#11), `angular_effective_mass_raw` was adopted by `solve_contacts` and `RaycastVehicle` but not `solve_constraints` (#17), and `polygon2_clip_halfplane` was written in core but never consumed (#12). Grepping for "each previously carried its own copy"-style comments is a reliable way to find the residue.
-
-4. **Axis triplication.** The MAC kernels and the effectors write x/y/z as three near-identical blocks with different strides. In the *kernels* (`v3_mac_advect_sl_velocity.js`, `v3_mac_advect_maccormack_velocity.js`) this is legitimate — see below. In the *effectors* it is not (#13), because those loops are radius-bounded, not grid-bounded.
-
-**Where inlining is legitimately correct (do not "fix" these):**
-
-- `v3_mac_clip_trace.js:25-29` is an explicit measured performance contract (8.6× on the SL kernel) and the three inline solid tests in `v3_mac_advect_sl_velocity.js` honour it. These run per *face* over the whole lattice — millions of evaluations per step. Finding #19 targets only the two redundant *function declarations*, and even that is gated on measurement.
-- The x/y/z block triplication inside `v3_mac_advect_sl_velocity.js` and `v3_mac_advect_maccormack_velocity.js`: each block has different index strides (`sx*res_y`, `res_x*sy`, `cell_slice`) and different loop bounds (`<= res_x` on the own axis). Parameterising would put stride variables in the innermost loop of a whole-grid kernel. Correct as written; I did not flag it.
-- `capsule_contacts.js` / `capsule_triangle_contact.js` / the manifold builders are **per-contact**, not per-cell — a few thousand calls per frame, not millions. Extracting 20-line leaf helpers there (#9, #10, #11) is squarely on the reuse side of the line, and the codebase already does exactly this (`reduce_manifold_contacts`, `angular_effective_mass_raw`).
-- `solve_contacts` / `solve_constraints` inner rows are per-contact-row × per-iteration — the hottest code in the engine. Finding #1 is still worth doing because it is a *verbatim* duplicate of the most correctness-critical routine present, but it must be benchmarked (rain and KEVA-mini) and must preserve operand order exactly for `determinism.spec.js`.
-
-**Determinism summary:** findings 2, 5 and 12 can change simulation output and need before/after numerical diffs. Findings 1, 4, 6, 7, 9, 10, 11, 14, 15, 17, 18 are order-preserving by construction *provided* the extracted body is copied verbatim rather than rewritten — that is the whole risk. Findings 16, 20, 21, 22 have no simulation-state exposure.
+# Domain E — engine/physics
+
+Scope: `engine/physics/**` (+ `engine/ecs/ik/*` where the task named it). Every finding below was verified by opening the cited files. `*.spec.js`, `prototype*.js`, `test*.js` excluded.
+
+The mechanical brief was thin and its three "A. token-identical" hits turned out to be the *least* interesting things in the domain (two are explicitly, correctly justified). The real duplication here is semantic re-derivation, and it clusters in four places: (1) the fluid solver's collocated-vs-MAC twin kernel families, (2) the narrowphase contact-emission epilogues, (3) the two solvers (contacts / constraints) which independently implement the same impulse application, (4) core primitives that return *parameters* where every single caller wants *points*.
+
+## Findings
+
+| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
+|---|---|---|---|---|---|---|---|
+| 1 | HIGH | **Solver impulse application written twice, verbatim.** `Δv = P·invM; Δω = Iw⁻¹·(r×P)` with the identical `invM===0` guard, identical sign folding, identical `world_inverse_inertia_apply_raw` argument order and identical AV write-back. | `engine/physics/constraint/solve_constraints.js:250` `apply_impulse(ss, base, invM, rx,ry,rz, Px,Py,Pz, sign)` ⟷ `engine/physics/solver/solve_contacts.js:401` `apply_impulse_to_body(ss, base, invM, rx,ry,rz, Px,Py,Pz, sign, scratch_inertia)` | Bodies are line-for-line identical (15 statements each). The *only* difference is that the contacts version takes `scratch_inertia` as an 11th parameter where the constraints version closes over a module-static one. Both call the same kernel with the same operand order. | UNJUSTIFIED | Promote one copy to `engine/physics/solver/apply_impulse_to_body.js` (next to `friction_cone.js`) with the explicit `scratch` parameter; both solvers import it. Keep the parameter form — it is already the more explicit of the two. | Low effort. **Determinism: LOW risk** — identical operand order means bit-identical output; `determinism.spec.js` is the gate. This is the single most load-bearing routine in the step (per-row × per-iteration), so re-measure the rain/KEVA benches: a cross-module call here must stay inlined. |
+| 2 | HIGH | **SAT minimum-overlap magnitude computed three ways, one of which diverges.** Same invariant ("how far along this axis must I push to separate?"), three independent expressions. | `engine/physics/narrowphase/box_box_manifold.js:135` `overlap = (rA + rB) - dist`; `engine/physics/narrowphase/box_triangle_contact.js:209-211` `overlap = min(bmax - tmin, tmax - bmin)`; `engine/physics/narrowphase/convex_convex_manifold.js:261` `overlap = Math.min(maxA,maxB) - Math.max(minA,minB)` | The first two are the minimum-translation (push-out) distance and agree. The third is the *interval intersection length*, which is smaller whenever one projection interval contains the other (A=[0,10], B=[4,5] → push-out 5, intersection 1). SAT then picks the axis by minimum overlap, so an understated value makes a containment axis *more* likely to win and be reported as the depth. `convex_convex_manifold` is documented as being for "the SMALL convex pieces of a decomposed mesh" — exactly where a thin piece is contained in a fat one. The three sites also carry three different degeneracy tests (`PARALLEL_EPS_SQR` absolute in two files, `PARALLEL_EPS_REL * ref2` relative in the third) and only two of three have the `TIE_REL/TIE_ABS` deadband. | UNJUSTIFIED (and needs a correctness decision before unification) | Extract `sat_track_min_overlap(state, ux,uy,uz, minA,maxA, minB,maxB, kind, sign_ref)` covering: normalise-and-reject, separation test, push-out overlap, deadband tie-break, centre-delta sign orientation. Each caller keeps its own *projection* (box half-extent vs 3 vertices vs vertex loop) — that part is legitimately shape-specific. | Medium effort. **Determinism: HIGH risk** and behaviour-changing: fixing `convex_convex`'s formula changes chosen axes on containment configs. Do it test-first against `convex_convex_manifold`'s own suite, then the determinism gate. |
+| 3 | HIGH | **Whole collocated advection family shadows the MAC family and has zero callers.** `FluidSimulator` uses only the `v3_mac_*` kernels (imports at `engine/physics/fluid/FluidSimulator.js:6-11`). | Zero non-spec importers: `v3_grid_advect_sl_velocity.js`, `v3_grid_apply_advection_forward.js`, `v3_grid_apply_scalar_advection.js`, `v3_grid_advect_maccormack_scalar.js`, `v3_grid_advect_maccormack_velocity.js` (≈555 LOC) | Verified by importer count across `engine/` and `app/` (spec files excluded). Each is a collocated-grid re-implementation of an algorithm the MAC file next to it also implements (SL trace, MacCormack forward/backward/correct, Selle limiter, solid pass-through). A fix in the MAC limiter or the solid handling silently misses five files. | UNJUSTIFIED (as duplication) — but **NOT dead code**: meep is a library, these are public surface. | Do not delete. Collapse the *internal* redundancy first (findings 4 and 5), then leave the collocated family as thin, correct, exported kernels. Add a one-line "the simulator uses the MAC family; this is the collocated variant" note to each so the next reviewer does not re-derive this. | Low effort for 4/5; the family itself stays. Determinism: none (unreferenced by the sim). |
+| 4 | MEDIUM | **MacCormack pass 1 re-implements the SL kernel that sits in the same directory.** The MAC file does this correctly (calls the SL kernel); the grid file does not. | `engine/physics/fluid/solver/v3_grid_advect_maccormack_scalar.js:66-82` (pass 1) ⟷ `v3_grid_apply_scalar_advection.js:38-58`; `v3_grid_advect_maccormack_velocity.js:73-94` (pass 1) ⟷ `v3_grid_advect_sl_velocity.js:69-96` | Both pairs are statement-for-statement identical: same solid pass-through, same `s = x - vel[c]*dt`, same sampler call. Contrast `v3_mac_advect_scalar.js:146`, which *does* call `v3_mac_advect_sl_scalar(fwd, ...)` for its forward pass — proving the delegation is viable and this is an oversight, not a design choice. | UNJUSTIFIED | Replace each pass-1 loop with the call to its SL sibling, exactly as the MAC scalar file already does. | Low effort. **Determinism: LOW** — identical arithmetic and identical loop order; the only change is a function boundary. |
+| 5 | MEDIUM | **`v3_grid_apply_advection_forward` is a slower copy of `v3_grid_advect_sl_velocity`, and says so in its own docstring.** | `engine/physics/fluid/solver/v3_grid_apply_advection_forward.js:32` ⟷ `v3_grid_advect_sl_velocity.js:38` | The docstring at `v3_grid_apply_advection_forward.js:16` states: it "is exactly `v3_grid_advect_sl_velocity(outputs, inputs, inputs...)`". The body differs only by issuing three separate `scs3d_sample_linear` calls instead of one fused `scs3d_sample_linear3` — i.e. it recomputes the trilinear corner indices and weights three times per cell. MinHash flagged the pair at 0.813. | UNJUSTIFIED | Keep the export (public surface, meaningful name); make the body a one-line delegation to `v3_grid_advect_sl_velocity`. | Low effort. **Determinism: MEDIUM** — the fused 3-channel sampler may associate weights differently from three scalar samples. Diff numerically before/after; `quality.spec.js` is the fluid gate. |
+| 6 | MEDIUM | **Selle monotone limiter written four times, twice under the same name `limit8` with different signatures in the same directory.** | `engine/physics/fluid/solver/v3_grid_advect_maccormack_velocity.js:155` `limit8(value, data, c0..c7)`; `v3_mac_advect_maccormack_velocity.js:293` `limit8(value, data, lx,ly,lz, dim_x,dim_y,dim_z, row, slice)`; hand-inlined at `v3_grid_advect_maccormack_scalar.js:107-132`; hand-inlined **with solid masking** at `v3_mac_advect_scalar.js:191-232` | The two named `limit8`s are different functions with the same name two files apart — a genuine reader hazard, and invisible to the mechanical pass because neither is exported (brief §G is empty). The grid-scalar inline is a *byte-level* match for the MAC-velocity `limit8` signature (`limit8(corrected, source, x-vx, y-vy, z-vz, res_x,res_y,res_z, res_x, slice_size)` reproduces it exactly). The MAC-scalar inline is a genuine superset (skips solid corners, `Infinity` init, fallback to the forward value). | UNJUSTIFIED for 3 of 4 | Extract two files: `v3_limit8_lattice.js` (position-form, absorbs the MAC-velocity version, the grid-scalar inline and — via a precomputed-index overload or by the caller passing the position — the grid-velocity version) and `v3_limit8_lattice_masked.js` for the solid-aware variant. Do **not** merge masked and unmasked behind a flag (uniform-control-flow rule). | Low-medium effort. **Determinism: LOW** for the unmasked merge (identical comparison order). These are per-cell kernels over the whole grid, so verify the extracted call stays inlined — the bodies are branchy but loop-free, which is the inlinable shape. |
+| 7 | MEDIUM | **Vorticity confinement: the MAC kernel collocates to cell centres and then re-derives the collocated kernel's two passes verbatim.** | `engine/physics/fluid/solver/v3_grid_apply_vorticity_confinement.js:78-130` (pass 1 curl+\|ω\|, pass 2 N×ω) ⟷ `v3_mac_apply_vorticity_confinement.js:98-164` (pass 2, pass 3) | The MAC file's pass 1 (lines 70-90) averages faces into `scratch_cu/cv/cw` cell-centred arrays; its passes 2 and 3 are then character-identical to the grid file's passes 1 and 2 — same central-difference curl expressions, same `scratch_wmag` fill, same `magnitude_floor = 1e-10`, same `s = epsilon_dt / g_len`, same `N × ω` cross. Only the final deposit differs (cell write vs `0.5 *` scatter to two faces per axis). ≈60 lines. | UNJUSTIFIED | Extract `v3_grid_compute_vorticity(scratch_wx,wy,wz,wmag, vel_x,vel_y,vel_z, res, solid)` and `v3_grid_compute_confinement_force(out3, scratch_*, c, res_x, cell_slice, epsilon_dt)`; the MAC kernel calls both and keeps only its collocate-in / scatter-out ends. | Medium effort. **Determinism: LOW** (same expressions, same order). Per-cell whole-grid kernel — measure; the force helper writing 3 floats to a module-static may cost vs the current fully-inlined form. |
+| 8 | MEDIUM | **Two-bone and one-bone IK solvers share a ~75-line terrain-probe + influence prologue verbatim.** | `engine/ecs/ik/TwoBoneInverseKinematicsSolver.js:76-151` (`solve`) ⟷ `engine/ecs/ik/OneBoneSurfaceAlignmentSolver.js:74-151` (`solve`) | Identical: the ray direction from parent→bone, the primary `terrain.raycastFirstSync`, the early return, the secondary cast back along the contact normal from the bone + normal, the second early return, `constraint.offset * <scale>` → `v3_displace_in_direction`, the `delta_contact_c_*` triple, `v3_dot` side test, `v3_length`, the `dot_contact_side < 0 ? 1 : 1 - clamp01(constraint.distance.normalizeValue(inverseLerp(0, <scale>, d)))` influence, and the `influence <= 0` bail. Only two things differ and both are plain inputs: the ray origin (parent bone world position vs root bone A world position) and the length scale (`boneWorldScale.length() * 1/√3` vs limb length A→B→C). The mechanical brief missed this entirely because its path filter was `^engine/physics/`. | UNJUSTIFIED | Extract `ik_probe_surface_influence(contact_out, terrain, origin_xyz, direction_xyz, effector_xyz, length_scale, constraint) -> number` returning influence (0 = no contact / no influence) and leaving the contact in the supplied `SurfacePoint3`. Both solvers keep only their own post-influence rotation math, which is genuinely different. | Low-medium effort. No determinism exposure (animation-side, not the physics step). Note: the task hypothesis "two competing two-bone IK solvers" is **false** — `TwoBoneInverseKinematicsSolver` *imports* `two_joint_ik` (line 11). The real duplication is this sibling prologue. |
+| 9 | MEDIUM | **Closest-point-pair → contact epilogue written five times.** Given two witness points and two radii, produce (unit normal B→A, depth, witness on A, witness on B) with a degenerate-distance tie-break. | `engine/physics/narrowphase/sphere_sphere_contact.js:27-51`; `sphere_triangle_contact.js:99-141`; `capsule_contacts.js:89-116` (`capsule_sphere_contact`); `capsule_contacts.js:158-197` (`capsule_capsule_contact`); `capsule_contacts.js:293-324` (`capsule_capsule_multi_contacts` inner loop) | All five: `d = pa - pb`, `dist_sqr`, `sum = ra + rb`, `if (dist_sqr >= sum*sum) return false`, `dist = sqrt`, `if (dist > 0) normalize else <tie-break>`, `out[3] = sum - dist`, `out[4..6] = pa - n*ra`, `out[7..9] = pb + n*rb`. The tie-break direction is the only real variation: `(1,0,0)` at two sites, segment-centre delta at one, body-centre delta at two — i.e. it is an *input*, not a mode. | UNJUSTIFIED | `narrowphase/emit_pair_contact.js`: `emit_pair_contact(out, pax,pay,paz, pbx,pby,pbz, ra, rb, fbx,fby,fbz) -> boolean`, fallback direction always supplied by the caller (no null-sentinel). `sphere_sphere_contact` writes only lanes 0-3 today and would need to keep that shorter contract or gain witness lanes — check its callers first. | Low-medium effort. Per-contact hot path but not per-cell; a leaf function of this size is a normal V8 inline candidate. **Determinism: LOW** (identical order), but the tie-break unification changes `capsule_sphere_contact`'s `(1,0,0)` if you "improve" it — don't; pass `(1,0,0)` explicitly. |
+| 10 | MEDIUM | **Cap-endpoint contact append + spatial dedup written twice, with the same magic constant.** | `engine/physics/narrowphase/capsule_contacts.js:582-619` (endpoint loop inside `capsule_box_multi_contacts`) ⟷ `capsule_triangle_contact.js:360-395` (`try_endpoint_contact`) | Both: run a sphere-vs-X query at a cap centre, unpack the 10-float `(n, depth, A, B)` scratch, loop `k < count` comparing the capsule-side world position against every already-emitted contact, reject below `DEDUPE_DIST_SQR`, then write the `(A, B, n, depth)` stride-10 record. `DEDUPE_DIST_SQR = 1e-6` is declared independently in both files (`capsule_contacts.js:510`, `capsule_triangle_contact.js:64`) with near-identical justifying comments, and both files independently declare a stride-10 constant (`CAPSULE_BOX_CONTACT_STRIDE`, `CAPSULE_TRIANGLE_CONTACT_STRIDE`). | UNJUSTIFIED | `narrowphase/append_deduped_contact.js`: `append_deduped_contact(out, count, scratch10) -> number`, with `DEDUPE_DIST_SQR` and the stride-10 candidate layout defined once (the layout is already shared by three files — put it next to `decomposition/triangle_buffer_layout.js`). | Low effort. **Determinism: LOW.** Real payoff is the single definition of the tolerance: today a tuning change to one leaves the other. |
+| 11 | MEDIUM | **Reference-face manifold emission epilogue written three times.** Project each clipped point, reject non-penetrating, push `(x,y,z,depth)` candidates, `reduce_manifold_contacts`, then per kept point project onto the reference plane and swap A/B by `ref_is_A`. | `engine/physics/narrowphase/convex_convex_manifold.js:596-622` (`emit_face_manifold`); `box_box_manifold.js:578-670`; `box_triangle_contact.js:455-497` (`emit_box_face_manifold`) | All three build a stride-4 (or 7) candidate array, call `reduce_manifold_contacts(cand, n, stride, MAX_CONTACTS, depth_lane)`, then run the identical "ref-side witness = point − ref_out · dist_to_plane" projection and the identical `if (ref_is_A) {A=proj,B=pt} else {A=pt,B=proj}` swap into `4 + k*CONTACT_STRIDE`. A previous review already lifted the *reduction* out of these three (see the "Each previously carried its own byte-identical copy" note at `reduce_manifold_contacts.js:14-18`) — this is the un-lifted residue of the same block. | UNJUSTIFIED | Finish the extraction the previous review started: `emit_reference_face_manifold(out, cand, n, stride, ref_is_A, r0x,r0y,r0z, rmx,rmy,rmz)` doing reduce + project + swap + write. The *clipping* stays per-shape. | Medium effort. **Determinism: LOW** if the projection expression is copied verbatim. The three sites use different candidate strides (4 and 7), so the stride stays a parameter — `reduce_manifold_contacts` already set that precedent. |
+| 12 | MEDIUM | **A general 2D half-plane Sutherland–Hodgman clipper exists in core, unused, while narrowphase ships its own.** | `core/geom/2d/polygon/polygon2_clip_halfplane.js:20` (exported, spec'd, **zero consumers**) ⟷ `engine/physics/narrowphase/box_triangle_contact.js:110` `clip_against_half_plane_uv` | Same algorithm: walk edges, evaluate a signed side function at both endpoints, emit the start point if inside, emit the crossing at `t = sa/(sa-sb)`. The core version parameterises the line by point+direction and tests `cross(dir, P-e)`; the physics version by point+normal and tests `(P-e)·n` — algebraically the same half-plane with `n = perp(dir)`. Note `box_box_manifold.js:3` and `box_triangle_contact.js:3` *already* import the sibling `polygon2_clip_axis_halfplane` from core, so the boundary crossing is established practice. | UNJUSTIFIED | `box_triangle_contact` imports `polygon2_clip_halfplane` and converts its normal to a direction (or add a normal-form export next to it). | Low effort. **Determinism: MEDIUM** — the core version carries `POINT_EPS = 1e-9` inside/outside slack; the physics version uses exact `<= 0`. That changes the surviving vertex count on boundary-coincident points, hence the manifold. Diff on the box-triangle suite before adopting. |
+| 13 | MEDIUM | **Effector face-lattice splat scaffolding written six times (3 axes × 2 effectors).** | `engine/physics/fluid/effector/ImpulseFluidEffector.js:105-132, 134-161, 163-191` ⟷ `WakeFluidEffector.js:249-273, 275-298, 300-~330` | Each block: derive the per-lattice index range as `max(0, floor(box_min [+0.5 on own axis]))` … `min(res_axis [−1 off-axis], ceil(box_max [+0.5]))`, triple loop, compute the lattice offset (`sx*res_y` / `res_x*(res_y+1)` / `res_x*res_y`), evaluate a falloff weight at the face position (offset −0.5 on the own axis), `continue` on zero weight, `continue` on `pin[f] !== 0`, accumulate `v[f] += impulse_axis * w`. The only per-block variation is the weight function — and `WakeFluidEffector` already proves this can be a callback (`tube_weight` closure at line 230). | UNJUSTIFIED | `fluid/effector/mac_splat_axis.js`: `mac_splat_axis(velocity, pin, axis, res_x,res_y,res_z, box6, deposit, weight_fn)`. The two effectors then differ only in their weight function and box, which is the actual content. | Medium effort. **Determinism: LOW.** Perf: this is a *bounded* splat (influence radius), not a whole-grid kernel, and the Wake path already pays a closure call per face — so the reuse-over-micro-opt rule applies cleanly here. |
+| 14 | PROMOTION | **`tri3_closest_point_barycentric` returns barycentrics; all 12 callers immediately reconstruct the world point.** The missing primitive is `tri3_closest_point`. | Physics: `sphere_triangle_contact.js:89-96`; `capsule_triangle_contact.js:186-191`, `:210-215`, `:234-239`; `compute_penetration.js:331-335`. Core/graphics (context): `core/geom/3d/shape/Triangle3D.js:169-175` and `:212-…`; `core/geom/3d/topology/struct/binary/query/bt_mesh_find_nearest_face.js:131-137`; `core/geom/3d/shape/MeshShape3D.js:439`, `:491`; `core/geom/3d/shape/ConvexHullShape3D.js:254`, `:285`; `engine/graphics/geometry/buffered/query/bvh32_geometry_nearest.js:203`; `.../query_bvh_geometry_nearest.js:164` | Every site writes the same four lines: `const c = 1 - a - b; qx = a*ax + b*bx + c*cx; qy = …; qz = …`. Several then compute the same `d = p - q; d_sqr` follow-up. This is the block the brief flagged as shared between `Triangle3D.js:162`, `capsule_triangle_contact.js:181`, `bt_mesh_find_nearest_face.js` and the two BVH nearest queries. | PROMOTION | Add `core/geom/3d/triangle/tri3_closest_point.js` — `tri3_closest_point(out, out_offset, px,py,pz, ax..cz)` writing the world point (wrapping the barycentric version) — and `tri3_point_distance_sqr(...)` for the distance-only callers. Keep the barycentric export (public surface; a few callers genuinely want the weights). | Low effort per site, 12 sites. **Determinism: LOW** if the reconstruction expression is copied verbatim (`a*ax + b*bx + c*cx` in that order — `bt_mesh_find_nearest_face.js:135` writes `ax*wa + bx*wb + cx*wc`, which is the same order of operands; check each before converting). |
+| 15 | PROMOTION | **`line3_compute_segment_segment_closest_points` returns `(s, t)`; all four physics callers immediately lerp both segments.** | `engine/physics/narrowphase/capsule_contacts.js:142-156`; `capsule_triangle_contact.js:105-117` (`test_edge`); `convex_convex_manifold.js:501-516` (`emit_edge_pair_contact`); `box_triangle_contact.js:874-885` (`emit_edge_cross_contact`) | All four: call the core function into a length-2 scratch, then six `p = a0 + (a1 - a0) * s` lines. This is the bulk of the brief's 39 `inline_lerp` hits in narrowphase. `core/geom/3d/line/` already contains a differently-named `line3_closest_points_segment_segment.js` — worth checking whether *it* is the point-returning variant that was never adopted. | PROMOTION | Add `line3_segment_segment_closest_point_pair(out6, a0x..a1z, b0x..b1z)` writing both world points (and returning the squared distance, which three of the four sites compute next anyway). | Low effort. **Determinism: LOW** — the lerp form `a + (b-a)*t` is used identically at all four sites; preserve it exactly (do not "improve" to `(1-t)*a + t*b`). |
+| 16 | LOW/MEDIUM | **Two hash-combine conventions coexist inside `engine/physics`, producing different values for the same inputs.** | Hand-rolled `h = (h*31 + x) | 0`, seeded with the first field: `engine/physics/ecs/Collider.js:157`, `RigidBody.js:279`, `Joint.js:442`. Canonical `combine_hash(...)`: `engine/physics/fluid/effector/GlobalFluidEffector.js:182`, `ImpulseFluidEffector.js:228`. A third variant `h = ((h<<5) - h) + v; h \|= 0` seeded with `n`: `engine/physics/fluid/ecs/FluidEffectorsComponent.js:77` | `core/collection/array/combine_hash.js` → `computeIntegerArrayHash` → `computeStridedIntegerArrayHash` is the canonical fold: `hash = length`, then `hash = ((hash<<5) - hash) + (v >>> 0)`, returning **uint32**. `(h<<5)-h` and `h*31` are the same multiply; the divergences are the seed (`length` vs first field) and the output signedness (`>>> 0` vs `\| 0`). Three conventions in one package. | UNJUSTIFIED as a *convention* split; the hand-rolled fold itself is JUSTIFIED (`combine_hash(...args)` allocates a rest-array per call — `RigidBody.hash()` folds 12 fields and runs during dirty-checking) | Do **not** route the ECS components through `combine_hash`. Instead add a non-allocating `hash_combine_step(h, v)`-style primitive next to `computeStridedIntegerArrayHash` and have all three physics families use it, so the seed and signedness are decided once. Then `FluidEffectorsComponent` and the two effectors stop being a third and fourth answer. | Low effort. No determinism exposure (hashes are change-detection, not simulation state) — but do check nothing persists these values across versions before changing seed/signedness. |
+| 17 | LOW/MEDIUM | **`solve_constraints` re-derives `angular_effective_mass_raw`, which was extracted for exactly this purpose.** | `engine/physics/constraint/solve_constraints.js:191-204` `axis_effective_mass` ⟷ `engine/physics/inertia/world_inverse_inertia.js:102` `angular_effective_mass_raw` | The core of `axis_effective_mass` is `cx,cy,cz = r × d; world_inverse_inertia_apply_raw(scratch, …, cx,cy,cz); k += cx*s[0] + cy*s[1] + cz*s[2]` — character-for-character the body of `angular_effective_mass_raw`. That kernel's own docstring (lines 80-84) says it is "The shared kernel behind the contact/joint solver's SoA path and the raycast-vehicle's component path — each previously inlined the cross product + apply_raw + dot themselves." `solve_contacts.js:526` and `RaycastVehicle.js:54` adopted it; `solve_constraints.js` was missed. | UNJUSTIFIED (incomplete prior extraction) | `axis_effective_mass` becomes `invM === 0 ? 0 : invM + angular_effective_mass_raw(iix,iiy,iiz, qx,qy,qz,qw, rx,ry,rz, dx,dy,dz, scratch_inertia)`, keeping the existing zero-inertia short-circuit. | Low effort. **Determinism: LOW** — identical operand order by construction. Note `angular_axis_effective_mass` at `solve_constraints.js:146` is genuinely different (`a·Iw⁻¹·a`, no lever arm) and should be left alone. |
+| 18 | LOW/MEDIUM | **EPA→MPR fallback + MTV sign-validation + normalise written three times.** | `engine/physics/narrowphase/narrowphase_step.js:1128-1138` and `:1245-1255` (concave-triangle path and general convex fallback, same file) ⟷ `engine/physics/queries/shape_cast.js:394-408` (MPR-only variant) | The two `narrowphase_step` copies are identical: `gjk_epa_penetration` → `pen_depth > 0 && Number.isFinite(pen_depth)` → scale unit axis by depth, else `mpr()` → `depth = Math.sqrt(ex*ex+ey*ey+ez*ez)` → `!(depth > 0) \|\| !Number.isFinite(depth)` bail. All three then dot the MTV against a centre-delta reference, flip on negative, and emit `-e * (1/depth)` as the B→A normal (`shape_cast.js:401-407` even says "same pattern as `narrowphase_step`'s EPA path"). | UNJUSTIFIED for the two same-file copies | `narrowphase/resolve_penetration_mtv.js`: `resolve_penetration_mtv(out4, posed_a, posed_b, ref_x, ref_y, ref_z) -> boolean` writing unit normal + depth. `shape_cast` keeps its MPR-only path (it deliberately skips EPA — documented at `shape_cast.js:361-366` — so folding it in would need a mode flag; leave it). | Low effort for the two `narrowphase_step` copies. **Determinism: LOW.** Do not unify the third site — that would need the sentinel-parameter shape the house rules forbid. |
+| 19 | LOW | **The `(p + 0.5) \| 0` + clamp + solid-lookup convention is written six times.** | `engine/physics/fluid/solver/v3_mac_clip_trace.js:83` `point_in_solid`; `v3_mac_advect_scalar.js:23` `end_in_solid`; `v3_mac_advect_maccormack_velocity.js:23` `end_in_solid`; inline ×3 at `v3_mac_advect_sl_velocity.js:112-118`, `:155-161`, `:200-206` | The two `end_in_solid` copies are byte-identical (brief §A, 120 tokens ×3 with `point_in_solid`). | **JUSTIFIED — with one exception.** `v3_mac_clip_trace.js:25-29` carries an explicit, measured performance contract: the loop in `v3_mac_clip_trace` blocks V8 inlining and "a per-face call costs several times the entire surrounding advection body (measured 8.6× on the SL kernel)", so hot kernels must inline the fluid test. The three inline copies in `v3_mac_advect_sl_velocity` are unambiguously correct. **But** the two `end_in_solid` *functions* are already function calls — the perf argument that justifies inlining does not justify a private copy of a loop-free leaf. | Export `point_in_solid` from `v3_mac_clip_trace.js` and have the two advect kernels import it instead of redeclaring it; leave the three genuine inline expansions alone. | Low effort, **but measure first** — that is the whole point of the contract comment. If the imported leaf does not inline as well as the module-local one, revert and instead cross-reference the copies in a comment. Determinism: none (integer indexing). |
+| 20 | LOW | **Unnormalised triangle face normal (`(B−A) × (C−A)`) inline-derived at five physics sites.** | `engine/physics/narrowphase/sphere_triangle_contact.js:73-78`; `capsule_triangle_contact.js:162-166` and `:320-325`; `refine_ray_concave.js:142-146`; `compute_penetration.js:263-271` | Same three cross-product lines each time, three of the five followed by the same `mag = sqrt(...)`, degeneracy bail, `1/mag` normalise. Context: `core/geom/3d/triangle/` already offers **three** names for this — `compute_triangle_normal.js`, `tri3_compute_normal.js`, `v3_compute_triangle_normal.js` — which is likely why nobody reaches for one. | UNJUSTIFIED, but low value | Pick the canonical core name (a domain-A decision) and use it. Worth doing only as part of that consolidation, not on its own. | Low effort. **Determinism: LOW** if operand order matches. Per-triangle in a concave dispatch loop — inlining is defensible here; this is a readability finding, not a perf one. |
+| 21 | LOW | **"Perpendicular axis pair from an axis index" written three times.** | `engine/physics/narrowphase/box_box_manifold.js:417-432`; `box_triangle_contact.js:835-842`; and again in `box_triangle_contact.js`'s `emit_box_face_manifold` (half-extent selection at `:441-442` region) | Identical `if (idx===0){u=1;v=2}else if(idx===1){u=2;v=0}else{u=0;v=1}` plus the identical `half_u = u===0 ? hx : (u===1 ? hy : hz)` ternary chain. | UNJUSTIFIED, low value | Two module-static `Uint8Array` lookup tables (`PERP_U = [1,2,0]`, `PERP_V = [2,0,1]`) in a shared `narrowphase/box_axis_tables.js`, plus a 3-float half-extent read. Typed constants, no string keys. | Trivial effort, **determinism: none** (integer selection only). |
+| 22 | LOW | **World→grid direction transform and uniform-scale extraction re-derived across the fluid effectors.** | Direction transform `m[0]*x + m[4]*y + m[8]*z` (etc.): `GlobalFluidEffector.js:99-101` and `:117-119`, `ImpulseFluidEffector.js:75-77`. Uniform scale `sqrt(m[0]²+m[1]²+m[2]²)`: `ImpulseFluidEffector.js:88`, `WakeFluidEffector.js:172` | `core/geom/vec3/` has `v3_matrix4_multiply` (point, with perspective divide) and `v3_matrix4_rotate_unit` (direction, **but it normalises the output**) — neither fits, because the effectors need the *unnormalised* linear part so world units/s² become grid units/s². So the re-derivation is caused by a genuine gap in the core surface. `v3_matrix4_rotate.js` is just a deprecated re-export of `v3_matrix4_rotate_unit`. | PROMOTION | Add `core/geom/vec3/v3_matrix4_transform_direction.js` (linear part, no normalise, no divide) and `m4_uniform_scale.js`. Three and two sites respectively. | Trivial effort. **Determinism: LOW.** Cold code (once per effector per frame), so this is a pure clarity/gap-closing win. |
+
+## Dismissed leads
+
+- **"Two competing two-bone IK solvers"** (`engine/ecs/ik/TwoBoneInverseKinematicsSolver.js` vs `engine/physics/inverse_kinematics/two_joint_ik.js`) — not duplicates. The former *imports and calls* the latter at `TwoBoneInverseKinematicsSolver.js:11,157`; it is the ECS/terrain wrapper, `two_joint_ik` is the pure analytic core. Correctly factored. The real finding in that pair of files is #8.
+- **FABRIK vs `two_joint_ik`** — `engine/physics/inverse_kinematics/fabrik/fabrik3d_solve_primitive.js` is an iterative N-joint positional solver; `two_joint_ik` is an analytic 2-joint rotational solver on a different data model (Vector3/Quaternion objects vs flat Float32Array). No shared body. FABRIK has no internal callers, but meep is a library.
+- **`GlobalFluidEffector.equals`/`hash` vs `ImpulseFluidEffector.equals`/`hash`** (brief §A, 118 and 71 tokens) — same *shape*, different *fields* (`drag`/`force`/`wind` vs `radius`/`position`/`force`). Unifying needs a field-list registry, i.e. exactly the string-keyed metaprogramming the house rules forbid. Correctly written out per class.
+- **`v3_grid_patch_edges_uniform` vs `v3_grid_patch_edges_constant`** (brief §C, 0.75) — genuinely different operations (replicate the adjacent valid slab vs write a constant), and the constant version exploits `fill` contiguity the replication version cannot. Shared surface is a ~10-line dispatch preamble whose `|shift| >= res` branches *differ* (return vs full fill). Not worth unifying.
+- **`v3_grid_compute_divergence` vs `v3_mac_compute_divergence`** — different discretisations (central differences with one-sided boundary handling on collocated cells vs exact face differences on the staggered lattice). Different algorithms, not a copy. Same for the two `subtract_pressure_gradient` kernels.
+- **`Collider.setFlag/clearFlag/getFlag/writeFlag` vs `RigidBody.*`** (brief §E) — the same four one-line bodies appear in **32** engine classes. A codebase-wide idiom over a `this.flags` int, no shared state, one line each; a base class would impose an inheritance constraint on unrelated component hierarchies. Not a physics finding.
+- **`reduce_manifold_contacts`** — already extracted by a previous review; `reduce_manifold_contacts.js:14-18` documents that box_box, convex_convex, box_triangle and the dispatcher "each previously carried its own byte-identical copy". `box_triangle_contact.js:146 reduce_contacts` is a 1-line binding, not a copy. Do not re-flag.
+- **`mls-mpm` vs `fluid`** — `MLS_MPM.js` is 2D with quadratic B-spline P2G/G2P weights; the fluid stack is 3D trilinear on a MAC lattice. No shared indexing or weight code. It is also plainly a prototype (`Math.random()` at `:388-389`, per-step array allocation in `advance`, a `testMLS_MPM.js` harness beside it). No reuse opportunity.
+- **"Second broadphase / AABB tree inside physics"** — none. `engine/physics/broadphase/generate_pairs.js:1` queries `core/bvh2`, and `compute_fat_world_aabb.js:1` uses `core/geom/3d/aabb/aabb3_transform_oriented`. Clean.
+- **`solve_contacts.js:458 apply_impulse_to_pseudo` vs `:401 apply_impulse_to_body`** — same math, but the destination is a different buffer with a different stride and split lin/ang lanes. Unifying needs `(dst, lin_offset, ang_offset)` threading through the hottest routine in the solver for one caller's benefit. Borderline; folded into finding #1 only if that extraction happens anyway.
+- **`SBS_AV_X/SBS_INV_I_X` block shared by `solve_constraints.js` and `solve_contacts.js`** (brief §E) — that is an import list of shared lane constants from `body/SolverBodyState.js`. Correct reuse, not duplication.
+- **`convex_convex_manifold.js:243` vs `box_box_manifold.js:117` vs `box_triangle_contact.js:182` — the *projection* halves of `test_axis`** — legitimately shape-specific (symmetric half-extent projection vs three explicit vertex dots vs a vertex-buffer min/max loop). Only the tracking half is duplicated; that is finding #2.
+- **The `g_bb_*` / `g_bt_*` / `g_ct_*` module-static accumulator idiom** appearing in three narrowphase files — each carries a comment explaining it replaced a per-call closure allocation ("D3"). Same *technique*, different state. Correct as-is.
+
+## Notes
+
+**Why duplication accumulates here, structurally:**
+
+1. **Twin kernel families.** The fluid solver carries a full collocated (`v3_grid_*`) and a full staggered-MAC (`v3_mac_*`) implementation of advection. The MAC family superseded the collocated one (memory: "MAC staggered, exact projection; MacCormack velocity default") but the collocated family stayed as library surface — so every algorithm in it (SL trace, MacCormack, Selle limiter, solid pass-through) now exists twice, and the two copies have already begun to drift (findings 4, 5, 6, 7). This is the largest single source of duplication in the domain by line count.
+
+2. **Core primitives that return parameters, not points.** `tri3_closest_point_barycentric` returns `(α, β)` and `line3_compute_segment_segment_closest_points` returns `(s, t)`. Sixteen call sites across physics, core and graphics then write the same reconstruction arithmetic. This is the highest-leverage class of finding (#14, #15) because the fix is additive — two new core functions, no behaviour change, and the existing exports stay.
+
+3. **Partial prior extractions.** Three separate extractions were done and each missed one site: `reduce_manifold_contacts` left the surrounding emit epilogue behind (#11), `angular_effective_mass_raw` was adopted by `solve_contacts` and `RaycastVehicle` but not `solve_constraints` (#17), and `polygon2_clip_halfplane` was written in core but never consumed (#12). Grepping for "each previously carried its own copy"-style comments is a reliable way to find the residue.
+
+4. **Axis triplication.** The MAC kernels and the effectors write x/y/z as three near-identical blocks with different strides. In the *kernels* (`v3_mac_advect_sl_velocity.js`, `v3_mac_advect_maccormack_velocity.js`) this is legitimate — see below. In the *effectors* it is not (#13), because those loops are radius-bounded, not grid-bounded.
+
+**Where inlining is legitimately correct (do not "fix" these):**
+
+- `v3_mac_clip_trace.js:25-29` is an explicit measured performance contract (8.6× on the SL kernel) and the three inline solid tests in `v3_mac_advect_sl_velocity.js` honour it. These run per *face* over the whole lattice — millions of evaluations per step. Finding #19 targets only the two redundant *function declarations*, and even that is gated on measurement.
+- The x/y/z block triplication inside `v3_mac_advect_sl_velocity.js` and `v3_mac_advect_maccormack_velocity.js`: each block has different index strides (`sx*res_y`, `res_x*sy`, `cell_slice`) and different loop bounds (`<= res_x` on the own axis). Parameterising would put stride variables in the innermost loop of a whole-grid kernel. Correct as written; I did not flag it.
+- `capsule_contacts.js` / `capsule_triangle_contact.js` / the manifold builders are **per-contact**, not per-cell — a few thousand calls per frame, not millions. Extracting 20-line leaf helpers there (#9, #10, #11) is squarely on the reuse side of the line, and the codebase already does exactly this (`reduce_manifold_contacts`, `angular_effective_mass_raw`).
+- `solve_contacts` / `solve_constraints` inner rows are per-contact-row × per-iteration — the hottest code in the engine. Finding #1 is still worth doing because it is a *verbatim* duplicate of the most correctness-critical routine present, but it must be benchmarked (rain and KEVA-mini) and must preserve operand order exactly for `determinism.spec.js`.
+
+**Determinism summary:** findings 2, 5 and 12 can change simulation output and need before/after numerical diffs. Findings 1, 4, 6, 7, 9, 10, 11, 14, 15, 17, 18 are order-preserving by construction *provided* the extracted body is copied verbatim rather than rewritten — that is the whole risk. Findings 16, 20, 21, 22 have no simulation-state exposure.

package/src/DUPLICATION_AUDIT_2026_08_07/F_sound.md

@@ -1,102 +1,102 @@
-# 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 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.