@woosh/meep-engine 3.1.0 → 3.3.0

package/src/DUPLICATION_AUDIT_2026_08_07.md

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