@woosh/meep-engine 3.1.0 → 3.2.0

package/src/DUPLICATION_AUDIT_2026_08_07/K_crosscutting.md

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