@woosh/meep-engine 2.169.1 → 2.169.2

package/src/DUPLICATION_AUDIT_2026_08_07/K_crosscutting.md

@@ -0,0 +1,169 @@
+# Domain K — cross-cutting reuse failures
+
+Scope: concerns that cut across packages. Every count below comes from a grep/AST census run over
+`H:/git/moh/app/src/mir-engine/meep/src/` excluding `*.spec.js`, `prototype*.js`, `test*.js`.
+Census scripts are in the scratchpad (`grow.mjs`, `sys.mjs`, `sys2.mjs`, `census.mjs`).
+
+## Findings
+
+| # | Severity | Concept | # of independent impls | Representative sites | Existing primitive (if any) | Verdict | Proposed common path | Effort/Risk |
+|---|---|---|---|---|---|---|---|---|
+| K1 | **HIGH** ⚠ **INCONSISTENT** | 32-bit hash *combine* (`h*31 + v`) | **33 files** hand-roll the mix (74 mix statements) while **62 files** import the primitive | `engine/physics/ecs/Joint.js:444`, `engine/physics/ecs/RigidBody.js:281`, `engine/physics/ecs/Collider.js:159`, `core/geom/3d/shape/HeightMapShape3D.js:461`, `core/model/BoundedValue.js:180`, `core/geom/Vector2.js:640`, `core/graph/csr/CSRGraph.js:281` | `core/collection/array/combine_hash.js:9` (variadic); `core/math/hash/lowbias32.js`, `murmur3_32.js`, `squirrel3.js` | **UNJUSTIFIED** — but see K1a: the mixes are not the same function | Add a non-variadic, allocation-free `hash_combine(h, v)` in `core/math/hash/` (2 args, `|0`-truncating) and route both `combine_hash` and the 33 hand-rolled chains through it | M / M — every changed `hash()` changes its value; any persisted hash must be re-baselined |
+| K1a | **HIGH** ⚠ **INCONSISTENT** | integer-domain discipline of the *same* hash | **4 mutually-incompatible disciplines** across 5 sibling functions | `core/collection/array/computeHashArray.js:24` (`hash \|= 0` every iteration) vs `core/collection/array/typed/uint32_array_hash.js:15` (**never truncates**) vs `core/collection/array/computeStridedIntegerArrayHash.js:27` (`>>> 0` at the end only) vs `core/primitives/strings/computeStringHash.js:40` (`>>> 0`) vs `core/geom/Vector2.js:640` (no truncation, returns a non-int32) | — | **UNJUSTIFIED / correctness hazard** | One truncation rule (`\| 0` per step) applied by the shared `hash_combine`; `uint32_array_hash` currently returns an ever-widening float (its accumulator escapes int32 on the first ≥2³¹ element and drifts as a ±random walk — the exact workload `CSRGraph.hash()` feeds it at `CSRGraph.js:285-292`) | S / M |
+| K2 | **HIGH** ⚠ **INCONSISTENT** | `(array, offset, length)` array-hash contract | latent off-by-semantics replicated into **5** clones | `core/collection/array/typed/uint32_array_hash.js:11`, `uint8_array_hash.js:19`, `uint16_array_hash.js:17`, `core/collection/array/computeStridedIntegerArrayHash.js:14`, `computeStridedArrayHash.js:23` — all loop `i < length` while the JSDoc and `array_buffer_hash.js:12` treat `length` as a **count**, so any `offset > 0` silently hashes the wrong (short) range | — | **UNJUSTIFIED** — copy-paste propagated the defect into every clone | Fix once in a shared `hash_combine`-based loop; `uint8_array_hash.js:15` is even self-contradictory (head loop `i < offset + overflow`, body loop `i < length`). All current callers pass `offset === 0`, so nothing is broken **today**, but `offset` is public library surface | S / L |
+| K3 | LOW ⚠ **INCONSISTENT** | word packing in sibling array hashes | 2 | `core/collection/array/typed/uint8_array_hash.js:26-29` packs **little-endian** (`v0 \| v1<<8 \| v2<<16 \| v3<<24`); `uint16_array_hash.js:22` packs **big-endian** (`(v0 << 16) \| v1`) | — | UNJUSTIFIED (cosmetic) | Pick one byte order across the family | S / L |
+| K4 | **HIGH** ⚠ **INCONSISTENT** | explicit-stack quicksort partition | **9** (4 in `core`, 5 hand-rolled) | core: `core/collection/array/array_sort_quick.js:45`, `array_quick_sort_by_comparator.js:36`, `array_quick_sort_by_lookup_map.js:39`, `array_quick_sort_by_lookup_uint.js:38`; hand-rolled: `engine/graphics/render/forward_plus/sort_decal_data.js:65`, `view/minimap/gl/MinimapMarkersGL.js:165`, `engine/graphics/particles/particular/engine/emitter/ParticleEmitter.js:756`, `core/bvh2/binary/2/BinaryUint32BVH.js:364`, `core/geom/2d/r-tree/StaticR2Tree.js:250` | `core/collection/array/array_quick_sort_by_comparator.js` | **UNJUSTIFIED for `sort_decal_data`; JUSTIFIED for the 4 others** (BVH/R-Tree/particles partition a *parallel* index array by a derived key with an inline swap — no existing signature covers that) | Give `core/collection/array/` a `quick_sort_indices(lookup, count, less_fn)` that partitions an index array; port `sort_decal_data` + `MinimapMarkersGL` onto it | M / M |
+| K4a | **HIGH** | pivot capture in the copied quicksort | 1 divergent copy of 9 | `engine/graphics/render/forward_plus/sort_decal_data.js:70,74` compares `compare_decals(i, pivotIndex, …)` against the **live pivot index**; every other copy captures the pivot **value** first (`array_quick_sort_by_comparator.js:38`, `ParticleEmitter.js:758`, `MinimapMarkersGL.js:168`) | — | **UNJUSTIFIED / correctness hazard** | Once the element at `pivotIndex` is swapped the partition invariant breaks and decals come out in a wrong blend order. Fix by capturing the pivot's encoded value before the partition loop | S / L |
+| K5 | **MED** ⚠ **INCONSISTENT** | binary search / lower bound | **6** (2 in `core`, 4 hand-rolled) with **4 different miss/tie semantics** | `core/collection/array/binarySearchLowIndex.js:10` (floor index, `-1` if below range, arbitrary index inside an equal run); `binarySearchHighIndex.js:10` (exact index, else insertion point `min`); `engine/animation/async/table_find_min_index_in_ordered_column.js:14` (returns `min2(minIndex,maxIndex)`; its JSDoc claims "low index of matching value" but it returns an **arbitrary** index of an equal run); `engine/animation/curve/AnimationCurve.js:233` (last index with `time ≤ t`, then explicitly fast-forwards over duplicates); `engine/graphics/sh3/lpg/bake_probe_sh3_resampled.js:61` (true `lower_bound`: `low < high`, `> value → high = mid`); `engine/sound/simulation/probe/probe_visibility_augment.js:170` (membership only) | `core/collection/array/binarySearch{Low,High}Index.js` | **UNJUSTIFIED for the semantics; JUSTIFIED for the typed-array/CSR ones** (`probe_visibility_augment` searches a `Uint32Array` slice, the core helpers take a comparator closure) | Document + name the two semantics explicitly (`array_lower_bound` = first index with `arr[i] >= v`, `array_upper_bound` = first index with `arr[i] > v`), fix `table_find_min_index_in_ordered_column`'s JSDoc-vs-behaviour mismatch, and give `core/graph/csr/` a `csr_adjacency_contains(adj, addr, u, v)` for the CSR case | M / M |
+| K6 | **MED** | typed-array capacity growth (`new T(newCap)` + `.set(old)`) | **22** independent implementations, **5 different growth policies** | `core/collection/heap/Uint32Heap.js:103` (`max(cap*F, cap+MIN)`), `engine/physics/broadphase/PairList.js:91` (`cap << 1`), `engine/physics/events/ContactEventBuffer.js:65` (`cap << 1`, inlined in `push`), `engine/network/state/ReplicationSlotTable.js:198` (`max(cap*2, cap+64)`), `engine/sound/simulation/probe/AcousticProbeField.js:160` (`do{cap = max(cap*2, DEFAULT)}while`), `core/geom/2d/packing/skyline.js:90` (`while(cap<n) cap*=2`), plus `core/graph/csr/CSRGraph.js:191`, `core/collection/table/RowFirstTable.js:185`, `engine/graphics/sh3/lpv/LightProbeVolume.js:137`, `engine/physics/contact/ManifoldStore.js:742`, `engine/physics/body/BodyStorage.js:400`, `core/binary/BitSet.js:152` … | **none** — `core/collection/array/typed/` has copy/hash/convert helpers but no grow | **PROMOTION** | Add `core/collection/array/typed/typed_array_grow(array, min_capacity)` returning a new array of the same constructor with the old contents copied, using one geometric policy. Callers that keep several parallel arrays (CSRGraph, ManifoldStore, LightProbeVolume) call it once per array | M / L — pure refactor, growth policy change is a perf-only delta |
+| K7 | LOW | defensive byte-slice copy (`new Uint8Array(len)` + `.set(src.subarray(0,len))`) | **6**, byte-identical | `engine/network/diagnostics/ReplayLog.js:42`, `engine/network/transport/LoopbackTransport.js:95`, `engine/network/transport/adapters/SimulatedTransport.js:157`, `engine/network/transport/fragments/FragmentAssembler.js:188`, `engine/network/transport/fragments/FragmentRetention.js:108`, `engine/network/transport/ReliableCommandPipeline.js:226` | `core/collection/array/typed/typed_array_copy.js` (copies into an *existing* destination, doesn't allocate) | **PROMOTION** | `core/collection/array/typed/typed_array_slice_copy(source, length)` → fresh same-type array. 6 call sites, 2 lines each | S / L |
+| K8 | **HIGH** | ECS per-entity link/unlink bookkeeping | **17** hand-rolled vs **7** using the existing base class | hand-rolled: `engine/sound/simulation/ecs/AcousticVolumeSystem.js:40/55`, `engine/sound/simulation/ecs/AcousticSimulationSystem.js:45/62`, `engine/grid/grid2transform/GridPosition2TransformSystem.js:40/79`, `engine/graphics/ecs/mesh/MeshSystem.js:256/296`, `engine/interpolation/InterpolationSystem.js:119/132`, `engine/graphics/ecs/mesh-v2/ShadedGeometrySystem.js:307/356`, `engine/sound/ecs/audio/AudioEmitterSystem.js:129/162` (+10 more) | `engine/ecs/system/AbstractContextSystem.js` (+ `SystemEntityContext`), used by `LightSystem`, `FPDecalSystem`, `PathDisplaySystem`, `SpriteSystemPE`, `VoiceSystem`, `ParentEntitySystem`, `DynamicActorSystem` | **UNJUSTIFIED at the census level** — the shape is identical: build a record in `link`, store at `this.data[entity]`, subscribe signals, `delete this.data[entity]` + unsubscribe in `unlink` | See notes: the blocker is that `AbstractContextSystem.link()` dispatches through `arguments` (`AbstractContextSystem.js:69-90`), which is exactly the "magic" the house style rejects. Propose typed arity-specific bases (`ContextSystem1`/`ContextSystem2`/`ContextSystem3` with real named parameters) and migrate the 17 | L / M |
+| K8a | LOW | `delete this.data[entity]` on a dense array | 17 (same files as K8) | `engine/sound/simulation/ecs/AcousticVolumeSystem.js:60`, `engine/grid/grid2transform/GridPosition2TransformSystem.js:85`, `engine/graphics/ecs/mesh/MeshSystem.js` unlink | — | UNJUSTIFIED (perf, folds into K8) | `delete` on an array index forces the backing store to dictionary mode. Whatever K8 lands should store contexts in a `Uint32Map`/plain array + tombstone instead | folds into K8 |
+| K9 | **MED** ⚠ **INCONSISTENT** | linear scan for an element by `.id`/`.name` | **22** explicit loops (plus ~20 more using `Array.prototype.find`) | `core/binary/type/Type.js:44` (returns **`null`**), `engine/graphics/geometry/AttributeGroupSpec.js:56` (returns **`undefined`**), `generation/grid/GridData.js:82` (returns **`undefined`**), `engine/scene/SceneManager.js:101` (returns **`-1`**), `core/model/node-graph/node/NodeDescription.js:169`, `engine/graphics/particles/particular/group/ParticleSpecification.js:26`, `engine/plugin/EnginePluginManager.js:311` | `core/collection/array/array_index_by_equality.js` | **JUSTIFIED for the loop; UNJUSTIFIED for the sentinel** — a generic `find_by(array, key, value)` would be a **string-keyed** lookup, which the house style forbids; the closure form is already `Array.prototype.find`. The real defect is that the "not found" answer is three different values across sibling APIs | Do **not** extract a helper. Instead standardise the miss sentinel per return kind (element-returning → `undefined`, index-returning → `-1`) and drop the `null` returns (`Type.js:50`) per the no-null house rule | S / L |
+| K10 | **HIGH** | raw `Math.random()` on paths that must be deterministic | **11** sites; 2 are simulation-authoritative | `engine/ecs/dynamic_actions/actions/definition/WeightedRandomActionDescription.js:31` (**seeds an AI behaviour tree** — `actor_seed ^ computeHashFloat(Math.random())`), `engine/intelligence/behavior/util/RandomDelayBehavior.js:9` (**seeds behaviour-tree delays** — `Date.now() ^ Math.random()*UINT32_MAX`), `engine/physics/mls-mpm/MLS_MPM.js:388`, `engine/sound/sopra/definition/effect/ReverbEffect.js:59` (reverb IR differs every session), `engine/animation/removeEntityWithMeshParticlesEffect.js:167`, `view/minimap/dom/MinimapCameraView.js:110`, `engine/ecs/terrain/tiles/TerrainTileManager.js:208` (debug-only), `engine/sound/ecs/SoundControllerSystem.js:15` (`@deprecated`) | `core/math/random/seededRandom.js`, `randomSeed.js`, `randomFromArray.js` (63 files already use them) | **UNJUSTIFIED for the top 4; JUSTIFIED (cosmetic) for minimap jitter, VFX seed, debug tile colour** | Route the two behaviour-tree seeds off a run-level seeded stream (the engine already threads seeds — `MarkerNodeActionSelectWeighted.js:92` shows the pattern). `MLS_MPM.add_rnd_square` should take a `random` argument like every other `sample_random_point_in_volume` in `core/geom/3d/shape/`. `ReverbEffect` should hash its own parameters into a `seededRandom` | M / M |
+| K11 | — | seeded RNG algorithm count | **2** (`seededRandom_Mulberry32.js`, `seededRandom_MersenneTwister.js`; `seededRandom.js` is an alias for the former) | `core/math/random/seededRandom.js:4` | — | **CLEAN — no finding.** There are *not* several competing RNGs. Stateless mixers (`lowbias32`, `murmur3_32`, `squirrel3`) are a different concept and each has one implementation | — | — |
+| K12 | LOW ⚠ **INCONSISTENT** | weighted (cumulative) random selection | **3 core entry points + 1 hand-rolled** | `core/math/random/random_pick_weighted_index.js:12`, `core/collection/array/weightedRandomFromArray.js:21`, `core/geom/3d/shape/UnionShape3D.js:131,257` (both call the core `binarySearchHighIndex`), hand-rolled: `engine/graphics/sh3/lpg/bake_probe_sh3_resampled.js:53` (`pick_candidate`, a true `lower_bound`) | `core/math/random/random_pick_weighted_index.js` | **JUSTIFIED (`pick_candidate` works on a module-static `Float64Array` with no comparator closure, in a per-probe inner loop) — but the tie-break disagrees** | `binarySearchHighIndex` returns an **arbitrary** index inside an equal cumulative run, so `random_pick_weighted_index` can select a **zero-weight** entry when `random()*total` lands exactly on a boundary (reachable: Mulberry32 returns exact `0`). `pick_candidate` cannot. Make the shared path use `lower_bound` semantics | S / L |
+| K13 | **MED** ⚠ **INCONSISTENT** | three.js material `transform()` / `onBeforeCompile` marker injection | **3** near-identical copies with **3 different clone semantics** | `engine/graphics/render/forward_plus/plugin/MaterialTransformer.js:91` (`result = source.clone()` — clones, source untouched), `engine/graphics/sh3/gi/material/MaterialTransformer.js:294` (**`result.clone();` — return value discarded**, then mutates `source` in place: a dead statement, clear copy-paste artifact), `engine/graphics/sh3/lpg/material/LightProbeGridMaterialTransformer.js:207` (no clone at all, mutates `source`) | `engine/graphics/material/composeCompile.js`, `…/forward_plus/plugin/isLitMaterial.js` — the *pieces* are already shared; the ~25-line guard/clone/mark envelope is not | **UNJUSTIFIED / correctness hazard** | Extract `material_transform_once(source, marker, on_before_compile, {clone})` — or, house-style, a small `AbstractMaterialTransformer` base with an explicit `clone` policy decided once. Also: two of the three declare a **module-local `const PROPERTY_TRANSFORMER_MARKER`** with *different values* (`MaterialTransformer.js:19` vs `LightProbeGridMaterialTransformer.js:15`) — same identifier, different meaning | M / M |
+| K14 | LOW ⚠ **INCONSISTENT** | the identifier `EPSILON` | **5 different values** live under one name | `core/math/EPSILON.js:5` = `1e-7` (imported by 21 files) vs module-local `const EPSILON` = `1e-10` in `core/math/linalg/eigen/matrix_qr_in_place.js:1` and `matrix_householder_in_place.js:1`, `1e-9` in `engine/animation/curve/animation_curve_optimize.js:106`, `1e-17` in `core/geom/3d/topology/struct/binary/io/bt_mesh_face_island_erode.js:427` | `core/math/EPSILON.js`, `FLT_EPSILON_{16,32,64}.js` | **JUSTIFIED (the tolerances are algorithm-specific) / UNJUSTIFIED (the name is not)** | Rename the locals to domain names, as ~20 other files already do (`MPR_EPSILON`, `PLANE_EPS`, `BARY_EPS`, `EPA_EPS`, `STALE_EPSILON`) | S / L |
+| K15 | LOW | `Math.abs(a - b) < eps` inline | 23 sites; `epsilonEquals` used by 10 files | `core/geom/mat2/m2_is_orthogonal.js:18`, `engine/sound/simulation/render/ProbeReverbRenderer.js:198-200`, `engine/physics/fluid/ecs/FluidSystem.js:232-234`, `core/math/spline/spline3_hermite_nearest_point.js:103` | `core/math/epsilonEquals.js:11` | **JUSTIFIED** — every site passes its own domain tolerance; `epsilonEquals(a,b,tol)` adds only asserts, and half the sites are `>` (not-equal) tests that `epsilonEquals` cannot express without a negation. `roughlyEquals`/`_roughlyEquals` on `Vector2/3/Quaternion/ConicRay` is already the shared vector-level primitive | — | — |
+| K16 | LOW | AABB accumulation over a point set (`x0 = Infinity` … min/max) | **10** hand-rolled + 4 primitives | hand-rolled: `core/bvh8/build/TriangleCluster.js:13`, `core/geom/2d/quad-tree-binary/QuadTree.js:142`, `core/geom/3d/shape/MeshShape3D.js:251`, `core/geom/3d/topology/struct/binary/query/bt_mesh_build_face_bvh.js:24`, `engine/graphics/particles/particular/engine/emitter/ParticleEmitter.js:158`, `engine/sound/simulation/probe/probe_delaunay_edges.js:156`, `engine/sound/simulation/probe/probe_visibility_bridge_components.js` | `core/geom/3d/aabb/aabb3_from_v3_array.js`, `aabb3_from_v3_array_transformed.js`, `aabb_nd_from_points.js`, `core/geom/2d/aabb/aabb2_from_v2_buffer.js` | **PARTIALLY JUSTIFIED** — the *iteration source* genuinely differs (flat float buffer vs accessor methods vs half-edge loop walk), so one function cannot cover all. The reusable part is the 6-line accumulate step | Add `aabb3_array_expand_by_point(aabb, x, y, z)` next to the existing `aabb3_expand_array.js` and use it as the inner step; `probe_delaunay_edges` and `TriangleCluster` can call `aabb3_from_v3_array` outright | S / L |
+| K17 | LOW | `traverseThreeObject` | 1 helper that reimplements `THREE.Object3D.prototype.traverse` | `engine/graphics/ecs/highlight/renderer/traverseThreeObject.js:7`; imported by `engine/asset/loaders/GLTFAssetLoader.js:9` and `engine/graphics/material/optimization/MaterialOptimizationContext.js:25`, while ~28 other sites call three's native `.traverse()` | `THREE.Object3D.traverse` | **JUSTIFIED (it adds a `thisArg`, which three's does not) / but misplaced** | Move it to `engine/graphics/three/` — the package's declared three-adapter boundary — rather than living under `highlight/renderer/` and being reached by a 4-level relative import from the asset loader | S / L |
+| K18 | LOW | `WebGLRenderTarget` option bags | 15 construction sites, each repeating `depthBuffer/stencilBuffer/generateMipmaps/minFilter/magFilter` | `engine/graphics/ecs/highlight/renderer/OutlineRenderer.js:232,241,250,259,268`, `engine/graphics/render/visibility/hiz/query/BatchOcclusionQuery.js:41`, `engine/graphics/texture/virtual/VirtualTextureUsageUpdater.js:105`, `engine/graphics/render/visibility/hiz/buffer/HierarchicalZBuffer.js:94` | — | **JUSTIFIED** — three's constructor *is* the primitive; a wrapper would need per-field override sentinels, which the "uniform control flow" rule forbids. Only `OutlineRenderer`'s 5 adjacent near-identical bags are worth a local named-constant pair | — | — |
+| K19 | — | three.js texture format / type / wrap translation | 1 composed family, no duplicates | `engine/graphics/texture/channelCountToThreeTextureFormat.js:9`, `computeThreeTextureFormat.js:10`, `attribute_spec_to_three_format.js:12`, `formatToChannelCount.js:19`, `computeThreeTextureFormatFromDataType.js` (`@deprecated`, delegates) | — | **CLEAN — no finding**, and the counter-example that proves the pattern works: one `switch`, everything else composes onto it | — | — |
+| K20 | LOW | `document.createElement('canvas')` + size + `getContext` | 10 production sites | `engine/graphics/GraphicsEngine.js:492`, `engine/graphics/makeModelView.js:15`, `engine/graphics/render/RendererPool.js:9`, `engine/graphics/texture/sampler/sampler2d_to_data_url.js:14`, `engine/graphics/texture/sampler/convertTexture2Sampler2D.js:57`, `engine/asset/loaders/image/codec/NativeImageDecoder.js:14`, `engine/asset/loaders/material/computeImageBitmapEquality.js:61` | — | **JUSTIFIED** — 3 lines, and the contexts requested differ (`2d` vs `webgl2` vs none) | — | — |
+| K21 | — | `clamp` / `lerp` / `DEG_TO_RAD` adoption | 1 inline clamp in the whole tree | only `core/graph/metis/native/bisection/fm_2way.js:50` nests `Math.min(Math.max(…))`; `Math.PI/180` appears inline 3× and all 3 are named constants for a fixed angle | `core/math/clamp.js`, `lerp.js`, `DEG_TO_RAD.js` | **CLEAN — no finding.** The 129 "inline lerp" pattern hits are flat-array vector math (`a + (b-a)*t` on `Float32Array` offsets), where a scalar `lerp` call is not the same operation | — | — |
+| K22 | — | grid index ↔ coordinate (`y*width + x`) | ~25 inline sites | `engine/graphics/texture/sampler/Sampler2D.js:488`, `engine/graphics/sh3/lightmap/lightmap_denoise.js:60`, `engine/physics/fluid/ecs/FluidObstacleSystem.js:335` | — | **JUSTIFIED** — one arithmetic expression in hot per-texel loops; extracting it is a pure pessimisation with no correctness payoff | — | — |
+
+## Per-concern detail
+
+### 1. Hash combination
+`core/collection/array/combine_hash.js` is the house primitive and is **well adopted — 62 importing files**.
+Against that, **33 files** still hand-roll `h = h*31 + v` (74 statements). The worst concentrations are
+`engine/physics/ecs` (Joint 13, RigidBody 12, Collider 4) and `core/geom/3d/shape` (7 files). These are
+determinism/dedup hashes, called at checkpoints, not in inner loops — `combine_hash` is variadic (rest-arg
+allocation), which is a fair reason to avoid it *there*, but not a reason to hand-inline a mix: the fix is a
+2-arg `hash_combine(h, v)`. The mixes are **not** the same function once you account for truncation
+(K1a): `|0` per step, `>>>0` at the end, or never — four disciplines in five sibling functions, and
+`uint32_array_hash` leaks out of int32 entirely. Two further shared defects (K2 `offset` handling, K3
+endianness) were copied into every clone, which is the clearest evidence in this audit that duplication here
+propagates bugs rather than merely wasting lines.
+
+### 2. `equals()` / epsilon comparison
+`core/math/epsilonEquals.js` exists (10 importers) and `EPSILON = 1e-7`, `FLT_EPSILON_{16,32,64}` are all
+provided. 23 inline `Math.abs(a-b) < eps` sites remain, but **every one passes a domain tolerance** chosen for
+its algorithm (`PLANE_EPS = 1e-3`, `BARY_EPS = 1e-6`, `SEGMENT_EPS = 1e-12`, `DIR_EPS = 1e-18`), and about
+half are `>` not-equal tests. This is **not** a reuse failure. The one real hazard is K14: four modules declare
+a local `const EPSILON` with values from `1e-9` to `1e-17`, colliding with the imported `1e-7` name. Vector-level
+tolerant comparison is already consolidated on `roughlyEquals`/`_roughlyEquals` (`Vector2.js:696`,
+`Vector3.js:867`, `Quaternion.js:1479`, `ConicRay.js:83`).
+
+### 3. Linear scan by id
+**22** explicit for-loops that scan for `.id`/`.name`/`.key` and return the match, plus ~20 more written as
+`Array.prototype.find`. Verdict is deliberately **not** "extract a helper": the only generic form is either
+string-keyed (`find_by(array, 'name', x)` — forbidden by the typed-over-magic rule) or a closure, which
+`Array.prototype.find` and `core/collection/array/array_index_by_equality.js` already are. The finding that
+survives is the **miss sentinel**: `Type.getFieldByName` returns `null`, `AttributeGroupSpec.getAttribute` and
+`GridData.getLayerById` return `undefined`, index-returning variants return `-1`. Three conventions for the
+same question, and the `null` returns contradict the no-null-defaults house rule.
+
+### 4. Binary search / lower bound
+Six real implementations (the 30 `binary_search_inline` pattern hits are mostly `>> 1` bit arithmetic and
+quicksort pivots — false positives). `core` provides two, `engine` hand-rolls four. They disagree on the two
+questions that matter: what is returned on a **miss**, and which index is returned inside an **equal run**.
+`AnimationCurve.js:238` is the only one that explicitly handles duplicate keys (it fast-forwards past the equal
+run at `:249`) — and it had to, because the shared `binarySearchHighIndex` would have handed it an arbitrary
+one. `table_find_min_index_in_ordered_column`'s JSDoc claims "low index of matching value"; the code does not
+deliver that. `bake_probe_sh3_resampled.pick_candidate` is the only correct `lower_bound` in the tree.
+
+### 5. Seeded vs unseeded randomness
+Two questions, two different answers. **How many RNGs?** Only two (Mulberry32, Mersenne Twister), with
+`seededRandom` aliasing the former — this is clean, no finding. **How many raw `Math.random()`?** Eleven, of
+which four matter. `WeightedRandomActionDescription.js:31` and `RandomDelayBehavior.js:9` seed *behaviour trees*
+from wall-clock/`Math.random()`, which defeats replay, rewind (`engine/network/sim/RewindEngine.js`) and the
+action-log replication model. `MLS_MPM.add_rnd_square` (`:388`) is the only shape-sampling function in the tree
+that does not take a `random` argument — every `sample_random_point_in_volume` in `core/geom/3d/shape/` does.
+`ReverbEffect.js:59` bakes a fresh noise impulse response each session, so the same event sounds different run
+to run. The remaining seven (minimap jitter, VFX seed, debug tile colour, a `@deprecated` sound picker) are
+cosmetic and fine.
+
+### 6. Weighted random selection
+Better consolidated than the brief suggested: `random_pick_weighted_index`, `weightedRandomFromArray` and the
+two `UnionShape3D` sites all funnel into `binarySearchHighIndex`, and `MarkerNodeActionSelectWeighted.js:92`
+already uses the core helper. Only one hand-rolled selector remains — `pick_candidate` in
+`bake_probe_sh3_resampled.js:53` — and it is justified (module-static `Float64Array`, no comparator closure, per-probe
+inner loop). The finding is not duplication but disagreement: `pick_candidate` is a true `lower_bound` and so can
+never select a zero-weight entry; the shared path can, because `binarySearchHighIndex` returns an arbitrary index
+inside an equal cumulative run.
+
+### 7. Typed-array growth
+**22 independent grow implementations, 5 distinct growth policies**, and `core/collection/array/typed/` has no
+grow helper despite holding copy/hash/convert/normalise helpers. Policies range from `cap << 1` (unbounded
+doubling from a possibly-zero start — `PairList.js:91` would loop forever at `cap === 0`) to
+`max(cap*1.5, cap+64)`. This is the cleanest **PROMOTION** in the audit: one function, no semantic choice to
+make, and every call site is already isolated inside a private `#grow`/`__grow_capacity`/`ensureCapacity`.
+Six further sites in `engine/network/transport` do exact-size defensive byte-slice copies (K7) — a different,
+equally trivial promotion.
+
+### 8. Object pooling
+`core/model/object/ObjectPoolFactory.js` has 6 importers. Applying the brief's own distinction: the
+module-static scratch objects (`weightedRandomFromArray.js:10`, `sort_decal_data.js:1`,
+`bake_probe_sh3_resampled.js:37`) are idiomatic and **not** findings. The free-list allocators
+(`core/bvh2/bvh3/BVH.js:156`, `core/geom/2d/bvh/BVH2D.js:111`, `core/geom/3d/tetrahedra/TetrahedralMesh.js:127`,
+`core/geom/3d/topology/struct/binary/BinaryElementPool.js:40`) are **slot** allocators over typed arrays —
+a different concept from `ObjectPoolFactory`'s object recycling, and three of them already delegate to
+`BinaryElementPool`. **No genuine hand-rolled duplicate of `ObjectPoolFactory` was found.** The one soft spot
+is `core/cache/wtinylfu/CacheWTinylfu.js:757` (`pool.length > 0 ? pool.pop() : new CacheElementWTinylfu()`),
+a 1-line inline pool in a hot cache path — justified.
+
+### 9. three.js translation at non-boundary sites
+The 208 `from 'three'` imports are *not* the story: 26 of them are in `engine/graphics/ecs`, which is a
+rendering-binding layer by design. Checking the four candidate translations named in the brief:
+texture format/type/wrap enum mapping is **cleanly factored** (K19) — one `switch`, everything composes;
+`WebGLRenderTarget` construction is 15 vendor option bags with no shared logic to extract (K18);
+`BufferGeometry` attribute setup (179 `setAttribute`/`BufferAttribute` sites) is genuinely per-geometry;
+`Object3D` traversal has one helper that duplicates three's own but adds `thisArg`, merely misplaced (K17).
+The one real repeat is **material `onBeforeCompile` marker injection** (K13): three copies of a 25-line
+guard/clone/mark envelope that disagree on whether they clone, one of which contains a dead `result.clone();`.
+
+### 10. ECS System lifecycle boilerplate
+58 `extends System` classes tree-wide: 44 define `link`, 43 `unlink`, 23 `startup`, 18 `shutdown`.
+Signal subscribe/unsubscribe is **balanced in all 17 systems that subscribe** — no leak pattern at the census
+level. The duplication is the per-entity record: **17 systems** build a record in `link`, store it at
+`this.data[entity]`, and `delete this.data[entity]` in `unlink`, while **7 systems** get exactly that from
+`engine/ecs/system/AbstractContextSystem.js`. A typed shared helper is viable, but the existing one is not the
+one to spread: its `link()` reads `arguments` positionally and copies components into `ctx.components[i]`
+(`AbstractContextSystem.js:69-90`), i.e. untyped variadic dispatch — the house style's stated objection. The
+honest recommendation is arity-specific typed bases with named parameters, then migrate.
+
+### 11. Other systemic patterns checked
+Checked and **clean, no finding**: `clamp` (1 inline site tree-wide), `lerp`, `smoothStep`,
+`DEG_TO_RAD`/`RAD_TO_DEG` (3 inline `Math.PI/180`, all named angle constants), dB↔linear
+(`engine/sound/dB2Volume.js` + `volume2dB.js` are the single pair; `EventInstance.js:34` and
+`echogram_band_rt60.js:49` are distinct formulas, not copies), sRGB↔linear (`core/color/sRGB/`, one impl;
+the shader-side uses three's own), string padding/`toFixed` (no repeated formatter), grid index↔coord (K22),
+`Object.assign` shallow clone (9 sites, all genuinely different objects), `JSON.parse(JSON.stringify())`
+deep clone (3 sites, all in cold paths).
+
+## Notes — what structurally causes cross-cutting reuse failure here
+
+1. **The primitives exist and are known; the gap is at the *last mile*.** `combine_hash` has 62 importers,
+   `seededRandom` 63, `clamp`/`lerp` are near-universal. Reuse failure is not ignorance of `core/` — it
+   concentrates in the last two lines of an otherwise-reusing function (`h = h*31 + v` written inline inside a
+   `hash()` that already imports three other core helpers).
+2. **The missing primitives are the ones nobody thought to name.** Typed-array growth (22 impls) and
+   defensive byte-slice copy (6 impls) have no `core/` home at all — and both are single-signature functions
+   with zero design choices. Where `core/` names a concept, the codebase converges on it; where it does not,
+   it diverges 22 ways.
+3. **Copy-paste is the propagation vector for defects, not just for lines.** The `offset`/`length` confusion
+   (K2) exists identically in five hash functions; the four-way truncation disagreement (K1a) exists because
+   each was typed fresh; the live-pivot quicksort (K4a) is a copy that dropped one line
+   (`const pivot = data[pivotIndex]`); the dead `result.clone();` in the GI material transformer (K13) is a
+   copy that dropped an assignment. Every ⚠ in this report is a *divergence introduced by copying*, not an
+   independently-invented alternative.
+4. **When a shared abstraction violates the house style, adoption stalls and the duplication grows around it.**
+   `AbstractContextSystem` is the correct abstraction for 24 systems and has 7 users; the other 17 hand-roll it.
+   Its `link()` is `arguments`-based magic. This is the codebase telling you which rule wins.
+5. **Family functions written as siblings rather than as one function plus adapters drift.** The five array-hash
+   functions, the four quicksorts in `core/collection/array/`, the two binary searches — each family was written
+   as N parallel files, and each family now disagrees internally. The texture-format family (K19), written as
+   one `switch` plus composing wrappers, is the counter-example and has no drift at all.

package/src/DUPLICATION_AUDIT_2026_08_07.md

@@ -0,0 +1,254 @@
+# meep — unjustified code duplication audit
+
+**Date:** 2026-08-07
+**Scope:** `meep/src/**` (+ `meep/editor/**` for the view domain). 5,321 `.js` files.
+**Excluded from findings:** `*.spec.js`, `prototype*.js` / `test*.js` browser harnesses, `samples/**`.
+
+---
+
+## 1. The headline
+
+The interesting result is not that meep repeats itself. It is **what the repetition costs**.
+
+Across 241 verified findings, the recurring failure mode is not wasted lines — it is **fixes that
+reach one copy and not the others**. In every pair below, someone found a bug, reasoned about it,
+often wrote a comment explaining it, and fixed the copy in front of them. The twin still has the bug.
+
+✔ = re-verified against source during the adversarial pass on this document; the rest are as reported
+by the domain reviewers and carry their evidence in §8.
+
+| ✔ | Fix that landed | Twin that never got it | Consequence |
+|---|---|---|---|
+| ✔ | `IndexedDBStorage.store()` (`engine/save/storage/IndexedDBStorage.js:98`) resolves on transaction **commit**, with a comment: reporting success off the request "turns a lost save into a reported save" | `IndexedDBStorage.remove()` (same file, `:45`) still resolves on `idbRequest` `success` (`:57`) | A delete is reported durable when its transaction later aborts |
+| ✔ | `inOpen` BitSet mirror — *"O(1) replacement for linear heap.contains scans"* — in `GridTaskBuildSourceDistanceMap.js:103` and `GridTaskGenerateRoads.js:125` | `GridTaskConnectRooms.js:292` still calls `open.contains(...)` | The optimisation reached 2 of 3 grid searches |
+| ✔ | `canvas2d_draw_linear_scale.js:46` uses `Math.floor`, with a comment: *"using ceil would place a final tick past position_1 with an extrapolated value"* | `canvas2dDrawWorldAxisLabels.js:44` still `Math.ceil`, commented only *"// number of marks"* | Over-extrapolated axis ticks |
+| ✔ | `removeEntityWithEffect` (`engine/animation/AnimationUtils.js:179`) adds `SerializationMetadata.Transient` | `engine/animation/removeEntityWithMeshParticlesEffect.js` — no `SerializationMetadata` reference at all | Effect entities leak into saves |
+| ✔ | `CellFilterGaussianBlur.js:99` centres taps at `(samples - 1) * 0.5`, commented *"the kernel spans ±(samples-1)/2 indices"* | `PointFitnessGaussianBlur.js:67` uses `(samples / 2)` | Off-centre by half a sample: for 5 taps the window runs −2.5…+1.5 instead of −2…+2 |
+| ✔ | `array_quick_sort_by_lookup_uint.js:40` captures the pivot **value** before partitioning | `sort_decal_data.js:70,74` compares against the live pivot **index** through the array it is swapping | Partition invariant breaks once the pivot element moves |
+| ✔ | `forward_plus/plugin/MaterialTransformer.js:105` — `result = source.clone()` | `sh3/gi/material/MaterialTransformer.js:311` — `result.clone();`, **return value discarded** | Mutates the caller's material |
+| | BVH `balance_rotate` (Box2D-v3 SAH rotation) | `BVH2D` still on height-only AVL rotation | 2D tree builds worse-quality trees |
+| | `Trail3DSystem.js:31-45` documents a head-seeding bug | `Trail2DSystem.js:157` still exhibits it under rotation/scale | Wrong trail head under transform |
+| | `BinaryUint32BVH` scratch-stack seeding | `StaticR2Tree` fork carries an indexing bug the original lacks | 2D static tree mis-builds |
+| | `bt_radial_loop_add` performs the self-link | one of its 3 copies omits it | Works only via an undocumented `loop_initialize` dependency |
+| ✔ | Bounds-checked action-header read `in_buffer.position + ACTION_HEADER_BYTES > in_buffer_end`, guarding against "stale/out-of-bounds bytes — process crash on OOB" (`replication/Replicator.js:222` comment) | Written **three times in one method**: `:224`, `:256`, `:272`, each with its own paired payload-length check at `:229`, `:261`, `:277` | Security-relevant bounds check hand-repeated; a hardening change must land in all six |
+
+**That is the argument for acting on this report.** The line-count savings are secondary; the
+divergence risk is not. A useful heuristic fell out of the audit: *in a duplicated pair, the file
+carrying the explanatory comment is the fixed one, and its twin still has the defect.* That heuristic
+held in every re-verified row above.
+
+---
+
+## 2. How this was found
+
+Five layers, because no single technique finds all of it:
+
+| Layer | Technique | Yield |
+|---|---|---|
+| 1 | Custom JS tokeniser + brace-matched function extraction; identifiers blinded; SHA-1 grouping | 110 token-identical clone groups; 79 more identical incl. member names |
+| 2 | MinHash (64 hashes) + 16-band LSH over 6-gram shingles, Jaccard ≥ 0.70 | 241 near-duplicate function *pairs* (coincidentally equal to the final finding count — unrelated numbers); 23 whole-file pairs |
+| 3 | 30 hand-written semantic patterns (inline lerp / length / clamp / hash-mix / binary search) | 129 inline-lerp, 78 inline-length3, 74 hash-mix, 30 binary-search hits |
+| 4 | Import graph, orphan detection, basename + camel/snake collision sweep | 27 basename collisions, 598 files with no importer, 21 rename-alias pairs |
+| 5 | 11 agents verifying by reading the code, one per domain + one cross-cutting | 241 findings; ~90 leads dismissed |
+
+**Layers 1–2 are blind to GLSL inside template literals.** The single largest duplication in the
+graphics domain — the octahedral impostor shader library — was found only in layer 5. Any future
+sweep of this codebase must treat shader source as a first-class corpus.
+
+---
+
+## 3. Findings — CRITICAL
+
+| # | Concept | Sites | Evidence | Proposed common path | Effort |
+|---|---|---|---|---|---|
+| C1 | **Dynamic AABB tree (Box2D-style) implemented twice; the 2D fork has diverged.** Node allocator, free list, capacity growth, SAH insertion, rotation, refit, node swap, traversal. | `core/bvh2/bvh3/BVH.js` (class `BVH`) ⟷ `core/geom/2d/bvh/BVH2D.js` (class `BVH2D`) | **32 of BVH2D's 33 methods share a name with BVH's 37** (method-name census, this audit). Only `balance` differs (`balance_height`/`balance_rotate` in 3D). Column constants (`COLUMN_PARENT`, `NULL_NODE`, `ELEMENT_WORD_COUNT`…) are duplicated exports. 2D lacks `balance_rotate`, `allocate_linear`, `node_assign_children*`, the `data_buffer` serialisation accessors, and `size`. | Extract the dimension-independent tree over an abstract "AABB word count + surface-area metric" seam; keep 2D/3D AABB ops specialised. | **L** |
+| C2 | **Octahedral impostor GLSL library copy-pasted.** `VecToSphereOct` + `VecToHemiSphereOct` + sampling helpers. | `VecToSphereOct` declared **10×** across **8 files**: `ImpostorShader{V0:71, DepthV0:59, NormalsV0:52, ViewportDepthV0:46, WireframeV0:31}`, `ImpostorShaderLitV0.js:65` **and** `:328`, `ImpostorShaderPerPixelV0.js:39` **and** `:178`, `sh3/gi/material/common.js:118` | **2 distinct bodies** (counts verified in this audit — see §7 for the correction). 9 impostor copies are byte-identical and use GLSL `sign()`, which returns **0.0** at exactly 0.0 and collapses the mapping on axis-aligned directions. `common.js` and the CPU bake reference `octahedral_direction_to_uv.js` use `sign_not_zero()` (±1). The two disagree precisely on the axis-aligned cases. | `engine/graphics/shaders/chunks/octahedral.js` as named string exports. The raw-loader path already works — `ImpostorShaderV1.js:10` imports a `.glsl` file. | **M** |
+| C3 | **Production GI probe-depth GLSL copied into its own debug visualiser.** | `sh3/gi/material/common.js:76-298` ⟷ `sh3/lpv/depth/octahedral/v2/visualise.frag.glsl:26-408` ⟷ `.../shader/visualize.frag.js` | 220 of 320 lines verbatim, shared typo `quadBlendWieghts` included. A visualiser that has forked from the thing it visualises can silently lie. | Same shader-chunk module as C2. | **M** |
+| C4 | **ActionLog record wire-format hand-parsed in 5 independent readers; written in 1.** Format exists only as a docblock comment. | writer `sim/SimActionExecutor.js:242-302`; readers `replication/Replicator.js:335` `#scan_record_in_scope`, `:376` `#copy_action_to`, `sim/RewindEngine.js` `#skip_record` + `#restore_prior_state`, `orchestrator/ServerAuthoritativeServer.js` `#read_historical` | Six coordinated edits for any format change, with zero compile-time coupling. | A single typed record cursor (`ActionRecordReader`) with `next()`/field accessors; all five readers drive it. Not a registry — a typed class. | **M** |
+| C5 | **Two complete ECS animation runtimes over three.js `AnimationMixer`.** | `engine/ecs/systems/AnimationSystem.js:179` (+`ecs/animation/{Animation,AnimationClip,AnimationClipFlag}.js`) ⟷ `engine/graphics/ecs/animation/**` (`AnimationGraphSystem`, `AnimationGraph`) | `screenSpaceSize` and `shouldEntityBeAnimated` copy-pasted verbatim including the `areaInPixel < 32` threshold. **`AnimationClipFlag` exists twice, both assigning `1`** — `ClampWhenFinished` in `engine/ecs/animation/AnimationClipFlag.js` vs `Repeat` in `engine/graphics/ecs/animation/animator/AnimationClipFlag.js` (both verified). That byte is serialised: `engine/ecs/animation/AnimationClip.js:124` `buffer.writeUint8(this.flags)`. | Decide which runtime is canonical; at minimum give the two flag enums non-colliding values **before** more saves are written. | **L** |
+| C6 | **No canonical `hash_combine`, and the hand-rolled mixes disagree.** ⚠ INCONSISTENT | `combine_hash` has **62** importers, yet **33** files still hand-roll `h*31+v` (74 hits project-wide) — both counts re-verified. Five sibling array-hash functions use **four different int32-truncation disciplines** (`\|0` per step / `>>>0` at end / never). | `uint32_array_hash` never truncates; its accumulator escapes int32 into a double — on exactly the workload `CSRGraph.hash()` feeds it. Separately, all five loop `i < length` while their JSDoc treats `length` as a **count**; `uint8_array_hash` contradicts itself between its head and body loops. | Make `combine_hash` the only mixer; fix the five array hashes to one truncation discipline and one `(array, offset, length)` contract. | **M** |
+
+---
+
+## 4. Findings — HIGH (selected; 51 total)
+
+| # | Concept | Sites | Verdict | Proposed common path |
+|---|---|---|---|---|
+| H1 | Boolean and distance-returning AABB-vs-ray-segment slab tests whose **docs state they must agree** are independent copies of subtle NaN handling | `core/geom/3d/aabb/aabb3_intersects_ray_segment.js:35` ⟷ `aabb3_ray_segment_entry_distance.js:40` | UNJUSTIFIED | 45 lines character-identical; differ only in the last 4. Boolean delegates to the distance version. **S** |
+| H2 | BVH traversal-order invariant duplicated and drifted ⚠ INCONSISTENT | 8 files carry the byte-identical comment *"write to stack in reverse order, so that fist child ends up being visited first"* (typo included). **2 match it** (`bvh_query_leaves_generic.js:65`, `bvh_query_user_data_generic.js:74`); **6 contradict it** (`bvh_collect_user_data.js:52`, `..._intersects_aabb.js:74`, `..._capsule.js:92`, `..._frustum.js:73`, `..._sphere.js:83`, `compute_tight_near_far_clipping_planes.js:182`) | UNJUSTIFIED | Specialised queries emit the same result **set** in the opposite **order** from the generic ones. Result order is observable and `determinism.spec.js` is a standing gate. Pick one order, fix the comment, add a test asserting generic and specialised agree. **M** |
+| H3 | Solver impulse application written twice | `physics/constraint/solve_constraints.js:250` `apply_impulse` ⟷ `physics/solver/solve_contacts.js:401` `apply_impulse_to_body` | UNJUSTIFIED | Arithmetic identical statement-for-statement. **Signatures differ**: 10 params + module-scope `scratch_inertia` vs 11 params with scratch passed in (verified — see §7). Keep the caller-provided form; the module-scope one shares state between call sites. **S**, determinism-safe if copied verbatim |
+| H4 | SAT minimum-overlap computed three ways, one diverging ⚠ INCONSISTENT | `narrowphase/box_box_manifold.js:135` `(rA+rB)-dist`; `box_triangle_contact.js:209` `min(bmax-tmin, tmax-bmin)`; `convex_convex_manifold.js:261` | UNJUSTIFIED | `convex_convex_manifold` uses interval-**intersection length** where the others use **push-out distance**. These differ under projection containment (a thin decomposed piece inside a fat one), and SAT takes the minimum — so it likely under-reports depth. **Needs a correctness decision, not a merge.** **M** |
+| H5 | Point-in-closed-surface classifier (BVH build + 3-ray parity vote) copy-pasted | `core/geom/3d/tetrahedra/tetrahedral_mesh_carve_outside_surface.js:19,33,81,127` ⟷ `core/geom/3d/topology/struct/binary/query/bt_mesh_sample_interior_grid_points.js:12,29,78` | UNJUSTIFIED | `build_surface_bvh` token-identical (435 tokens), including the magic ray directions. Promote to `core/geom/3d/query/point_in_closed_surface.js`. **M** |
+| H6 | Radial-cycle splice (half-edge face-ring invariant) written 3×, two behaviourally different ⚠ INCONSISTENT | `bt_radial_loop_add.js:9` (exported, canonical) ⟷ `face/bt_face_poke.js:130` `_link_loop_to_edge_local` ⟷ `bt_mesh_from_indexed_geometry.js` `link_loop_to_edge` | UNJUSTIFIED | Opposite insertion side; one copy omits the self-link. One copy's comment claims the canonical function "is not exported" — **it is**. **S** |
+| H7 | `StaticR2Tree` is a 2D fork of `BinaryUint32BVH` | `core/bvh2/binary/2/BinaryUint32BVH.js:336,411,426` ⟷ `core/geom/2d/r-tree/StaticR2Tree.js:210,296,313` | UNJUSTIFIED | `build` token-identical (289 tokens). Fork carries a bounds-copy bug (`array_copy(...,6)` on a 4-float 2D box) documented in an in-tree comment. **M** |
+| H8 | Relative-epsilon quadratic solver written 3×, deliberately bypassing `solveQuadratic` | `core/math/spline/spline3_hermite_bounds.js:22`, `spline3_hermite_bounds_t.js:26`, `spline3_bezier_bounds.js:20` vs `core/math/solveQuadratic.js:15` | UNJUSTIFIED | The bypass is *reasonable* — `solveQuadratic` still uses an absolute epsilon — but it makes 4 places to fix, with the justifying comment copy-pasted verbatim. Fix `solveQuadratic` to relative epsilon, then collapse. **M** |
+| H9 | `Uint32Heap4` is a whole-file copy of `Uint32Heap` | `core/collection/heap/Uint32Heap.js:56` ⟷ `Uint32Heap4.js:59` | UNJUSTIFIED | 194/208 lines identical; only 4 of 22 members carry the arity difference. **M** |
+| H10 | Triangle-vertex fetch from a normalised/implicitly-indexed buffer copy-pasted 3×, comment-for-comment | `geometry/buffered/query/bvh32_geometry_{nearest.js:151, raycast.js:59, overlap_clipping_volume.js}` | UNJUSTIFIED | ~45 lines each: index resolve → 3 addresses → 9 reads → 9 denormalisations. **S** |
+| H11 | Nearest-point-on-mesh implemented twice against two BVH layouts | `bvh32_geometry_nearest.js:37-247` ⟷ `query_bvh_geometry_nearest.js:35-208` | UNJUSTIFIED | Leaf bodies token-identical. **M** |
+| H12 | Material-texture coalescing loop duplicated — **and the extracted helper already exists, unused by both** | `material/manager/compilers/CoalesceTextures.js:25-69` ⟷ `asset/loaders/material/StaticMaterialCache.js:48-89`; helper at `asset/loaders/material/traverseMaterialTextures.js:9` | UNJUSTIFIED | 40 byte-identical lines. **S** |
+| H13 | Shadow-ray "segment clear of occluders" test written 3× | `sound/simulation/probe/probe_edge_visible.js:20`, `probe_refine_connectivity.js:168` `segment_clear`, `AcousticProbeField.js:328` | UNJUSTIFIED | `probe_edge_visible`'s own doc **falsely claims** it is the single shared test. **S** |
+| H14 | Listener resolution + `sopra.update()` duplicated in two ECS systems sharing **one** `SopraEngine` | `sound/ecs/emitter/SoundEmitterSystem.js:137-158` ⟷ `sound/ecs/audio/AudioEmitterSystem.js:246-315` | UNJUSTIFIED | Co-registering both (the documented design intent) **double-ticks the shared engine**. This is a bug, not hygiene. **M** |
+| H15 | Container child-hash fold copy-pasted into 4 subclasses; base owns `children` but has **no `hash()`** ⚠ INCONSISTENT | `sopra/definition/clip/ContainerAudioClip.js:80` `equals` (no `hash`); `BlendContainerAudioClip.js:108` `equals` / `:126` `hash` | UNJUSTIFIED | Verified: `BlendContainerAudioClip.equals()` compares `blends`; `hash()` does **not** fold them. Two objects differing only in `blends` compare unequal but hash equal. **S** |
+| H16 | Collocated `v3_grid_advect_*` family (5 files, ~555 LOC) shadows the MAC family and has **zero importers** | `v3_grid_advect_sl_velocity.js`, `v3_grid_apply_advection_forward.js`, `v3_grid_apply_scalar_advection.js`, `v3_grid_advect_maccormack_{scalar,velocity}.js` | UNJUSTIFIED | Full shadow copy of SL/MacCormack/limiter/solid handling; copies have already drifted. **meep is a library, so this is not a deletion recommendation** — collapse the internal redundancy. **M** |
+| H17 | `AbstractContextSystem` is the engine's own typed answer to per-entity link/unlink — adopted by 7 systems, hand-rolled by 17 more in 3 incompatible conventions | e.g. `ViewportPositionSystem` subscribes **six** listeners and unsubscribes **five** | UNJUSTIFIED | The blocker is genuine: the existing base dispatches through `arguments`, i.e. exactly the "magic" the house style rejects. Recommendation is **typed arity-specific bases**, not spreading the current one. **L** |
+| H18 | Transport adapters copy-paste `getStats()` (×6) and the disconnect latch (×3) instead of using the base | `transport/{Loopback,WebSocket,WebRTCDataChannel,Simulated,WebTransport}Transport.js` | UNJUSTIFIED | `WebTransportTransport` is **missing** the latch the other three independently invented. **S** |
+| H19 | `send_fragmented` / `resend_fragment_chunk` duplicate the header write with **two different `total_chunks` formulas** ⚠ INCONSISTENT | `network/transport/fragments/fragment_send.js` | UNJUSTIFIED | **S** |
+| H20 | Trail 2D/3D whole-file fork | `ecs/trail2d/Trail2DSystem.js` (274 ln) ⟷ `ecs/trail3d/Trail3DSystem.js` (280 ln); `Trail2D.js:210,298` ⟷ `Trail3D.js:275,417` | UNJUSTIFIED | ~85% shared; the 3D copy documents a head-seeding bug the 2D copy still has. **M** |
+
+*(Remaining HIGH rows — SH sign-convention divergence across 4 evaluators, voxel-impostor GLSL ×5, CSR-builder absence, `AnimationClipFlag`, quicksort family, Robin-Hood map machinery, LPG/gi fork, grid-Dijkstra ×3, `ImageView`/`VideoView`, `GroupView` link bug, `NumericInterval` invariant ×3 — are in the per-domain files listed in §8.)*
+
+---
+
+## 5. Promotion opportunities — primitives that should exist and don't
+
+These are the cheapest wins: additive, no behaviour change, and each already has ≥2 consumers
+re-deriving it.
+
+| # | Missing primitive | Proposed home | Consumers re-deriving it today |
+|---|---|---|---|
+| P1 | **Typed-array growth / capacity doubling** | `core/collection/array/typed/typed_array_grow.js` | **22 independent implementations, 5 different growth policies, no core helper at all.** Heaps, CSR graphs, BVH, particle pools, trail buffers, action logs. Single signature, no design choices — the cleanest promotion in the audit. |
+| P2 | **`hash_combine` as the only mixer** | `core/math/hash/` (exists; enforce it) | 33 files hand-roll `h*31+v`; 5 array hashes disagree on truncation (see C6) |
+| P3 | **Edge-list → CSR builder** | `core/graph/csr/` | `core/graph/csr` ships *consumers* but no *builder*; `sound/simulation/probe/bakeVisibility.js:109` and `probe_visibility_augment.js:50` each wrote one. This single gap spawned 4 findings. |
+| P4 | **`v2_rotate(out, x, y, radians)`** | `core/geom/vec2/` | The 2D rotate-a-local-offset formula is inlined **8×** in `generation/`; `core/geom/vec2/` has no `v2_rotate` |
+| P5 | **`tri3_closest_point_barycentric` world-point variant** | `core/geom/3d/triangle/` | Returns barycentrics; **every caller** immediately writes the same reconstruction arithmetic. (Count reported inconsistently as 12 vs 16 across physics/core/graphics — enumerate before acting.) |
+| P6 | **`line3_segment_segment_closest_points` point variant** | `core/geom/3d/line/` | Returns `(s,t)`; all 4 physics callers immediately lerp both segments |
+| P7 | **`quat3_nlerp`** | `core/geom/3d/quaternion/` | Genuinely absent; inlined 3× in network adapters — one site comments *"use the static helper variant if available"* |
+| P8 | **GLSL chunk module** | `engine/graphics/shaders/chunks/` | Octahedral, SH, packing, frame primitives. Retires C2, C3 and ~4 more findings — on the order of **1,400 lines** of copied shader source (reviewer estimate, not counted by tooling, since layers 1–2 cannot see GLSL). `ShaderChunks.js` already proves the pattern; the clouds feature uses it correctly. |
+| P9 | **`FrameBufferRing`** (per-frame `BinaryBuffer` ring) | `core/collection/` | `network/sim/ActionLog.js:49` ⟷ `network/state/InputRing.js:37` — constructors 97% identical, `buffer_for`/`write_end_for` token-identical; only the framing policy differs |
+| P10 | **Binary codec for engine value types** | `core/geom/*/serialization/` | `Transform` has **5** hand-maintained encodings, `Vector3` ~14, `Quaternion` 6, coupled by nothing. `Vector3.toBinaryBuffer` is `@deprecated` in favour of *nothing*, so 9 adapters regressed to inline `writeFloat64(v.x/y/z)`. The one primitive that does exist (`v3_binary_equality_encode`) is reused by 3 adapters — proving the shape works. |
+
+---
+
+## 6. Leads ruled out — and three false-positive classes
+
+Roughly 90 mechanical leads were checked and rejected. Three classes would have produced confident,
+wrong rows, and are documented so the next sweep skips them:
+
+**(a) Re-export shims.** The earlier core→engine decoupling left deliberate 2-line shims. Verified:
+`engine/graphics/sh3/path_tracer/geometry/compute_triangle_group_aabb3.js`,
+`engine/graphics/render/forward_plus/read_frustum_corner.js`,
+`engine/graphics/texture/isImageBitmap.js`, `engine/network/convertPathToURL.js`,
+`engine/graphics/particles/particular/engine/parameter/ParameterLookupTable{,Flags}.js`.
+*Rule: engine-side copy ≤ 3 lines ⇒ shim.*
+
+**(b) `@deprecated` rename aliases.** A camelCase→snake_case migration (plus `vert`→`vertex`,
+`quat`→`quat3`, `shape`→`shape3`, `frustum`→`frustum3`) left ~21 old-name files, each
+`import X` + `@deprecated` + `export const oldName = X`, kept because **meep is a library and old
+names are public surface**.
+
+**(c) Same name, different function.** `core/math/gaussian(sigma, distance)` (un-normalised bell) vs
+`engine/graphics/texture/sampler/filter/gaussian(x)` (`sqrt(2/π)·exp(-2x²)`, with `.support = 1.25`)
+are genuinely different maths. A name hazard, not duplication — do **not** merge.
+
+Other notable rejections, with reasons:
+
+- **`TwoBoneInverseKinematicsSolver` vs `two_joint_ik` are not rivals.** This audit seeded that lead
+  and it was wrong: `engine/ecs/ik/TwoBoneInverseKinematicsSolver.js:11` imports `two_joint_ik` and
+  calls it at `:157`. It is a wrapper. *(The real duplication in those files is a ~75-line
+  terrain-probe prologue shared with `OneBoneSurfaceAlignmentSolver` — reported separately.)*
+- **Three `AnimationClip` classes are a naming problem, not code duplication** — three genuinely
+  different data models sharing a name.
+- **`node-based` vs `particular` particles**: an unfinished parallel system plus an export-name
+  collision, not a fork. `TubeX`/`RibbonX`: a genuine rewrite.
+- **Shape-boilerplate is deliberate.** Per-class `from()`/`hash()`/`equals()`/`fromJSON()` and the
+  sopra `serialize`/`deserialize` adapters were dismissed under the *typed over magic* rule. The
+  three sopra type-tag `switch` dispatchers are JUSTIFIED — core's `abstractJSONDeserializer` is
+  exactly the string-keyed registry the house style rejects.
+- **2D/3D and row/column-major scalar pairs** (`v2_*`/`v3_*`, `m3_cm_*`/`m3_rm_*`, `aabb2_*`/`aabb3_*`)
+  are justified specialisation.
+- **`IndexedFloatMin/MaxHeap`**: documented monomorphism choice.
+- **`PosedShape3D`'s inlined quaternion math**: measured, documented hot-loop carve-out.
+- **The 78 `inline_length3` / 129 `inline_lerp` pattern hits**: mostly misclassified dot products or
+  genuine per-triangle inner loops. Pattern 3's `binary_search_inline` was ~all false positives
+  (quicksort pivot arithmetic).
+- **`end_in_solid` triplication in the fluid solver**: carries a *measured* 8.6× perf contract.
+- **three.js texture-format translation**: written as one `switch` plus composing wrappers, it has
+  **no drift** — the useful counter-example to every family written as N parallel sibling files.
+
+---
+
+## 7. Corrections applied to agent findings
+
+Verified against the source; the report uses the corrected version:
+
+| Claim as reported | Correction |
+|---|---|
+| `VecToSphereOct` "declared **17 times** in **four** mutually incompatible conventions" | **10 declarations across 8 files, 2 distinct bodies.** (11 of the 21 occurrences are call sites; 2 files declare it twice, once per shader stage.) The substantive hazard — GPU copies use `sign()`, reference uses `sign_not_zero()` — is real and stated in C2. |
+| `apply_impulse` / `apply_impulse_to_body` "line-for-line identical" | Arithmetic is identical; **signatures are not** (10 params + module-scope scratch vs 11 params with scratch passed in). This changes the recommendation — keep the caller-provided form. |
+| BVH2D overlap: "521 of 576 code lines" (domain B) vs "~1000 lines" (domain A) | Three methods gave three numbers. Report uses the reproducible measure: **32 of 33 methods share a name**, overlap ≈ 90% of BVH2D. |
+| "Six files carry the comment while pushing `child1` first" | Right count, inverted description. Precisely: 8 files carry it, **2 match, 6 contradict** — the 6 push `child1` first in source order, which makes `child2` visited first. |
+| "Recommend **deletion** of `BinaryObjectSerializationAdapter2.js`" (493 ln, zero importers) | Downgraded to **removal candidate, owner's call** — collides with the standing rule that unreferenced exports in meep are public surface. Same for the "fully dead" `engine/sound/material/**`. |
+| `removeEntityWithEffect` cited as though it were its own file | **No such file exists.** The function is `engine/animation/AnimationUtils.js:168`, and the `SerializationMetadata.Transient` call is at `:179`. The finding is correct; the citation would have failed a spot-check. |
+| `PointFitnessGaussianBlur` "has the centring bug" | Correct, and sharper than stated: `CellFilterGaussianBlur.js:99` uses `(samples - 1) * 0.5`, the twin at `PointFitnessGaussianBlur.js:67` uses `(samples / 2)`. Note the two are 2D vs 3D and share no code — this is **re-derivation**, not copy-paste, so it would never have surfaced from clone detection alone. |
+
+**Error rate of the source material.** Eight §1 rows plus the C6 counts were re-verified:
+**every one was substantively true**, and the two independently-verified counts (`combine_hash`
+62 importers, 33 hand-rolled sites) were exact. But **2 of 8 carried a wrong or unciteable file
+reference**, and 3 of the sharpest claims elsewhere (`VecToSphereOct` counts, `apply_impulse`
+"line-for-line", the traversal-order direction) were overstated or inverted.
+
+The pattern is consistent: **the reviewers were reliable about *what* is duplicated and unreliable
+about *where* and *how much*.** Trust the per-domain files for the finding; spot-check the citation
+before acting.
+
+Two additional items found by this audit directly, with no agent assigned:
+
+- **Two mesh-simplification drivers.** `Quadric3` is correctly shared, but the driver is not: the
+  `TopoMesh`/`tm_*` stack (`simplifyTopoMesh.js` 263 ln — **no importer**; `simplifyTopoMesh2.js`
+  119 ln — imported **only by a prototype harness**; `decimate_edge_collapse_snap.js` 272 ln;
+  `edge_collapse_quadratic.js` 71 ln) parallels the live `bt_*` stack
+  (`bt_mesh_simplify_by_error.js` 590 ln, used by `engine/navigation/mesh/build/navmesh_build_topology.js:29`).
+  The two quadric *accumulation* loops walk different mesh representations, so **that** part is
+  justified; the driver is not.
+- **`core/geom/3d/sphere/harmonics/compute_legendre_polynomial.js` is a 0-byte file**, colliding by
+  name with the live `core/math/compute_legendre_polynomial.js` (50 ln). Cruft, not duplication.
+
+---
+
+## 8. Where the detail lives
+
+241 verified findings with full evidence, dismissed-lead lists and per-domain notes, in
+`src/DUPLICATION_AUDIT_2026_08_07/`:
+
+| Domain | Findings | File |
+|---|---|---|
+| `core/geom` + `core/math` | 30 | `A_core_math_geom.md` |
+| `core/` data structures, binary, graph, cache, parser, colour | 21 | `B_core_data.md` |
+| `engine/graphics` render / material / texture / geometry | 28 | `C_gfx_render.md` |
+| `engine/graphics` ecs / particles / trail / impostors / sh3 | 29 | `D_gfx_features.md` |
+| `engine/physics` | 22 | `E_physics.md` |
+| `engine/sound` (legacy + sopra + simulation) | 23 | `F_sound.md` |
+| `engine/network` + `engine/save` + `ecs/storage` | 25 | `G_net_save.md` |
+| `engine/` ecs / intelligence / animation / input / control / asset | 29 | `H_engine_misc.md` |
+| `generation/` + `view/` + `editor/` | 17 | `I_generation_view.md` |
+| Cross-cutting concerns | 17 | `K_crosscutting.md` |
+
+Also `00_core_reuse_surface.md` — a 598-row inventory of what `core/` already provides, built as the
+reference against which re-derivation was judged. Useful independently of this audit.
+
+### Confidence
+
+Severity split: 6 CRITICAL, 51 HIGH, 107 MEDIUM, 71 LOW, 2 explicit PROMOTION (plus 24 rows carrying
+a PROMOTION verdict inside other tiers). 158 rows are verdict `UNJUSTIFIED`, 11 explicitly
+`JUSTIFIED` (kept deliberately, so the reasoning isn't re-litigated later).
+
+Every row was produced by an agent that opened the files. Everything in §1, §3 and §7 of *this*
+document was additionally re-read during the adversarial pass. The MEDIUM and LOW tiers in the
+per-domain files have **not** been independently re-verified — treat the specific line numbers there
+as needing a spot-check before acting, and see §7 for the error rate that pass actually found.
+
+---
+
+## 9. Recommended order of work
+
+1. **C6 + P2 (hash consistency)** and **H2 (traversal order)** — correctness hazards under a standing
+   determinism gate, both cheap.
+2. **The fix-divergence table in §1** — each row is a known bug sitting in a known file. Mostly **S**.
+3. **P1, P3, P4, P7 (missing primitives)** — additive, no behaviour change, retire many findings.
+4. **P8 (GLSL chunk module)** — highest line-count leverage: ~1,400 lines, retires C2 + C3.
+5. **C5 flag collision** — do this *before* more saves are written.
+6. **C1 (BVH/BVH2D)** and **H17 (ECS lifecycle bases)** — largest and riskiest; schedule deliberately.
+
+**Two items need a decision, not a refactor:** H4 (SAT overlap semantics — which definition is
+correct?) and the C2 `sign`/`sign_not_zero` convention (unifying changes rendered output and needs a
+bake-vs-shader A/B first).