@woosh/meep-engine 2.169.1 → 2.169.2

package/src/DUPLICATION_AUDIT_2026_08_07/A_core_math_geom.md

@@ -0,0 +1,79 @@
+# Domain A — core/geom + core/math
+
+Source root: `H:/git/moh/app/src/mir-engine/meep/src/` — all paths below are relative to it unless absolute.
+Every row was verified by opening the files. Rename shims (`@deprecated ... re-export`) were checked in bulk and
+are **not** duplication — see Dismissed leads.
+
+## Findings
+
+| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
+|---|---|---|---|---|---|---|---|
+| 1 | CRITICAL | **Whole dynamic-AABB-tree (Box2D-style) implemented twice, 2D fork has already diverged.** Node allocation, free list, capacity growth, SAH insertion, AVL rotation, refit, node swap, traversal. | `core/bvh2/bvh3/BVH.js` (1437 ln, class `BVH`) ⟷ `core/geom/2d/bvh/BVH2D.js` (1138 ln, class `BVH2D`). Method-for-method: `__grow_capacity` 217/155, `allocate_node` 300/214, `node_set_aabb` 501/411, `node_get_surface_area` 574/477, `node_get_combined_surface_area` 600/501, `insert_leaf` 663/557, `bubble_up_refit` 775/675, `bubble_up_update` 803/705, `remove_leaf` 845/740, `balance_height` 902 ⟷ `balance` 792, `traverse` 1302/1008, `__move_node_links` 1357/1063, `swap_nodes` 1394/1100. Column constants re-declared: `COLUMN_PARENT/CHILD_1/CHILD_2/HEIGHT/USER_DATA`, `NULL_NODE`, `ELEMENT_WORD_COUNT` exported from **both**. | `remove_leaf` (55 ln), `bubble_up_update` (35 ln), `swap_nodes`, `__move_node_links`, `traverse` are token-identical. `balance_height`/`balance` are 1206/1208 tokens with only 3 real diffs (`node_is_leaf(iA)` vs inline `iB === NULL_NODE`; `this.node_capacity` vs `this.__capacity`). **Proof of drift:** BVH.js has gained `balance_rotate` (SAH rotation, Box2D v3, BVH.js:1120), `allocate_linear` (:288), `node_assign_children` (:1249), `node_assign_children_only` (:1268) — BVH2D has **none** of them and still calls the old height-only rotation. Only truly dimensional code: AABB word layout (6 vs 4 floats, `ELEMENT_WORD_COUNT` 10 vs 8) and `aabb3_array_combine`/`aabb3_surface_area` vs `aabb2_union_array`/perimeter. | **UNJUSTIFIED** (2D/3D carve-out does not cover 1000 lines of dimension-independent pointer surgery) | Extract the topology half into a dimension-agnostic base holding `__data_uint32` links only: `core/bvh2/DynamicTreeTopology.js` with `allocate_node/release_node/node_get_*/insert_leaf/remove_leaf/bubble_up_*/balance_height/balance_rotate/swap_nodes/traverse`, parameterised at *class* level (subclass supplies `ELEMENT_WORD_COUNT`, `node_set_combined_aabb`, `node_get_surface_area`, `node_get_combined_surface_area` — 4 overrides, no runtime flags). `BVH extends`, `BVH2D extends`. | **L** / high. This is the physics broadphase; `determinism.spec.js` + the bvh3 suite are the gate. Risk is real — do it only with the 70-test BVH suite green before and after, and mirror `balance_rotate` into 2D as a *separate* commit so the behaviour change is isolated. |
+| 2 | HIGH | **Boolean and distance-returning AABB-vs-ray-segment slab tests, whose docs declare they MUST agree, are two independent copies of the same numerically-subtle NaN handling.** | `core/geom/3d/aabb/aabb3_intersects_ray_segment.js:35` `aabb3_intersects_ray_segment` ⟷ `core/geom/3d/aabb/aabb3_ray_segment_entry_distance.js:40` `aabb3_ray_segment_entry_distance` | Bodies are character-identical for 45 lines (ray-space shift, 6 slab `t`s, the three `t !== t` NaN probes, the `±Infinity` interval substitution, `max of mins / min of maxes`). They differ ONLY in the last 4 lines (`return t_box_min <= t_box_max` vs `if (t_box_min > t_box_max) return Infinity; return t_box_min`). The entry-distance doc states verbatim that the two "MUST agree on every input". The whole NaN dance is a hardening fix that was applied twice by hand. | **UNJUSTIFIED** | Delete the duplicated body: `export function aabb3_intersects_ray_segment(...) { return aabb3_ray_segment_entry_distance(...) !== Infinity; }`. No mode flag, no sentinel parameter — the miss sentinel already exists and is documented. | **S** / low. Both have specs. One extra call in a broadphase leaf test; V8 inlines it (single call site, monomorphic). |
+| 3 | HIGH | **Point-in-closed-triangle-surface classifier (BVH build + 3-ray parity majority vote) copy-pasted whole between the tetrahedral carver and the interior-point sampler.** | `core/geom/3d/tetrahedra/tetrahedral_mesh_carve_outside_surface.js`: `RAY_DIRECTIONS` :19, `build_surface_bvh` :33, `single_ray_parity_inside` :81, `point_is_inside_surface` :127. ⟷ `core/geom/3d/topology/struct/binary/query/bt_mesh_sample_interior_grid_points.js`: `RAY_DIRECTIONS` :12, `build_surface_bvh` :29, `point_is_inside` :78. | `build_surface_bvh` is 435 tokens, token-identical (only the parameter name `surface` vs `mesh` differs). The three magic ray directions (`0.97123, 0.18927, 0.14431`, …) are duplicated digit-for-digit; the module-static scratch (`ray_hit`, `ray_candidates`, `va`, `vb`, `vc`) is duplicated; the majority rule `inside_votes * 2 > RAY_COUNT` is duplicated. The second file's comment says "Same scheme as tetrahedral_mesh_carve_outside_surface" — an acknowledged copy. ~100 lines. | **UNJUSTIFIED** | New module `core/geom/3d/topology/struct/binary/query/bt_mesh_build_face_bvh.js` already exists for the BVH half — reuse it or add `bt_mesh_point_is_inside_surface(mesh, bvh, x, y, z)` beside it, plus `bt_mesh_build_surface_triangle_bvh(bvh, mesh)`. Both callers then hold a `BVH` and call the predicate. | **S–M** / low. Both call sites have specs (`tetrahedral_mesh_carve_outside_surface.spec.js`, `bt_mesh_sample_interior_grid_points.spec.js`). |
+| 4 | HIGH | **Radial-cycle splice (the core half-edge invariant "link a loop into an edge's face ring") implemented three times, with two of them behaviourally different from the exported canonical one.** | `core/geom/3d/topology/struct/binary/io/bt_radial_loop_add.js:9` `bt_radial_loop_add` (exported, canonical) ⟷ `core/geom/3d/topology/struct/binary/io/face/bt_face_poke.js:130` `_link_loop_to_edge_local` ⟷ `core/geom/3d/topology/struct/binary/io/bt_mesh_from_indexed_geometry.js:123` `link_loop_to_edge` | All three set `loop_write_edge`, read `edge_read_loop`, branch on `NULL_POINTER`. **Divergence 1:** `bt_radial_loop_add` splices *before* the base loop (`loop_read_radial_prev`); the other two splice *after* (`loop_read_radial_next`) — different resulting ring order. **Divergence 2:** `bt_mesh_from_indexed_geometry.link_loop_to_edge` omits the self-link (`radial_next = radial_prev = loop`) in the first-loop branch entirely; it works only because `BinaryTopology.loop_initialize` (BinaryTopology.js:686) happens to self-link on allocation — an undocumented dependency the other two do not have. **Divergence 3:** `bt_face_poke.js:127` comments "Replicates logic from 'link_loop_to_edge' since it is not exported" — but `bt_radial_loop_add` *is* exported and does exactly this. | **UNJUSTIFIED** | Both private copies call `bt_radial_loop_add(mesh, loop, edge)`. Pick one ring order deliberately (the `prev` splice) and document it in `bt_radial_loop_add`'s JSDoc as the mesh-wide invariant. | **S** / medium. Ring *order* is observable through `loop_read_radial_next` walks, so `bt_face_poke` and `bt_mesh_from_indexed_geometry` specs plus `bt_mesh_validate` must be re-run; a change in insertion side can flip which face a two-face edge reports first. |
+| 5 | HIGH | **Static implicit-binary-tree spatial index (morton quicksort + bottom-up bounds assembly) forked 3D→2D; the fork carries a scratch-stack indexing bug the original does not.** | `core/bvh2/binary/2/BinaryUint32BVH.js`: `sort_morton` :336, `__swap_leaves` :411, `build` :426 ⟷ `core/geom/2d/r-tree/StaticR2Tree.js`: `sort_morton` :210, `__swap_leaves` :296, `build` :313. Also `initialize_structure`, `setLeafCount`, `setLeafData`, `getLeafBlockAddress`, `readLeafPayload` mirror one-for-one. | `build` is 289 tokens, token-identical modulo `BVH_BINARY_NODE_SIZE`→`BINARY_NODE_SIZE`, `BVH_LEAF_NODE_SIZE`→`LEAF_NODE_SIZE`, `aabb3_array_combine`→`aabb2_union_array`, `array_copy(...,6)`→`array_copy(...,4)`. `sort_morton` is the same hand-rolled explicit-stack quicksort. **Fork bug:** `StaticR2Tree.js:219-226` sets `stackPointer = stack_top + 2` but then writes the two seed values to the *absolute* slots `stack[0]` / `stack[1]` instead of `stack[stack_top]` / `stack[stack_top + 1]`; `BinaryUint32BVH.js:350-351` correctly uses `stack[stackPointer++]`. Only reachable when the shared `SCRATCH_UINT32_TRAVERSAL_STACK` is entered with a non-zero pointer, but the two implementations now disagree on a shared-scratch contract. | **UNJUSTIFIED** | Same shape as finding #1 but far smaller: hoist the two dimension-free routines into `core/bvh2/binary/implicit_tree_sort_morton.js` + `implicit_tree_build_bounds.js` taking `(data, binary_node_count, leaf_count, binary_node_size, leaf_node_size, combine_fn, morton_fn)`. If the per-node indirect call is unacceptable for `build`, at minimum fix the seed-write divergence and cross-reference the two in JSDoc. | **M** / medium. Both classes have specs. Prefer fixing the stack-seed divergence first as its own change. |
+| 6 | HIGH | **Relative-epsilon degenerate-quadratic critical-point solver written three times in `core/math/spline`, deliberately bypassing the shared `solveQuadratic` because that one still uses an absolute epsilon.** | `core/math/spline/spline3_hermite_bounds.js:22`, `core/math/spline/spline3_hermite_bounds_t.js:26`, `core/math/spline/spline3_bezier_bounds.js:20`. Existing primitive: `core/math/solveQuadratic.js:15`. | All three contain the identical block `const epsilon = max3(abs(a),abs(b),abs(c)) * 1e-12; if (abs(a) <= epsilon) { if (abs(b) > epsilon) {...linear root...} } else { const b2ac = b*b - 4*c*a; if (b2ac >= 0) {...two roots, each gated on 0 < t < 1...} }` — and the *same 3-line explanatory comment* about relative vs absolute thresholds is copy-pasted verbatim into all three. `solveQuadratic` uses `Math.abs(a) < EPSILON` (absolute, `core/math/EPSILON.js`) — i.e. exactly the defect these three were fixed for. A future fix to the degeneracy rule now has to land in four places. | **UNJUSTIFIED** | Add `core/math/solve_quadratic_relative(result, result_offset, a, b, c) -> count` implementing the relative-epsilon rule, then have all three spline functions call it and reduce min/max (or min/max + argmin/argmax for `_bounds_t`). Note: `_bounds` and `_bounds_t` cannot be merged into one function without an output-mode flag — do **not** try; sharing the *root finder* is the whole win. Separately consider whether `solveQuadratic` should adopt the relative rule (behaviour change, own commit). | **M** / medium. All three have specs; the `_t` variant additionally tracks argmin/argmax so its reduction stays local. |
+| 7 | MEDIUM | **`ConvexHullShape3D` and `MeshShape3D` share five copy-pasted query methods.** | `core/geom/3d/shape/ConvexHullShape3D.js`: `compute_bounding_box` :185, `signed_distance_at_point` :241, `nearest_point_on_surface` :271, `sample_random_point_in_volume` :297, `equals` :322. ⟷ `core/geom/3d/shape/MeshShape3D.js`: `compute_bounding_box` :145, `nearest_point_on_surface` :421, `signed_distance_at_point` :474, `sample_random_point_in_volume` :522, `equals` :576. | `sample_random_point_in_volume` is token-identical (sim 1.0, 210 tok) — 256-attempt bbox rejection sampling with a bbox-centre fallback. `compute_bounding_box` is identical (6 array copies from `__bbox`). `equals` is identical (128 tok) modulo the field name `vertices`/`positions`. `nearest_point_on_surface` (378/381 tok) and `signed_distance_at_point` (353/356 tok) differ only in field names and local variable names — the per-triangle `tri3_closest_point_barycentric` scan is line-for-line the same. | **UNJUSTIFIED** (this is duplicated *logic*, not per-class typed boilerplate) | Three moves: (a) `sample_random_point_in_volume` becomes the default implementation on `AbstractShape3D` (it needs only `compute_bounding_box` + `contains_point`, both already abstract) — every convex shape gets it free; (b) `compute_bounding_box` from a cached `__bbox` likewise; (c) add `core/geom/3d/shape/util/shape3_surface_scan_nearest_point.js` exporting `surface_scan_nearest_point(out, positions, indices, px, py, pz) -> number` returning best_d2 — both `nearest_point_on_surface` and `signed_distance_at_point` become 5-line wrappers in both classes. | **S** / low. Both classes have specs (`ConvexHullShape3D.spec.js`, `MeshShape3D.spec.js`, `raycast.spec.js`). |
+| 8 | MEDIUM | **Bounding box of a flat `(x,y,z)` buffer re-inlined instead of calling `aabb3_from_v3_array`.** | `core/geom/3d/shape/ConvexHullShape3D.js:103-114` (inside `recompute`), `core/geom/3d/shape/MeshShape3D.js:251-266` (inside `recompute_cached`). Existing primitive: `core/geom/3d/aabb/aabb3_from_v3_array.js:12`. | Both write the same 12-line `Infinity`/`-Infinity` seed + per-component `if (x < mn) …; if (x > mx) …` loop, then the same `if (count === 0) { all = 0 }` normalisation. `aabb3_from_v3_array` does the identical reduction via `min2`/`max2` and `aabb3_array_set`; the only real semantic delta is the empty-input policy (primitive leaves ±Infinity; the shapes zero it). `bt_mesh_sample_interior_grid_points.js:161-175` is a third copy over the topology vertex pool. | **UNJUSTIFIED** for the shapes | Call `aabb3_from_v3_array(this.__bbox, v, v.length)` and keep the two-line empty-input normalisation at the call site (or add `aabb3_array_is_empty`). Do **not** add an "empty policy" parameter — that is exactly the sentinel the house rules forbid. | **S** / low. |
+| 9 | MEDIUM | **`Vector3.applyQuaternion` and `Vector4.applyQuaternion` inline the quaternion sandwich product that `v3_quaternion_apply` already implements — and the "inlined for speed" justification is dominated by the `set()` signal dispatch in the same method.** | `core/geom/Vector3.js:675` `applyQuaternion`, `core/geom/Vector4.js:360` `applyQuaternion`. Existing primitive: `core/geom/vec3/v3_quaternion_apply.js:28`. | The 8-line expansion (`ix/iy/iz/iw` then `_x/_y/_z`) is identical in all three, term for term. `Vector3.js:676` says "NOTE: the logic is inlines for speed" — but both methods end in `this.set(...)` (`core/geom/Vector3.js:160`, `core/geom/Quaternion.js:1314`), which runs 6 asserts, a 3-way change comparison and `onChanged.send6(...)` when handlers exist. The array round-trip a `v3_quaternion_apply` call would cost is orders of magnitude below that. Contrast `core/geom/3d/shape/PosedShape3D.js:60` `support`, which inlines the *same* expansion with a **measured, documented** justification ("V8 declines to inline v3_quat3_apply at 9-arg call sites… hottest GJK call") — that one is legitimately hot and stays. | **UNJUSTIFIED** for `Vector3`/`Vector4`; the `PosedShape3D` copy is **JUSTIFIED** (documented hot-loop scalar inlining) | `Vector3.applyQuaternion(q)` → `v3_quaternion_apply(SCRATCH, 0, this[0], this[1], this[2], q.x, q.y, q.z, q.w); return this.set(SCRATCH[0], SCRATCH[1], SCRATCH[2]);` with a module-static `SCRATCH`. Same for `Vector4` (preserving `w`). | **S** / low. `Vector3.spec.js`/`Vector4.spec.js` cover it; note `v3_quaternion_apply` uses `q*` sign inlined identically so results are bit-identical. |
+| 10 | MEDIUM | **"Normalize a 3-vector, or emit zero when degenerate" is re-derived in at least four places with three different degenerate policies — there is no scalar `v3_normalize`.** | `core/geom/vec3/v3_matrix3_rotate.js:21`, `core/geom/vec3/v3_matrix4_rotate_unit.js:21`, `core/geom/vec3/v3_matrix4_rotate_normal.js:24` (identical 20-line tails: `length > 1e-7 ? scale : write zeros`), `core/geom/3d/shape/TransformedShape3D.js:199-209` (`mag > 0 ? scale : zeros`), `core/geom/3d/shape/util/compute_signed_distance_gradient_by_sampling.js:38-48` (`mag > 0 ? scale : zeros`), `core/geom/3d/mat4/m4_transform_direction_v3_buffer.js:44` (`1 / v3_length(...)` with **no** guard at all → ±Infinity on a zero vector). Nearest existing primitive: `core/geom/vec3/v3_normalize_array.js:10` (array-in, and its policy is `n = 1` on zero — i.e. leaves the vector as-is). | The three `v3_matrix*_rotate*` tails are token-identical (158/165 tok pairs at sim 0.938) including the `1e-7` literal and the "The transform is invalid. Provide arbitrary vector." comment. Four different answers to the same degenerate question is the actual hazard, not the line count. | **PROMOTION** | Add `core/geom/vec3/v3_normalize.js` → `v3_normalize(out, out_offset, x, y, z)` writing the unit vector, and `v3_normalize_or_zero(out, out_offset, x, y, z, epsilon)` documenting the zero policy once. Have the three rotate variants, `TransformedShape3D`, and the SDF-gradient sampler call it. Leave `v3_normalize_array` alone (different, documented policy) but cross-reference it. | **S** / low. `v3_matrix3_rotate.spec.js`, `v3_matrix4_rotate_normal.spec.js` exist. |
+| 11 | MEDIUM | **`MeshShape3D` re-implements the shared finite-difference SDF-gradient sampler with a different step size and no normalisation, while every other shape delegates to it.** | `core/geom/3d/shape/MeshShape3D.js:552` `signed_distance_gradient_at_point` ⟷ `core/geom/3d/shape/util/compute_signed_distance_gradient_by_sampling.js:11`. Delegating shapes: `ConvexHullShape3D.js:267`, `CapsuleShape3D.js:115`, `CylinderShape3D.js:129`, `SphereShape3D.js:103`, `BoxShape3D.js:112`, `UnionShape3D.js:219`. | Same forward-difference structure (centre sample + 3 axis samples + `(d_axis - d_center)/h`), but `MeshShape3D` uses `h = 1e-4` vs `SAMPLE_STEP = 1e-5`, and — unlike the shared helper — does **not** normalise the resulting gradient to unit length. Six shapes agree; one does not. | **UNJUSTIFIED** | `signed_distance_gradient_at_point(result, point) { return compute_signed_distance_gradient_by_sampling(result, this, point); }` — one line, matching every sibling. | **S** / low. Changes the returned gradient magnitude for meshes; `MeshShape3D.spec.js` may assert the current unnormalised values and would need updating to the (correct) unit-gradient contract. |
+| 12 | MEDIUM | **`hammersley_sequence` is `halton_sequence` with the arguments swapped.** | `core/math/statistics/hammersley_sequence.js:21` ⟷ `core/math/statistics/halton_sequence.js:11`. | Bodies: `let result = 0; let f = 1; let n = i; while (n > 0) { f = f / R; result += f * (n % R); n = (n / R) >>> 0; } return result;` vs the same with `base`/`index` names. Character-identical after renaming. The Hammersley doc even says "Computed in closed form, as {@link halton_sequence} does." Only real delta: `halton_sequence` asserts both args are non-negative integers; `hammersley_sequence` does not (and asserts are free in prod). Note `hammersley_sequence_2d.js` is a *different*, base-2 bit-reversal path (`radical_inverse_VdC_base_2`) and is fine. | **UNJUSTIFIED** | `export function hammersley_sequence(i, R) { return halton_sequence(R, i); }` — keeps the public name (library surface) and the argument order its callers use. | **S** / low. Both have specs. |
+| 13 | MEDIUM | **`curl_noise_3d` is `curl_noise_3dt` with `w = 0`, including the six duplicated decorrelation offsets.** | `core/math/noise/curl_noise_3d.js:15` ⟷ `core/math/noise/curl_noise_3dt.js:15`. | `diff -u` shows the entire difference is the extra `w` parameter added to one component of each of the three `sdnoise3` calls. With `w = 0` the two are literally the same function. The offsets `31.341, -43.23, 12.34, -231.141, 124.123, -54.4341` are duplicated digit-for-digit — retuning one silently decorrelates the pair. | **UNJUSTIFIED** | `export function curl_noise_3d(result, x, y, z) { curl_noise_3dt(result, x, y, z, 0); }`. Passing 0 is a real time value, not a sentinel. | **S** / low. `sdnoise.spec.js` covers the underlying noise; add a same-value assertion. |
+| 14 | MEDIUM | **`m4_compose` (object args) and `m4_from_rotation_translation_scale` (array args) contain the same 45-line quaternion→matrix expansion.** | `core/geom/3d/mat4/m4_compose.js:8` ⟷ `core/geom/3d/mat4/m4_from_rotation_translation_scale.js:20`. | The `x2/y2/z2 → xx/xy/xz/yy/yz/zz/wx/wy/wz` block and all 16 `result[i] = …` writes are identical; only the operand *reads* differ (`rotation.x` vs `q[0]`, `scale.x` vs `s[0]`). The array version's doc already calls itself the "array-argument companion to m4_compose", acknowledging the fork. The codebase's own convention elsewhere (`tri3_area` scalar + `tri3_compute_normal_v3_objects` wrapper) is exactly the fix. | **UNJUSTIFIED** | Add the scalar core `m4_from_rotation_translation_scale_scalar(out, qx,qy,qz,qw, tx,ty,tz, sx,sy,sz)` in the same directory; both existing exports become 3-line unpackers. Preserves both public names (library surface). | **S** / low. `m4_from_rotation_translation_scale.spec.js` exists. |
+| 15 | MEDIUM | **The boolean segment-segment intersection test is an exact prefix of the point-returning one.** | `core/geom/2d/line/segment2_intersects_segment2_2d.js:14` ⟷ `core/geom/2d/line/segment2_segment_compute_intersection_array_2d.js:20`. | Lines 15-27 of the boolean version and 25-37 of the array version are character-identical: `s1_x/s1_y/s2_x/s2_y`, `dy_02/dx_02`, `inv_denom = 1 / (-s2_x*s1_y + s1_x*s2_y)`, `s`, `t`, then the same `s >= 0 && s <= 1 && t >= 0 && t <= 1` test. The array version adds 6 lines to compute and store the intercept. Both share the same undocumented parallel-segments behaviour (`inv_denom = ±Infinity` → `s`/`t` become `±Infinity` or `NaN`). | **UNJUSTIFIED** | Extract `segment2_segment_intersection_fractions(out, out_offset, a0_x…b1_y) -> boolean` writing `[s, t]`; both public functions become thin. Document the parallel case once. | **S** / low. Both have callers in navigation/generation; behaviour must stay bit-identical. |
+| 16 | MEDIUM | **Reading a triangular face's three vertex ids / coordinates out of a `BinaryTopology` is hand-written at ~8 non-spec sites, with inconsistent "is it actually a triangle?" checking.** | `core/geom/3d/topology/struct/binary/query/bt_mesh_face_find_path.js:80` `face_read_vertices`; `…/bt_mesh_face_find_path_polyanya.js:93` `triangle_vertices`; `…/bt_mesh_sample_interior_grid_points.js:38-44`; `core/geom/3d/tetrahedra/tetrahedral_mesh_carve_outside_surface.js:41-48`; `core/geom/3d/atlas/data/atlas_build_face_areas.js:30-40`; `core/geom/3d/topology/struct/binary/io/bt_mesh_compute_face_normals.js:35-45`; `…/io/bt_mesh_compute_vertex_quadrics.js:54-68`; `…/query/bt_mesh_find_nearest_face.js:109-119`. | Every one is `l0 = face_read_loop(f); l1 = loop_read_next(l0); l2 = loop_read_next(l1);` followed by three `loop_read_vertex` and (usually) three `vertex_read_coordinate` into three 3-element scratch buffers. `atlas_build_face_areas`, `bt_mesh_compute_face_normals` and `bt_mesh_compute_vertex_quadrics` additionally check `loop_read_next(l2) === l0` and skip non-triangles; `tetrahedral_mesh_carve_outside_surface` and `bt_mesh_sample_interior_grid_points` **do not** and will silently mis-handle an n-gon. Each site declares its own module-static scratch. | **PROMOTION** | Add `core/geom/3d/topology/struct/binary/query/bt_face_read_triangle.js` exporting `bt_face_read_triangle_vertices(out, mesh, face) -> boolean` and `bt_face_read_triangle_coordinates(out, out_offset, mesh, face) -> boolean` (9 floats), both returning `false` for a non-triangular/unallocated face. That makes the triangle check impossible to forget. | **M** / low. Purely additive; migrate call sites one at a time. |
+| 17 | MEDIUM | **Straight-line vertex-to-vertex distance re-implemented inside both pathfinders while the primitive sits in the same directory — and the two copies use different formulas.** | `core/geom/3d/topology/struct/binary/query/bt_vertex_distance_to_vertex.js:12` (existing, uses `v3_distance`) ⟷ `…/bt_mesh_face_find_path.js:100` `vertex_distance` (`Math.sqrt(dx*dx+dy*dy+dz*dz)`) ⟷ `…/bt_mesh_face_find_path_polyanya.js:103` `vid_distance_3d` (`Math.hypot`). A fourth copy is `…/bt_mesh_build_boundary_distance_field.js:79` (`Math.hypot` inline). | Same three coordinate reads + same distance, three different spellings. `Math.hypot` and `sqrt(sum of squares)` are **not** bit-identical, so a geodesic cost computed by one pathfinder is not reproducible by the other on the same mesh — relevant because both are A*-style and their costs get compared in the bench specs. | **UNJUSTIFIED** | All four call `bt_vertex_distance_to_vertex(mesh, a, b)` (it already exists and is spec'd). If the module-static scratch inside it is a re-entrancy concern for the pathfinders, give it a `_scratch`-free scalar sibling — but pick **one** formula. | **S** / low, except that switching `hypot`→`sqrt` (or vice versa) can shift A* tie-breaking; run `bt_mesh_face_find_path.shortest_path.spec.js` and the polyanya specs. |
+| 18 | MEDIUM | **`order_cycle_from` and the fan-fill of a boundary loop are copy-pasted between the two hole-closing modules.** | `core/geom/3d/topology/struct/binary/io/bt_mesh_close_boundary_holes.js:20` `order_cycle_from` + the per-cycle body at :81-132 ⟷ `core/geom/3d/topology/struct/binary/io/bt_mesh_fill_small_holes.js:13` `order_cycle_from` + :60 `fill_loop`. | `order_cycle_from` is 245 tokens, token-identical (only brace formatting differs). `fill_loop` (:60-94) is a line-for-line copy of `bt_mesh_close_boundary_holes`'s loop body: same seed-edge/start-vertex derivation, same centroid accumulation, same face+loop allocation, same `bt_radial_loop_add` wiring, same `% n` next/prev ring, same `bt_face_poke` centroid fan. `bt_mesh_fill_small_holes.js:12` and :59 both say "Same as / as close_boundary_holes does" — acknowledged copies. ~75 lines. | **UNJUSTIFIED** | Export both from a new `core/geom/3d/topology/struct/binary/io/bt_boundary_loop.js`: `bt_boundary_loop_order_from(mesh, cycle, start_vertex, out_vertices, out_edges)` and `bt_boundary_loop_fill_fan(mesh, cycle)`. `bt_mesh_close_boundary_holes` becomes a loop over cycles calling `fill_fan`; `bt_mesh_fill_small_holes` keeps its measurement/threshold logic. | **S** / low. Both have specs. |
+| 19 | MEDIUM | **`project_triangle` (isometric triangle flattening) duplicated between the two chart parameterisers.** | `core/geom/3d/atlas/param/atlas_chart_parameterize_bff.js:39` ⟷ `core/geom/3d/atlas/param/atlas_chart_parameterize_lscm.js:64`. | Same algorithm (place v0 at origin, v1 on +x, project v2, write `[len1, x3, y3]`), 236/267 tokens, sim 0.78 — the BFF copy is just a tighter rewriting with intermediate `bx/by/bz`/`cx/cy/cz` folded away. The BFF version's comment reads "(Same as LSCM.)". | **UNJUSTIFIED** | Move to `core/geom/3d/triangle/tri3_flatten_isometric.js` → `tri3_flatten_isometric(out, out_offset, ax,ay,az, bx,by,bz, cx,cy,cz)` writing `[len_ab, x_c, y_c]`, plus an indexed wrapper for the `pos, i0, i1, i2` form both callers use. This is a genuinely reusable primitive (any conformal/ARAP/LSCM/geodesic-unfolding pass wants it — `bt_mesh_face_find_path_polyanya.js:137` `unfold_apex` solves a related problem). | **S** / low. Both parameterisers have specs. |
+| 20 | MEDIUM | **`qt_collect_by_circle` and `qt_match_data_by_circle` are the same traversal, differing by one predicate conjunct; and the circle queries lost the child-pruning the box/point queries have.** | `core/geom/2d/quad-tree/qt_collect_by_circle.js:19` ⟷ `core/geom/2d/quad-tree/qt_match_data_by_circle.js:21`. Contrast `qt_collect_by_box.js:22` and `qt_collect_by_point.js:19`. | The two circle functions are 212/228 tokens at sim 0.81; the only semantic delta is `&& predicate.call(predicateContext, datum.data)` on the accept line. Stack management differs cosmetically (`while (stack_pointer-- > 0)` vs `while (stack_pointer > 0) { --stack_pointer;`). Separately: both circle variants push all four children unconditionally (`:56-61`, `:61-66`), whereas `qt_collect_by_box` (:63-83) and `qt_collect_by_point` (:58-78) compute the node's half-planes and push only the quadrants that can overlap — so the circle path descends up to 4× more nodes. Each of the four files also declares its own module-static `node_stack`, none of which is re-entrancy-safe. | **UNJUSTIFIED** for the body; the missing pruning is a genuine divergence worth fixing at the same time | Make `qt_match_data_by_circle` the single implementation and define `qt_collect_by_circle` as it with a module-static `const ACCEPT_ALL = () => true` — a real function, not a null sentinel, and monomorphic so V8 inlines it. Add the quadrant pruning (`hx`/`hy` vs `x ± radius`) while you are in there. | **S–M** / low. `qt_match_data_by_circle.spec.js` and `qt_collect_by_point.spec.js` exist; add a circle-pruning spec. |
+| 21 | MEDIUM | **Winding-agnostic point-in-tetrahedron and coordinate-form `orient3d` are file-private in `MeshShape3D` while the shared versions sit in `core/geom/3d`.** | `core/geom/3d/shape/MeshShape3D.js:646` `orient3d_with_point`, `:686` `tet_contains_point_coords`. Existing: `core/geom/3d/plane/orient3d_fast.js:22`, `core/geom/3d/tetrahedra/tetrahedron_contains_point.js:17`. | `orient3d_with_point` is `orient3d_fast` with the fourth point taken as raw scalars instead of an index — the determinant expansion (`adx*(bdy*cdz - bdz*cdy) + …`) is character-identical. `tet_contains_point_coords` is `tetrahedron_contains_point` made winding-agnostic (accepts all-nonneg **or** all-nonpos rather than assuming one convention). `MeshShape3D.js:663-671` documents this explicitly: "the existing tetrahedron_contains_point helper, by contrast, was authored against a CW convention". So the shared helper is known to be convention-locked and the better version was written privately instead of promoted. `tetrahedral_mesh_walk_towards_containing_tetrahedron.js` is a third consumer of the convention-locked one. | **PROMOTION** | Add `core/geom/3d/plane/orient3d_fast_point.js` → `orient3d_fast_point(points, a, b, c, ex, ey, ez)` and `core/geom/3d/tetrahedra/tetrahedron_contains_point_either_winding.js` (or fix `tetrahedron_contains_point` to be winding-agnostic and document the change). `MeshShape3D` then imports both. | **S** / low if added as new exports; **medium** if `tetrahedron_contains_point` is changed in place (its spec encodes the CW convention). |
+| 22 | LOW-MEDIUM | **`m4_decompose` re-derives the whole of `m4_extract_scale`.** | `core/geom/3d/mat4/m4_decompose.js:10` ⟷ `core/geom/3d/mat4/m4_extract_scale.js:11`. | Lines 11-28 of `m4_decompose` are `m4_extract_scale`'s body verbatim (three `v3_length` calls over matrix columns 0/1/2, 4/5/6, 8/9/10, with the same `m11…m33` local names). `m4_decompose` then needs the raw `m11…m33` for the rotation extraction, so only the three `v3_length` calls are strictly shareable — but a change to how scale is read (e.g. handling a reflected basis) currently has to land twice, and `m4_decompose` already carries a determinant-sign correction that `m4_extract_scale` does not. | **UNJUSTIFIED (mild)** | `m4_decompose` calls `m4_extract_scale(scratch3, 0, mat4)` for the magnitudes and keeps its own `m11…m33` reads for the rotation. Or: document in both that the reflection handling deliberately lives only in `m4_decompose`. | **S** / low. `decompose_matrix_4_array.spec.js` exists. |
+| 23 | LOW-MEDIUM | **Barycentric-weights → 3D point reconstruction re-expanded at five sites instead of a `tri3_closest_point` primitive.** | `core/geom/3d/shape/ConvexHullShape3D.js:255-258` and `:286-289`, `core/geom/3d/shape/MeshShape3D.js:446-450` and `:498-502`, `core/geom/3d/shape/Triangle3D.js:169-175` and `:214-219`. Existing: `core/geom/3d/triangle/tri3_closest_point_barycentric.js` (returns weights only). | Every site does `tri3_closest_point_barycentric(bary, 0, p, a, b, c)` then the same `u = bary[0]; w = bary[1]; t = 1 - u - w; q = u*a + w*b + t*c` expansion — and each independently names the third weight differently (`t` / `w` / `alpha_c`), which is how one of them could quietly get the ordering wrong. | **PROMOTION** | Add `core/geom/3d/triangle/tri3_closest_point.js` → `tri3_closest_point(out, out_offset, px,py,pz, ax…cz) -> number` writing the closest point and returning the squared distance. Every one of the five call sites collapses to one line, and finding #7's surface-scan helper is then trivial to build on top. | **S** / low. |
+| 24 | LOW-MEDIUM | **The two `atlas_segment_charts` variants re-declare the same tuning constants and the same roundness term, with a comment claiming they must stay local.** | `core/geom/3d/atlas/segment/atlas_segment_charts.js`: `REJECT` :10, `NORMAL_DEVIATION_REJECT` :18, `STALE_EPSILON` :25, `chart_unit_normal` :97, roundness block :~140. ⟷ `core/geom/3d/atlas/segment/atlas_segment_charts_atomic.js`: `REJECT` :7, `NORMAL_DEVIATION_REJECT` :8, `STALE_EPSILON` :9, `chart_unit_normal` :49, roundness block :~100. | `chart_unit_normal` is token-identical (49 tok). The roundness block (`if (chart_area > 0 && chart_boundary > 0 && new_boundary > 0) { old_ratio = b²/a; new_ratio = …; R = … }`) is an identical 8-line window. The three constants are identical literals; the atomic file's comment says "kept local so the two segmenters stay monomorphic" — but the file **already imports `ATLAS_SEGMENT_DEFAULTS`** from its twin (`:3`), so the monomorphism argument doesn't cover module-level `const` numbers, which are inlined by V8 regardless of which module they come from. Retuning the 0.707 cutoff in one silently desyncs the two segmenters. | **Constants + roundness: UNJUSTIFIED. The greedy traversal itself: JUSTIFIED** (different growth graph — faces vs `RegionGraph` regions; unifying would require an adjacency-accessor abstraction that genuinely does de-monomorphize the inner loop, and the author documented that trade-off). | Export `REJECT`, `NORMAL_DEVIATION_REJECT`, `STALE_EPSILON` from `atlas_segment_charts.js` alongside `ATLAS_SEGMENT_DEFAULTS` and import them in the atomic variant. Move the roundness term to `atlas_chart_roundness_delta(chart_area, chart_boundary, new_area, new_boundary)` in `core/geom/3d/atlas/segment/`. Leave the loops alone. | **S** / low. Both have specs. |
+| 25 | LOW-MEDIUM | **The spatial-hash-grid cell walk (read element AABB out of the pool) is duplicated between the circle and line queries, including the same no-deduplication behaviour.** | `core/geom/2d/hash-grid/shg_query_elements_circle.js:118-146` ⟷ `core/geom/2d/hash-grid/shg_query_elements_line.js:71-100`. | Both contain the identical 15-line block: `let node = grid.cell_get_first_node(cell_index); while (node !== NULL_POINTER) { const element = grid.node_get_element(node); const element_address = element_pool.element_word(element); const element_x0/y0/x1/y1 = element_float32[element_address + COLUMN_ELEMENT_*]; … node = grid.node_get_same_cell_next_node(node); }` — only the acceptance predicate differs (`aabb2_distance_sqr_to_point <= r2` vs `aabb2_clip_line_cohen_sutherland`). Both share the consequence that an element linked into several visited cells is appended to `result` once per cell. | **PROMOTION** (the *cell iteration* is worth sharing; the predicate is not) | Add `shg_element_read_aabb(out, out_offset, grid, element)` next to `SpatialHashGrid.js` and use it in both. Whether to also share the walk depends on whether an accept-callback is acceptable in this path — if not, at minimum share the AABB read and document the multi-cell duplicate-emission behaviour in one place. | **S** / low. Both have specs. |
+| 26 | LOW | **Shape `hash()` methods disagree on the integer mixing function even though `combine_hash` exists.** | `core/geom/3d/shape/CapsuleShape3D.js:223` and `core/geom/3d/shape/CylinderShape3D.js:207` use `((a << 5) - a + b) \| 0`; `core/geom/3d/shape/BoxShape3D.js:158`, `HeightMapShape3D.js:456`, `ConvexHullShape3D.js:335`, `MeshShape3D.js:593` use `(h * 31 + x) \| 0`; `core/geom/Vector2.js:636` uses `((x << 5) - x) + y` with no `\| 0`. Existing: `core/collection/array/combine_hash.js:8` (used by `Vector4.js:394`). | The *shape* of these methods is per-class boilerplate and deliberate (house rule) — but the *mixing logic* is not, and it is inconsistent five ways across one class family. `Vector2.hash` also omits the `\| 0`, so it can return a non-int32. `CapsuleShape3D.hash` and `CylinderShape3D.hash` are byte-identical, meaning a capsule and a cylinder with equal radius/height collide — harmless given `equals` checks `constructor`, but unintended. | **UNJUSTIFIED (logic, not shape)** | Pick one mixer and use it everywhere. `combine_hash(...)` is varargs (allocates a rest array) so it is not ideal for a per-frame path — add `core/math/hash/hash_mix2(a, b)` / `hash_mix3(a, b, c)` returning `(a * 31 + b) \| 0` etc., and have every shape's `hash()` call it. Keep the per-class `hash()` methods; only the mixer moves. | **S** / low. |
+| 27 | LOW | **BFF's `interior_angle` re-implements `v3_angle` from an indexed buffer, using the acos form rather than the atan2-stable form that also exists.** | `core/geom/3d/atlas/param/atlas_chart_parameterize_bff.js:27` `interior_angle`. Existing: `core/geom/vec3/v3_angle.js:13` (`acos(v3_cos_angle(...))`, with a `clamp(-1,1)` inside `v3_cos_angle`), `core/geom/vec3/v3_angle_stable.js:14` (`atan2(|a×b|, a·b)`). | Identical math to `v3_angle`: two edge vectors, both lengths, `acos(clamp(dot/(lu*lv), -1, 1))`. Differences: BFF returns 0 when either length `< 1e-20` (where `v3_cos_angle` returns 0 for exactly-zero length only), and BFF clamps inline (`Math.acos(Math.max(-1, Math.min(1, c)))`) rather than via `clamp`. The angles feed the Gaussian-curvature sum `Ω = 2π − Σθ`, which is precisely where the acos form loses precision for near-degenerate slivers — and `v3_angle_stable` (the atan2 form) already exists for exactly that. | **UNJUSTIFIED (small), with a follow-up** | Call `v3_angle(ux,uy,uz, vx,vy,vz)` (or `v3_angle_stable` if the sliver precision matters — that is a numerical decision, not a refactor, and should be measured against `atlas_chart_parameterize_bff.spec.js`). | **S** / low for the swap to `v3_angle`; medium if switching to the stable form (changes BFF output on sliver charts). |
+| 28 | LOW | **Two different exported functions named `compute_edge_collapse_cost` in the same package.** | `core/geom/3d/topology/simplify/compute_edge_collapse_cost.js:20` — `(victim, target, victim_edge, vertex_quadratics)`, quadric + normal-flip + boundary penalty. ⟷ `core/geom/3d/topology/simplify/decimate_edge_collapse_snap.js:139` — `(edge, quadratics, restricted_vertices)`, quadric with a topological fallback. | Not shared code — two different cost models with the same name, in sibling files, both exported. For a library this is an import hazard (`import { compute_edge_collapse_cost } from '.../simplify/...'` resolves to whichever path you happened to type) and it makes "which cost does the simplifier use?" unanswerable without opening both. Flagged by the mechanical pass as a duplicate export; it is a naming collision, not duplication. | **UNJUSTIFIED (naming)** | Rename the one in `decimate_edge_collapse_snap.js` to `edge_collapse_cost_with_topology_fallback` (keeping a deprecated alias, per the library rule) — or move it to its own file with a distinct name. No code moves. | **S** / low. |
+| 29 | LOW | **Per-vertex quadric accumulation implemented twice, once per mesh representation, with divergent feature sets.** | `core/geom/3d/topology/simplify/quadratic/build_vertex_quadrics.js:37` (TopoMesh) ⟷ `core/geom/3d/topology/struct/binary/io/bt_mesh_compute_vertex_quadrics.js:23` (BinaryTopology). | Both: derive the face's supporting plane `(n, d = -n·v0)`, `q.setFromVector4(n, d)`, add `q` to each of the three vertices' `Quadric3`. The shared kernel is ~10 lines. Genuinely different iteration (object graph vs pooled ids). **Behavioural divergence worth noting:** the TopoMesh version supports `use_triangle_area` weighting and applies a border penalty (`apply_border_penalty_to_vertex_quadrics`, default `use_border_constraints = true`); the BinaryTopology version does neither, so the two simplification stacks weight boundaries differently. | **JUSTIFIED (two mesh representations, no common iteration surface)** — but the plane-quadric kernel is a promotion candidate and the feature divergence should be documented | Add `quadric3_set_from_triangle(q, ax,ay,az, bx,by,bz, cx,cy,cz)` beside `Quadric3.js` and call it from both. Do **not** try to unify the iteration. Add a JSDoc note on the BinaryTopology version stating that area weighting and border penalties are intentionally absent (or add them). | **S** / low. |
+| 30 | LOW | **`read_frustum_corner` is `v3_copy_array` with an index instead of an offset.** | `core/geom/3d/frustum/read_frustum_corner.js:8` ⟷ `core/geom/vec3/v3_copy_array.js:8`. | Same three reads + three writes; `read_frustum_corner` computes `address = source_index * 3` first, `v3_copy_array` takes the offset directly. `v3_copy_array` additionally reads all three components before writing any (documented, so overlapping ranges are safe); `read_frustum_corner` does the same by accident of ordering but does not say so. | **UNJUSTIFIED (trivial)** | `read_frustum_corner(source, source_index, destination, destination_offset) { v3_copy_array(destination, destination_offset, source, source_index * 3); }` — keeps the public name and the index-flavoured signature. | **S** / low. |
+
+## Dismissed leads
+
+- **All `@deprecated` rename shims.** I sampled ~40 of the 7-line `import X from './x.js'; export const OldName = X;` files across `geom/3d/triangle`, `geom/3d/aabb`, `geom/3d/mat4`, `geom/3d/sphere`, `geom/2d/circle`, `geom/2d/line`, `geom/vec3`, `geom/packing/max-rect`, `geom/random`, `geom/3d/tetrahedra`, `geom/3d/topology/simplify`. Every one is a genuine alias with zero duplicated logic. This accounts for the large majority of "same concept, two files" impressions in this domain. Not duplication; correct library practice.
+- `v2_*` vs `v3_*`, `aabb2_*` vs `aabb3_*` scalar pairs (`v2_distance`/`v2_distance_sqr`, `line2_compute_segment_point_distance_sqr` ⟷ `line3_…`, `aabb2_distance_sqr_to_point` ⟷ `aabb3_unsigned_distance_sqr_to_point`, `aabb2_from_v2_buffer` ⟷ `aabb3_from_v3_array`, `v2_array_normalize` ⟷ `v3_normalize_array`) — dimensional specialisation, house-rule justified.
+- `m3_cm_compose_transform` ⟷ `m3_rm_compose_transform`, `v2_matrix3_cm_multiply` ⟷ `v2_matrix3_rm_multiply` — row-major/column-major variants, house-rule justified.
+- `m2_multiply` ⟷ `m2_multiply_transposed` ⟷ `m2_add` ⟷ `m2_sub_transposed`; `polynomial_add_into` ⟷ `polynomial_sub_into`; `aabb3_compute_distance_above_plane_max` ⟷ `_min`; `query_face_next_vertex` ⟷ `query_face_prev_vertex`; `aabb3_array_intersects_ray` ⟷ `aabb3_array_near_distance_to_intersection_ray_segment` — same *shape*, genuinely different arithmetic. No shareable kernel.
+- `v3_quaternion_apply` ⟷ `v3_quaternion_apply_inverse` — the inverse is NOT the forward with negated components; the sign pattern genuinely differs and the file documents why (`v3_quaternion_apply_inverse.js:11-18`). Justified.
+- `sh3_sample_by_direction` ⟷ `sh3_sample_irradiance_by_direction` — same coefficient layout, different convolution (radiance vs cosine-convolved irradiance) and different constants. Justified.
+- `bt_mesh_build_boundary_distance_field` ⟷ `bt_mesh_build_boundary_euclidean_distance_field` — geodesic (eikonal fast-marching) vs Euclidean clearance. Documented as different metrics; 150 lines vs 32. Not duplication.
+- `bt_mesh_is_closed` ⟷ `bt_mesh_is_manifold` — same 8-line "for every allocated edge, count faces" loop but the predicate is `!== 2` vs `> 2`; extraction would need a callback for a loop this small. Both already delegate the counting to `bt_mesh_count_edge_faces`. Justified.
+- `orient3d_robust` / `in_sphere3d_robust` / `tetrahedron_compute_signed_volume` / `TetrahedralMesh.js` "gather 4 indexed points from a flat array" boilerplate (flagged 4× by the mechanical pass) — different arities, and extracting it means either boxing into an out-array or a 12-parameter call. Justified index-expansion boilerplate.
+- `polygon2_clip_axis_halfplane` ⟷ `polygon2_clip_halfplane` — the axis version is the general one specialised to an axis-aligned edge, and its only callers are `engine/physics/narrowphase/box_box_manifold.js:511-529` and `box_triangle_contact.js:414-420`, i.e. per-contact-manifold. Genuine hot-loop specialisation. **One caveat worth a separate look:** the general version applies a `POINT_EPS = 1e-9` boundary slack and the axis version applies none, so the two disagree on vertices exactly on the clip line.
+- `PosedShape3D.support` / `#world_point_to_local` inlining `v3_quaternion_apply(_inverse)` — explicitly justified in-file with a measured reason (V8 will not inline at 9-arg call sites; hottest GJK call). Correct application of the hot-loop carve-out. (Contrast finding #9.)
+- `CapsuleShape3D.from` ⟷ `CylinderShape3D.from`, `compute_bounding_box`, `equals` — per-class typed constructor/accessor boilerplate. House-rule deliberate. (Only their `hash()` *mixer* is flagged, in finding #26.)
+- `Vector2/3/4` + `Quaternion` + `Color` `fromBinaryBuffer` / `toBinaryBuffer` / `toArray` / `set` / `constructor` families (flagged 6× by the mechanical pass) — per-class serialization and accessor boilerplate over different component counts. House-rule deliberate; unifying would need string-keyed or metaprogrammed field lists.
+- `bvh_query_leaves_ray` / `bvh_query_leaves_ray_segment` ⟷ `bvh2d_query_all_data_by_circle` — share only the generic explicit-stack tree-descent skeleton (`if (root === NULL_NODE) return 0; stack[stack_top] = root; …`); the node test and payload differ entirely. Not a shareable unit without a visitor.
+- `tetrahedron_compute_quality` / `tetrahedral_mesh_compute_tet_quality` / `compute_tetrahedron_quality` and the volume trio — already correctly factored as indexed primitive + mesh wrapper + deprecated alias. Exemplary, not duplication.
+- `simplify/quadratic/compute_edge_collapse_cost_quadratic.js`, `bt_mesh_compute_vertex_quadratics.js`, `shape3d_voxelize_to_grid.js`, `sh_compute_K.js`, `aabb3_near_distance_to_intersection_ray_segment.js` — all rename shims (the "quadratic"→"quadric" pass).
+- `core/geom/3d/sphere/harmonics/compute_legendre_polynomial.js` — a **0-byte file** dated 2024 shadowing `core/math/compute_legendre_polynomial.js`. Not duplication; dead empty file. Worth deleting but out of scope.
+- `aabb3_intersects_ray` ⟷ `aabb3_intersects_segment3` — both separating-axis tests, but one is an infinite ray with `diff*dir >= 0` early-outs and the other inflates the box by the segment half-extent. Different tests; only stylistic resemblance.
+- `Math.sqrt(x*x+y*y+z*z)` hits (78 global, ~32 in domain) — checked the concentrations. In `tri3_area`, `tri3_incenter`, `atlas_chart_parameterize_bff/lscm`, `polygon3_compute_normal`, `bt_mesh_face_find_path`: these are per-triangle / per-vertex / per-CG-iteration inner loops, and `v3_length` is itself `Math.sqrt(x*x+y*y+z*z)` with no guard, so calling it buys nothing but a call. Justified. The ones that *matter* are the normalize-with-a-policy sites, which are finding #10.
+- `inline_lerp` hits (129 global, 27 in domain) — every one I opened is either a dot product misclassified by the pattern (`(px-ax)*nx + …` in `Triangle3D.js:191`, `bt_mesh_segment_penetrates_surface.js:44`, `bt_mesh_face_find_path.js:342`) or a per-component 3-float interpolation in a hot mesh loop (`bt_edge_split.js:55-64`, `capsule_intersects_aabb3_closed.js:57-59`). No cold-code `lerp` bypasses found.
+- `computeHashArray` ⟷ `computeHashFloatArray` — different input domains (integers vs floats needing `computeHashFloat`). Out of domain anyway (`core/collection`).
+- `halton_sequence` ⟷ `hammersley_sequence_2d` — different algorithms (general-base closed form vs base-2 bit reversal). Only the 1-D `hammersley_sequence` is a duplicate (finding #12).
+- `mie/ri_*.js` repeated 8-line data blocks, `atlas_test_fixtures.js` ⟷ `RGB_LUT_*.js` — these are numeric data tables, not code.
+- `complex_mul` ⟷ `m3_multiply` / `m4_normal_matrix3`; `linear_to_sRGB` ⟷ `aabb2_union_array`; `BVHGeometry.makeCube` ⟷ `bt_edge_create.edge_link_disk`; `plane3_lerp` ⟷ `edge_link_disk`; `read_frustum_corner` ⟷ `mat4x4_transpose_copy_to_mat4x3` — MinHash noise. Structurally similar (flat arithmetic over indexed arrays), semantically unrelated.
+
+## Notes
+
+Why duplication accumulates here, structurally:
+
+1. **The "scalar arguments, caller-owned output buffer" convention has no composition story for *policies*.** Every primitive is `f(out, out_offset, …scalars)`, which is excellent for allocation-freedom and terrible for sharing decisions like "what do we do when the length is zero" or "how relative should the degeneracy epsilon be". So the arithmetic gets reused (`v3_length`, `v3_dot`, `tri3_area` are called everywhere) while the *policy* around it gets retyped — findings #6, #10, #11 are all the same failure. The fix is not more helpers; it is naming the policy (`v3_normalize_or_zero`, `solve_quadratic_relative`) so it has somewhere to live.
+
+2. **Dimensional forks start as copies and are never re-synced.** `BVH2D` and `StaticR2Tree` were each created by copying a 3D file and deleting a `z`. Because the copy is complete rather than layered, every later improvement to the 3D side (SAH rotation, linear allocation, the stack-seed fix) lands in one place only. Both forks are now measurably behind their originals. The house rule that 2D/3D scalar specialisation is justified is right for `v2_dot` vs `v3_dot`; it does not extend to 1100-line classes whose pointer machinery never touches a coordinate.
+
+3. **Private helpers get re-derived because the public one is not discoverable from where you are standing.** `bt_face_poke` wrote its own radial splice with a comment saying the function it wanted "is not exported" — while `bt_radial_loop_add` sat exported two directories up. `bt_mesh_face_find_path` wrote `vertex_distance` while `bt_vertex_distance_to_vertex` sat in the *same directory*. `MeshShape3D` wrote its own SDF gradient while six sibling shapes call the shared one from `./util/`. With ~1000 files in this domain and a naming scheme that encodes the *operand type* rather than the *operation*, grep-by-concept genuinely does not work.
+
+4. **The good news, which shapes the recommendations:** the domain is already unusually disciplined about the *renaming* half of this problem — hundreds of `@deprecated` re-export shims mean old names never became second implementations. The remaining duplication is almost entirely (a) pre-shim forks that predate that discipline, and (b) private helpers that should have been promoted. Both are addressable incrementally; none of the findings above except #1 requires touching more than a handful of files.

package/src/DUPLICATION_AUDIT_2026_08_07/B_core_data.md

@@ -0,0 +1,93 @@
+# Domain B — core (data structures, binary, graph, cache, parser, color)
+
+Scope: `meep/src/core/` excluding `core/geom` and `core/math` (2D counterparts under `core/geom` are
+cited where they are the *other half* of a fork whose primary copy lives in my domain).
+
+Quantification method: for the whole-file forks I computed the LCS over comment-stripped,
+whitespace-normalised code lines (`shared / A vs B`). Those numbers are reproducible and are what
+the "Evidence" column cites.
+
+## Findings
+
+| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
+|---|---|---|---|---|---|---|---|
+| 1 | CRITICAL | **Dynamic BVH tree is forked wholesale for 2D.** Node allocator, free-list, capacity growth, all 10 node-field accessors, `insert_leaf` (SAH branch-and-bound descent), `remove_leaf`, `bubble_up_refit`, `bubble_up_update`, `balance`, `traverse`, `collect_nodes_all`, `__move_node_links`, `swap_nodes` are the same code with `ELEMENT_WORD_COUNT` 10→8 and 6→4 AABB floats. | `core/bvh2/bvh3/BVH.js:73` `class BVH` ⟷ `core/geom/2d/bvh/BVH2D.js:70` `class BVH2D`. Method-for-method: `__grow_capacity` 217/155, `__set_capacity` 240/178, `allocate_node` 300/214, `release_node` 358/270, `node_is_leaf` 369/281, `node_get/set_{user_data,child1,child2,parent,height}` 381–471 / 293–383, `node_move_aabb` 528/434, `insert_leaf` 663/557, `bubble_up_refit` 775/675, `bubble_up_update` 803/705, `remove_leaf` 845/740, `balance_height` 902 ⟷ `balance` 792, `release_all` 1291/997, `traverse` 1302/1008, `collect_nodes_all` 1340/1046, `__move_node_links` 1357/1063, `swap_nodes` 1394/1100. Column constants re-exported: `BVH.js:10-13,21,27,47` ⟷ `BVH2D.js:11-14,22,28,48`. | **UNJUSTIFIED** | **521 of 576 BVH2D code lines are shared with BVH.js (90%).** Only 7 methods are truly dimension-specific (`allocate_node`'s ±INF init, `node_get_aabb`, `node_set_aabb`, `node_set_aabb_primitive`, `node_get_surface_area`, `node_get_combined_surface_area`, `node_set_combined_aabb`) ≈ 130 lines. **The fork has already cost a real divergence:** `BVH.bubble_up_update:806` uses the Box2D-v3 SAH rotation `balance_rotate` (added with a long design comment and `balance_rotate.spec.js`), while `BVH2D.bubble_up_update:713` still calls the Box2D-v2 height-AVL `balance`; and `BVH2D.bubble_up_refit:681` balances on every refit whereas `BVH.bubble_up_refit:775` deliberately does not. The 2D tree silently never received the SAH upgrade. Also missing in 2D: `data_buffer` get/set (serialisation round-trip, with a fix comment at `BVH.js:107-112`), `size` getter, `allocate_linear`, `node_assign_children{,_only}`. | Extract a shared `BvhTreeBase` holding the topology half (allocator/free-list/capacity/child-parent-height accessors/insert/remove/refit/balance/traverse/swap), and leave the ~7 AABB methods + `ELEMENT_WORD_COUNT`/column constants as the per-dimension typed subclass surface (`BVH extends BvhTreeBase`, `BVH2D extends BvhTreeBase`). Column offsets become `static` class fields on the subclass, not string keys — no magic. Keep both public classes and their exported constants (library surface). | **High effort / High risk.** ~500 lines move; two standing spec suites (`BVH.spec.js`, `balance_rotate.spec.js`) plus every physics broadphase consumer gate it. Do it in two steps: (a) port `balance_rotate` + the missing methods into BVH2D so the two are behaviourally aligned *first*, (b) then unify. Step (a) alone is worth doing even if (b) is rejected. |
+| 2 | HIGH | **Static Morton-ordered binary tree forked for 2D** — `build()` (bottom-up level assembly), `sort_morton()` (explicit-stack quicksort on Morton codes), `__swap_leaves()`, `initialize_structure()`, `setLeafCount()`, `setLeafData()`, `getLeafBlockAddress()`, `readLeafPayload()`, and a module-private `copy_box_zero_size()` are duplicated. | `core/bvh2/binary/2/BinaryUint32BVH.js:426` `build` ⟷ `core/geom/2d/r-tree/StaticR2Tree.js:313` `build` (token-identical, 289 tokens); `BinaryUint32BVH.js:336` `sort_morton` ⟷ `StaticR2Tree.js:210` `sort_morton`; `BinaryUint32BVH.js:411` `__swap_leaves` ⟷ `StaticR2Tree.js:296`; `BinaryUint32BVH.js:35` `copy_box_zero_size` ⟷ `StaticR2Tree.js:51` (same private helper, same name, two files). | **UNJUSTIFIED** | 113 of 205 StaticR2Tree code lines shared. **A bug caused by the copy is already documented in the tree:** `StaticR2Tree.js:346-347` carries the comment "a 2D box is 4 floats \[x0,y0,x1,y1\] (copying 6 would spill into the following node's data)" — i.e. the 3D `array_copy(..., 6)` was pasted into the 2D file and had to be fixed there. Exactly the "fix in one copy misses the other" class. | Same shape as #1: a `MortonLeafTreeBase` carrying `build`/`sort_morton`/`__swap_leaves`/`copy_box_zero_size` parameterised by two `static` sizes (`BINARY_NODE_SIZE`, `LEAF_NODE_SIZE`) and one abstract `combine_bounds(dst_off, a_off, b_off)` that the subclass points at `aabb3_array_combine` / `aabb2_union_array`. | Medium effort / Medium risk. `build()` is cold (construction only), so the one virtual call per node pair is irrelevant. `sort_morton` is warm but only at build. |
+| 3 | HIGH | **Traversal-order invariant duplicated 14× and drifted.** Every hand-written BVH2 traversal repeats the same stack skeleton *and* the comment "write to stack in reverse order, so that first child ends up being visited first" — but half of them push `child1` then `child2`, which visits **child2 first**, the opposite of what the comment claims and of what the generic implementation does. | Comment-matching (child2 pushed first): `core/bvh2/bvh3/query/bvh_query_user_data_generic.js:74-76`, `core/bvh2/bvh3/query/bvh_query_leaves_generic.js:65-67`, `bvh_query_user_data_ray.js:85-86`, `bvh_query_user_data_ray_segment.js:89-90`, `bvh_query_leaves_ray.js:79-80`, `bvh_query_leaves_ray_segment.js:83-84`. Comment present but **contradicted** (child1 pushed first): `bvh_collect_user_data.js:52-54`, `bvh_query_user_data_intersects_aabb.js:74-76`, `bvh_query_user_data_intersects_sphere.js:83-85`, `bvh_query_user_data_intersects_capsule.js:92-94`, `bvh_query_user_data_intersects_frustum.js:73-75`, `compute_tight_near_far_clipping_planes.js:182-184`. | **UNJUSTIFIED** | The result *ordering* of `bvh_query_user_data_intersects_sphere` is the reverse of `bvh_query_user_data_generic` + `BVHQueryIntersectsSphere` (`core/bvh2/bvh3/query/BVHQueryIntersectsSphere.js`), which computes the same set. Since this project has a standing determinism gate, "same set, different order" is a live hazard: switching a caller between the two paths silently reorders results. The generic path with `BVHQuery*` objects already exists and is fully implemented — the specialised files are hand-inlined copies of it. | Two separate actions, both cheap: (a) **normalise the push order in the 6 contradicting files** so all 14 agree with the documented invariant (pure ordering fix, spec-guarded); (b) for the *cold* consumers among them (`compute_tight_near_far_clipping_planes`, `bvh_collect_user_data`) delete the inlined skeleton and call `bvh_query_user_data_generic` with the corresponding `BVHQuery*` object. Leave the genuinely hot ray/AABB/sphere ones inlined — that inlining is legitimate. | (a) Low effort / Low risk. (b) Low effort / Low risk, cold code only. |
+| 4 | HIGH | **`Uint32Heap4` is a whole-file copy of `Uint32Heap`** with only the arity arithmetic changed. | `core/collection/heap/Uint32Heap.js:56` `class Uint32Heap` ⟷ `core/collection/heap/Uint32Heap4.js:59` `class Uint32Heap4`. Identical bodies: `constructor` 63/62, `__capacity_grow` 101/100, `compare` 131/130, `swap` 146/145, `size`/`capacity`/`top_id`/`is_empty`/`peek_score`/`peek_min` getters, `pop_min` 274/289, `find_index_by_id` 301/316, `contains`, `clear`, `remove`, `__remove_by_index` 356/371, `update_score`, `__update_score_by_index` 391/406, `get_score`, `insert_or_update`, `insert` 447/462. Differing: `HEAP_PARENT` (`>>1` vs `>>2`), `HEAP_LEFT`/`HEAP_RIGHT` vs `HEAP_FIRST_CHILD`, `heap_down` (2 vs 4 child compares), `heap_up`'s parent shift. | **UNJUSTIFIED** | **194 of 208 code lines shared (93%).** Only 4 of 22 members carry the 4-ary difference; the storage layout (packed float32 score + uint32 id, 8 bytes/slot) is byte-identical. `__remove_by_index` is a `pop_min`-based delete that depends on `HEAP_PARENT` — if that routine is ever fixed (it is O(depth) swaps rather than a sift), the fix lands in one file only. `Uint32Heap.js:57` still carries the Blender attribution comment that `Uint32Heap4` dropped. | Shared base `Uint32ScoreHeapBase` owning storage + all id-lookup/insert/remove/update machinery, with `heap_up`/`heap_down` (and only those) overridden per arity. Both are already using `this.compare`/`this.swap` method calls in their inner loops, so no new polymorphism is introduced on the hot path — the megamorphic risk argument does not apply here (`heap_up`/`heap_down` are the *leaf* of the call chain, not the caller). | Medium effort / Low risk. `Uint32Heap.spec.js` + `Uint32Heap4.spec.js` both exist and gate it. |
+| 5 | HIGH / PROMOTION | **No canonical `hash_combine` primitive.** The `(h << 5) - h + v` (== `h*31 + v`) step is written out inline at 15+ sites in `core/` alone (74 project-wide), with **three mutually incompatible normalisations** and a shared-but-broken `(array, offset, length)` contract. | `core/collection/array/computeHashArray.js:10` (`hash \|= 0`, signed), `core/math/hash/computeHashFloatArray.js:8` (`\|= 0`), `core/collection/array/computeStridedArrayHash.js:14` (`>>> 0`, unsigned), `core/collection/array/computeStridedIntegerArrayHash.js:9` (`>>> 0`), `core/primitives/strings/computeStringHash.js:10` (`>>> 0`), `core/collection/array/typed/uint8_array_hash.js:8`, `uint16_array_hash.js:8`, `uint32_array_hash.js:8` (**neither** — the accumulator escapes int32 into a double), `core/collection/list/List.js:967`, `core/collection/table/RowFirstTable.js:146`, `core/graph/csr/CSRGraph.js:281-292`, `core/model/BoundedValue.js:180-182`. `CSRGraph.js:275` explicitly documents it as "meep's standard `(h*31 + element)` convention" — a convention with no implementation. | **PROMOTION** | Three concrete consequences, all from re-derivation rather than reuse: (i) `uint32_array_hash` never truncates, so `((hash<<5)-hash) + channel_value` with `channel_value` near 2^32 produces a non-int32 double and the "32-bit rolling hash" property is lost — then `CSRGraph.hash():285` feeds that double straight back into another combine step; (ii) signed vs unsigned finalisation means the same byte sequence hashes differently depending on which family member you call; (iii) the shared `(array, offset, length)` signature is interpreted as `length = absolute end index` by all three `uintN_array_hash` (loops run `i < length`, not `i < offset + length`, so a non-zero `offset` under-reads), and `core/collection/array/typed/sparse_typed_array_hash.js:13` accepts `offset` and then **discards it**, passing a hard-coded `0` to `computeStridedArrayHash`. All current callers pass `offset === 0`, so nothing is visibly broken today — which is exactly why it will bite later. | Add `core/math/hash/hash_combine.js` — `export function hash_combine(hash, value) { return (((hash << 5) - hash) + value) | 0; }` — and a companion `hash_finalize(h) { return h >>> 0; }`. Rewrite the 8 array/string hash functions on top of it, and fix the `offset`/`length` contract to `count` semantics in the same change (with the three `.spec.js` files as the gate). Do **not** touch the inline uses inside genuinely hot scalar loops (`List.js:967`, `RowFirstTable.js:146`) beyond making them agree on finalisation. | Medium effort / **Medium risk** — changing finalisation changes hash *values*. Anything persisting a hash (serialised caches, `RowFirstTableSpec` keys) must be checked first. Safe subset: land `hash_combine` + fix the `offset` contract without changing any finalisation. |
+| 6 | MEDIUM | **`IndexedFloatMinHeap` is a copy of `IndexedFloatMaxHeap`** with the comparison operators flipped. | `core/collection/heap/IndexedFloatMaxHeap.js:37` `class IndexedFloatMaxHeap` ⟷ `core/collection/heap/IndexedFloatMinHeap.js:37` `class IndexedFloatMinHeap`. Identical: `constructor` 38/45, `clear` 65/72, `__swap_slots` 83/90, `__grow_capacity` 151/158, `insert` 167/174, `update` 212/219, `remove` 231/238, plus `size`/`has`/`get_score`/`peek`. Differing: 6 comparison operators inside `__sift_down` 108/115, `__sift_up` 137/144, `update` 224-228, `remove` 258-261; and `pop_max` 185 ⟷ `pop_min` 192. | **JUSTIFIED (documented, but the stated reason is weaker than claimed)** | **154 of 168 code lines shared (92%).** `IndexedFloatMinHeap.js:19-23` carries an explicit rationale: "deliberately a standalone copy rather than a subclass … extracting the order-specific `__sift_*` comparisons behind an overridable method would turn the hot-loop call sites polymorphic and defeat V8 inlining." That reasoning is correct *for the subclass approach they considered*, and per house rules I will not argue against a measured perf choice. Worth recording, though: the subclass approach is not the only one — a min-heap is a max-heap over negated scores, which needs zero new polymorphism (negate in `insert`/`update`, negate on read in `peek`/`get_score`). That would collapse ~150 lines with no call-site polymorphism at all, at the cost of `-0`/NaN edge semantics. | No change recommended without a measurement. If revisited, prefer the negation wrapper over a base class. | n/a |
+| 7 | MEDIUM | **Robin-Hood open-addressing machinery duplicated** between the single-key and pair-key uint32 maps: probe loop with displacement early-exit, steal-on-insert, backward-shift deletion, power-of-two capacity + `Math.clz32` shift, load-factor growth, rehash-on-resize. | `core/collection/Uint32Map.js:63` ctor / `:126` `get` / `:198` `__insert_no_grow` / `:249` `delete` / `:326` `__resize` ⟷ `core/collection/PairUint32Map.js:62` ctor / `:106` `get` / `:168` `__insert_no_grow` / `:224` `delete` / `:297` `__resize`. | **UNJUSTIFIED** | 100 of 178 code lines shared (the LCS is depressed by identifier renames — `slot2`/`k` vs `off`/`ka` — the *algorithm* is line-for-line the same). Differences are exactly two: slot stride (2 vs 3 words) and the hash (`Math.imul(k, FIB)` vs `imul(ka, MIX_A) ^ imul(kb+1, MIX_B)`). Everything invariant-bearing — the `dist > slot_dist` early-exit, the `slot_dist < dist` steal, the `next_dist === 0` stop condition in backward-shift delete — is duplicated verbatim. These are the classic hard-to-get-right parts of Robin Hood; a fix to one will not reach the other. Note `PairUint32Map` already routes its hash through a `this.__hash(...)` **method call** inside every probe iteration, so the "monomorphic hot loop" argument that justifies #6 does not apply here. | Shared `Uint32RobinHoodMapBase` owning capacity/mask/shift/threshold/size/`__data`, the probe skeleton, steal, backward-shift delete and resize, parameterised by a `static SLOT_STRIDE` and an abstract `__hash(...)` / `__slot_matches(off, …)` pair. Both public classes and their `*_ABSENT` constants stay (library surface). | Medium effort / Medium risk. `Uint32Map.spec.js` and `PairUint32Map.spec.js` both exist. |
+| 8 | MEDIUM | **Four quicksort implementations** sharing one explicit-stack partition skeleton; two of them are already fully expressible by a third. | `core/collection/array/array_sort_quick.js:18` `array_sort_quick(data, score_function, ctx, start, end, swap_operator, swap_ctx)`; `core/collection/array/array_quick_sort_by_comparator.js:11`; `core/collection/array/array_quick_sort_by_lookup_map.js:16`; `core/collection/array/array_quick_sort_by_lookup_uint.js:15`. A fifth copy of the same skeleton is inlined at `core/bvh2/binary/2/BinaryUint32BVH.js:336` `sort_morton` and a sixth at `core/geom/2d/r-tree/StaticR2Tree.js:210`. | **UNJUSTIFIED** (for the two lookup variants) | `array_quick_sort_by_lookup_map` and `array_quick_sort_by_lookup_uint` differ from each other by **one token** (`lookup.get(x)` vs `lookup[x]`) across 35 lines, and both are exactly `array_sort_quick(data, t => lookup.get(t), …)` / `array_sort_quick(data, t => lookup[t], …)`. `array_sort_quick` already takes a score function and a context, so no closure allocation is needed. A second, sharper problem: the four copies do **not** agree on stack ownership — `array_sort_quick.js:4` and `array_quick_sort_by_comparator.js:1` each hold a *private* `const stack = []`, while the two lookup variants (`:3`) alias the **globally shared** `SCRATCH_UINT32_TRAVERSAL_STACK`, which is simultaneously the BVH traversal stack (17 other importers). Sorting from inside a BVH query callback silently corrupts that traversal; the private-array copies have no such hazard. The invariant is duplicated three ways and reconciled nowhere. | Delete the bodies of the two lookup variants and implement them as one-line delegations to `array_sort_quick` (keep both exports — library surface). Separately, decide the stack-ownership rule once: either all sorts own a private stack, or all document the shared-stack precondition the way `bvh_query_user_data_generic.js:9-14` does. | Low effort / Low risk. `array_quick_sort_by_lookup_map.spec.js`, `..._uint.spec.js`, `array_sort_quick.spec.js` all exist. |
+| 9 | MEDIUM | **Intrusive MRU doubly-linked-list splice duplicated** between the two cache implementations. | `core/cache/Cache.js:149` `__promote(element)` ⟷ `core/cache/wtinylfu/CacheRegionWTinylfu.js:78` `touch(element)` (token-identical, 68 tokens). Also `core/cache/Cache.js:481` `__removeElement` ⟷ `core/cache/wtinylfu/CacheRegionWTinylfu.js:112` `__removeElement` — same head/tail fix-up + `element.unlink()`. | **UNJUSTIFIED** | The head/tail-pointer maintenance around `CacheElement.unlink()` (`core/cache/CacheElement.js`) is the whole of both routines, and it is the part with the invariant (a node that *is* `__first` must not be re-linked; a node that *is* `__last` must move the tail back before unlinking). `CacheElementWTinylfu` **already** extends `CacheElement`, so the element type is shared — only the list head/tail holder was re-derived. | Promote the head/tail pair into a small `IntrusiveMruList` (fields `#first`/`#last`, methods `add`, `promote`, `detach`) in `core/cache/`, and have both `Cache` and `CacheRegionWTinylfu` hold one. `CacheRegionWTinylfu` keeps its weight accounting; `Cache` keeps its `data` map and signals. | Low effort / Low risk. `Cache.spec.js`, `CacheRegionWTinylfu.spec.js`, `CacheWTinylfu.fuzz.spec.js` all exist. |
+| 10 | MEDIUM | **BVH8 geometry validator duplicated** for the direct vs pool-indirect triangle addressing conventions. | `core/bvh8/bvh8_geometry_validate.js:29` `bvh8_geometry_validate_bounds` ⟷ `core/bvh8/bvh8_geometry_validate_indirect.js:29` `bvh8_geometry_validate_bounds_indirect`; plus a byte-identical private `aabb3_round_to_float32` at `bvh8_geometry_validate.js:13` ⟷ `bvh8_geometry_validate_indirect.js:13`. | **UNJUSTIFIED** | **76 of 83 code lines shared (92%).** The entire difference in the bounds walk is one line: `const triangle_index = triangle_offset + base_index_triangle + j;` vs `= pool[triangle_offset + base_index_triangle + j];`. This is a *validator* — cold, debug-only code, run once after a build — so there is no perf argument for inlining. The duplicated `aabb3_round_to_float32` helper is pure and belongs next to the other `aabb3_*` helpers. | Move `aabb3_round_to_float32` to a shared module. For the walk, pass the resolved index array explicitly: give the direct caller an identity `Uint32Array` view or, better, have `bvh8_geometry_validate` build the trivial identity pool once and call the single indirect implementation. No sentinel parameter, uniform control flow. | Low effort / Low risk. Cold path, both are already `throw`-on-violation. |
+| 11 | MEDIUM | **`ebvh_geometry_query_any_triangle_ray` is a copy of `ebvh_geometry_query_nearest_triangle_ray`** with the "keep best" bookkeeping replaced by an early return. | `core/bvh2/bvh3/ebvh_geometry_query_any_triangle_ray.js:30` ⟷ `core/bvh2/bvh3/ebvh_geometry_query_nearest_triangle_ray.js:25`. | **JUSTIFIED (hot path, and the algorithms genuinely differ)** | 70 of 80 code lines shared, but the 10 that differ are the algorithm: `any` prunes on a *fixed* `max_distance_sqr` and unwinds the stack on first hit (`stack.pointer = stack_top; return true`), `nearest` prunes on a *shrinking* `best_t * best_t` and must drain the whole stack. Occlusion/shadow rays are the hottest query in the path tracer; merging them behind a flag would put a branch in the innermost loop and would also require the "unwind and return" to become a sentinel-driven exit — a direct house-rule violation. Recorded so a future reader does not re-flag it. | No change. Consider a cross-reference comment on `..._nearest_...` mirroring the one already on `..._any_...:11-15`. | n/a |
+| 12 | MEDIUM | **Graph-layout helpers duplicated between the box and circle layouters**, including a verbatim topological-layer peel. | `core/graph/layout/box/BoxLayouter.js:361` `buildLayer` (inside `doLayerLayout:355`) ⟷ `core/graph/layout/CircleLayout.js:25` `buildLayer` (inside `doLayerLayout:19`) — token-identical, 116 tokens. `BoxLayouter.js:301` `applyClusteredLayoutStep` ⟷ `CircleLayout.js:88` `applyClusteredLayoutStep`. `BoxLayouter.js:431` `centerAABB2CollectionOn` ⟷ `CircleLayout.js:250` `centerCircleCollectionOn`. | **UNJUSTIFIED** (for `buildLayer`) / **PROMOTION** | `buildLayer` touches no geometry at all — it peels nodes whose `connections[].source` are all already laid out. It is pure graph topology and identical in both files. `applyClusteredLayoutStep` has already diverged: the cluster-translation loop honours `if (box.locked) return;` at `CircleLayout.js:135-138` but **not** at `BoxLayouter.js:341-347`, so locked boxes are moved by cluster gravity in the box layouter and not in the circle one. Same divergence in `centerCircleCollectionOn:256-259` vs `centerAABB2CollectionOn:431`. Only one of the two behaviours can be right. | Hoist `buildLayer` to `core/graph/layout/graph_peel_topological_layer.js` (takes `nodes[]`, mutates/returns the layer) and call it from both `doLayerLayout`s. Decide the `locked` semantics once and apply it to both `applyClusteredLayoutStep` copies — do that even if the functions stay separate. | Low effort / Low risk for `buildLayer`. The `locked` reconciliation is a behaviour decision, not a refactor. |
+| 13 | MEDIUM | **Ray vs ray-segment BVH queries duplicated** — the traversal is byte-identical, only the AABB predicate and two extra parameters differ. | `core/bvh2/bvh3/query/bvh_query_leaves_ray.js:27` ⟷ `bvh_query_leaves_ray_segment.js:30`; `bvh_query_user_data_ray.js:26` ⟷ `bvh_query_user_data_ray_segment.js:29` (39 of 44 code lines shared). | **JUSTIFIED (hot path) — but flag the API asymmetry** | These are the innermost traversals of the path tracer and the physics raycaster; the inlined `float32[address + n]` reads and the absence of a predicate call are the point. However the copies expose an inconsistency worth fixing on its own merits: `bvh_query_leaves_ray.js:65-69` passes **raw** direction components to `aabb3_intersects_ray`, while `bvh_query_leaves_ray_segment.js:68-70` passes **reciprocals** (`1 / direction_x`, …) to `aabb3_intersects_ray_segment` — and computes those three divisions *per node*, inside the loop, instead of once before it. | Leave the duplication. Hoist the three reciprocals out of the traversal loop in both `*_ray_segment` files, and align the two `aabb3_intersects_ray*` signatures on one convention (both raw or both reciprocal). | Low effort / Low risk. |
+| 14 | MEDIUM | **Four colour-adjustment operators are the same 20-line body** (`assert` pair → early-return on `amount === 0` → `new Color()` → `linear_srgb_to_okhsv` → scale one OkHSV channel → `okhsv_to_linear_srgb`). | `core/color/operations/color_lighten.js:15`, `color_darken.js:15`, `color_saturate.js:15`, `color_desaturate.js:15` — each also carries its own module-static `const hsv = [0,0,0]` scratch. | **UNJUSTIFIED** | The only difference is the channel index (`hsv[2]` vs `hsv[1]`) and the factor. And the factor has already drifted: `color_darken.js:29` uses `clamp01(hsv[2] * clamp01(1 - amount))` (inner clamp on the factor) while `color_desaturate.js:29` uses `clamp01(hsv[1] * (1 - amount))` (no inner clamp). They happen to agree numerically because of the outer `clamp01`, which is luck, not design — and it means a reader cannot tell which form is intended. Note also all four call `okhsv_to_linear_srgb(r, ...hsv)`, spreading an array on every call (an allocation in what is otherwise carefully allocation-free colour code). | One non-exported `color_scale_okhsv_channel(input, channel, factor)` in `core/color/operations/`, with the four public functions as three-line typed wrappers. Public API and file layout unchanged (library surface preserved); the channel index is a numeric constant, not a string key, so no magic-registry rule is violated. Replace the four `...hsv` spreads with explicit `hsv[0], hsv[1], hsv[2]` while in there. | Low effort / Low risk. |
+| 15 | LOW | `bvh_query_user_data_nearest_to_point_filtered` is `bvh_query_user_data_nearest_to_point` with a predicate on the leaf-accept step. | `core/bvh2/bvh3/query/bvh_query_user_data_nearest_to_point.js:16` ⟷ `core/bvh2/bvh3/query/bvh_query_user_data_nearest_to_point_filtered.js:28`. | **JUSTIFIED (avoiding an optional-callback sentinel)** | ~55 lines duplicated for one `if (filter(user_data))`. Unifying would mean an optional `filter` parameter that defaults to "accept everything" — precisely the `x === null ? auto : override` shape the codebase rejects, and it would add an indirect call per accepted leaf on a branch-and-bound search. The `_filtered` variant already documents the shared-stack re-entrancy contract properly (`:14-17`), which the unfiltered one does not. | No merge. Copy the re-entrancy/`SCRATCH_UINT32_TRAVERSAL_STACK` doc block onto the unfiltered variant so the contract is stated in both. | Trivial / none. |
+| 16 | LOW | Decimal and hex integer token readers duplicate a 45-line `switch` over digit characters. | `core/parser/simple/readHexToken.js:13` ⟷ `core/parser/simple/readUnsignedIntegerToken.js:13`. | **UNJUSTIFIED** | Cases `'0'`–`'9'` are identical in both (20 lines); hex adds `a-f`/`A-F` and swaps `value * 10` for `value * 16`. Cold code (a config/expression parser, not a hot loop). The copy has already produced dead code, called out in-tree: `readHexToken.js:96-100` notes the per-character `i === cursor` guard inherited from the decimal version "is dead code because i starts at cursor + 2" — the guard is still there in both. | One `char_to_digit(char)` returning `-1` for non-digits (0–15 for hex chars), used by both readers with a `radix` bound check. Removes the dead guard as a side effect. | Low effort / Low risk. Both have callers via `core/parser/simple`. |
+| 17 | LOW | `insert_after` / `insert_before` and `insert_after_or_replace` / `insert_before_or_replace` — four near-identical string splice helpers; the `_or_replace` pair re-implements the plain pair's body rather than calling it. | `core/primitives/strings/insert_after.js:8`, `insert_before.js:8`, `insert_after_or_replace.js:9`, `insert_before_or_replace.js:9`. | **UNJUSTIFIED (marginal)** | The four differ only in whether the insertion offset is `i` or `i + term.length`. All four are cold (shader-source patching). The `_or_replace` variants can't literally call the plain ones because they must distinguish "not found" from "found" without the `console.warn` side effect — but a shared `splice_at(source, position, value)` would still remove the duplicated `slice`/`+`/`slice` idiom. | One private `string_splice(source, position, value)`; the four public exports become 3–5 lines each. Keep all four exports. | Trivial / none. |
+| 18 | LOW | `futureTask` and `promiseTask` build the same `Task` from the same `resolved`/`rejected`/`error` closure trio. | `core/process/task/util/futureTask.js:10` ⟷ `core/process/task/util/promiseTask.js:10`. | **JUSTIFIED (barely) — uniform control flow** | ~35 lines shared. `futureTask` differs by a `typeof future.resolve !== 'function'` guard and by calling `future.resolve()` at the top of every `cycle()` (it *pumps* the future, `promiseTask` only waits). Factoring that out needs an optional pre-cycle hook — a sentinel parameter. Leave it. | No change. | n/a |
+| 19 | LOW | `MEASUREMENT_UNITS_SI` and `UNIT_DIMENSION_MAPPING` are the **same seven `NamedUnit` values in the same order**, exported twice from two files with the same seven imports. | `core/science/units/MEASUREMENT_UNITS_SI.js:20` ⟷ `core/science/units/UNIT_DIMENSION_MAPPING.js:21`. | **UNJUSTIFIED** | Both are `[METER, KILOGRAM, SECOND, AMPERE, KELVIN, MOLE, CANDELA]`, both are consumed by `unit_matrix_to_string` / `format_quantity`, and both encode the invariant "array index === `UnitDimension` ordinal". If the dimension order ever changes, one of the two will be missed and the other will silently mis-label every quantity. The JSDoc on each explains a *usage* difference, not a *value* difference. | Keep both exports (library surface) but make one derive from the other: `export const MEASUREMENT_UNITS_SI = UNIT_DIMENSION_MAPPING;` with the existing doc retained, so the ordering invariant has exactly one definition. | Trivial / Low risk. `MEASUREMENT_UNITS.spec.js` and `UNIT_DIMENSION_MAPPING.spec.js` both exist. |
+| 20 | LOW | Two connected-components implementations, one of them quadratic. | `core/graph/layout/computeDisconnectedSubGraphs.js:6` ⟷ `core/graph/graph_compute_disconnected_clusters.js:6`. | **UNJUSTIFIED (already acknowledged in-tree)** | Same BFS-over-a-worklist algorithm. `computeDisconnectedSubGraphs.js:2` already carries `NOTE: use graph_compute_disconnected_clusters instead where possible`, and it uses `unexplored.indexOf(node)` + `splice` inside the inner loop — O(n²) — where the other uses a `Set`. It has two live callers (`BoxLayouter.js:303`, `CircleLayout.js:90`) that pass `{connections: Connection[]}` node objects rather than a `Graph`. | Give `graph_compute_disconnected_clusters` a sibling that takes an edge-accessor over plain node objects, or make the two layouters build a `Graph`. Failing that, at minimum swap the `indexOf`/`splice` for a `Set` so the two implementations have the same complexity. | Low effort / Low risk. Layout output ordering may shift — check `CircleLayout.spec.js`. |
+| 21 | LOW | Inline 2-D length/distance re-derived next to an imported primitive that already does it. | `core/graph/layout/CircleLayout.js:288` (`Math.sqrt(dX*dX + dY*dY)` — this file already imports `v2_distance` at `:5`), `CircleLayout.js:745`, `CircleLayout.js:880`, `core/graph/layout/box/position_box_next_to_box.js:37`. Related: `BoxLayouter.js:32` `evaluateEdgeCost` uses `Vector2._distance(...)` while `CircleLayout.js:344` `evaluateEdgeCost` uses `v2_distance(...)` for the identical computation. | **UNJUSTIFIED (cold code)** | Layout runs once per graph edit, not per frame, so there is no inlining justification. Two different primitives (`Vector2._distance` and `v2_distance`) are used for the same operation in two files that otherwise mirror each other. | Use `v2_length`/`v2_distance` at the four inline sites, and pick one of the two distance primitives for both `evaluateEdgeCost` copies. | Trivial / none. |
+
+## Dismissed leads
+
+- **`core/debug/matchers/matchers.js` vs `core/process/matcher/{not,isNull,isDefined}.js`** — name collision only. `core/debug` is a Hamcrest-style DSL returning `Matcher` *objects* (`new IsNot(matcher)`); `core/process/matcher` returns bare predicate *functions* (`v => !m(v)`). Different abstractions, different consumers.
+- **`core/parser/simple/readReferenceToken.js` vs `view/tooltip/gml/parser/readReferenceToken.js`** — name collision only. One parses dotted identifier chains (`a.b.c`), the other parses `[tag: k=v, k=v]` tooltip references. Zero shared code.
+- **`core/parser/simple/DataType.js` vs `core/model/node-graph/type/DataType.js`** — name collision only. One is a 5-entry frozen string enum, the other a class with `id`/`name`/`hash`/`equals`/`toJSON`.
+- **`core/graph/layout/Connection.js` vs `core/model/node-graph/Connection.js`** — name collision only. One is `{source, target, points: Vector2[]}` with a polyline `length()`; the other is a node-graph port link with `id`, `validate()`, `PortDirection`.
+- **`core/binary/data_view/DataType2DataViewReaders.js` vs `...Writers.js`** — two 10-entry lookup tables mapping `BinaryDataType` → `"getUint8"` / `"setUint8"`. Deriving one from the other means string concatenation on method names — exactly the magic-string pattern the house rules reject. Typed tables are correct here.
+- **`core/binary/split_by_2.js` vs `split_by_3.js`** — shape-identical bit-spreading, but the masks and shift counts encode genuinely different Morton interleavings (2-way vs 3-way). Not duplication.
+- **`core/color/sRGB/linear_to_sRGB.js` vs `sRGB_to_linear.js`** — inverse transfer functions with different breakpoints (0.0031308 / 0.04045), different constants and different exponents (0.4166… / 2.4). Only the 3-channel wrapper shape matches, and that's 3 lines.
+- **`core/collection/set/compute_set_difference.js` vs `compute_set_intersection.js`** — different set operations. (Separately noted, out of scope for this audit: `compute_set_difference` computes the *symmetric* difference despite its name — a naming defect, not duplication.)
+- **`core/collection/array/binarySearchHighIndex.js` vs `binarySearchLowIndex.js`** — different return contracts (ceiling/insertion point vs floor index, `-1` on underflow). The bodies diverge in the branch structure, not just a comparator.
+- **`core/collection/Uint32MinHeap.js` vs `core/collection/heap/Uint32Heap.js`** — different payloads (bare uint32 values vs id+float32 score pairs). `Uint32MinHeap.js:1-18` documents that it *is* the result of a completed promotion (two byte-identical private copies in physics were merged into it). Already fixed.
+- **`core/collection/map/HashMap.js` vs `core/collection/Uint32Map.js`** — separate-chaining map over arbitrary keys with user-supplied hash/equality vs typed-array open addressing over uint32. No shared machinery.
+- **`setFlag`/`clearFlag`/`writeFlag` repeated across 30 files** (`core/events/signal/Signal.js:59`, `SignalHandler.js:60`, +28 in `engine/`) — three-line per-class bit accessors. Extracting them would be a mixin (magic) or would make call sites *more* verbose. Justified boilerplate.
+- **Repeated `const edge_addresses = graph.edge_addresses; …` unpacking across `core/graph/metis/native/`** (`compute_2way_params.js:17-24`, `fm_2way.js:30-37`, `grow_bisection.js:25-31`, `create_coarse_graph.js:27-32`, `match_shem.js:54-58`, `initial_kway_bfs.js:36-42`, `refine/compute_kway_params.js`) — hoisting property loads out of hot loops. This is the intended idiom, not duplication.
+- **`core/model/Observed{Integer,String,Boolean,Enum,Value}.js`** — per-type `set`/`setSilent`/`onChanged` boilerplate with type-specific asserts. Shape duplication only; explicitly protected by the "typed over magic" rule.
+- **`core/json/resolvePath.js` vs `resolvePathByArray.js`** — already correct reuse; `resolvePath` splits and delegates.
+- **`core/cache/CacheElement.js` vs `core/cache/wtinylfu/CacheElementWTinylfu.js`** — already correct reuse via `extends`.
+- **30 `binary_search_inline` pattern hits from the brief** — false positive. All but one are quicksort pivot midpoints (`(left + right) >> 1`) or unrelated bit shifts (`header >>> 1`, `triangle_mask >>>= 1`). The only real binary search in the list, `binarySearchHighIndex.js:23`, *is* the canonical primitive and has 8 external callers. Nothing bypasses it.
+- **`Color.fromBinaryBuffer` / `Quaternion.fromBinaryBuffer` / `Vector4.fromBinaryBuffer` (49-token identical group)** — per-type binary adapters reading N float32s. Shape, not logic; deliberate typed serialization surface.
+- **`core/bvh8/bvh8_convert_to_dot.js:110` vs `engine/intelligence/behavior/behavior_to_dot.js:240`** — both emit Graphviz `digraph{…}` wrappers; the ~6 shared lines are the DOT preamble/epilogue. Below the noise floor.
+
+## Notes
+
+Structural reasons duplication concentrates in this domain:
+
+1. **The 2D/3D split is implemented by forking files, not by parameterising a dimension.** Three separate
+   forks exist along exactly this seam — `BVH` ⟷ `BVH2D` (finding #1), `BinaryUint32BVH` ⟷ `StaticR2Tree`
+   (#2), and the query families that hang off each. In every case the *spatial* code is ~15% of the file
+   and the *topological* code (allocator, free list, parent/child links, stack traversal, rebalancing) is
+   ~85%, yet the fork is drawn around the whole class. Both forks have already produced measurable
+   divergence: the SAH rotation upgrade reached only the 3D tree, and an AABB word-count bug had to be
+   fixed independently in the 2D one.
+
+2. **Typed-array specialisation is used as a reason to fork the whole class rather than the storage.**
+   `Uint32Heap`/`Uint32Heap4` and `IndexedFloatMaxHeap`/`IndexedFloatMinHeap` are both 90%+ identical, and
+   in both cases the specialised part is 2–4 methods. The `IndexedFloat*` pair at least *documents* the
+   decision (`IndexedFloatMinHeap.js:19-23`); the `Uint32Heap4` pair does not, and inherits an
+   `__remove_by_index` implementation whose correctness depends on the very constant that was changed.
+
+3. **Hot-path inlining is applied without a rule for when it stops.** The BVH query directory contains a
+   complete generic implementation (`bvh_query_user_data_generic` + four `BVHQuery*` predicate classes)
+   *and* eight hand-inlined specialisations of it. Inlining the ray and sphere queries is defensible;
+   inlining `compute_tight_near_far_clipping_planes` and `bvh_collect_user_data` is not, and it is in
+   exactly those cold copies that the child-visit-order invariant silently inverted (finding #3).
+
+4. **There is a documented hash convention with no implementation.** `CSRGraph.js:275` names
+   "meep's standard `(h*31 + element)` convention", but there is no `hash_combine` in `core/math/hash/`
+   (which does contain `murmur3_32`, `squirrel3`, `lowbias32`). Fifteen sites therefore re-type the
+   expression, and the three variants of the *finalisation* step — `| 0`, `>>> 0`, and nothing at all —
+   are the direct consequence. The same re-derivation produced three copies of an `(array, offset, length)`
+   signature that no member actually honours.
+
+5. **Shared mutable scratch state is imported ad hoc.** `SCRATCH_UINT32_TRAVERSAL_STACK` has 17 importers
+   spanning BVH traversal, R-tree traversal, *and* two array sorts. The BVH consumers document the
+   no-throw/no-reentrancy precondition; the sorts do not, and two sibling sorts use private arrays instead.
+   Duplicating a primitive is one failure mode; duplicating a *precondition* across files that never
+   reference each other is the harder one to detect.

package/src/DUPLICATION_AUDIT_2026_08_07/C_gfx_render.md

@@ -0,0 +1,80 @@
+# Domain C — engine/graphics (render, material, texture, geometry, shaders)
+
+All paths are relative to `H:/git/moh/app/src/mir-engine/meep/src/`.
+Every finding below was verified by opening both (all) sites.
+
+## Findings
+
+| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
+|---|---|---|---|---|---|---|---|
+| 1 | HIGH | Triangle-vertex fetch from a possibly-normalized, possibly-implicitly-indexed vertex buffer (~45 lines: index resolve → 3 addresses → 9 reads → 9 denormalize + 6 asserts) | `engine/graphics/geometry/buffered/query/bvh32_geometry_nearest.js:151-201` (leaf block of `bvh32_geometry_nearest`) — `.../bvh32_geometry_raycast.js:59-109` (`bvh32_geometry_raycast`) — `.../bvh32_geometry_overlap_clipping_volume.js:46-96` (`bvh32_geometry_overlap_clipping_volume`) | Character-identical apart from the local name of the triangle index. Same assert strings verbatim (`'triangle index overflow, possibly geometry changed but tree was not rebuilt?'`, `'a-vertex overflow'`). Any change to the interleaved/normalized contract must be made in 3 places. | UNJUSTIFIED | New `engine/graphics/geometry/buffered/read_triangle_vertices.js` — `read_triangle_vertices(out9, vertices, vertex_offset, vertex_stride, vertex_data_normalized, indices, triangle_index)` writing into a module-static `Float64Array(9)`. Asserts stay (free in prod). | M / low — 3 mechanical call-site rewrites, covered by `bvh32_geometry_nearest.spec.js` |
+| 2 | HIGH | Nearest-point-on-mesh BVH query: ordered child descent by `aabb3_unsigned_distance_sqr_to_point` + leaf `tri3_closest_point_barycentric` → barycentric reconstruct → `v3_distance_sqr` → write `SurfacePoint3` + `tri3_compute_normal` | `engine/graphics/geometry/buffered/query/bvh32_geometry_nearest.js:37-247` — `engine/graphics/geometry/buffered/query/query_bvh_geometry_nearest.js:35-208` | Two whole implementations of the same algorithm against two BVH layouts (`BinaryUint32BVH` implicit-index vs `BVH` pointer nodes). Child-ordering block (`bvh32:110-130` vs `query:114-134`) and the entire leaf body (`bvh32:203-242` vs `query:164-203`) are token-identical. `query_bvh_geometry_nearest` has exactly one caller (`engine/graphics/sh3/path_tracer/BufferedGeometryBVH.js:286`). | UNJUSTIFIED (traversal genuinely differs; the leaf work does not) | Extract the leaf into `engine/graphics/geometry/buffered/query/nearest_point_on_triangle_record.js` — `(result, triangle_index, best_distance_sqr, x,y,z, ax..cz) → number` returning the new best distance (or `-1` when not improved); both traversals call it. | M / medium — behaviour-preserving, both have specs |
+| 3 | HIGH | Material-texture coalescing loop over `TextureAttachmentsByMaterialType` + identically-configured `Cache<Texture,Texture>` | `engine/graphics/material/manager/compilers/CoalesceTextures.js:18-22` + `:25-69` (`transform`) — `engine/asset/loaders/material/StaticMaterialCache.js:27-31` + `:48-89` (`acquire`) | Lines 48-89 of `StaticMaterialCache.acquire` are byte-identical to lines 26-66 of `CoalesceTextures.transform`, comment-for-comment (`//check cache`, `//console.log('Re-using texture', existingTexture);`, `//texture was not in cache, cache it`). **The extracted helper already exists** — `engine/asset/loaders/material/traverseMaterialTextures.js:9-37` is exactly this traversal — and neither caller uses it. | UNJUSTIFIED | Give `engine/asset/loaders/material/` a `TextureCoalescer` class holding the `Cache` and a `coalesce(material)` method built on `traverseMaterialTextures`; `CoalesceTextures` (transformer) and `StaticMaterialCache` both own one. | S / low |
+| 4 | HIGH | "Marked material transform" protocol: own-property marker check → throw on foreign transformer → clone → `composeCompile` → stamp marker | `engine/graphics/render/forward_plus/plugin/MaterialTransformer.js:91-124` (`transform`) — `engine/graphics/sh3/gi/material/MaterialTransformer.js:294-321` (`transform`) | Same 5-step protocol, same error string verbatim (`'The material is already transformed, but is associated with a different transformer instance'`). **The copy has already diverged into a defect**: `sh3/gi` line 311 is `result.clone();` — the clone's return value is discarded, so it mutates the *caller's* material; it also omits the `source.isShaderMaterial` uniforms/defines copy that the FP version does at `:110-114`. `AbstractMaterialTransformer` (`engine/graphics/material/manager/AbstractMaterialTransformer.js`) is an empty 10-line stub that could own this. | UNJUSTIFIED | Move the protocol into `AbstractMaterialTransformer` as a final `transform(source)` that calls an abstract `#build(source)`; both concrete transformers implement only the shader-patching hook. Also fixes the `sh3/gi` clone bug. | M / medium — touches the Forward+ contract, but `MaterialManager.spec.js` covers the chain |
+| 5 | HIGH | Iterative (stack-based) quicksort partition loop | `engine/graphics/render/forward_plus/sort_decal_data.js:47-102` (`sort_decal_data`) — `core/collection/array/array_quick_sort_by_comparator.js:11-75` — `core/collection/array/array_sort_quick.js:17-…` — `view/minimap/gl/MinimapMarkersGL.js:141-198` (`__sortByZIndex`) | Identical stack/pivot/partition/recursion skeleton (`stackPointer -= 2`, `(left + right) >> 1`, same `/* partition */` and `/* recursion */` comments). **The copy has diverged into a hazard**: both core versions capture the pivot *value* first (`const pivot = data[pivotIndex]`), while `sort_decal_data.js:70,74` re-reads `lookup[pivotIndex]` through `compare_decals` on every comparison — and `lookup[pivotIndex]` is itself swapped during partitioning, so the pivot changes mid-partition. `array_sort_quick` already supports a custom `swap_operator`, which is precisely what both copies needed. | UNJUSTIFIED | `sort_decal_data` should call `core/collection/array/array_quick_sort_by_comparator.js` with a bound comparator (and, if the lookup indirection must stay, extend that primitive with the `swap_operator` parameter `array_sort_quick` already has). | S / medium — fixes a latent ordering bug; decal draw order is visible |
+| 6 | MEDIUM | Frustum corner extraction: which triple of planes produces which of the 8 corners, and in what output order | `engine/graphics/render/forward_plus/computeFrustumCorners.js:9-68` (`computeFrustumCorners`, three.js `Plane[]`) — `core/geom/3d/frustum/frustum_compute_corners.js:13-…` (`frustum_compute_corners`, flat array) | Same 8-entry corner table, same output stride, only the plane accessor differs. The vendor→flat converter already exists (`core/geom/3d/frustum/frustum3_planes_to_flat_from_three.js`) and **`LightManager.js` already imports it at line 28** while also importing `computeFrustumCorners` at line 48. The JSDoc even points at the twin (`computeFrustumCorners.js:5`). Violates "confine vendor imports to boundaries". | UNJUSTIFIED | Delete the body: `computeFrustumCorners` becomes `frustum3_planes_to_flat_from_three(planes, scratch)` + `frustum_compute_corners(result, 0, scratch, 0)`. Keep the export (public surface). | S / low — `frustum_compute_corners.spec.js` exists |
+| 7 | MEDIUM | GPU internal-format string, hand-written instead of derived | 22 literal sites; in-domain: `engine/graphics/render/buffer/buffers/NormalFrameBuffer.js:44` `'RGBA16F'` — `.../ColorAndDepthFrameBuffer.js:58` — `.../simple-fx/ao/AmbientOcclusionPostProcessEffect.js:97,388` — `.../ao/generateHilbertNoiseTexture.js:27` — `.../forward_plus/LightManager.js:185` — `.../visibility/hiz/buffer/HierarchicalZBuffer.js:99` — `.../hiz/query/BatchOcclusionQuery.js:32` — `engine/graphics/texture/atlas/AtlasLookupTexture.js:34` — `.../texture/virtual/VirtualTextureMemoryMapping.js:51` — `.../virtual/VirtualTexturePage.js:184` — `.../virtual/VirtualTextureUsageUpdater.js:112` — `engine/graphics/sh3/gi/material/makeLookupTexture3D.js:30`, `makeOctahedralDepthAtlas.js:26`, `sh3/lpg/light_probe_grid_textures.js:61,100` | `engine/graphics/texture/computeThreeTextureInternalFormatFromDataType.js` and `.../normalized_internal_format.js` exist precisely to derive this from (`BinaryDataType`, channel count) — only 6 files use them. The `format` / `type` / `internalFormat` triple must agree or the texture silently fails to upload; three copies of the knowledge (three enum, three enum, GL string) are maintained by hand at each site. Note `AtlasLookupTexture.js:32-34` carries a comment explaining a past mismatch — i.e. this has already bitten. | UNJUSTIFIED | Route every site through the existing `engine/graphics/texture/computeThreeTextureInternalFormatFromDataType.js` / `normalized_internal_format.js` (both already in the right home). | M / low — mechanical, per-site verifiable |
+| 8 | MEDIUM | `DataTexture3D` construction recipe (name, `flipY=false`, `generateMipmaps=false`, min/mag filter, `wrapS/T/R = ClampToEdgeWrapping`, type, format, internalFormat, `unpackAlignment = 4`, `needsUpdate = true`) | `engine/graphics/sh3/gi/material/makeLookupTexture3D.js:8-36` — `engine/graphics/sh3/lpg/light_probe_grid_textures.js:39-68` (`make_light_probe_grid_luma_texture`) — `.../light_probe_grid_textures.js:78-107` (`make_light_probe_grid_chroma_texture`) | Three copies of the same 12-property block; the two in `light_probe_grid_textures.js` differ only in typed-array constructor / type / format / internalFormat. 2D siblings of the same recipe: `engine/graphics/sh3/gi/material/makeOctahedralDepthAtlas.js:8-30`, `engine/graphics/texture/virtual/VirtualTextureMemoryMapping.js:31-58`, `engine/graphics/texture/atlas/AtlasLookupTexture.js:25-34`. | UNJUSTIFIED | New `engine/graphics/texture/3d/make_data_texture_3d.js` taking an `AttributeSpec` + resolution + a `TextureFilterMode` enum value, deriving format/type/internalFormat via the helpers in finding #7 (this is the natural home per the task brief). A 2D sibling `engine/graphics/texture/make_data_texture_2d.js` covers the other three. | M / low |
+| 9 | MEDIUM | "Data render target" option object: `{minFilter/magFilter: NearestFilter, format, type, internalFormat, depthBuffer:false, stencilBuffer:false, wrapS/T: ClampToEdgeWrapping, generateMipmaps:false}` | `engine/graphics/ecs/highlight/renderer/OutlineRenderer.js:232-273` (**five** near-identical literals in one constructor) — `engine/graphics/render/visibility/hiz/buffer/HierarchicalZBuffer.js:94-105` — `engine/graphics/render/visibility/hiz/query/BatchOcclusionQuery.js:41-52` — `engine/graphics/texture/virtual/VirtualTextureUsageUpdater.js:105-117` — `engine/graphics/render/buffer/simple-fx/ao/AmbientOcclusionPostProcessEffect.js:91-101` — `engine/graphics/filter/ImageFilter.js:46-51` — `engine/graphics/render/visibility/hiz/buildCanvasViewFromTexture.js:167-172` — `engine/graphics/util/renderObjectToSampler2D.js:29-36` | Ten+ copies of one recipe, each independently re-picking the three.js enums. This is the exact "same three.js translation logic repeated" case the house rule names. Divergences are already visible: `BatchOcclusionQuery.js:46` has the `internalFormat` commented out; `ImageFilter` uses `LinearFilter` where its twin `renderObjectToSampler2D` sets `magFilter` too. | UNJUSTIFIED | New `engine/graphics/texture/make_data_render_target.js` — typed parameters (resolution, `AttributeSpec`, a project-owned `TextureFilterMode`, `depth: boolean`), all three.js enums confined inside. | M / low |
+| 10 | MEDIUM | Offscreen full-screen-quad pass → `readPixels` into a `Sampler2D`/typed array, with `getRenderTarget()`/`setRenderTarget()` save-restore | `engine/graphics/filter/ImageFilter.js:14-77` (`processTexture`) — `engine/graphics/render/visibility/hiz/buildCanvasViewFromTexture.js:139-227` (`renderSamplerFromTexture`) — `engine/graphics/util/renderObjectToSampler2D.js:15-83` | All three build their own `OrthographicCamera(-1,1,1,-1,0,1)` + `Scene` + `Mesh(FULL_SCREEN_TRIANGLE_GEOMETRY)`, their own `renderTargetOptions` literal (same variable name in all three), then `renderer.getContext(); gl.readPixels(0,0,w,h,gl.RGBA,gl.UNSIGNED_BYTE, dest)` and restore. **The scene/camera/quad half already exists** as `engine/graphics/render/utils/renderScreenSpace.js:6-33` (module-static, matrix-auto-update disabled) — none of the three use it. | UNJUSTIFIED | Two steps: (a) all three switch the draw to `renderScreenSpace(renderer, material)`; (b) extract `engine/graphics/render/utils/read_render_target_to_sampler2d.js` for the RT+readPixels+restore half. | M / medium — `renderObjectToSampler2D` feeds the model-preview path |
+| 11 | MEDIUM | Forward+ uniform block (`fp_t_light_tiles`, `fp_t_light_lookup`, `fp_t_light_data`, `fp_t_decal_atlas`, `fp_t_decal_atlas_resolution`, `fp_v3_light_cluster_resolution`, `fp_f_camera_near`, `fp_f_camera_far`, `fp_resolution`) declared in JS | `engine/graphics/render/forward_plus/materials/ForwardPlusThreeMaterial.js:9-40` — `engine/graphics/render/forward_plus/plugin/MaterialTransformer.js:23-56` — `engine/graphics/render/forward_plus/materials/FPlusDebugMaterial.js:105-130` — matching GLSL declarations in `engine/graphics/render/forward_plus/materials/FP_SHADER_CHUNK_PREAMBLE.js:8-31` | Four hand-maintained copies of one uniform contract. They have **already drifted**: `ForwardPlusThreeMaterial` omits `fp_t_decal_atlas_resolution` and `fp_v3_light_cluster_resolution` that the preamble declares; `MaterialTransformer.js:40-43` declares `fp_t_decal_atlas_resolution` with `type:'t'` while the GLSL declares it `uniform vec2`. A missing/mistyped uniform here degrades silently (decals/lights just stop). | UNJUSTIFIED | New `engine/graphics/render/forward_plus/materials/fp_make_common_uniforms.js` returning the typed uniform object, exported next to `FP_SHADER_CHUNK_PREAMBLE` so the GLSL and JS declarations live in one directory and are reviewed together. | S / medium — Forward+ contract; A/B by adding a clustered point light |
+| 12 | MEDIUM | GLSL: concentric-disk mapping + cosine-weighted hemisphere sample + branchless (Duff/Frisvad) orthonormal basis | `engine/graphics/render/buffer/simple-fx/ao/SAOShader.js:173-219` (`sampleUniformDiskConcentric`, `sampleCosineWeightedHemisphere`, `buildOrthonormalBasis`) — `engine/graphics/shaders/AmbientOcclusionShader.js:174-219` (`sample_uniform_disk_concentric`, `sample_cosine_weighted_hemisphere`, `build_orthonormal_matrix_n`) | ~45 lines of GLSL, mathematically identical line-for-line (same branch structure, same `n.z < 0.0` split, same `a`/`b` temporaries); only identifier casing and `const float PI_4` vs inline `PI * 0.25` differ. Invisible to the token-based pass because both live inside template literals. | UNJUSTIFIED | New `engine/graphics/shaders/lib/GLSL_CHUNK_HEMISPHERE_SAMPLING.js` next to the existing `engine/graphics/shaders/lib/ShaderChunks.js` (which already is the project's GLSL-chunk home), interpolated into both shaders. | S / low — text move, verify by compiling both effects |
+| 13 | MEDIUM | GLSL: depth decode / view-Z reconstruction / blue-noise permutation shared by the two halves of one effect | `engine/graphics/render/buffer/simple-fx/ao/SAOShader.js:86-92` (`getDepth`), `:94-100` (`getViewZ`), `:169-171` (`r2_marty`), `:47-54` (vertex shader), `:252` (Hilbert texelFetch) — `engine/graphics/render/buffer/simple-fx/ao/SAOUpscaleShader.js:79-85`, `:87-93`, `:96-98`, `:51-58`, `:129` | Verbatim, including the magic constants `vec2( 0.245122333753, 0.430159709002 )` and the `ivec2( gl_FragCoord.xy ) & 63` mask. The two shaders are a matched pair (the upscale explicitly reproduces the AO pass's depth-texel snapping — see its header comment); a change to `getDepth`/`getViewZ` in one and not the other silently breaks the pairing. | UNJUSTIFIED | Shared `engine/graphics/render/buffer/simple-fx/ao/SAO_GLSL_COMMON.js` exporting the `DEPTH_PACKING`/`PERSPECTIVE_CAMERA`-guarded depth chunk, `r2_marty`, and the vertex shader; both descriptors interpolate it. | S / low |
+| 14 | MEDIUM | GLSL: `convert_depth_to_linear` + Forward+ cluster addressing (`textureSize` → `ivec3` cluster position → `texelFetch` metadata) | `engine/graphics/render/forward_plus/materials/FP_SHADER_CHUNK_DECODE_PARS.js:30-45` and `FP_SHADER_CHUNK_LOAD_METADATA.js:5-8` and `FP_SHADER_CHUNK_PREAMBLE.js:8-31` — re-typed by hand in `engine/graphics/render/forward_plus/materials/FPlusDebugMaterial.js:63-78` (`convert_depth_to_linear`), `:84-87` (cluster addressing), `:29-45` (uniform declarations) | `convert_depth_to_linear` is line-for-line identical between the chunk and the debug material. The cluster-addressing lines differ only in where the `1.0 - x` flip is applied (`fp_build_fragment_shader.js:15` does `clip_v.x = 1.0 - clip_v.x`; `FPlusDebugMaterial.js:85` inlines `( 1.0 - clip_v.x)`). This is the *debug visualiser for the binning* — if binning changes, the debug view silently keeps showing the old mapping and lies about the bug you are hunting. | UNJUSTIFIED | `FPlusDebugMaterial` should compose `FP_SHADER_CHUNK_PREAMBLE` + `FP_SHADER_CHUNK_DECODE_PARS` + `FP_SHADER_CHUNK_LOAD_METADATA` instead of re-typing them. | S / low |
+| 15 | MEDIUM | GPU-resident growable typed-array-backed `DataTexture` (allocate from `BinaryDataType`, set format/type/internalFormat, nearest filters, no mipmaps, `dispose()` + copy-forward on resize) | `engine/graphics/texture/AttributeDataTexture.js:121-196` (`resize`, `build`) — `engine/graphics/texture/TextureBackedMemoryRegion.js:57-73` + `:187-227` (`build`) | Same responsibility, same three helper calls (`compute_typed_array_constructor_from_data_type`, `computeThreeTextureTypeFromDataType`, `computeThreeTextureInternalFormatFromDataType`), same dispose-then-reassign-`image.data` resize protocol. They differ only in how the element description arrives (`AttributeSpec` vs `NumericType`+`precision`+`channel_count`) and in row-packing policy. | UNJUSTIFIED | `TextureBackedMemoryRegion` should hold an `AttributeSpec` and delegate storage to `AttributeDataTexture` (which is the more complete of the two), keeping only its `DATA_TEXTURE_WIDTH`/grow-shrink policy. | M / medium — both are live GPU paths; `AttributeDataTexture.spec.js` exists |
+| 16 | MEDIUM | Whole-file duplicate: `CopyShader` | `engine/graphics/postprocess/threejs/shaders/CopyShader.js:6-45` — `engine/graphics/shaders/CopyShader.js:5-47` | Identical uniforms + identical vertex and fragment source, differing only in shape (frozen object vs zero-arg factory returning a fresh object). The `postprocess/threejs/shaders/` directory contains nothing else. Only `engine/graphics/texture/sampler/convertTexture2Sampler2D.js:4` imports one of them; `engine/graphics/shaders/CopyShader.js` has no internal caller (public surface — keep). A *third* copy is pulled from `three/examples/jsm/shaders/CopyShader.js` in `prototypeNormalFrameBuffer.js:12`. | UNJUSTIFIED | Keep `engine/graphics/shaders/CopyShader.js` as the home; make `engine/graphics/postprocess/threejs/shaders/CopyShader.js` a one-line re-export (`export default CopyShader()` shape shim) marked `@deprecated`, per the library rule. Then delete the empty `postprocess/` tree in a later pass. | S / low |
+| 17 | MEDIUM | Sampler channel extremum scan (42 lines) | `engine/graphics/texture/sampler/sampler2d_channel_compute_max.js:9-51` — `engine/graphics/texture/sampler/sampler2d_channel_compute_min.js:9-51` | Byte-identical except the comparison operator on line 31 (`bestValue < value` vs `bestValue > value`). Same three asserts, same `//no data` comment, same `{index, value, x, y}` return shape, same `(bestIndex / itemSize) | 0` index→xy math. | UNJUSTIFIED | New `engine/graphics/texture/sampler/sampler2d_channel_compute_extreme.js` taking an explicit `ExtremumDirection` enum member (typed constant, not a string key, not a `null`-means-auto sentinel); both existing exports become 2-line wrappers and stay public. | S / low — both have specs |
+| 18 | MEDIUM | Cloud-shadow uniform block (13 uniforms + the `SHADOWMAP_CLOUDS` define) | `engine/graphics/material/SplatMaterial.js:80-96` + `:116` — `engine/graphics/material/WaterMaterial.js:22-38` + `:53` | Verbatim apart from `f_CloudsIntensity` default (0.3 vs 0.5). The **GLSL** half of the same feature is already centralised (`engine/graphics/shaders/lib/ShaderChunks.js:8-54`, four chunks) and a third file drives them by name (`engine/ecs/terrain/TerrainClouds.js:98-118,192`). So one feature's uniform names live in four files with only three of them sharing a home. | UNJUSTIFIED | Export a `make_clouds_uniforms()` factory from `engine/graphics/shaders/lib/` alongside the chunks it feeds, so the GLSL declarations and the JS uniform objects sit in one module. | S / low |
+| 19 | MEDIUM | Channel-count → format-prefix switch (`1→R, 2→RG, 3→RGB, 4→RGBA`, same throw message) | `engine/graphics/texture/computeThreeTextureInternalFormatFromDataType.js:43-60` — `engine/graphics/texture/normalized_internal_format.js:28-45` | 18 lines byte-identical including `` throw new Error(`Unsupported channel count '${channel_count}'`) ``. Only the *suffix* switch legitimately differs (integer vs normalized). | UNJUSTIFIED | New `engine/graphics/texture/channel_count_to_format_prefix.js`; both callers use it. | S / very low |
+| 20 | MEDIUM | GLSL: full-screen quad vertex shader | `engine/graphics/FULL_SCREEN_QUAD_VERTEX_SHADER.js:1-10` — `engine/graphics/shaders/ScreenSpaceQuadShader.js:3-14` (`vertexShader()`) | Both emit the identical `varying vec2 vUv; void main(){ vUv = uv; gl_Position = vec4((uv - 0.5)*2.0, 0.0, 1.0); }`. Two shared homes for one shader: `FULL_SCREEN_QUAD_VERTEX_SHADER` is used by `engine/graphics/filter/ImageFilter.js:33` and `engine/ecs/fow/shader/screenSpaceFogOfWarShader.js:10`; `ScreenSpaceQuadShader.vertexShader()` by six other files. The separate `projectionMatrix * modelViewMatrix` variant is retyped in 7 more files (see GLSL section). | UNJUSTIFIED | Keep `engine/graphics/shaders/ScreenSpaceQuadShader.js` as the home (more consumers, co-located with `glsl_gen_swizzled_read`); make `FULL_SCREEN_QUAD_VERTEX_SHADER` re-export from it. | S / very low |
+| 21 | LOW / PROMOTION | Screen-space material pass: build scene/camera/quad, bind material, draw | `engine/graphics/render/visibility/hiz/buildCanvasViewFromTexture.js:153-163` + `:196-213` (`renderSamplerFromTexture`) vs the existing `engine/graphics/render/utils/renderScreenSpace.js:6-33` and `engine/graphics/render/utils/renderTextureToScreenQuad.js:25-29` | `renderTextureToScreenQuad` is *exactly* what `renderSamplerFromTexture` re-implements, plus swizzle and integer-sampler support (`makeShader` at `:82-125`). Its `defineSamplerType`/`sampleTexel`/`scaleSample` helpers (`:30-74`) are generic texture-format→GLSL translation with no home. | PROMOTION | Move `defineSamplerType`/`sampleTexel`/`scaleSample` and the integer-capable swizzle shader into `engine/graphics/shaders/ScreenSpaceQuadShader.js` (extending it to integer formats), then have `renderSamplerFromTexture` use `renderScreenSpace`. | M / medium |
+| 22 | LOW / PROMOTION | Live-occupancy iteration over `VirtualTextureUsage` (occupancy array → fingerprint → count → skip ≤0 → decompose) | `engine/graphics/texture/virtual/debug/UsageDebugView.js:41-57` (`set usage`) — `engine/graphics/texture/virtual/debug/UsagePyramidDebugView.js:212-225` (`set usage`) — third raw consumer at `engine/graphics/texture/virtual/VirtualTexturePage.js:459-472` | Identical loop; the `count <= 0` skip is the non-obvious invariant (occupancy entries are not compacted) and it is re-stated in each consumer. `VirtualTextureUsage` exposes only `occupancy` / `occupancy_count` getters (`VirtualTextureUsage.js:42-51`). | PROMOTION | Add `traverse_live(callback, thisArg)` to `engine/graphics/texture/virtual/VirtualTextureUsage.js` and have all three consumers use it; the raw getters stay (public surface). | S / low — debug views only, plus one hot loop |
+| 23 | LOW | Numeric-type → channel-count-format dispatch | `engine/graphics/texture/attribute_spec_to_three_format.js:12-25` — `engine/graphics/texture/computeThreeTextureFormat.js:10-18` | Same `Uint/Int → channelCountToThreIntegerTextureType`, `Float → channelCountToThreeTextureFormat`, same throw message. `attribute_spec_to_three_format` only adds the `spec.normalized` pre-branch. | UNJUSTIFIED | `attribute_spec_to_three_format` should call `computeThreeTextureFormat(numeric_type, spec.itemSize)` for the non-normalized case. | S / very low |
+| 24 | LOW | Render-target save/restore idiom | 14 sites, 6 different local names: `engine/graphics/render/buffer/FrameBuffer.js:76` `_renderTarget` — `.../buffers/NormalFrameBuffer.js:124` `_state_rt` — `.../simple-fx/ao/AmbientOcclusionPostProcessEffect.js:255` `__old_state_rt` — `.../simple-fx/DepthLimitedBlur.js:130` `__old_state_rt` — `.../visibility/hiz/buffer/HierarchicalZBuffer.js:186` `__rt` — `.../hiz/query/BatchOcclusionQuery.js:167` `__rt` — `.../hiz/buildCanvasViewFromTexture.js:202` `_rt` — `engine/graphics/texture/virtual/VirtualTextureUsageUpdater.js:295` — `engine/graphics/ecs/highlight/renderer/OutlineRenderer.js:628` — `engine/graphics/filter/ImageFilter.js:55` — `engine/graphics/util/renderObjectToSampler2D.js:48` — `engine/graphics/shadows/ShadowMapRenderer.js:77` — `engine/graphics/sh3/lpv/WebGLCubeProbeRenderer.js:133` — `engine/graphics/impostors/octahedral/ImpostorBaker.js:78` | Not a *code* duplication so much as a repeated invariant ("restore or you corrupt the next pass"), and `DepthLimitedBlur.js:130-153` shows how much bigger it gets once clear-colour/alpha/`autoClear` join in. Low value on its own, but it is the through-line of findings #9 and #10. | UNJUSTIFIED (low) | A typed `RenderTargetScope` class in `engine/graphics/render/utils/` with `enter(renderer, target)` / `exit()` — no callbacks, no sentinels. Adopt opportunistically. | S / low |
+| 25 | LOW | Canvas + `createImageData` + `Sampler2D` over `imageData.data` + `putImageData` | `engine/graphics/makeModelView.js:15-35` — `engine/graphics/render/visibility/hiz/buildCanvasViewFromTexture.js:248-279` (`buildCanvasViewFromTexture`) | Same 4-step recipe (size canvas → `createImageData` → wrap the backing array in a `Sampler2D` → `putImageData` after each render). Related: `engine/graphics/texture/html_canvas_to_sampler2d.js:10-22` and `engine/graphics/texture/canvasDataToSampler.js:8-19` are two spellings of "getImageData → Sampler2D". | UNJUSTIFIED (low) | New `engine/graphics/texture/sampler/sampler2d_backed_canvas.js` returning `{canvas, sampler, present()}`; `canvasDataToSampler` delegates to `html_canvas_to_sampler2d`. | S / low |
+| 26 | LOW | Heat-map `ParameterLookupTable` colour ramp | `engine/graphics/render/forward_plus/debug/createScreenGrid.js:180-188` — `engine/ecs/terrain/util/paintTerrainOverlayViaLookupTable.js:11-20` — variant with an extra purple stop at `engine/graphics/render/forward_plus/materials/FPlusDebugMaterial.js:137-146` | The first two are byte-identical (same 6 RGBA stops, same `computeUniformPositions()` call). Debug-only, but three copies of one palette that is meant to be read comparatively across the two Forward+ debug views. | UNJUSTIFIED (low) | Export `make_heatmap_lut()` from `engine/graphics/render/forward_plus/debug/` (or `core/color/`) and use it in all three. | S / very low |
+| 27 | LOW | Direct `canvas.getContext("2d")` where a caching helper exists | `engine/graphics/texture/sampler/sampler2d_write_to_canvas_raw.js:31` — vs `engine/graphics/texture/html_canvas_to_rendering_context2d_cached.js:12-20` | The cached accessor exists specifically because repeated `getContext` on the same canvas is wasteful; `sampler2d_write_to_canvas_raw` (called per download/preview) bypasses it. Also `engine/graphics/texture/sampler/convertTexture2Sampler2D.js:62` and `engine/graphics/makeModelView.js:22`. | UNJUSTIFIED (low) | Use `html_canvas_to_rendering_context2d_cached`. | S / very low |
+| 28 | LOW | WebGL2 renderer construction (`createElement('canvas')` → `getContext('webgl2', …)` → `new WebGLRenderer({canvas, context, …})`) | `engine/graphics/render/RendererPool.js:9-16` (`WebGLRendererPool.get`) — `engine/graphics/GraphicsEngine.js:492-506` (`start`) | Same three-step vendor dance with divergent options (`antialias: true` on the context in the pool, `false` in the engine; `alpha: true` vs `powerPreference`). Two places to touch when a context attribute must change engine-wide. | UNJUSTIFIED (low) | New `engine/graphics/render/make_webgl2_renderer.js` taking a typed options object; both callers use it. | S / low |
+
+## Dismissed leads
+
+- `engine/graphics/geometry/geometry_construct_triangle_normal.js` vs `core/geom/3d/triangle/tri3_compute_normal.js` — **not** a duplicate: it already delegates on line 30. It is the correct index-fetch adapter. (MinHash matched the shared index→address prologue, which is finding #1.)
+- `engine/graphics/geometry/buffered/geometry_compute_vertex_normals_indexed.js` vs `..._unindexed.js` — both delegate to `geometry_construct_triangle_normal`; the remaining difference (accumulate-then-normalize vs copy) is the actual semantic difference. Model of correct reuse.
+- `engine/graphics/texture/3d/scs3d_sample_linear.js` vs `scs3d_sample_linear3.js` — JUSTIFIED. The 3-channel version documents (lines 6-16) that it deliberately shares one index/weight computation across three grids for the fluid advection hot loop; the duplicated prologue *is* the optimisation.
+- `engine/graphics/render/forward_plus/model/Decal.js` vs `engine/graphics/ecs/decal/v2/Decal.js` — name collision only. One is an encoded GPU record extending `AbstractLight` (`toArray`, `getAABB`); the other is a serializable ECS component (`toJSON`/`hash`/`equals`). No shared code.
+- `MaterialTransformer` name collision (finding #4 covers the real duplication) — the classes are otherwise unrelated; renaming is a separate naming concern, not a reuse failure.
+- `engine/graphics/geometry/AttributeGroupSpec.js:211` `getByteSize` vs `core/process/task/TaskGroup.js:50` — both are "sum a field over an array"; unrelated domains, no shared abstraction worth naming.
+- `engine/graphics/geometry/AttributeGroupSpec.js:51` `getAttributeByName` vs `engine/graphics/particles/particular/group/ParticleSpecification.js:23` `getByName` — `ParticleSpecification` is already marked `@deprecated use AttributeGroupSpec` (line 3). Documented migration state, not a new finding.
+- `engine/graphics/geometry/AttributeSpec.js:157` `getByteSize` — already derives from the shared `core/binary/type/DataTypeByteSizes.js`; the particle-side `getTypeByteSize.js` / `itemSizeFromAttributeType.js` key off different enums (`ParticleDataTypes` / `ParticleAttributeType`) in different units (bytes vs items) and live outside this domain.
+- `engine/graphics/render/forward_plus/model/{PointLight,SpotLight,DirectionalLight}.js` `onX`/`offX` signal-pair mirrors — verbose typed code, exactly what the house rules prefer over a signal-list registry.
+- `engine/graphics/render/forward_plus/cluster/read_plane_pair.js` vs `core/geom/vec3/v3_copy_array.js` / `aabb3_array_size.js` — false positive; `read_plane_pair` negates the second plane, which is its whole reason to exist.
+- `engine/graphics/render/visibility/IncrementalDeltaSet.js:310` `pushOther` vs `engine/ecs/animation/AnimationOptimizer.js:123` — false positive (generic array append loop).
+- `engine/graphics/texture/atlas/TextureAtlas.js:98` `getPatch`, `engine/graphics/render/layers/RenderLayerManager.js:47` `hideAll` — false positives (linear scan / forEach).
+- `engine/graphics/render/forward_plus/query/query_bvh_frustum_from_texture.js` vs `core/bvh2/binary/2/bvh32_query_user_data_*.js` — shared stack-traversal *shape*, but the payload (frustum plane rejection against a texture-backed light record) is genuinely different. Not worth unifying.
+- `engine/graphics/render/forward_plus/materials/FPlusStandardMaterial.js` — 350 lines of uniform accessors mirroring three's `MeshStandardMaterial`. This is the vendor adapter boundary doing its job; typed verbosity is the house preference.
+- `prototype*.js` / `test*.js` browser harnesses (`prototypeNormalFrameBuffer.js`, `prototypeHiZ.js`, `ptototypeFPPlugin.js`, `testClippingPlaneComputation.js`, …) account for ~20 of the 32 MinHash pairs — they share a `makeConfig`/`init` harness boilerplate. Out of scope per instructions; one shared `makeHarnessConfig()` would cover them all if ever wanted.
+
+## Notes
+
+Three structural reasons duplication accumulates in this domain:
+
+1. **The three.js boundary is not actually a boundary.** There are ~208 `from 'three'` imports and no adapter layer: every call site that needs a texture or a render target independently re-picks `format` / `type` / `internalFormat` / `wrapS` / `minFilter`, and hand-writes the GL internal-format string even though `computeThreeTextureInternalFormatFromDataType` and `normalized_internal_format` exist two directories away. Findings #7, #8, #9, #15, #28 are all one root cause. The `engine/graphics/texture/` directory already contains a well-factored translation layer (`attribute_spec_to_three_format`, `channelCountToThree*`, `numericTypeFromBinaryDataType`, `formatToChannelCount`, `GL_RGBFormat`) — it is simply bypassed by most of the engine.
+
+2. **Shared primitives exist but are not discovered.** In four separate findings the extracted helper was already in the tree and unused by its obvious callers: `traverseMaterialTextures` (#3), `frustum3_planes_to_flat_from_three` (#6 — imported in the same file that also imports the duplicate), `array_quick_sort_by_comparator` (#5), `renderScreenSpace` / `renderTextureToScreenQuad` (#10, #21). Naming is the likely cause: `computeFrustumCorners` and `frustum_compute_corners`, `sampler2d_to_texture` and `sampler2d_to_float32_texture`, `FULL_SCREEN_QUAD_VERTEX_SHADER` and `ScreenSpaceQuadShader.vertexShader()` are pairwise indistinguishable from an import list.
+
+3. **Copies drift into defects.** Two findings are not hygiene items — the duplicate is already wrong. `engine/graphics/sh3/gi/material/MaterialTransformer.js:311` discards the result of `result.clone()` (mutating the caller's material) where its twin at `plugin/MaterialTransformer.js:107` assigns it; `engine/graphics/render/forward_plus/sort_decal_data.js:70,74` re-reads the pivot through a mutating array where both core quicksorts capture the pivot value first. That is the argument for consolidating: these bugs cannot exist in a single implementation.
+
+### GLSL duplication
+
+Token-based detection is blind here — every one of these lives inside a template literal or a `[...].join("\n")` array. Verbatim-repeated fragments found:
+
+- **Concentric-disk → cosine-hemisphere → branchless orthonormal basis** (~45 lines, 3 functions). `render/buffer/simple-fx/ao/SAOShader.js:173-219` ⟷ `shaders/AmbientOcclusionShader.js:174-219`. Should live in `engine/graphics/shaders/lib/` (finding #12).
+- **`getDepth` (DEPTH_PACKING-guarded) + `getViewZ` (PERSPECTIVE_CAMERA-guarded) + `r2_marty` + the Hilbert `texelFetch(tHilbert, ivec2(gl_FragCoord.xy) & 63, 0).x` idiom.** `SAOShader.js:86-100,169-171,252` ⟷ `SAOUpscaleShader.js:79-93,96-98,129`. Should live in a `SAO_GLSL_COMMON.js` next to them (finding #13).
+- **`float convert_depth_to_linear(in float d)`** — 16 lines, identical. `render/forward_plus/materials/FP_SHADER_CHUNK_DECODE_PARS.js:30-45` ⟷ `render/forward_plus/materials/FPlusDebugMaterial.js:63-78`. The chunk is the home; the debug material should include it (finding #14).
+- **Forward+ cluster addressing** (`textureSize(fp_t_light_tiles,0)` → `ivec3` position → `texelFetch(...).rgba`). `FP_SHADER_CHUNK_LOAD_METADATA.js:5-8` ⟷ `FPlusDebugMaterial.js:84-87` (with the x-flip applied at a different place). Same home (finding #14).
+- **Forward+ uniform declarations** (`fp_t_light_tiles`, `fp_f_camera_near/far`, `fp_resolution`, `fp_v3_light_cluster_resolution`). `FP_SHADER_CHUNK_PREAMBLE.js:8-31` ⟷ `FPlusDebugMaterial.js:29-45`. Same home (finding #14); the JS-side twin is finding #11.
+- **Full-screen quad vertex shader, NDC form.** `FULL_SCREEN_QUAD_VERTEX_SHADER.js:1-10` ⟷ `shaders/ScreenSpaceQuadShader.js:3-14` — identical GLSL, two shared homes (finding #20).
+- **Full-screen quad vertex shader, `projectionMatrix * modelViewMatrix` form** — the same 5 lines (`varying vec2 vUv; void main(){ vUv = uv; gl_Position = projectionMatrix * modelViewMatrix * vec4(position,1.0); }`) retyped in **seven** places: `postprocess/threejs/shaders/CopyShader.js:15-26`, `shaders/CopyShader.js:16-27`, `shaders/AlphaBlendShader.js:10-21`, `shaders/ClearShader.js:8-16` (vUv-less variant), `shaders/NormalMapShader2.js:40-51`, `render/buffer/simple-fx/ao/SAOShader.js:47-54`, `render/buffer/simple-fx/ao/SAOUpscaleShader.js:51-58`, `render/visibility/hiz/buildCanvasViewFromTexture.js:94-103`. Belongs beside `ScreenSpaceQuadShader` as a second named export (the two forms are not interchangeable — the NDC form ignores the quad's model matrix — so they must both exist, but each only once).
+- **Cloud-shadow chunks** — correctly centralised already in `shaders/lib/ShaderChunks.js:8-54`; only the JS uniform block is duplicated (finding #18). Included here as the counter-example of what the rest should look like.
+
+No duplicated octahedral encode/decode, normal/depth packing, tonemapping, sRGB conversion or IGN dithering was found *inside this domain* — those chunks are either single-sourced (`core/geom/3d/octahedra/**`), taken from three's `#include <packing>`, or live in `engine/graphics/impostors/**` and `engine/ecs/fow/**` which belong to other domains.