@woosh/meep-engine 3.0.2 → 3.2.0

package/src/DUPLICATION_AUDIT_2026_08_07/H_engine_misc.md

@@ -1,72 +1,72 @@
-# Domain H — engine (ecs, intelligence, animation, input, control, asset, misc)
-
-Source root: `H:/git/moh/app/src/mir-engine/meep/src/`. All paths below are relative to that root.
-Every finding below was verified by opening the cited files.
-
-## Findings
-
-| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
-|---|---|---|---|---|---|---|---|
-| 1 | CRITICAL | **Two complete ECS animation-playback systems over three.js `AnimationMixer`**, each with its own component, clip type, flag enum, screen-space culling and debt-time accumulator | `engine/ecs/systems/AnimationSystem.js:179` `AnimationSystem` (+ `engine/ecs/animation/Animation.js:10`, `engine/ecs/animation/AnimationClip.js:6`, `engine/ecs/animation/AnimationClipFlag.js:5`) ⟷ `engine/graphics/ecs/animation/animator/AnimationGraphSystem.js:21` `AnimationGraphSystem` (+ `graph/AnimationGraph.js`, `animator/AnimationClip.js:8`, `animator/AnimationClipFlag.js:5`) | `AnimationSystem.screenSpaceSize:271` vs `AnimationGraphSystem.screenSpaceSize:221` are the same body (`boundingSphere`→`max3(scale)`→`sphere_project`→`* viewport.x * viewport.y`, same `assert.notEqual(cameraMatrix,null,'camera matrix is null')`). `AnimationSystem.shouldEntityBeAnimated:302` vs `AnimationGraphSystem.shouldEntityBeAnimated:181` — same early-outs, same `areaInPixel < 32` magic threshold. Both do `traverseComponents(...)` debt accumulation then `meshSystem.traverseVisible(...)` and both call `CameraSystem.getFirstActiveCamera(ecd)` + `matrixWorld.copy/invert` + `c.fov/180`. | UNJUSTIFIED | `AnimationGraph` (E) is the richer/newer path (blend state, transitions, notifications, declares `components_used`). Extract the shared visibility gate as a typed helper `engine/graphics/ecs/mesh/mesh_screen_space_pixel_area(mesh, cameraMatrixElements, focalLength, viewportW, viewportH)` in `engine/graphics/ecs/mesh/`, called by both; then mark `Animation`/`AnimationSystem` `@deprecated` in favour of `AnimationGraph` (library — do not delete). | M / M — `screenSpaceSize` extraction is mechanical and covered by both systems' behaviour; the deprecation is doc-only |
-| 2 | HIGH | **`AnimationClipFlag` declared twice with the same numeric value `1` and opposite meanings** | `engine/ecs/animation/AnimationClipFlag.js:6` `{ ClampWhenFinished: 1 }` ⟷ `engine/graphics/ecs/animation/animator/AnimationClipFlag.js:9` `{ Repeat: 1 }` | Both are consumed as `clip.flags` on a class named `AnimationClip`; `engine/ecs/systems/AnimationSystem.js:93` reads `clip.getFlag(AnimationClipFlag.ClampWhenFinished)` while `engine/graphics/ecs/animation/animator/AnimationClip.js:48,142` reads `getFlag(AnimationClipFlag.Repeat)`. `engine/ecs/animation/AnimationClip.js:124` writes `flags` as a raw `uint8` to the save stream (`AnimationSerializationAdapter.js:16`), so byte `1` decodes to "clamp" or "repeat" depending only on which import a future reader picks. An import auto-completed to the wrong sibling type-checks, runs, and silently inverts looping. | UNJUSTIFIED | Rename the enums to match their owning systems (`AnimationClipFlag` → `MixerAnimationClipFlag` in `engine/ecs/animation/`, `AnimationGraphClipFlag` in `animator/`), keeping the old names as `@deprecated` re-exports (library surface). | S / L |
-| 3 | HIGH | **Three unrelated classes exported as `AnimationClip`**, plus three as `AnimationTrack` | `engine/animation/clip/AnimationClip.js:1` (name + `AnimationTrack[]`, glTF-shaped, no flags) ⟷ `engine/ecs/animation/AnimationClip.js:6` (`ObservedString` name + `repeatCount`/`weight`/`timeScale` + flags) ⟷ `engine/graphics/ecs/animation/animator/AnimationClip.js:8` (`def` + `weight`/`timeScale` + flags + notification dispatch). Tracks: `engine/animation/clip/AnimationTrack.js:6` ⟷ `engine/animation/keyed2/AnimationTrack.js:8` ⟷ three's `KeyframeTrack` | Overlap is *conceptual, not textual* — none of the three shares a field layout, so these are genuinely three parallel clip models, not copies. `keyed2/AnimationTrack.js:6` documents its own obsolescence: "Consider using `AnimationCurve` instead if you're starting a new project". | UNJUSTIFIED (naming) — not code duplication | Same as #2: disambiguate the exported names, add `@deprecated` on `keyed2/AnimationTrack`. Do **not** merge the data models; they serve different runtimes. | S / L |
-| 4 | HIGH | **Divergent copy of the Gaussian-blur-over-a-sampled-function algorithm — the copy still carries the bug the other one fixed** | `engine/ecs/evaluation/complex/PointFitnessGaussianBlur.js:62` `evaluate` ⟷ `generation/filtering/numeric/complex/CellFilterGaussianBlur.js:93` `execute` | `CellFilter` version precomputes a normalized kernel via `core/math/build_gaussian_kernel_2d.js`, centres it at `(samples-1)*0.5`, forces odd sample counts (`nextOdd`) and derives `sigma = (samples-1)/6`. `PointFitness` version centres at `samplesX / 2` — for `samples=5` the taps land at `-2.5,-1.5,-0.5,0.5,1.5`, i.e. **shifted half a sample off centre**, so the blur biases the result; it also hard-codes `sigma = 10` regardless of sample count (with taps in ±2.5 that is effectively a box filter), normalizes by an accumulated `powerTotal` instead of a normalized kernel, and never calls the existing `build_gaussian_kernel_*` primitives. | UNJUSTIFIED | Port the fixed formulation: use `build_gaussian_kernel_2d`/`_1d` and the `(samples-1)*0.5` centring in `PointFitnessGaussianBlur`. Third-axis (`z`) support means a `build_gaussian_kernel_3d` sibling in `core/math/` is the clean shared path. | M / M — output values change (they are currently wrong); `PointFitnessFunction` has one external consumer (`mir-engine/model/game/logic/combat/scene-selection/SceneAffliction.js`) |
-| 5 | HIGH | **Binary wire format written in two places: the serializer and the version upgrader each re-derive the same header encoding** | `engine/grid/position/GridPositionSerializationAdapter.js:14` `serialize` ⟷ `engine/grid/position/GridPositionSerializationUpdater_0_1.js:11` `upgrade`; and `engine/grid/grid2transform/GridPosition2TransformSerializationAdapter.js:15` `serialize` ⟷ `engine/grid/grid2transform/GridPosition2TransformSerializationUpgrader_0_1.js:12` `upgrade` | The upgraders reproduce the v1 write path byte-for-byte, comments included (`//both coordinates are present`, `//write X`, `//both components are uint`). Changing the v1 encoding in the adapter leaves the upgrader emitting the old bytes into a stream the new deserializer will misread — a silent save-corruption path. Contrast `engine/navigation/ecs/path_following/PathFollowerSerializationUpgrader_3_4.js:8`, which uses `BinaryBuffer.copyUint16/copyFloat32` and never re-derives a format. | UNJUSTIFIED | Extract the v1 writers as typed free functions next to the adapters — `grid_position_write_v1(buffer, x, y)` and `grid_position_2_transform_write_offset_v1(buffer, offsetX, offsetY)` — and call them from both `serialize` and `upgrade`. | S / L |
-| 6 | HIGH | **Two parallel transform-parenting subsystems** (component + deferred binding + parent-transform subscription), one carrying a TODO that points at the other's implementation | `engine/ecs/attachment/Attachment.js:5` + `engine/ecs/attachment/AttachmentSystem.js:100/254` + `engine/ecs/attachment/TransformAttachmentBinding.js:8` ⟷ `engine/ecs/transform-attachment/TransformAttachment.js:17` + `engine/ecs/transform-attachment/TransformAttachmentSystem.js:176/201` + its `UpdateContext:14` | Components are near-identical (`parent:number = -1`, local `transform:Transform`, an `immediate`/`Immediate` flag). Both systems queue an entity until the parent `Transform` exists (`AttachmentSystem.processWaiting:105` / `TransformAttachmentSystem.__queue`), then subscribe to parent-transform change and recompose the child's world transform. `TransformAttachmentBinding.js:10` literally says *"TODO make use of `Transform.multiplyTransforms` for better readability and performance"* — which is exactly what `TransformAttachmentSystem`'s `UpdateContext.update:51` already does. Both are live: `Attachment` via `engine/ecs/speaker/VoiceSystem.js:423` and `engine/graphics/debug/shape_to_visual_entity.js:56`; `TransformAttachment` via `engine/ecs/parent/EntityNode.js:187`. | UNJUSTIFIED | `TransformAttachment` == `Attachment` with no socket. Make `AttachmentSystem`'s `TransformAttachmentBinding.update` delegate to `Transform.multiplyTransforms` (kills the matrix path and the TODO), and route both systems' deferred-parent wait through one typed `PendingParentQueue` class. Longer term the socket-less case should be expressed as `Attachment` with an identity socket. | L / M |
-| 7 | HIGH | **Per-entity link/unlink bookkeeping hand-rolled in ≥9 systems while the engine already ships a typed base class for it — and one hand-rolled copy has drifted into a listener leak** | Hand-rolled: `engine/grid/position/GridPositionSystem.js:47/79/88`, `engine/grid/grid2transform/GridPosition2TransformSystem.js:40/79/87`, `engine/grid/transform2grid/Transform2GridPositionSystem.js:100/119`, `engine/ecs/transform-attachment/TransformAttachmentSystem.js:176/201`, `engine/ecs/terrain/ecs/cling/ClingToTerrainSystem.js:88/110`, `engine/ecs/gui/position/ViewportPositionSystem.js:132/167`, `engine/input/ecs/systems/InputSystem.js:113/141`, `engine/graphics/ecs/animation/AnimationControllerSystem.js:18/64`, `engine/sound/ecs/SoundControllerSystem.js:49/103`. Existing solution: `engine/ecs/system/AbstractContextSystem.js:9` + `engine/ecs/system/SystemEntityContext.js` | Same shape everywhere: sparse per-entity store + a binding object subscribed in `link` and unsubscribed in `unlink`. Three incompatible store conventions (`this.data[]`, `this.removers[]`, `Map`) and three binding conventions (closure with a `.clear` property, plain `{update, transform, component}` + a module-level `deregister`, and a class with `link()`/`unlink()`). `GridPositionSystem.reset:88` and `GridPosition2TransformSystem.reset:87` are the same `for (let entity in data) { if (!data.hasOwnProperty(entity)) continue; … sync.clear(); }` body. **Drift already happened:** `ViewportPositionSystem.link:154` adds `el.view.size.onChanged.add(updatePosition, eventContext)` and `unlink:167-181` never removes it — a per-entity listener leak on a live GUI system. Only 7 systems engine-wide use `AbstractContextSystem` (`ParentEntitySystem`, `DynamicActorSystem`, `VoiceSystem`, `LightSystem`, `PathDisplaySystem`, `SpriteSystemPE`, `FPDecalSystem`). | UNJUSTIFIED | Migrate the hand-rolled systems onto `AbstractContextSystem` + a per-system `SystemEntityContext` subclass — already typed, already verbose, no strings/registries/decorators. `Transform2GridPositionSystem.Synchronizer` and `TransformAttachmentSystem.UpdateContext` are `SystemEntityContext` in all but name. Fix the `ViewportPositionSystem` leak as part of the migration. | L / M — one system at a time; each migration is behaviour-preserving and independently testable |
-| 8 | HIGH | **Vendored copy of three.js `KeyframeTrack.optimize()` that diverged from upstream and no longer does anything** | `engine/ecs/animation/AnimationOptimizer.js:16` `optimizeTrack` (called from `engine/asset/loaders/GLTFAssetLoader.js:426` on every loaded glTF animation) | The body is three.js's `KeyframeTrack.optimize`, but `this` here is the `AnimationOptimizer`, not the track — so lines 111-112 write `this.times`/`this.values` **onto the shared module-level optimizer instance** (`GLTFAssetLoader.js:32 const animationOptimizer = new AnimationOptimizer()`) and the track is never modified. It also carries upstream's typo `time !== time[0]` (should be `times[0]`). Net effect per track: two full array copies allocated and discarded. Meanwhile meep has its own, tested curve reducers: `engine/animation/curve/animation_curve_optimize.js:91` and `engine/animation/curve/compression/downsample_float_array_curve_by_error.js`. | UNJUSTIFIED | Either drop the call (it is a pure cost today) or re-target the writes to the track (`track.times = …; track.values = …`) and add a spec. Do not re-vendor: prefer `animation_curve_optimize` semantics once glTF tracks are routed through `engine/animation/clip/`. | S / L (currently a no-op, so "fixing" it changes glTF output — gate behind a test) |
-| 9 | MEDIUM | **`TextureAttachmentsByMaterialType` iteration written five times, twice in the same file** | `engine/asset/loaders/material/traverseMaterialTextures.js:9` (the generic one) ⟷ `engine/asset/loaders/GLTFAssetLoader.js:40` `replace_material_textures_from_cache` ⟷ `engine/asset/loaders/GLTFAssetLoader.js:92` `configureTextures` ⟷ `engine/asset/loaders/material/StaticMaterialCache.js:39` `acquire` ⟷ `engine/graphics/material/manager/compilers/CoalesceTextures.js:25` `transform` | `StaticMaterialCache.acquire:48-89` and `CoalesceTextures.transform:26-66` are byte-identical including the commented-out `//console.log('Re-using texture', existingTexture);`. `traverseMaterialTextures` already exists and is used by three other call sites (`MaterialDescriptor.js:23`, `promiseMaterialLoaded.js:13`, `prototypeLightManager.js:1232`) — the loader/compiler path just never adopted it. A new material type added to `TextureAttachmentsByMaterialType` propagates to all five automatically, but any change to the *null-texture* or *write-back* convention has five edit sites. | UNJUSTIFIED | Route all five through `traverseMaterialTextures(material, cb, thisArg)`. The texture-cache body shared by `StaticMaterialCache.acquire` and `CoalesceTextures.transform` becomes one exported `coalesce_material_textures(material, textureCache)` used by both. | S / L |
-| 10 | MEDIUM | **~70-line terrain-contact probe + influence computation copy-pasted between the two IK solvers** | `engine/ecs/ik/TwoBoneInverseKinematicsSolver.js:80-151` (inside `solve:50`) ⟷ `engine/ecs/ik/OneBoneSurfaceAlignmentSolver.js:80-151` (inside `solve:42`) | Identical sequence, same variable names, same comments: primary `terrain.raycastFirstSync` along the bone direction → `if (!contactExists) return` → secondary cast from the effector back along `-contactNormal` → `if (!contactExists) return` → `v3_displace_in_direction(targetPosition, offset*scale, contact…, normal…)` → `v3_dot(direction…, delta_contact_c…)` side test → `dot < 0 ? influence = 1 : influence = 1 - clamp01(constraint.distance.normalizeValue(inverseLerp(0, scale, len)))` → `if (influence <= 0) return`. Only `limbLength` vs `bone_scale` and the ray origin differ. Both solvers are live via `engine/ecs/ik/InverseKinematicsSystem.js:26-27`. | UNJUSTIFIED | Extract `engine/ecs/ik/ik_probe_terrain_contact(out_target, terrain, origin, effector, direction, constraint, length_scale) → number` returning the influence (`0` = no contact / no influence). Both solvers then keep only their rotation math. | M / L — pure extraction, both solvers already spec-adjacent |
-| 11 | MEDIUM | **Axis-tick-walking algorithm forked; the ceil→floor fix landed in only one copy** | `engine/animation/curve/editor/canvas2dDrawWorldAxisLabels.js:17` ⟷ `engine/graphics/canvas/canvas2d_draw_linear_scale.js:18` | Same prologue verbatim (`if (spacing <= 0) throw`, `delta_x/delta_y`, `v2_length`, `if (distance === 0) throw`, `direction_x/direction_y`). `canvas2d_draw_linear_scale.js:44-46` carries the fix *and the explanation*: "using ceil would place a final tick past position_1 with an extrapolated value" → `Math.floor`. `canvas2dDrawWorldAxisLabels.js:44` still has `Math.ceil` and therefore still draws that extrapolated final tick. They also use two different number formatters (`formatTruncDecimal` vs `core/primitives/numbers/number_pretty_print`). | UNJUSTIFIED | One `canvas2d_draw_linear_scale` taking an explicit `value_step` (uniform control flow — always supply the step; callers compute `(value_1-value_0)/mark_count` when they want a fitted scale). Delete the `Math.ceil` variant's body and re-export. | S / L |
-| 12 | MEDIUM | **A second 2D chart-plotting toolkit under `engine/animation/curve/editor/`, forked from `engine/graphics/canvas/`** | `engine/animation/curve/editor/canvas2dPlotCurveLine.js:17` ⟷ `engine/graphics/canvas/canvas2d_plot_data_line.js:16`; supporting pairs `canvas2dDrawWorldGrid.js` ⟷ `canvas2d_draw_grid.js`, `canvas2dDrawWorldAxisLabels.js` ⟷ `canvas2d_draw_linear_scale.js`, `canvas2dPlotCurvePoints.js` ⟷ `canvas2d_plot_line_array.js` | The two plot functions share the same skeleton and the same hard-coded palette: `'#222222'` background fill, two grid passes at `'#262626'` then `'#303030'` spacing 32, axis at `height - 4` and `x = 4`, `strokeStyle = '#00ff00'`, `lineWidth = 1`. A third copy of the same palette+grid pass is inlined at `engine/animation/curve/view/AnimationCurveView.js:159-203`. Style split (`snake_case` vs `camelCase`) marks the fork. `canvas2dPlotCurvePoints.js:1` also imports `Vector2` **from `three`** inside a pure-2D canvas helper — a vendor-boundary leak. | UNJUSTIFIED | Keep `engine/graphics/canvas/*` as the toolkit. The genuinely new capability in the editor fork is *world-space* grid/labels (`canvas2dDrawWorldGrid` handles a value range, `canvas2d_draw_grid` is screen-space only) — promote that as `canvas2d_draw_grid_world` alongside the existing helpers, then make the editor call the shared functions. Fix the `three` import to `core/geom/Vector2`. | M / M |
-| 13 | MEDIUM | **Three curve-space ↔ canvas-space mapping implementations inside the same feature** | `engine/animation/curve/view/AnimationCurveView.js:120/137` `point_curve_to_canvas` / `point_canvas_to_curve` (3×3 matrix + inverse) ⟷ `engine/animation/curve/draw/position_curve_to_canvas.js:12` / `position_canvas_to_curve.js:12` (size/frame/margin, allocates a `Vector2` per call) ⟷ `engine/animation/curve/editor/canvas2dPlotCurvePoints.js:32-60` (inline `axisSize`/`offset`/`inverseTimeRange` normalization) | All three map `(time, value) ↔ (px, py)` for the same `AnimationCurve` under the same margin convention. The `draw/` pair is used by `build_tangent_editor.js:127`, `displayMousePos.js:17`, `isInjectedKeyframeInBounds.js:21/56`, `createKeyframeDraggableAspect.js:64`, `createPanTool.js:30`; the matrix pair only by `AnimationCurveView`; the inline one only by the plot. A margin/anchoring change has to be made three ways or the editor's hit-testing desyncs from what is drawn. | UNJUSTIFIED | Keep the matrix formulation (`AnimationCurveView`'s `m3_cm_compose_transform` + `m3_invert`) — it is the only one that is exactly invertible — and expose it as a small typed `CurveViewport` class in `engine/animation/curve/` with `curve_to_canvas(out, x, y)` / `canvas_to_curve(out, x, y)` writing into caller-supplied arrays (kills the per-call `Vector2` allocation too). | M / M |
-| 14 | MEDIUM | **Mouse-parallax 3D tilt math copy-pasted, and the copy's pivot silently diverged** | `engine/ecs/gui/parallax/GuiElementParallaxSystem.js:36` `updateEntity` ⟷ `engine/ui/bindings/processors/DomElementProcessorTilt3D.js:56` `handleFrame` | Identical body down to the variable names and the CSS write (`transformOrigin = '50% 50%'`, `` transform = `rotate3d(${tilt_x},${tilt_y},0,${angle}deg)` ``). `GuiElementParallaxSystem.js:53-54` computes `center_x`/`center_y` from `getBoundingClientRect()` **and never uses them** — line 60-61 takes the delta against the *viewport* centre instead, so the ECS version tilts every element identically regardless of where it sits on screen. `DomElementProcessorTilt3D.js:82-83` uses the element centre (the evidently intended behaviour). The unused pair is the copy-paste fingerprint. | UNJUSTIFIED | Extract `engine/ui/apply_pointer_tilt_3d(el, pointerX, pointerY, viewportW, viewportH, angle, depth)` and call it from both. Decide the pivot once (element centre) — that also removes the dead `getBoundingClientRect()` call from the ECS path. | S / L |
-| 15 | MEDIUM | **`AnimationController` and `SoundController` are the same rule-driven event-binding system twice** | `engine/graphics/ecs/animation/AnimationControllerSystem.js:18` `link` / `:64` `unlink` ⟷ `engine/sound/ecs/SoundControllerSystem.js:49` `link` / `:103` `unlink` | `unlink` is token-identical (`this.removers[entity]` → `delete` → `callbacks.forEach(cb => dataset.removeEntityEventListener(entity, cb.name, cb.handler))`). `link` differs only in the payload built inside the start handler (`new AnimationClip()` + `animation.clips.add` vs `new SoundTrack()` + `emitter.tracks.add`); the surrounding rule-walk, the optional `stopEvent` registration and the `callbacks.push({name, handler})` bookkeeping are identical, comment placement included. | UNJUSTIFIED | Fold both onto `AbstractContextSystem` (finding #7) with a per-system `SystemEntityContext` subclass; the `{startEvent, stopEvent}` rule subscription becomes a shared typed `EntityRuleBinder` holding the `{name, handler}[]` and its teardown. The two payload builders stay as distinct typed methods. | M / L |
-| 16 | MEDIUM | **`removeEntityWithMeshParticlesEffect` reimplements `removeEntityWithEffect` and drops the transient-save guard** | `engine/animation/removeEntityWithMeshParticlesEffect.js:150` ⟷ `engine/animation/AnimationUtils.js:168` `removeEntityWithEffect` (used by `engine/animation/removeEntityGenericEffect.js:150`) | Same skeleton: same `removeComponentsExcept(ecd, entity, [Mesh, ParticleEmitter, Trail2D, Transform])` list, same `stopEntityAndNotifyWhenStopped(entity, ecd).then(() => ecd.removeEntity(entity))` tail. `removeEntityWithEffect:179` adds `SerializationMetadata.Transient` so a dying entity cannot land in a save; the mesh-particles copy never does — an entity mid-death-effect is serializable there. | UNJUSTIFIED | Have `removeEntityWithMeshParticlesEffect` call `removeEntityWithEffect`, passing the already-built emitter (it only needs the extra `distributeParticlesOnObject3D` step before the call). | S / L |
-| 17 | MEDIUM | **`setFlag`/`clearFlag`/`writeFlag`/`getFlag` quartet copied into 34 classes, with the `getFlag` predicate already diverged** | 34 files carry the identical quartet, e.g. `engine/ecs/animation/Animation.js:64-97`, `engine/ecs/gui/GUIElement.js`, `engine/ecs/speaker/Voice.js`, `engine/ecs/transform/Transform.js`, `engine/navigation/ecs/path_following/PathFollower.js`, `engine/grid/grid2transform/GridPosition2Transform.js`, `engine/asset/AssetRequest.js`, `core/events/signal/Signal.js`, `view/View.js`. Divergent `getFlag`: `engine/ecs/animation/AnimationClip.js:62`, `engine/ecs/Entity.js:142`, `core/math/lookup/ParameterLookupTable.js:82` | 34 sites use `return (this.flags & flag) === flag;` (all-bits-of-the-mask); 3 use `!== 0` (any-bit). Equivalent for single-bit flags, **opposite for composite masks** — and composite masks exist (`engine/ecs/animation/Animation.js:40` seeds `flags = MeshSizeCulling \| Playing`). Nothing documents which convention a given class follows. | UNJUSTIFIED (in logic, not merely shape — the predicate semantics disagree) | Two typed pieces, no metaprogramming: (a) free functions in `core/binary/bitfield/` (`bitfield_test_all`, `bitfield_test_any`) so intent is named at each call site; (b) a concrete `BitFlagCarrier` base class in `core/model/` for the ~25 classes with no other superclass. At minimum, unify the 3 outliers on the documented convention. | M / M — mechanical but wide; a codemod plus one spec asserting composite-mask behaviour per class |
-| 18 | MEDIUM | **Two parallel input-binding ECS subsystems, one deprecated only in a JSDoc line** | `engine/input/ecs/systems/InputSystem.js:92` + `engine/input/ecs/components/Input.js` + `engine/input/ecs/ism/InputBinding.js:4` (path → event name, `ecd.sendEvent`) ⟷ `engine/input/ecs/systems/InputControllerSystem.js:186` + `engine/input/ecs/components/InputController.js` + `engine/input/ecs/components/InputBinding.js:3` (path → listener fn, priority/exclusive proxy dispatch) | `InputControllerSystem.js:184` says "Prefer to use {@link InputSystem} instead" but the class is otherwise undecorated and fully live. Both resolve the device signal identically via `resolvePath(devices, path)` and subscribe/unsubscribe. Within `InputSystem.js`, `linkBinding:14` and `unlinkBinding:29` are a 14-line verbatim pair differing only in `signal.add` vs `signal.remove` — all three assert messages duplicated. | UNJUSTIFIED (the `linkBinding`/`unlinkBinding` pair); the two subsystems are a migration in progress | Collapse `linkBinding`/`unlinkBinding` into one `resolve_device_signal(devices, path) → Signal` (the asserts live there) with `.add`/`.remove` at the two call sites. Add `@deprecated` to `InputControllerSystem`, `InputController` and `engine/input/ecs/components/InputBinding` so the JSDoc note is machine-visible. | S / L |
-| 19 | MEDIUM | **JSON-derived asset loaders repeat the same scaffold, and all of them lose parse errors** | `engine/ecs/sockets/serialization/AttachmentSocketsAssetLoader.js:7` ⟷ `engine/graphics/ecs/animation/animator/graph/definition/serialization/AnimationGraphDefinitionAssetLoader.js:7` ⟷ `engine/asset/loaders/JavascriptAssetLoader.js:22` | All three: `await this.assetManager.promise(path, GameAssetType.X, {scope, progress})` → `.create()` → `new Asset(() => parse(json), 1)` → `success(asset)`. None passes `failure`, so a throw out of the awaited call or out of the parser rejects the async `load()` into an unobserved promise — compare `GLTFAssetLoader.js:441`, which routes explicitly (`.then(success, failure)`) with a comment explaining exactly this hazard. | UNJUSTIFIED | A typed `DerivedAssetLoader extends AssetLoader` with an abstract `sourceType` getter and `build(json) → *`, whose `load` owns the `try/catch → failure(e)` wiring once. Verbose, typed, one subclass per asset kind. | S / L |
-| 20 | LOW | **Three loaders hand-roll a structural stand-in for the existing `Asset` class** | `engine/asset/loaders/TextAssetLoader.js:7`, `engine/asset/loaders/JsonAssetLoader.js:19`, `engine/asset/loaders/SVGAssetLoader.js:14` | Each builds `const asset = { create: function () { return X; } }` instead of `new Asset(factory, byteSize)`. `Asset` (`engine/asset/Asset.js`) carries `byteSize`, `dependencies` and the scope machinery the `AssetManager` overhaul introduced; the duck-typed objects report no weight to the cache. | UNJUSTIFIED | `new Asset(() => data, data.length)` in all three. | S / L |
-| 21 | LOW | **`Quaternion.fromAxisAngle` and `Quaternion.lookRotation` reimplemented module-privately** | `engine/input/ecs/util/TopDownCameraControllerHelper.js:21` `CreateFromAxisAngle` and `:32` `lookAt` ⟷ `core/geom/Quaternion.js:335` `fromAxisAngle` / `:217` `lookRotation`, and `core/geom/3d/quaternion/quat3_from_axis_angle.js:7` | `quat3_from_axis_angle.js` carries the JSDoc line "just in case you need that function also"; `TopDownCameraControllerHelper.js:20` carries the *same stray comment* as a `//` line — proof of a copy chain. The local `lookAt` also hard-codes `3.1415926535897932` and two `0.000001` epsilons instead of `core/math/PI.js` / `core/math/EPSILON.js`, and unlike `Quaternion.lookRotation` (which has a spec suite at `core/geom/Quaternion.spec.js:274-297`) it takes no up-vector. | UNJUSTIFIED | Delete the two module-private functions; call `Quaternion.prototype.fromAxisAngle` / `lookRotation`. (`core/geom/3d/quaternion/quat3_createFromAxisAngle.js` is a correctly-documented `@deprecated` alias — leave it.) | S / L |
-| 22 | LOW | **Quaternion-rotate-vector inlined in a GUI system** | `engine/ecs/gui/hud/HeadsUpDisplaySystem.js:92-106` (inside `__apply_entity_transformation:75`) ⟷ `core/geom/vec3/v3_quaternion_apply.js`, `core/geom/Vector3.js`, `core/geom/Vector4.js` | The `ix/iy/iz/iw` two-Hamilton-product expansion is reproduced verbatim. `v3_quaternion_apply(out, out_offset, vx, vy, vz, …)` already writes into a caller-supplied array, so the usual "avoid an object allocation" defence does not apply. | UNJUSTIFIED | Call `v3_quaternion_apply` with a module-static scratch `Float64Array(3)`. | S / L |
-| 23 | LOW | **Cubic easing functions redefined module-privately instead of joining the engine's easing enum** | `engine/control/first-person/abilities/Mantle.js:9` `easeInOutCubic`, `:21` `easeOutCubic`, `:30` `easeInCubic` ⟷ `engine/animation/TransitionFunctions.js:7` (`Linear`, `Sine`, `EaseIn`, `EaseOut`, `EaseInOut`, `CubicEaseIn`) | `TransitionFunctions` is the engine-wide easing enum (11 consumers across `achievements`, `ui`, `ecs/gui`, `ecs/speaker`, `animation`). Cubic in/out/in-out is exactly what it is missing, so the next consumer will write a fourth copy. A parallel *curve*-valued easing set also exists at `engine/animation/curve/preset/CURVE_EASE_IN.js` / `_OUT` / `_IN_OUT` — the same three concepts as `AnimationCurve` objects. | PROMOTION | Add `CubicEaseIn`/`CubicEaseOut`/`CubicEaseInOut` to `TransitionFunctions` and have `Mantle.js` import them. Cross-reference `TransitionFunctions.EaseIn` ↔ `CURVE_EASE_IN` in JSDoc so the two representations are discoverable as a pair. | S / L |
-| 24 | LOW | **The same 6-stop heatmap palette declared twice** | `engine/ecs/terrain/util/paintTerrainOverlayViaLookupTable.js:11-20` ⟷ `engine/graphics/render/forward_plus/debug/createScreenGrid.js:180-189` | Identical `new ParameterLookupTable(4)` + the same six RGBA rows (`0,0,0,255` … `255,5,5,255`) + `computeUniformPositions()`. A palette change makes the terrain overlay and the froxel debug grid disagree. | PROMOTION | `core/math/lookup/LUT_HEATMAP.js` exporting a frozen shared `ParameterLookupTable`. | S / L |
-| 25 | LOW | **Graphviz DOT preamble duplicated across graph dumpers** | `engine/intelligence/behavior/behavior_to_dot.js:240-257` ⟷ `core/bvh8/bvh8_convert_to_dot.js:110-122`; also `core/graph/convert_graph_to_dot_string.js:27`, `core/model/node-graph/util/convert_node_graph_to_dot_string.js:43`, `engine/graphics/render/frame_graph/FrameGraph.js:543` | The `font = {name:"helvetica", size:10}` object and the `graph [style=invis, rankdir="TB" ordering=out, splines=spline]` + `node [shape=record, fontname=…, fontsize=…, margin="0.2,0.03", fillcolor=ivory]` attribute lines are byte-identical between the behavior and BVH8 dumpers. Five emitters, five copies of the styling contract. | PROMOTION | `core/graph/dot/dot_graph_begin(line_builder, name)` / `dot_graph_end(line_builder)` in `core/`, carrying the default node/edge styling. | S / L |
-| 26 | LOW | **Third binary-search-over-sorted-keys implementation** | `engine/animation/curve/AnimationCurve.js:~228` (index search inside the keyframe lookup) ⟷ `engine/animation/async/table_find_min_index_in_ordered_column.js:10` ⟷ `core/collection/array/binarySearchLowIndex.js:10` | Same `(min + max) >>> 1` loop three ways, with three different out-of-range answers: `binarySearchLowIndex` returns `-1` below the range, `table_find_min_index_in_ordered_column` returns `min2(minIndex, maxIndex)`, `AnimationCurve` pre-clamps to `0` / `key_count - 1`. The table variant is legitimately different (it indexes a `RowFirstTable`, not an array). | UNJUSTIFIED for the `AnimationCurve` copy; JUSTIFIED for the table variant (different storage) | `AnimationCurve` can call `binarySearchLowIndex(keys, time, compare_time_to_keyframe)` with a module-static comparator (no per-call closure). Document the differing out-of-range contracts in all three JSDocs regardless. | S / L |
-| 27 | LOW | **Composite-behavior children wire format written twice** | `engine/intelligence/behavior/composite/SequenceBehaviorSerializationAdapter.js:19/37` ⟷ `engine/intelligence/behavior/composite/ParallelBehaviorSerializationAdapter.js:19/42` | Both encode the child list as `writeUintVar(n)` + N `objectAdapter.serialize`, and decode as `readUintVar()` + `clearChildren()` + N `addChild`. `ParallelBehavior` merely prefixes two policy bytes. Only two adapters exist today, so the blast radius is small — but a change to the child-list encoding needs both. | UNJUSTIFIED (marginal) | A typed `CompositeBehaviorSerializationAdapter extends ObjectBasedClassSerializationAdapter` exposing `serializeChildren(buffer, value)` / `deserializeChildren(buffer, value)`; the two concrete adapters keep their own `serialize`/`deserialize` and call them. | S / L |
-| 28 | LOW | **`1.0 + (raw - 1.0) * flatBoost` — `lerp` re-derived four times** | `engine/control/first-person/mastery/StrideTimingJumpEvaluator.js:95`, `SlideInitiationTimingEvaluator.js:81`, `BreathRhythmEvaluator.js:131`, `FootAsymmetryTurnEvaluator.js:107` | The identical "scale the deviation around 1.0" expression, each with its own 2–4 line comment explaining it. `core/math/lerp.js` exists and is spec'd. | UNJUSTIFIED (cosmetic) | `lerp(1.0, raw, this.flatBoost)`, with the explanation moved to `MasteryEvaluator`'s class JSDoc where the convention is already documented. | S / L |
-| 29 | LOW | **Cross-domain check — `engine/ecs/ik` correctly reuses the physics two-bone solver** | `engine/ecs/ik/TwoBoneInverseKinematicsSolver.js:11` imports `two_joint_ik` from `engine/physics/inverse_kinematics/two_joint_ik.js`; live via `engine/ecs/ik/InverseKinematicsSystem.js:26` | Verified: there is **no** second two-bone IK implementation on the ECS side — the solver delegates. Logged so the physics-domain agent does not double-report it. | JUSTIFIED (correct reuse) | none | — |
-
-## Dismissed leads
-
-- **`PointFitnessBinary.evaluate:29` ⟷ `CellFilterBinaryOperation.execute:31`** — same template-method shape, but different hierarchies with different sample signatures (`(ecd,x,y,z)` vs `(grid,x,y,rotation)`); no shared base is viable. Shape-only.
-- **`PointFitnessAdd.from` / `PointFitnessMultiply.from` (+ 10 more in the [49x12] group)** — per-class typed factories identical in shape. Explicitly deliberate per house rules.
-- **`CompositeBehavior.addChildren:36` ⟷ `Tag.addAll:59` ⟷ `Task.addDependencies:187`** — 5-line "for-each call the singular add" over three unrelated types. Too small to share; extracting would need a callback and lose the typing.
-- **`AnimationOptimizer.optimize:123` ⟷ `IncrementalDeltaSet.pushOther:310`** — the mechanical match is only the `for (i…) { … method(item) }` loop. The *real* problem with `AnimationOptimizer` is finding #8.
-- **`BehaviorComponent.from:121` ⟷ `KillBehavior.create:23`** — assert-then-construct factories on unrelated classes. (Worth noting only that the codebase uses `from` and `create` interchangeably for the same idiom.)
-- **`makeDefaultSlideInitiationTimingCurve:21` ⟷ `makeDefaultStrideTimingJumpCurve:18`** — identical construction *shape* but the four keyframe values are authored design data with different documented intent. Correctly built on the existing `AnimationCurve`/`Keyframe` types.
-- **`Voice`** declared in `engine/ecs/speaker/Voice.js` and `engine/sound/sopra/runtime/Voice.js` — completely different concepts (speech-bubble ECS component vs. a pooled WebAudio source). Name collision only, no shared code.
-- **`InputBinding`** declared in `engine/input/ecs/components/` and `engine/input/ecs/ism/` — different data models (path→callback vs path→event-name). Rolled into finding #18 as the deprecation half; not itself duplicated code.
-- **`canvas2dDrawWorldGrid` ⟷ `canvas2d_draw_grid`** — the world-space variant genuinely handles a value range the screen-space one does not. Covered as the promotion half of #12, not as duplication.
-- **`PoseInterpolationAdapter.interpolate:17`** (7 inline lerps + inline nlerp) — deliberate scalar-register hot path over a `BinaryBuffer`; using `Vector3`/`Quaternion` would force reads into objects. Justified.
-- **`HeadsUpDisplaySystem` ⟷ `ViewportPositionSystem`** — the HUD system writes into `ViewportPosition` and lets `ViewportPositionSystem.setElementPosition:197` do the DOM placement. Correct layering, no duplication.
-- **`prototype_first_person_controller.js` ⟷ `prototypeAcousticSolver.js`** (`makePhysicsGroundResolver`, `buildInputBindings`, `recomputeMove`, `bindMoveKey`, `logHelp`) — both are `prototype*.js` browser harnesses, out of scope.
-- **`table_find_min_index_in_ordered_column`** as a duplicate of `binarySearchLowIndex` — justified: it indexes a `RowFirstTable`, not an array. Only the `AnimationCurve` copy is flagged (#26).
-- **`GridPositionSerializationAdapter.serialize` ⟷ `GridPositionSerializationUpdater_0_1.upgrade` as "shape duplication"** — *not* dismissed; this is finding #5. Listed here only because the mechanical brief filed it as a MinHash near-match rather than as a format-invariant hazard.
-- **`removeEntityGenericEffect.js` / `removeEntityWithMeshParticlesEffect.js` embedded emitter JSON** (~130 lines each, `cloud-puff` vs `mesh-cloud-puff-0`) — duplicated *data*, not logic; the two presets have genuinely different tuning. Belongs in `data/` but is not a reuse failure.
-- **`engine/interpolation/**` vs `core/math` easing** — no duplicate easing library there; `engine/interpolation/` is snapshot interpolation (`InterpolationLog`, `Interpoland`, binary pose adapters), unrelated to easing curves. The real easing duplication is #23.
-- **`binary_search_inline` / `inline_clamp_ternary` hits under `engine/asset/loaders/**`** — checked: `image/png/crc32.js:24` and `png_filter_unFilterNone.js:42` are bit-shifts inside PNG codecs, not searches; `computeMassRatios.js:30`'s `Math.max(0, Math.min(1, x))` is one site and `clamp01` exists, but it is cold init code (LOW-of-LOW, folded into no row).
-
-## Notes
-
-Structural reasons duplication concentrates in this domain:
-
-1. **Three generations of animation coexist with no deprecation markers on the older two.** `engine/animation/keyed2/` (multi-property tracks + per-key transition functions, the only one the GUI/notifications/achievements actually use) → `engine/animation/curve/` (`AnimationCurve` + Hermite `Keyframe`, self-declared as the successor in `keyed2/AnimationTrack.js:6`) → `engine/animation/clip/` (glTF-shaped clip/track built on `AnimationCurve`). Orthogonally, **two** ECS animation runtimes drive three.js (`engine/ecs/animation/` + `AnimationSystem` vs `engine/graphics/ecs/animation/animator/` + `AnimationGraphSystem`). Five layers, one namespace: three exported `AnimationClip`, three `AnimationTrack`, two `AnimationClipFlag`. Because meep is a library, nothing was deleted during each migration — but nothing was marked `@deprecated` either, so each generation keeps attracting new code and each new consumer picks whichever name resolves first.
-
-2. **The engine already solved the ECS lifecycle problem and then only half-adopted the solution.** `AbstractContextSystem` + `SystemEntityContext` is exactly the typed, verbose, no-magic answer the house rules ask for — and only 7 systems use it. Nine more in this domain hand-roll the same store + binding + teardown, in three mutually incompatible conventions. That is where the drift shows up: `ViewportPositionSystem` subscribes six things and unsubscribes five.
-
-3. **Serialization upgraders re-derive formats instead of copying fields.** The `BinaryBuffer.copyUint16/copyFloat32` idiom (used correctly by the `PathFollower` upgrader chain) makes an upgrader immune to later format changes. The two `grid/` upgraders instead paste the serializer's write path, which couples every future format edit to two files that no test compares.
-
-4. **Fork-then-fix, never back-port.** Four independent instances of the same failure mode: `CellFilterGaussianBlur` fixed a centring/normalization bug that `PointFitnessGaussianBlur` still has; `canvas2d_draw_linear_scale` fixed a `ceil`→`floor` tick bug (with a comment explaining it) that `canvas2dDrawWorldAxisLabels` still has; `TransformAttachmentSystem` adopted `Transform.multiplyTransforms` while `TransformAttachmentBinding` still carries a TODO to do so; `removeEntityWithEffect` added the `SerializationMetadata.Transient` guard that `removeEntityWithMeshParticlesEffect` lacks. In each pair the *newer* file is correct, which means the duplication is actively hiding fixes rather than merely wasting lines.
-
-5. **`snake_case` vs `camelCase` marks the fault lines.** `engine/graphics/canvas/canvas2d_*` vs `engine/animation/curve/editor/canvas2d*` is the clearest case — the naming split is a reliable indicator of a fork, and searching for one convention never surfaces the other.
+# Domain H — engine (ecs, intelligence, animation, input, control, asset, misc)
+
+Source root: `H:/git/moh/app/src/mir-engine/meep/src/`. All paths below are relative to that root.
+Every finding below was verified by opening the cited files.
+
+## Findings
+
+| # | Severity | Concept | Sites | Evidence | Verdict | Proposed common path | Effort/Risk |
+|---|---|---|---|---|---|---|---|
+| 1 | CRITICAL | **Two complete ECS animation-playback systems over three.js `AnimationMixer`**, each with its own component, clip type, flag enum, screen-space culling and debt-time accumulator | `engine/ecs/systems/AnimationSystem.js:179` `AnimationSystem` (+ `engine/ecs/animation/Animation.js:10`, `engine/ecs/animation/AnimationClip.js:6`, `engine/ecs/animation/AnimationClipFlag.js:5`) ⟷ `engine/graphics/ecs/animation/animator/AnimationGraphSystem.js:21` `AnimationGraphSystem` (+ `graph/AnimationGraph.js`, `animator/AnimationClip.js:8`, `animator/AnimationClipFlag.js:5`) | `AnimationSystem.screenSpaceSize:271` vs `AnimationGraphSystem.screenSpaceSize:221` are the same body (`boundingSphere`→`max3(scale)`→`sphere_project`→`* viewport.x * viewport.y`, same `assert.notEqual(cameraMatrix,null,'camera matrix is null')`). `AnimationSystem.shouldEntityBeAnimated:302` vs `AnimationGraphSystem.shouldEntityBeAnimated:181` — same early-outs, same `areaInPixel < 32` magic threshold. Both do `traverseComponents(...)` debt accumulation then `meshSystem.traverseVisible(...)` and both call `CameraSystem.getFirstActiveCamera(ecd)` + `matrixWorld.copy/invert` + `c.fov/180`. | UNJUSTIFIED | `AnimationGraph` (E) is the richer/newer path (blend state, transitions, notifications, declares `components_used`). Extract the shared visibility gate as a typed helper `engine/graphics/ecs/mesh/mesh_screen_space_pixel_area(mesh, cameraMatrixElements, focalLength, viewportW, viewportH)` in `engine/graphics/ecs/mesh/`, called by both; then mark `Animation`/`AnimationSystem` `@deprecated` in favour of `AnimationGraph` (library — do not delete). | M / M — `screenSpaceSize` extraction is mechanical and covered by both systems' behaviour; the deprecation is doc-only |
+| 2 | HIGH | **`AnimationClipFlag` declared twice with the same numeric value `1` and opposite meanings** | `engine/ecs/animation/AnimationClipFlag.js:6` `{ ClampWhenFinished: 1 }` ⟷ `engine/graphics/ecs/animation/animator/AnimationClipFlag.js:9` `{ Repeat: 1 }` | Both are consumed as `clip.flags` on a class named `AnimationClip`; `engine/ecs/systems/AnimationSystem.js:93` reads `clip.getFlag(AnimationClipFlag.ClampWhenFinished)` while `engine/graphics/ecs/animation/animator/AnimationClip.js:48,142` reads `getFlag(AnimationClipFlag.Repeat)`. `engine/ecs/animation/AnimationClip.js:124` writes `flags` as a raw `uint8` to the save stream (`AnimationSerializationAdapter.js:16`), so byte `1` decodes to "clamp" or "repeat" depending only on which import a future reader picks. An import auto-completed to the wrong sibling type-checks, runs, and silently inverts looping. | UNJUSTIFIED | Rename the enums to match their owning systems (`AnimationClipFlag` → `MixerAnimationClipFlag` in `engine/ecs/animation/`, `AnimationGraphClipFlag` in `animator/`), keeping the old names as `@deprecated` re-exports (library surface). | S / L |
+| 3 | HIGH | **Three unrelated classes exported as `AnimationClip`**, plus three as `AnimationTrack` | `engine/animation/clip/AnimationClip.js:1` (name + `AnimationTrack[]`, glTF-shaped, no flags) ⟷ `engine/ecs/animation/AnimationClip.js:6` (`ObservedString` name + `repeatCount`/`weight`/`timeScale` + flags) ⟷ `engine/graphics/ecs/animation/animator/AnimationClip.js:8` (`def` + `weight`/`timeScale` + flags + notification dispatch). Tracks: `engine/animation/clip/AnimationTrack.js:6` ⟷ `engine/animation/keyed2/AnimationTrack.js:8` ⟷ three's `KeyframeTrack` | Overlap is *conceptual, not textual* — none of the three shares a field layout, so these are genuinely three parallel clip models, not copies. `keyed2/AnimationTrack.js:6` documents its own obsolescence: "Consider using `AnimationCurve` instead if you're starting a new project". | UNJUSTIFIED (naming) — not code duplication | Same as #2: disambiguate the exported names, add `@deprecated` on `keyed2/AnimationTrack`. Do **not** merge the data models; they serve different runtimes. | S / L |
+| 4 | HIGH | **Divergent copy of the Gaussian-blur-over-a-sampled-function algorithm — the copy still carries the bug the other one fixed** | `engine/ecs/evaluation/complex/PointFitnessGaussianBlur.js:62` `evaluate` ⟷ `generation/filtering/numeric/complex/CellFilterGaussianBlur.js:93` `execute` | `CellFilter` version precomputes a normalized kernel via `core/math/build_gaussian_kernel_2d.js`, centres it at `(samples-1)*0.5`, forces odd sample counts (`nextOdd`) and derives `sigma = (samples-1)/6`. `PointFitness` version centres at `samplesX / 2` — for `samples=5` the taps land at `-2.5,-1.5,-0.5,0.5,1.5`, i.e. **shifted half a sample off centre**, so the blur biases the result; it also hard-codes `sigma = 10` regardless of sample count (with taps in ±2.5 that is effectively a box filter), normalizes by an accumulated `powerTotal` instead of a normalized kernel, and never calls the existing `build_gaussian_kernel_*` primitives. | UNJUSTIFIED | Port the fixed formulation: use `build_gaussian_kernel_2d`/`_1d` and the `(samples-1)*0.5` centring in `PointFitnessGaussianBlur`. Third-axis (`z`) support means a `build_gaussian_kernel_3d` sibling in `core/math/` is the clean shared path. | M / M — output values change (they are currently wrong); `PointFitnessFunction` has one external consumer (`mir-engine/model/game/logic/combat/scene-selection/SceneAffliction.js`) |
+| 5 | HIGH | **Binary wire format written in two places: the serializer and the version upgrader each re-derive the same header encoding** | `engine/grid/position/GridPositionSerializationAdapter.js:14` `serialize` ⟷ `engine/grid/position/GridPositionSerializationUpdater_0_1.js:11` `upgrade`; and `engine/grid/grid2transform/GridPosition2TransformSerializationAdapter.js:15` `serialize` ⟷ `engine/grid/grid2transform/GridPosition2TransformSerializationUpgrader_0_1.js:12` `upgrade` | The upgraders reproduce the v1 write path byte-for-byte, comments included (`//both coordinates are present`, `//write X`, `//both components are uint`). Changing the v1 encoding in the adapter leaves the upgrader emitting the old bytes into a stream the new deserializer will misread — a silent save-corruption path. Contrast `engine/navigation/ecs/path_following/PathFollowerSerializationUpgrader_3_4.js:8`, which uses `BinaryBuffer.copyUint16/copyFloat32` and never re-derives a format. | UNJUSTIFIED | Extract the v1 writers as typed free functions next to the adapters — `grid_position_write_v1(buffer, x, y)` and `grid_position_2_transform_write_offset_v1(buffer, offsetX, offsetY)` — and call them from both `serialize` and `upgrade`. | S / L |
+| 6 | HIGH | **Two parallel transform-parenting subsystems** (component + deferred binding + parent-transform subscription), one carrying a TODO that points at the other's implementation | `engine/ecs/attachment/Attachment.js:5` + `engine/ecs/attachment/AttachmentSystem.js:100/254` + `engine/ecs/attachment/TransformAttachmentBinding.js:8` ⟷ `engine/ecs/transform-attachment/TransformAttachment.js:17` + `engine/ecs/transform-attachment/TransformAttachmentSystem.js:176/201` + its `UpdateContext:14` | Components are near-identical (`parent:number = -1`, local `transform:Transform`, an `immediate`/`Immediate` flag). Both systems queue an entity until the parent `Transform` exists (`AttachmentSystem.processWaiting:105` / `TransformAttachmentSystem.__queue`), then subscribe to parent-transform change and recompose the child's world transform. `TransformAttachmentBinding.js:10` literally says *"TODO make use of `Transform.multiplyTransforms` for better readability and performance"* — which is exactly what `TransformAttachmentSystem`'s `UpdateContext.update:51` already does. Both are live: `Attachment` via `engine/ecs/speaker/VoiceSystem.js:423` and `engine/graphics/debug/shape_to_visual_entity.js:56`; `TransformAttachment` via `engine/ecs/parent/EntityNode.js:187`. | UNJUSTIFIED | `TransformAttachment` == `Attachment` with no socket. Make `AttachmentSystem`'s `TransformAttachmentBinding.update` delegate to `Transform.multiplyTransforms` (kills the matrix path and the TODO), and route both systems' deferred-parent wait through one typed `PendingParentQueue` class. Longer term the socket-less case should be expressed as `Attachment` with an identity socket. | L / M |
+| 7 | HIGH | **Per-entity link/unlink bookkeeping hand-rolled in ≥9 systems while the engine already ships a typed base class for it — and one hand-rolled copy has drifted into a listener leak** | Hand-rolled: `engine/grid/position/GridPositionSystem.js:47/79/88`, `engine/grid/grid2transform/GridPosition2TransformSystem.js:40/79/87`, `engine/grid/transform2grid/Transform2GridPositionSystem.js:100/119`, `engine/ecs/transform-attachment/TransformAttachmentSystem.js:176/201`, `engine/ecs/terrain/ecs/cling/ClingToTerrainSystem.js:88/110`, `engine/ecs/gui/position/ViewportPositionSystem.js:132/167`, `engine/input/ecs/systems/InputSystem.js:113/141`, `engine/graphics/ecs/animation/AnimationControllerSystem.js:18/64`, `engine/sound/ecs/SoundControllerSystem.js:49/103`. Existing solution: `engine/ecs/system/AbstractContextSystem.js:9` + `engine/ecs/system/SystemEntityContext.js` | Same shape everywhere: sparse per-entity store + a binding object subscribed in `link` and unsubscribed in `unlink`. Three incompatible store conventions (`this.data[]`, `this.removers[]`, `Map`) and three binding conventions (closure with a `.clear` property, plain `{update, transform, component}` + a module-level `deregister`, and a class with `link()`/`unlink()`). `GridPositionSystem.reset:88` and `GridPosition2TransformSystem.reset:87` are the same `for (let entity in data) { if (!data.hasOwnProperty(entity)) continue; … sync.clear(); }` body. **Drift already happened:** `ViewportPositionSystem.link:154` adds `el.view.size.onChanged.add(updatePosition, eventContext)` and `unlink:167-181` never removes it — a per-entity listener leak on a live GUI system. Only 7 systems engine-wide use `AbstractContextSystem` (`ParentEntitySystem`, `DynamicActorSystem`, `VoiceSystem`, `LightSystem`, `PathDisplaySystem`, `SpriteSystemPE`, `FPDecalSystem`). | UNJUSTIFIED | Migrate the hand-rolled systems onto `AbstractContextSystem` + a per-system `SystemEntityContext` subclass — already typed, already verbose, no strings/registries/decorators. `Transform2GridPositionSystem.Synchronizer` and `TransformAttachmentSystem.UpdateContext` are `SystemEntityContext` in all but name. Fix the `ViewportPositionSystem` leak as part of the migration. | L / M — one system at a time; each migration is behaviour-preserving and independently testable |
+| 8 | HIGH | **Vendored copy of three.js `KeyframeTrack.optimize()` that diverged from upstream and no longer does anything** | `engine/ecs/animation/AnimationOptimizer.js:16` `optimizeTrack` (called from `engine/asset/loaders/GLTFAssetLoader.js:426` on every loaded glTF animation) | The body is three.js's `KeyframeTrack.optimize`, but `this` here is the `AnimationOptimizer`, not the track — so lines 111-112 write `this.times`/`this.values` **onto the shared module-level optimizer instance** (`GLTFAssetLoader.js:32 const animationOptimizer = new AnimationOptimizer()`) and the track is never modified. It also carries upstream's typo `time !== time[0]` (should be `times[0]`). Net effect per track: two full array copies allocated and discarded. Meanwhile meep has its own, tested curve reducers: `engine/animation/curve/animation_curve_optimize.js:91` and `engine/animation/curve/compression/downsample_float_array_curve_by_error.js`. | UNJUSTIFIED | Either drop the call (it is a pure cost today) or re-target the writes to the track (`track.times = …; track.values = …`) and add a spec. Do not re-vendor: prefer `animation_curve_optimize` semantics once glTF tracks are routed through `engine/animation/clip/`. | S / L (currently a no-op, so "fixing" it changes glTF output — gate behind a test) |
+| 9 | MEDIUM | **`TextureAttachmentsByMaterialType` iteration written five times, twice in the same file** | `engine/asset/loaders/material/traverseMaterialTextures.js:9` (the generic one) ⟷ `engine/asset/loaders/GLTFAssetLoader.js:40` `replace_material_textures_from_cache` ⟷ `engine/asset/loaders/GLTFAssetLoader.js:92` `configureTextures` ⟷ `engine/asset/loaders/material/StaticMaterialCache.js:39` `acquire` ⟷ `engine/graphics/material/manager/compilers/CoalesceTextures.js:25` `transform` | `StaticMaterialCache.acquire:48-89` and `CoalesceTextures.transform:26-66` are byte-identical including the commented-out `//console.log('Re-using texture', existingTexture);`. `traverseMaterialTextures` already exists and is used by three other call sites (`MaterialDescriptor.js:23`, `promiseMaterialLoaded.js:13`, `prototypeLightManager.js:1232`) — the loader/compiler path just never adopted it. A new material type added to `TextureAttachmentsByMaterialType` propagates to all five automatically, but any change to the *null-texture* or *write-back* convention has five edit sites. | UNJUSTIFIED | Route all five through `traverseMaterialTextures(material, cb, thisArg)`. The texture-cache body shared by `StaticMaterialCache.acquire` and `CoalesceTextures.transform` becomes one exported `coalesce_material_textures(material, textureCache)` used by both. | S / L |
+| 10 | MEDIUM | **~70-line terrain-contact probe + influence computation copy-pasted between the two IK solvers** | `engine/ecs/ik/TwoBoneInverseKinematicsSolver.js:80-151` (inside `solve:50`) ⟷ `engine/ecs/ik/OneBoneSurfaceAlignmentSolver.js:80-151` (inside `solve:42`) | Identical sequence, same variable names, same comments: primary `terrain.raycastFirstSync` along the bone direction → `if (!contactExists) return` → secondary cast from the effector back along `-contactNormal` → `if (!contactExists) return` → `v3_displace_in_direction(targetPosition, offset*scale, contact…, normal…)` → `v3_dot(direction…, delta_contact_c…)` side test → `dot < 0 ? influence = 1 : influence = 1 - clamp01(constraint.distance.normalizeValue(inverseLerp(0, scale, len)))` → `if (influence <= 0) return`. Only `limbLength` vs `bone_scale` and the ray origin differ. Both solvers are live via `engine/ecs/ik/InverseKinematicsSystem.js:26-27`. | UNJUSTIFIED | Extract `engine/ecs/ik/ik_probe_terrain_contact(out_target, terrain, origin, effector, direction, constraint, length_scale) → number` returning the influence (`0` = no contact / no influence). Both solvers then keep only their rotation math. | M / L — pure extraction, both solvers already spec-adjacent |
+| 11 | MEDIUM | **Axis-tick-walking algorithm forked; the ceil→floor fix landed in only one copy** | `engine/animation/curve/editor/canvas2dDrawWorldAxisLabels.js:17` ⟷ `engine/graphics/canvas/canvas2d_draw_linear_scale.js:18` | Same prologue verbatim (`if (spacing <= 0) throw`, `delta_x/delta_y`, `v2_length`, `if (distance === 0) throw`, `direction_x/direction_y`). `canvas2d_draw_linear_scale.js:44-46` carries the fix *and the explanation*: "using ceil would place a final tick past position_1 with an extrapolated value" → `Math.floor`. `canvas2dDrawWorldAxisLabels.js:44` still has `Math.ceil` and therefore still draws that extrapolated final tick. They also use two different number formatters (`formatTruncDecimal` vs `core/primitives/numbers/number_pretty_print`). | UNJUSTIFIED | One `canvas2d_draw_linear_scale` taking an explicit `value_step` (uniform control flow — always supply the step; callers compute `(value_1-value_0)/mark_count` when they want a fitted scale). Delete the `Math.ceil` variant's body and re-export. | S / L |
+| 12 | MEDIUM | **A second 2D chart-plotting toolkit under `engine/animation/curve/editor/`, forked from `engine/graphics/canvas/`** | `engine/animation/curve/editor/canvas2dPlotCurveLine.js:17` ⟷ `engine/graphics/canvas/canvas2d_plot_data_line.js:16`; supporting pairs `canvas2dDrawWorldGrid.js` ⟷ `canvas2d_draw_grid.js`, `canvas2dDrawWorldAxisLabels.js` ⟷ `canvas2d_draw_linear_scale.js`, `canvas2dPlotCurvePoints.js` ⟷ `canvas2d_plot_line_array.js` | The two plot functions share the same skeleton and the same hard-coded palette: `'#222222'` background fill, two grid passes at `'#262626'` then `'#303030'` spacing 32, axis at `height - 4` and `x = 4`, `strokeStyle = '#00ff00'`, `lineWidth = 1`. A third copy of the same palette+grid pass is inlined at `engine/animation/curve/view/AnimationCurveView.js:159-203`. Style split (`snake_case` vs `camelCase`) marks the fork. `canvas2dPlotCurvePoints.js:1` also imports `Vector2` **from `three`** inside a pure-2D canvas helper — a vendor-boundary leak. | UNJUSTIFIED | Keep `engine/graphics/canvas/*` as the toolkit. The genuinely new capability in the editor fork is *world-space* grid/labels (`canvas2dDrawWorldGrid` handles a value range, `canvas2d_draw_grid` is screen-space only) — promote that as `canvas2d_draw_grid_world` alongside the existing helpers, then make the editor call the shared functions. Fix the `three` import to `core/geom/Vector2`. | M / M |
+| 13 | MEDIUM | **Three curve-space ↔ canvas-space mapping implementations inside the same feature** | `engine/animation/curve/view/AnimationCurveView.js:120/137` `point_curve_to_canvas` / `point_canvas_to_curve` (3×3 matrix + inverse) ⟷ `engine/animation/curve/draw/position_curve_to_canvas.js:12` / `position_canvas_to_curve.js:12` (size/frame/margin, allocates a `Vector2` per call) ⟷ `engine/animation/curve/editor/canvas2dPlotCurvePoints.js:32-60` (inline `axisSize`/`offset`/`inverseTimeRange` normalization) | All three map `(time, value) ↔ (px, py)` for the same `AnimationCurve` under the same margin convention. The `draw/` pair is used by `build_tangent_editor.js:127`, `displayMousePos.js:17`, `isInjectedKeyframeInBounds.js:21/56`, `createKeyframeDraggableAspect.js:64`, `createPanTool.js:30`; the matrix pair only by `AnimationCurveView`; the inline one only by the plot. A margin/anchoring change has to be made three ways or the editor's hit-testing desyncs from what is drawn. | UNJUSTIFIED | Keep the matrix formulation (`AnimationCurveView`'s `m3_cm_compose_transform` + `m3_invert`) — it is the only one that is exactly invertible — and expose it as a small typed `CurveViewport` class in `engine/animation/curve/` with `curve_to_canvas(out, x, y)` / `canvas_to_curve(out, x, y)` writing into caller-supplied arrays (kills the per-call `Vector2` allocation too). | M / M |
+| 14 | MEDIUM | **Mouse-parallax 3D tilt math copy-pasted, and the copy's pivot silently diverged** | `engine/ecs/gui/parallax/GuiElementParallaxSystem.js:36` `updateEntity` ⟷ `engine/ui/bindings/processors/DomElementProcessorTilt3D.js:56` `handleFrame` | Identical body down to the variable names and the CSS write (`transformOrigin = '50% 50%'`, `` transform = `rotate3d(${tilt_x},${tilt_y},0,${angle}deg)` ``). `GuiElementParallaxSystem.js:53-54` computes `center_x`/`center_y` from `getBoundingClientRect()` **and never uses them** — line 60-61 takes the delta against the *viewport* centre instead, so the ECS version tilts every element identically regardless of where it sits on screen. `DomElementProcessorTilt3D.js:82-83` uses the element centre (the evidently intended behaviour). The unused pair is the copy-paste fingerprint. | UNJUSTIFIED | Extract `engine/ui/apply_pointer_tilt_3d(el, pointerX, pointerY, viewportW, viewportH, angle, depth)` and call it from both. Decide the pivot once (element centre) — that also removes the dead `getBoundingClientRect()` call from the ECS path. | S / L |
+| 15 | MEDIUM | **`AnimationController` and `SoundController` are the same rule-driven event-binding system twice** | `engine/graphics/ecs/animation/AnimationControllerSystem.js:18` `link` / `:64` `unlink` ⟷ `engine/sound/ecs/SoundControllerSystem.js:49` `link` / `:103` `unlink` | `unlink` is token-identical (`this.removers[entity]` → `delete` → `callbacks.forEach(cb => dataset.removeEntityEventListener(entity, cb.name, cb.handler))`). `link` differs only in the payload built inside the start handler (`new AnimationClip()` + `animation.clips.add` vs `new SoundTrack()` + `emitter.tracks.add`); the surrounding rule-walk, the optional `stopEvent` registration and the `callbacks.push({name, handler})` bookkeeping are identical, comment placement included. | UNJUSTIFIED | Fold both onto `AbstractContextSystem` (finding #7) with a per-system `SystemEntityContext` subclass; the `{startEvent, stopEvent}` rule subscription becomes a shared typed `EntityRuleBinder` holding the `{name, handler}[]` and its teardown. The two payload builders stay as distinct typed methods. | M / L |
+| 16 | MEDIUM | **`removeEntityWithMeshParticlesEffect` reimplements `removeEntityWithEffect` and drops the transient-save guard** | `engine/animation/removeEntityWithMeshParticlesEffect.js:150` ⟷ `engine/animation/AnimationUtils.js:168` `removeEntityWithEffect` (used by `engine/animation/removeEntityGenericEffect.js:150`) | Same skeleton: same `removeComponentsExcept(ecd, entity, [Mesh, ParticleEmitter, Trail2D, Transform])` list, same `stopEntityAndNotifyWhenStopped(entity, ecd).then(() => ecd.removeEntity(entity))` tail. `removeEntityWithEffect:179` adds `SerializationMetadata.Transient` so a dying entity cannot land in a save; the mesh-particles copy never does — an entity mid-death-effect is serializable there. | UNJUSTIFIED | Have `removeEntityWithMeshParticlesEffect` call `removeEntityWithEffect`, passing the already-built emitter (it only needs the extra `distributeParticlesOnObject3D` step before the call). | S / L |
+| 17 | MEDIUM | **`setFlag`/`clearFlag`/`writeFlag`/`getFlag` quartet copied into 34 classes, with the `getFlag` predicate already diverged** | 34 files carry the identical quartet, e.g. `engine/ecs/animation/Animation.js:64-97`, `engine/ecs/gui/GUIElement.js`, `engine/ecs/speaker/Voice.js`, `engine/ecs/transform/Transform.js`, `engine/navigation/ecs/path_following/PathFollower.js`, `engine/grid/grid2transform/GridPosition2Transform.js`, `engine/asset/AssetRequest.js`, `core/events/signal/Signal.js`, `view/View.js`. Divergent `getFlag`: `engine/ecs/animation/AnimationClip.js:62`, `engine/ecs/Entity.js:142`, `core/math/lookup/ParameterLookupTable.js:82` | 34 sites use `return (this.flags & flag) === flag;` (all-bits-of-the-mask); 3 use `!== 0` (any-bit). Equivalent for single-bit flags, **opposite for composite masks** — and composite masks exist (`engine/ecs/animation/Animation.js:40` seeds `flags = MeshSizeCulling \| Playing`). Nothing documents which convention a given class follows. | UNJUSTIFIED (in logic, not merely shape — the predicate semantics disagree) | Two typed pieces, no metaprogramming: (a) free functions in `core/binary/bitfield/` (`bitfield_test_all`, `bitfield_test_any`) so intent is named at each call site; (b) a concrete `BitFlagCarrier` base class in `core/model/` for the ~25 classes with no other superclass. At minimum, unify the 3 outliers on the documented convention. | M / M — mechanical but wide; a codemod plus one spec asserting composite-mask behaviour per class |
+| 18 | MEDIUM | **Two parallel input-binding ECS subsystems, one deprecated only in a JSDoc line** | `engine/input/ecs/systems/InputSystem.js:92` + `engine/input/ecs/components/Input.js` + `engine/input/ecs/ism/InputBinding.js:4` (path → event name, `ecd.sendEvent`) ⟷ `engine/input/ecs/systems/InputControllerSystem.js:186` + `engine/input/ecs/components/InputController.js` + `engine/input/ecs/components/InputBinding.js:3` (path → listener fn, priority/exclusive proxy dispatch) | `InputControllerSystem.js:184` says "Prefer to use {@link InputSystem} instead" but the class is otherwise undecorated and fully live. Both resolve the device signal identically via `resolvePath(devices, path)` and subscribe/unsubscribe. Within `InputSystem.js`, `linkBinding:14` and `unlinkBinding:29` are a 14-line verbatim pair differing only in `signal.add` vs `signal.remove` — all three assert messages duplicated. | UNJUSTIFIED (the `linkBinding`/`unlinkBinding` pair); the two subsystems are a migration in progress | Collapse `linkBinding`/`unlinkBinding` into one `resolve_device_signal(devices, path) → Signal` (the asserts live there) with `.add`/`.remove` at the two call sites. Add `@deprecated` to `InputControllerSystem`, `InputController` and `engine/input/ecs/components/InputBinding` so the JSDoc note is machine-visible. | S / L |
+| 19 | MEDIUM | **JSON-derived asset loaders repeat the same scaffold, and all of them lose parse errors** | `engine/ecs/sockets/serialization/AttachmentSocketsAssetLoader.js:7` ⟷ `engine/graphics/ecs/animation/animator/graph/definition/serialization/AnimationGraphDefinitionAssetLoader.js:7` ⟷ `engine/asset/loaders/JavascriptAssetLoader.js:22` | All three: `await this.assetManager.promise(path, GameAssetType.X, {scope, progress})` → `.create()` → `new Asset(() => parse(json), 1)` → `success(asset)`. None passes `failure`, so a throw out of the awaited call or out of the parser rejects the async `load()` into an unobserved promise — compare `GLTFAssetLoader.js:441`, which routes explicitly (`.then(success, failure)`) with a comment explaining exactly this hazard. | UNJUSTIFIED | A typed `DerivedAssetLoader extends AssetLoader` with an abstract `sourceType` getter and `build(json) → *`, whose `load` owns the `try/catch → failure(e)` wiring once. Verbose, typed, one subclass per asset kind. | S / L |
+| 20 | LOW | **Three loaders hand-roll a structural stand-in for the existing `Asset` class** | `engine/asset/loaders/TextAssetLoader.js:7`, `engine/asset/loaders/JsonAssetLoader.js:19`, `engine/asset/loaders/SVGAssetLoader.js:14` | Each builds `const asset = { create: function () { return X; } }` instead of `new Asset(factory, byteSize)`. `Asset` (`engine/asset/Asset.js`) carries `byteSize`, `dependencies` and the scope machinery the `AssetManager` overhaul introduced; the duck-typed objects report no weight to the cache. | UNJUSTIFIED | `new Asset(() => data, data.length)` in all three. | S / L |
+| 21 | LOW | **`Quaternion.fromAxisAngle` and `Quaternion.lookRotation` reimplemented module-privately** | `engine/input/ecs/util/TopDownCameraControllerHelper.js:21` `CreateFromAxisAngle` and `:32` `lookAt` ⟷ `core/geom/Quaternion.js:335` `fromAxisAngle` / `:217` `lookRotation`, and `core/geom/3d/quaternion/quat3_from_axis_angle.js:7` | `quat3_from_axis_angle.js` carries the JSDoc line "just in case you need that function also"; `TopDownCameraControllerHelper.js:20` carries the *same stray comment* as a `//` line — proof of a copy chain. The local `lookAt` also hard-codes `3.1415926535897932` and two `0.000001` epsilons instead of `core/math/PI.js` / `core/math/EPSILON.js`, and unlike `Quaternion.lookRotation` (which has a spec suite at `core/geom/Quaternion.spec.js:274-297`) it takes no up-vector. | UNJUSTIFIED | Delete the two module-private functions; call `Quaternion.prototype.fromAxisAngle` / `lookRotation`. (`core/geom/3d/quaternion/quat3_createFromAxisAngle.js` is a correctly-documented `@deprecated` alias — leave it.) | S / L |
+| 22 | LOW | **Quaternion-rotate-vector inlined in a GUI system** | `engine/ecs/gui/hud/HeadsUpDisplaySystem.js:92-106` (inside `__apply_entity_transformation:75`) ⟷ `core/geom/vec3/v3_quaternion_apply.js`, `core/geom/Vector3.js`, `core/geom/Vector4.js` | The `ix/iy/iz/iw` two-Hamilton-product expansion is reproduced verbatim. `v3_quaternion_apply(out, out_offset, vx, vy, vz, …)` already writes into a caller-supplied array, so the usual "avoid an object allocation" defence does not apply. | UNJUSTIFIED | Call `v3_quaternion_apply` with a module-static scratch `Float64Array(3)`. | S / L |
+| 23 | LOW | **Cubic easing functions redefined module-privately instead of joining the engine's easing enum** | `engine/control/first-person/abilities/Mantle.js:9` `easeInOutCubic`, `:21` `easeOutCubic`, `:30` `easeInCubic` ⟷ `engine/animation/TransitionFunctions.js:7` (`Linear`, `Sine`, `EaseIn`, `EaseOut`, `EaseInOut`, `CubicEaseIn`) | `TransitionFunctions` is the engine-wide easing enum (11 consumers across `achievements`, `ui`, `ecs/gui`, `ecs/speaker`, `animation`). Cubic in/out/in-out is exactly what it is missing, so the next consumer will write a fourth copy. A parallel *curve*-valued easing set also exists at `engine/animation/curve/preset/CURVE_EASE_IN.js` / `_OUT` / `_IN_OUT` — the same three concepts as `AnimationCurve` objects. | PROMOTION | Add `CubicEaseIn`/`CubicEaseOut`/`CubicEaseInOut` to `TransitionFunctions` and have `Mantle.js` import them. Cross-reference `TransitionFunctions.EaseIn` ↔ `CURVE_EASE_IN` in JSDoc so the two representations are discoverable as a pair. | S / L |
+| 24 | LOW | **The same 6-stop heatmap palette declared twice** | `engine/ecs/terrain/util/paintTerrainOverlayViaLookupTable.js:11-20` ⟷ `engine/graphics/render/forward_plus/debug/createScreenGrid.js:180-189` | Identical `new ParameterLookupTable(4)` + the same six RGBA rows (`0,0,0,255` … `255,5,5,255`) + `computeUniformPositions()`. A palette change makes the terrain overlay and the froxel debug grid disagree. | PROMOTION | `core/math/lookup/LUT_HEATMAP.js` exporting a frozen shared `ParameterLookupTable`. | S / L |
+| 25 | LOW | **Graphviz DOT preamble duplicated across graph dumpers** | `engine/intelligence/behavior/behavior_to_dot.js:240-257` ⟷ `core/bvh8/bvh8_convert_to_dot.js:110-122`; also `core/graph/convert_graph_to_dot_string.js:27`, `core/model/node-graph/util/convert_node_graph_to_dot_string.js:43`, `engine/graphics/render/frame_graph/FrameGraph.js:543` | The `font = {name:"helvetica", size:10}` object and the `graph [style=invis, rankdir="TB" ordering=out, splines=spline]` + `node [shape=record, fontname=…, fontsize=…, margin="0.2,0.03", fillcolor=ivory]` attribute lines are byte-identical between the behavior and BVH8 dumpers. Five emitters, five copies of the styling contract. | PROMOTION | `core/graph/dot/dot_graph_begin(line_builder, name)` / `dot_graph_end(line_builder)` in `core/`, carrying the default node/edge styling. | S / L |
+| 26 | LOW | **Third binary-search-over-sorted-keys implementation** | `engine/animation/curve/AnimationCurve.js:~228` (index search inside the keyframe lookup) ⟷ `engine/animation/async/table_find_min_index_in_ordered_column.js:10` ⟷ `core/collection/array/binarySearchLowIndex.js:10` | Same `(min + max) >>> 1` loop three ways, with three different out-of-range answers: `binarySearchLowIndex` returns `-1` below the range, `table_find_min_index_in_ordered_column` returns `min2(minIndex, maxIndex)`, `AnimationCurve` pre-clamps to `0` / `key_count - 1`. The table variant is legitimately different (it indexes a `RowFirstTable`, not an array). | UNJUSTIFIED for the `AnimationCurve` copy; JUSTIFIED for the table variant (different storage) | `AnimationCurve` can call `binarySearchLowIndex(keys, time, compare_time_to_keyframe)` with a module-static comparator (no per-call closure). Document the differing out-of-range contracts in all three JSDocs regardless. | S / L |
+| 27 | LOW | **Composite-behavior children wire format written twice** | `engine/intelligence/behavior/composite/SequenceBehaviorSerializationAdapter.js:19/37` ⟷ `engine/intelligence/behavior/composite/ParallelBehaviorSerializationAdapter.js:19/42` | Both encode the child list as `writeUintVar(n)` + N `objectAdapter.serialize`, and decode as `readUintVar()` + `clearChildren()` + N `addChild`. `ParallelBehavior` merely prefixes two policy bytes. Only two adapters exist today, so the blast radius is small — but a change to the child-list encoding needs both. | UNJUSTIFIED (marginal) | A typed `CompositeBehaviorSerializationAdapter extends ObjectBasedClassSerializationAdapter` exposing `serializeChildren(buffer, value)` / `deserializeChildren(buffer, value)`; the two concrete adapters keep their own `serialize`/`deserialize` and call them. | S / L |
+| 28 | LOW | **`1.0 + (raw - 1.0) * flatBoost` — `lerp` re-derived four times** | `engine/control/first-person/mastery/StrideTimingJumpEvaluator.js:95`, `SlideInitiationTimingEvaluator.js:81`, `BreathRhythmEvaluator.js:131`, `FootAsymmetryTurnEvaluator.js:107` | The identical "scale the deviation around 1.0" expression, each with its own 2–4 line comment explaining it. `core/math/lerp.js` exists and is spec'd. | UNJUSTIFIED (cosmetic) | `lerp(1.0, raw, this.flatBoost)`, with the explanation moved to `MasteryEvaluator`'s class JSDoc where the convention is already documented. | S / L |
+| 29 | LOW | **Cross-domain check — `engine/ecs/ik` correctly reuses the physics two-bone solver** | `engine/ecs/ik/TwoBoneInverseKinematicsSolver.js:11` imports `two_joint_ik` from `engine/physics/inverse_kinematics/two_joint_ik.js`; live via `engine/ecs/ik/InverseKinematicsSystem.js:26` | Verified: there is **no** second two-bone IK implementation on the ECS side — the solver delegates. Logged so the physics-domain agent does not double-report it. | JUSTIFIED (correct reuse) | none | — |
+
+## Dismissed leads
+
+- **`PointFitnessBinary.evaluate:29` ⟷ `CellFilterBinaryOperation.execute:31`** — same template-method shape, but different hierarchies with different sample signatures (`(ecd,x,y,z)` vs `(grid,x,y,rotation)`); no shared base is viable. Shape-only.
+- **`PointFitnessAdd.from` / `PointFitnessMultiply.from` (+ 10 more in the [49x12] group)** — per-class typed factories identical in shape. Explicitly deliberate per house rules.
+- **`CompositeBehavior.addChildren:36` ⟷ `Tag.addAll:59` ⟷ `Task.addDependencies:187`** — 5-line "for-each call the singular add" over three unrelated types. Too small to share; extracting would need a callback and lose the typing.
+- **`AnimationOptimizer.optimize:123` ⟷ `IncrementalDeltaSet.pushOther:310`** — the mechanical match is only the `for (i…) { … method(item) }` loop. The *real* problem with `AnimationOptimizer` is finding #8.
+- **`BehaviorComponent.from:121` ⟷ `KillBehavior.create:23`** — assert-then-construct factories on unrelated classes. (Worth noting only that the codebase uses `from` and `create` interchangeably for the same idiom.)
+- **`makeDefaultSlideInitiationTimingCurve:21` ⟷ `makeDefaultStrideTimingJumpCurve:18`** — identical construction *shape* but the four keyframe values are authored design data with different documented intent. Correctly built on the existing `AnimationCurve`/`Keyframe` types.
+- **`Voice`** declared in `engine/ecs/speaker/Voice.js` and `engine/sound/sopra/runtime/Voice.js` — completely different concepts (speech-bubble ECS component vs. a pooled WebAudio source). Name collision only, no shared code.
+- **`InputBinding`** declared in `engine/input/ecs/components/` and `engine/input/ecs/ism/` — different data models (path→callback vs path→event-name). Rolled into finding #18 as the deprecation half; not itself duplicated code.
+- **`canvas2dDrawWorldGrid` ⟷ `canvas2d_draw_grid`** — the world-space variant genuinely handles a value range the screen-space one does not. Covered as the promotion half of #12, not as duplication.
+- **`PoseInterpolationAdapter.interpolate:17`** (7 inline lerps + inline nlerp) — deliberate scalar-register hot path over a `BinaryBuffer`; using `Vector3`/`Quaternion` would force reads into objects. Justified.
+- **`HeadsUpDisplaySystem` ⟷ `ViewportPositionSystem`** — the HUD system writes into `ViewportPosition` and lets `ViewportPositionSystem.setElementPosition:197` do the DOM placement. Correct layering, no duplication.
+- **`prototype_first_person_controller.js` ⟷ `prototypeAcousticSolver.js`** (`makePhysicsGroundResolver`, `buildInputBindings`, `recomputeMove`, `bindMoveKey`, `logHelp`) — both are `prototype*.js` browser harnesses, out of scope.
+- **`table_find_min_index_in_ordered_column`** as a duplicate of `binarySearchLowIndex` — justified: it indexes a `RowFirstTable`, not an array. Only the `AnimationCurve` copy is flagged (#26).
+- **`GridPositionSerializationAdapter.serialize` ⟷ `GridPositionSerializationUpdater_0_1.upgrade` as "shape duplication"** — *not* dismissed; this is finding #5. Listed here only because the mechanical brief filed it as a MinHash near-match rather than as a format-invariant hazard.
+- **`removeEntityGenericEffect.js` / `removeEntityWithMeshParticlesEffect.js` embedded emitter JSON** (~130 lines each, `cloud-puff` vs `mesh-cloud-puff-0`) — duplicated *data*, not logic; the two presets have genuinely different tuning. Belongs in `data/` but is not a reuse failure.
+- **`engine/interpolation/**` vs `core/math` easing** — no duplicate easing library there; `engine/interpolation/` is snapshot interpolation (`InterpolationLog`, `Interpoland`, binary pose adapters), unrelated to easing curves. The real easing duplication is #23.
+- **`binary_search_inline` / `inline_clamp_ternary` hits under `engine/asset/loaders/**`** — checked: `image/png/crc32.js:24` and `png_filter_unFilterNone.js:42` are bit-shifts inside PNG codecs, not searches; `computeMassRatios.js:30`'s `Math.max(0, Math.min(1, x))` is one site and `clamp01` exists, but it is cold init code (LOW-of-LOW, folded into no row).
+
+## Notes
+
+Structural reasons duplication concentrates in this domain:
+
+1. **Three generations of animation coexist with no deprecation markers on the older two.** `engine/animation/keyed2/` (multi-property tracks + per-key transition functions, the only one the GUI/notifications/achievements actually use) → `engine/animation/curve/` (`AnimationCurve` + Hermite `Keyframe`, self-declared as the successor in `keyed2/AnimationTrack.js:6`) → `engine/animation/clip/` (glTF-shaped clip/track built on `AnimationCurve`). Orthogonally, **two** ECS animation runtimes drive three.js (`engine/ecs/animation/` + `AnimationSystem` vs `engine/graphics/ecs/animation/animator/` + `AnimationGraphSystem`). Five layers, one namespace: three exported `AnimationClip`, three `AnimationTrack`, two `AnimationClipFlag`. Because meep is a library, nothing was deleted during each migration — but nothing was marked `@deprecated` either, so each generation keeps attracting new code and each new consumer picks whichever name resolves first.
+
+2. **The engine already solved the ECS lifecycle problem and then only half-adopted the solution.** `AbstractContextSystem` + `SystemEntityContext` is exactly the typed, verbose, no-magic answer the house rules ask for — and only 7 systems use it. Nine more in this domain hand-roll the same store + binding + teardown, in three mutually incompatible conventions. That is where the drift shows up: `ViewportPositionSystem` subscribes six things and unsubscribes five.
+
+3. **Serialization upgraders re-derive formats instead of copying fields.** The `BinaryBuffer.copyUint16/copyFloat32` idiom (used correctly by the `PathFollower` upgrader chain) makes an upgrader immune to later format changes. The two `grid/` upgraders instead paste the serializer's write path, which couples every future format edit to two files that no test compares.
+
+4. **Fork-then-fix, never back-port.** Four independent instances of the same failure mode: `CellFilterGaussianBlur` fixed a centring/normalization bug that `PointFitnessGaussianBlur` still has; `canvas2d_draw_linear_scale` fixed a `ceil`→`floor` tick bug (with a comment explaining it) that `canvas2dDrawWorldAxisLabels` still has; `TransformAttachmentSystem` adopted `Transform.multiplyTransforms` while `TransformAttachmentBinding` still carries a TODO to do so; `removeEntityWithEffect` added the `SerializationMetadata.Transient` guard that `removeEntityWithMeshParticlesEffect` lacks. In each pair the *newer* file is correct, which means the duplication is actively hiding fixes rather than merely wasting lines.
+
+5. **`snake_case` vs `camelCase` marks the fault lines.** `engine/graphics/canvas/canvas2d_*` vs `engine/animation/curve/editor/canvas2d*` is the clearest case — the naming split is a reliable indicator of a fork, and searching for one convention never surfaces the other.