@woosh/meep-engine 3.1.0 → 3.2.0

package/src/engine/REVIEW_2026_07_03.md

@@ -1,211 +1,211 @@
-# Engine Package — Correctness Review (2026-07-03)
-
-**Scope:** `app/src/mir-engine/meep/src/engine` — the full engine package (~222,000 LOC of reviewable source across 1,782 non-spec, non-prototype `.js` files, 27 top-level subsystems).
-
-**Method:** Fanned-out review — ~26 specialist agents, each assigned a coherent subsystem with a strict *correctness-only* brief (no style, no nitpicks; `prototype*.js` out of scope; unreferenced exports treated as public library surface, not dead code; `assert.*` treated as stripped in production). Every finding requires a concrete failure scenario. The five highest-impact CRITICALs were re-verified by reading the actual source. This document is the synthesis.
-
----
-
-## 1. Executive summary
-
-The engine is **large, mature, and — in its heavily-exercised numerical cores — genuinely solid.** The recently-hardened subsystems held up under fresh scrutiny: **physics** (solver, narrowphase, fluid — 26k LOC) came back essentially clean (2 low-reach mediums in a 2D demo file and a near-parallel-capsule edge case); the **acoustic simulation core** (Steam-Audio-style sim + Sopra middleware) was verified line-by-line and is clean; the **network core** has had its four previously-known P0 security bugs **fixed** (malformed-packet crashes contained, pending-log bounded, RESUME_HELLO safe, inbound authorization now exists).
-
-The defects concentrate in the **glue and lifecycle code** rather than the algorithms: ECS entity/observer lifecycle, ECS↔render/audio bindings, component copy/clone and JSON-vs-binary serialization, GPU/listener cleanup on teardown, and a long tail of one-character typos that survive because they sit on paths without a regression test. Many are trivial to fix; several corrupt data or crash on common paths.
-
-### Headline counts
-
-| Severity | Count | Character |
-|---|---:|---|
-| **CRITICAL** | ~21 | Crash, data corruption, or wrong result on a common/default path (or a security hole). Mostly small, high-value fixes. |
-| **HIGH** | ~61 | Wrong result or crash on a real path (often a specific-but-normal configuration). |
-| **MEDIUM** | ~97 | Wrong result on an edge case, or a resource leak. |
-
-> A large fraction of the CRITICAL/HIGH items are **one-line or few-line fixes** (a typo, a wrong axis, a `subscribe` that should be `unsubscribe`, a `floor` that should be `ceil`). The volume reflects *breadth of surface*, not systemic rot — the numerical cores are trustworthy; the seams between systems are where correctness leaks.
-
-> **Correction (post-review verification):** an initial group of ~5 "re-entrancy" findings was adversarially re-verified against the actual call graph and largely withdrawn — see **§8**. JavaScript has no threaded concurrency, and *synchronous* re-entrancy (a callback calling back into the same function) turned out to have **no concrete triggering caller** for the ECS cases. The counts above already reflect the corrections (1 critical demoted, 3 highs dropped, 1 high reclassified to medium). The concrete, source-verified criticals below are unaffected.
-
-### Health by subsystem
-
-| Subsystem | Verdict |
-|---|---|
-| physics (solver / narrowphase / fluid) | **Solid.** Cores clean; only a 2D-demo bounds bug + one capsule edge case. |
-| sound (acoustic sim + Sopra) | **Solid.** Sim/render/serialization clean; a few edge-case runtime mediums. |
-| network (core + transport) | **Good.** Prior P0s fixed; 1 residual auth-default HIGH, a few mediums. |
-| interpolation, animation curve math | **Solid.** Easing/Hermite/binary-search correct; bugs are in serialization & playback wrapping. |
-| **ecs (core)** | **Concern.** 1 critical (observer-lifecycle leak) + several high-severity lifecycle/serialization bugs. (A re-entrant-scratch "critical" was withdrawn on verification — see §8.) |
-| **graphics (ecs bindings, texture, particles)** | **Concern.** Multiple criticals (atlas lookup, particle buffer, decal/light bindings). |
-| **gameplay glue (control/input, attachment, grid, terrain/fow)** | **Concern.** Criticals in wall sensors, input sort, attachment queue, fog-of-war, terrain seams, grid rounding. |
-| MikkTSpace tangent/weld | **Concern.** 2 criticals defeat tangent smoothing & vertex welding for real meshes. |
-| asset loaders | **Concern.** Preloader hang + several decode/round-trip bugs. |
-
----
-
-## 2. Recurring patterns (fix the class, not just the instance)
-
-The same mistakes recur across unrelated subsystems. Each is worth a targeted sweep:
-
-1. **`copy()` / `clone()` drops fields.** `Camera.copy` (fov, clip planes), `GridPosition2Transform.copy` (flags), `Transform.copy` (propagates a cleared auto-update flag). Cloned entities silently revert to defaults. → *Audit every `copy()`/`clone()` against its field list; add round-trip tests.*
-2. **JSON vs binary (de)serialization diverge.** AnimationGraph state `name`/`tags` dropped; `startingSate` typo; POINT-light `distance` binary-only; `SerializationMetadata` flags truncated to 8 bits; `Team` sentinel aliasing; `ViewportPosition.resolveGuiCollisions` dropped; `AnimationClip.repeatCount` defaults to ∞ in JSON but 1 in the field; sound-material `type` always `undefined`. → *Every component needs a JSON↔binary↔field round-trip test.*
-3. **subscribe/unsubscribe asymmetry & wrong-signal binding.** Decal `unlink` re-subscribes instead of unsubscribing; `LightBinding` binds the scale handler to `rotation.onChanged`; `TransformAttachmentBinding` never watches its local transform; `ForwardPlusRenderingPlugin.shutdown` removes from the wrong signal; `WaterSystem.shutdown` dereferences a non-existent field. → *Every `link/startup` subscription must have a matching `unlink/shutdown` removal on the same signal.*
-4. **GPU / listener leaks on teardown.** `GraphicsEngine.stop`, `GUIEngine.shutdown`, `SceneManager.clear`, `DomElementProcessorManager.unlink`, `Water`/`CameraSystem.rebuild`, `set_environment_texture`, virtual-atlas eviction. → *Teardown paths need the same rigor as setup.*
-5. **Shared instance state reused across a sequential loop.** `SimulationStepCurlNoiseVelocity` reuses one step instance for every emitter and accumulates `this.time` per call → curl-noise animates ∝ emitter count. → *Derive phase from a per-emitter/global clock, not an accumulator on the shared step.* *(This is the one surviving instance of what was originally framed as a broader "shared-scratch re-entrancy" pattern; the ECS re-entrancy findings were withdrawn on verification — see §8.)*
-6. **Axis / plane-index confusion.** FogOfWar width/height swap; HUD `z *= scale.y`; frustum near/far indexed as `[0]`/`[5]` inconsistently; sensor right-vector sign; ortho `bottom - top`. → *Centralize frustum-plane index constants; unit-test coordinate transforms with non-square / non-uniform inputs.*
-7. **Array mutation during iteration / bad sort comparators.** `SGMeshSystem` splices while modulo-indexing; `ParticleGroup.deleteIndices` uses a lexicographic sort; `optimizeCommandQueue` and `InputControllerSystem` comparators are non-antisymmetric/typo'd; `InputControllerSystem.remove` splices index `-1`. → *Snapshot before mutating; always pass a numeric comparator.*
-8. **Log-and-fall-through (missing `return` after an error).** `SoundControllerSystem`, `SoundEmitterSystem`, `ParticleVolume.fromJSON`, terrain `obtainTileAtWorldPosition2D` log or warn, then dereference the thing they just reported missing.
-9. **Default-value divergence between field init and `fromJSON`.** `repeatCount` (1 vs ∞), `screenEdgeWidth` (10 vs 0).
-
----
-
-## 3. Critical findings
-
-Ranked by blast radius on common/default paths. **✔ = re-verified against source by the lead reviewer.**
-
-| # | Subsystem | Location | Defect | One-line fix |
-|---|---|---|---|---|
-| C1 ✔ | ecs core | `ecs/EntityObserver.js:130` | `isConnected` returns `dataset === null` — **inverted**; `EntityManager.detachDataset` then skips `removeObserver` for every live observer → `System.unlink` never runs on detach → resources leak, re-attach double-links. | `return this.dataset !== null;` |
-| C3 ✔ | grid | `grid/transform2grid/Transform2GridPositionSystem.js:56` | `Ceil` mode calls `v2.floor()` (copy-paste) → Ceil-mode entities placed in the **wrong grid cell**; pathing/occupancy read the wrong tile. | `v2.ceil();` |
-| C4 ✔ | ecs attachment | `ecs/attachment/AttachmentSystem.js:80` | `clearAllWaitRecordsFor` shadows the param then tests `if (entity === entity)` (always true) → **wipes the entire attachment wait-queue** on any unlink. | Compare `waiting[i]` against the parameter. |
-| C5 ✔ | graphics/ecs | `graphics/ecs/decal/v2/FPDecalSystem.js:216` | `unlink()` calls `transform.subscribe(...)` (should be `unsubscribe`) after nulling `__fp_decal` → next transform change calls `.setTransform` on `null` → **crash** + listener leak. | `transform.unsubscribe(...)` |
-| C6 | control | `control/first-person/sensors/FirstPersonSensorsSystem.js:131` | Body-right vector is the **negation** of the controller's own convention → `wallLeft`/`wallRight` swapped → wall-run tilts the camera the wrong way, all wall logic mirrored. | `rx = -cos(yaw); rz = sin(yaw);` |
-| C7 | input | `input/ecs/systems/InputControllerSystem.js:100` | Priority comparator reads `b.priotity` (typo; field doesn't exist) → `NaN` comparator → **non-deterministic input dispatch order**; exclusive bindings cut the wrong handler. | `b.priority - a.priority` + define the field. |
-| C8 | particles | `particular/group/ParticleGroup.js:466` | `indices.sort()` (lexicographic) feeds a compaction that assumes ascending numeric order → with any index ≥ 10, **corrupts the particle buffer & reference maps**. | `indices.sort((a,b)=>a-b)` |
-| C9 | particles | `particular/engine/emitter/ParticlePool.js:507` | `updateRange.count = n` (particles) not `n*itemSize` (elements) → only the first `1/itemSize` of particles get multi-component attribute updates uploaded (e.g. ¾ of colors stale). | `attribute.updateRange.count = n * itemSize;` |
-| C10 | graphics texture | `graphics/texture/atlas/AtlasLookupTexture.js:80` | Writes patch **height into the width channel** (`size.y` twice, `size.x` never) → non-square atlas patches sample a wrong-width sub-rect → garbled sprites. | `data[address + 2] = size.x;` |
-| C11 | graphics texture | `graphics/texture/sampler/resize/sampler2d_scale_down_lanczos.js:93` | `rcp_ratio_y = 2 / ratio_x` → non-uniform Lanczos downscale uses the wrong support in Y (ships broken; its spec is `describe.skip`). | `2 / ratio_y` |
-| C12 | ecs fow | `ecs/fow/FogOfWar.js:562` | `rebuildSampler` swaps width/height → **transposed fog grid** for any non-square map; all reveal/conceal indexing uses the wrong stride and resize corrupts. | `samplerWidth = size.x+2; samplerHeight = size.y+2;` |
-| C13 | ecs terrain | `ecs/terrain/tiles/TerrainTileManager.js:562` | Seam-stitch uses `floor(size/tileSize)` but tiles are created with `ceil` → partial edge tiles **never seam-stitched** → lighting crease on every non-multiple terrain boundary. | Use `ceil` in `stitchTile`. |
-| C14 | asset | `preloader/AssetPreloader.js:291` | `assetLoadFailed` lacks the level-completion check `assetLoadSuccess` has → if a **failure is the last completion** in a level, `levelFinished` never fires → **the whole preload hangs**. | Dispatch `levelFinished` on `loaded+failed >= batch_size`. |
-| C15 | navigation | `navigation/ecs/path_following/PathFollower.js:160` | `fromJSON` gates on `json.loop` but writes `json.active` into the Loop flag → a one-shot mover deserializes as looping → teleports to start forever, never fires `EndReached`. | `writeFlag(Loop, json.loop)` |
-| C16 | animation | `animation/curve/actionProcessorOperations/curveActions.js:118` | `MoveKeyframeAction` aliases live curve keyframes to its undo snapshots then mutates them in place → **undo/redo corrupts the curve**. | Copy values into existing keyframes; don't reassign references. |
-| C17 | geometry | `graphics/geometry/MikkT/BuildNeighborsFast.js:116` | Edge-neighbor pairing reads the wrong array slots (compares a vertex index against an edge number) → neighbors never found for real meshes → **per-face (faceted) tangents** → normal-map seams everywhere. | Read `temp_edge_B[0],[1],[2]`; drop the bogus flip. |
-| C18 | geometry | `graphics/geometry/MikkT/GenerateSharedVerticesIndexList.js:79` | Radix-sort insertion has an operator-precedence bug (`&0xff` masks the whole sum) → multi-byte vertex hashes mis-sorted → **vertex welding fails** (duplicates survive). | `pass*257 + ((key>>shift)&0xff)` |
-| C19 | logging | `logging/elastic/ElasticSearchLogger.js:82` | Constructor sets `__timeout_ms` but the scheduler reads `__timeout` (undefined) → the timed flush is **never armed** → any session logging < 500 records loses **all** buffered logs on unload. | Unify the field name. |
-| C20 | ecs core | `ecs/EntityComponentDataset.js:1886` | `dropData` clears `__entityEventListeners` but not `__entityAnyEventListeners`; entity ids recycle → a new entity inherits the **previous scene's** any-listeners with a dangling context → crash/corruption on fast scene swap. | Also clear `__entityAnyEventListeners`. |
-| C21 ✔ | ecs core | `ecs/EntityManager.js:357` | `detachDataset` calls `system.handleDatasetAttached(dataset)` while tearing the dataset down (should be `handleDatasetDetached`) → dataset-switching systems re-run attach logic on detach. | `handleDatasetDetached(dataset)` |
-| C22 | sound | `sound/material/concrete/json/serializeSoundMaterialToJSON.js:3` | Reads `typeName` off the prototype but it's a **static** on the constructor → always `undefined` → every composite sound-material serializes `type: undefined` → deserialize throws. | `material.constructor.typeName` |
-
-> **`C2` is intentionally absent** — the original C2 (`traverseEntities` scratch re-entrancy) was demoted to a LOW latent-hazard on verification and moved to §8. Numbering C3–C22 is preserved for traceability with the working notes.
-
----
-
-## 4. High-severity findings by subsystem
-
-### ECS core & lifecycle
-- **`Entity.promiseEvent`** (`:327`): calls `removeEventListener(EntityRemoved, reject)` instead of `add` → the promise never rejects on entity removal → **awaiter hangs forever**.
-- Binary entity-id delta encoding (`BinaryBufferSerializer.js:174`) relies on ascending traversal order guarded only by a stripped assert → silent corruption if order ever breaks.
-- *(Two "re-entrant event dispatch / removeEntity" items previously listed here were withdrawn on verification — the dispatch path is deliberately recursion-safe, and no caller triggers the removeEntity hazard. See §8.)*
-
-### Graphics — ECS bindings
-- **`LightBinding`** (`graphics/ecs/light/binding/LightBinding.js:51`): scale handler bound to `rotation.onChanged` → spot-light range goes stale on scale.
-- **`WaterSystem.shutdown`** (`:61`): dereferences non-existent `graphicsEngine.size` → TypeError on teardown; real `preRender` hook leaked.
-- **`auto_set_camera_clipping_planes`** (`:44,100`): reads `old_near/far` *after* overwriting them with the outer bounds → autoClip hysteresis never tightens → persistent z-fighting.
-- **`set_camera_aspect_ratio`** (`:26`): ortho `h = bottom - top` (negative) → mirrored/inverted frustum on resize.
-- **`ForwardPlusRenderingPlugin.shutdown`** (`:80`): unsubscribes from the wrong signal → `__prepare_for_render` keeps firing on **disposed** GPU textures.
-- **`sg_hierarchy_compute_bounding_box_via_parent_entity`** (`:19`) & **`SGMeshSystem.update`** (`:281`): the former ignores its `entity` arg (empty AABB → wrong LPV probes); the latter splices its wait-queue while modulo-indexing → skips entities & dereferences `undefined`.
-
-### Graphics — texture / particles / geometry
-- Managed atlases serve **stale, atlas-evicted patches** from a TTL-∞ loader cache (`ManagedTextureAtlas.js`); `CachingTextureAtlas.__evict_all` leaves index 0 behind (`:152`).
-- `sampler2d_scale_down_linear` (`:53`) mis-indexes on non-integer ratios; `sampler2d_copy_with_margins` (`:124`) uses `width` for a vertical bound → non-square seams.
-- *(MEDIUM)* Curl-noise simulation time advances **once per emitter** on a shared step instance → noise animates ∝ emitter count (`SimulationStepCurlNoiseVelocity.js:22`). *Shared-sequential-state (a per-emitter loop reusing one instance), not re-entrancy.*
-- `ParticleEmitter` hash/equals disagree on flags; `ShaderManager` leaks a disposed emitter after a graveyard round-trip.
-- `equal_attribute_structure` returns truthy `-1` on name mismatch → **merges incompatible geometries** (`merge_geometry_hierarchy.js:92`); `InstancedMeshGroup.build` retains stale per-instance colors on shrink+regrow.
-- **`bvh32_geometry_nearest`** (`graphics/geometry/buffered/query/bvh32_geometry_nearest.js:188`): the denormalize block is **duplicated verbatim** → normalized (quantized-GLTF) vertex buffers are divided by 65535 **twice** → nearest-point/normal computed against a triangle collapsed to the origin.
-- **`ensureGeometryBoundingSphere`** (`:15`): returns the stale `null` on the first (compute) call — assigns the sphere to the geometry but not the local it returns → `s.radius` TypeError for any caller using the documented return value.
-
-### Graphics — water is broken three ways
-Water rendering is currently non-functional on the pinned three r136, via three independent defects — worth fixing as a unit:
-1. **`WaterShader.js`** (`:22,112,142`) references ShaderChunk symbols removed in r136 (`lights_pars`, `linear_to_gamma_fragment`) and the renamed `BRDF_Diffuse_Lambert` → **GLSL compile failure** → water surface throws / renders nothing.
-2. **`WaterSystem.shutdown`** (`:61`) dereferences a non-existent `graphicsEngine.size` → **TypeError on teardown**.
-3. **`Water`/`WaterSystem`** never dispose the per-terrain height `DataTexture`, plane geometry, or shader material → **GPU leak** on every water create/destroy.
-
-### Control / input
-- `phaseCrossed` misses exactly-on-boundary landings → dropped footstep/breath events; `PointerDevice.observeTap` leaks a shared move handler under multi-touch; `InputControllerSystem.remove` splices `-1` (deletes an unrelated pending binding); `TouchDevice` never attaches its handlers (pinch is dead).
-
-### ECS gui / actions / terrain / parent
-- `HeadsUpDisplaySystem` scales world-offset Z by `scale.y` (`:88`); `obtainTileAtWorldPosition2D` dereferences an out-of-bounds tile (crash in prod). *(A `DynamicActorSystem.match` re-entrancy item was withdrawn on verification — see §8.)*
-
-### Asset loaders
-- 1-bit and sub-8-bit palette PNGs decode to garbage (wrong byte index + bit order); `SVGAssetLoader` hangs on any non-200; the worker image decoder **detaches a cached ArrayBuffer** asset's buffer → second request gets an empty/garbage image.
-
-### Animation / navigation / intelligence
-- `AnimationTrackPlayback.advance` wraps with `%= timeEnd` (ignores `timeStart`) and re-fires `on.ended` **every frame** past the end; `estimatePathViaIterativeIntegral` never terminates (infinite loop); GLTF CUBICSPLINE tangents imported without `/Δt` denormalization; grid A* uses an **inadmissible** squared-distance heuristic → non-shortest paths; `OverrideContextBehavior` initializes its source twice (first with the wrong context); `ConditionalBehavior` abandons a running source without finalizing it (leak).
-
-### Root engine / UI / logging (supporting)
-- **`Ticker.pause()`** doesn't pause the clock → `resume()` emits the whole paused span as one `delta` → variable-rate systems jump seconds in a frame; `Ticker.start()` discards the initial rAF handle → double-start isn't caught and `stop()` can't cancel it → a self-perpetuating "stopped" loop.
-- **`SceneManager.clear()`** leaves the old scene's clock speed-modifiers applied (wrong sim speed next scene) + listener leak.
-- **ElasticSearchLogger**: even once armed, it POSTs a JSON array (not NDJSON) → ES rejects everything; `@timestamp = performance.now()` → all docs land in 1970.
-- `GraphicsEngine.stop()`/`GUIEngine.shutdown()`/`set_environment_texture` leak framebuffers/tickers/PMREM targets and viewport listeners.
-
-### Graphics GI (sh3)
-- **LPV GI vertex shader walks the tetrahedral mesh in object space, not world space** (`gi/material/space_vertex/build_vertex_shader.js:18`) → any mesh with a non-identity model matrix gets **wrong or missing indirect light** — and this is the *default* GI resolution stage.
-- Path-tracer material conversion never copies texture wrap mode → all baked/traced textures are force-clamped → tiled surfaces sample one stretched edge texel; tint is linearized twice (textured albedo ~7× too dark); emissive color/intensity dropped.
-
-### Network
-- **`ServerAuthoritativeServer`** applies remote actions with **no inbound authorization by default** (`authorize` stays `null` = permissive) — only the higher-level `NetworkSession` Host wires ownership enforcement, so a game built directly on this public primitive lets any peer drive another's entities. *(The four prior P0s — parse-crash, RESUME_HELLO, unbounded pending, missing auth mechanism — are otherwise fixed.)*
-- Receiver reassembly cap (64 KiB) is far below the sender's fragment capacity (~302 KiB) → large `INITIAL_SYNC`/`STATE_BURST` snapshots are **silently dropped** (client never gets initial state).
-
----
-
-## 5. What is clean / solid (do not re-open)
-
-- **Physics** — solver core (TGS split-impulse, friction cone, warm-start, soft-step, determinism), narrowphase (SAT/GJK/EPA, all primitive pairs), fluid MAC solver (staggered indexing, exact adjoint projection, MacCormack), and the physics↔ECS bridge (wake/sleep, ABA windows). Only 2 low-reach mediums.
-- **Sound** — the acoustic simulator (energy trace, RT60/Sabine, air absorption, reflection-IR + FOA directional reverb, corner-leak pathing, probe-visibility recheck), all probe-graph indexing, and all 24 binary adapters verified clean.
-- **Network** — seq/ack wrap math, quantization round-trip, slot tables, ledger repack, snapshot bounds-checking, time-sync — all correct; the parse boundary is hardened.
-- **Animation/interpolation math** — Hermite/Bézier eval, easing, keyframe binary search (before/after/exact/duplicate), interpolation-log ring/bloom, pose nlerp shortest-arc.
-- Most **serialization round-trips** are symmetric; the bugs are specific divergences (§2.2), not a broken framework.
-
----
-
-## 6. Remediation plan
-
-### Phase 0 — Immediate (hours): trivial, high-value, data-loss / crash on common paths
-These are one-line/few-line fixes; each has an unambiguous correct value. Land them first, each with a regression test.
-
-`C1` isConnected · `C3` grid Ceil · `C4` attachment queue · `C5` decal unsubscribe · `C7` input priority typo · `C8` particle sort · `C9` particle itemSize · `C10` atlas lookup · `C11` lanczos ratio · `C14` preloader hang · `C15` path-follower loop flag · `C19` ES logger timer · `C21` detach hook · `C22` sound-material type · plus `HUD scale.z`, `LightBinding scale signal`, `Ticker.pause clock`.
-
-### Phase 1 — Short (days): correctness with slightly wider blast radius
-- ECS lifecycle: `C20` any-listener clear on `dropData` (real id-recycling bug — **not** re-entrancy), and the `F5` curl-noise per-emitter time (§2.5).
-- The two **MikkTSpace** criticals (`C17`, `C18`) — normal-mapped meshes render wrong until fixed; add a multi-triangle tangent-continuity + weld test.
-- `C6` wall sensors, `C12` fog-of-war transpose, `C13` terrain seam — add **non-square / non-uniform** test fixtures (they hide behind square/identity inputs).
-- Teardown-leak sweep (pattern §2.4): `GraphicsEngine.stop`, `GUIEngine.shutdown`, `SceneManager.clear`, `ForwardPlusRenderingPlugin.shutdown`, `WaterSystem`, `DomElementProcessorManager`.
-
-### Phase 2 — Medium (days–weeks): higher-effort or design-touching
-- **LPV GI world-space fix** (verify against LPG chunk) — restores correct indirect lighting on transformed meshes.
-- Path-tracer wrap-mode / gamma / emissive fixes — improve every bake.
-- `AnimationTrackPlayback` loop/`ended` latching; asset PNG sub-8-bit decode; A* admissible heuristic.
-- Network: default `ServerAuthoritativeServer.authorize`, reconcile the fragment-reassembly cap, investigate the flagged client action-log overwrite caveat.
-
-### Cross-cutting (do alongside)
-1. **Serialization round-trip test harness** — for every component, assert `field-init == fromJSON(toJSON()) == fromBinary(toBinary())`. This catches the entire §2.2 class at once.
-2. **`copy()`/`clone()` field audit** (§2.1) — mechanical grep + review.
-3. **subscribe/unsubscribe pairing lint** (§2.3) — every `startup/link` subscription needs a matching removal on the same signal.
-4. Prefer numeric comparators everywhere (`(a,b)=>a-b`); grep for bare `.sort()`.
-
----
-
-## 7. Coverage & confidence
-
-- **Reviewed:** all non-spec/non-prototype source across every subsystem. The five highest-impact CRITICALs were re-read and confirmed against source; agent reliability sampled at 5/5.
-- **Verification pass:** the "re-entrancy" finding class was singled out for a dedicated adversarial re-check against the actual call graph (§8) — one instance was confirmed-but-not-reachable (demoted), three had no triggering caller (dropped), one was a mislabelled real bug (reclassified). This is the honest calibration: *concrete* findings (a wrong value on a direct code path) held up; *mechanism-only* findings that assumed a triggering caller did not.
-- **Confidence markers:** each finding in the source reports carries Confirmed / Likely / Possible. "Latent" (public library surface with no in-repo caller) items are still real bugs — meep is a library — and are called out where relevant.
-- **Excluded by design:** `prototype*.js` (internal tools), `*.spec.js`, hand-written `.d.ts`.
-- **Gap-fill passes (complete, folded in):** shaders/shadows/geometry-buffered/bvh (3 HIGH — WaterShader r136 compile failure, `bvh32_geometry_nearest` double-denormalize, `ensureGeometryBoundingSphere` null-return; + a point-light VSM-shadow medium); render gizmo/view/AO (4 MEDIUM — AO `ShaderMaterial` leak on shutdown, stale `projectionMatrixInverse` after projection-modifier, `DepthLimitedBlur` dropped `format`, `NormalFrameBuffer` shared-material wrong-normals); sh3/lightmap (clean apart from 1 MEDIUM — T-junction shading-normal carry). **No new CRITICALs surfaced in any gap-fill.** The lightmap baker and the AO shader math were verified clean.
-
----
-
-## 8. Corrections — the "re-entrancy" re-examination
-
-The first synthesis of this review flagged ~5 findings under a "shared-scratch re-entrancy" banner. That framing was challenged and re-verified against the actual call graph. **Note on terminology:** JavaScript has no threaded/preemptive concurrency, but *synchronous* re-entrancy (a callback calling back into the same function on one call stack) is real — so the deciding question was never "can JS re-enter" but "does a concrete caller in this codebase actually re-enter these functions." Adversarial verification (instructed to *refute* each and to hunt for a real triggering caller):
-
-| Finding | Was | Now | Verified reason |
-|---|---|---|---|
-| `traverseEntities` module-static scratch (`EntityComponentDataset.js:1331/1373`) | CRITICAL | **LOW (latent)** | Mechanism real (statics read after `visitor.apply`), but an exhaustive lexical + transitive search found **no** visitor that nests a `traverseEntities` call. `getComponent`/`hasComponent` are O(1) non-traversing; the only real nested traversal (`FluidObstacleSystem.js:140/174`) nests `traverseComponents`, which uses locals. Cheap optional hardening: use per-call locals like `traverseEntitiesExact` (`:1407/:1418`). |
-| Event-dispatch proxy stack (`EntityComponentDataset.js:2139/2186`) | HIGH | **LOW** | The dispatcher is **deliberately recursion-safe** (comment at `:2126`): each nested dispatch reserves a disjoint region via a saved/restored pointer, so a handler that synchronously fires another event does **not** corrupt the outer dispatch. The only real residue: no `try/finally`, so a *throwing* handler skips the pointer restore (`:2176`) → a slow monotonic growth (leak) of `entityListenersProxy`, not corruption. Fix: wrap the handler loop in `try/finally`. |
-| `removeEntity` reentrant component-add (`:980`) | HIGH | **dropped** | No production `ComponentRemoved` listeners exist, and no `System.unlink` adds a component to its own dying entity. No triggering caller — can't-happen. |
-| `DynamicActorSystem.match` shared `DataScope` (`DynamicActorSystem.js:523`) | HIGH | **dropped** | `match()`'s only caller is the dataset event listener; all actions defer side-effects to `BehaviorSystem.update` (a separate call stack), and the synchronous build emits events only on transient non-`DynamicActor` entities. No synchronous re-entry path. (`requestBestActors`'s per-call scope exists for a different reason — it traverses all actors during a tick.) |
-| Curl-noise `this.time` accumulation (`SimulationStepCurlNoiseVelocity.js:22`) | HIGH (mislabelled re-entrancy) | **MEDIUM (reclassified)** | A **real** bug but it is **shared-sequential-state**, not re-entrancy: one shared step instance is reused across a sequential per-emitter loop, so `this.time` advances ∝ emitter count. Kept in §2.5 / §4 with the correct label. |
-
-**Net:** 1 critical demoted (latent), 3 highs dropped as can't-happen, 1 high reclassified to a real medium. This aligns with the project's convention against flagging conditions that cannot occur. The lesson applied going forward: a mechanism-only finding is not reported unless a concrete triggering caller is demonstrated.
-
----
-*Detailed per-finding failure scenarios and fixes are preserved in the review working notes; each table/section entry cites `file:line` for direct navigation.*
+# Engine Package — Correctness Review (2026-07-03)
+
+**Scope:** `app/src/mir-engine/meep/src/engine` — the full engine package (~222,000 LOC of reviewable source across 1,782 non-spec, non-prototype `.js` files, 27 top-level subsystems).
+
+**Method:** Fanned-out review — ~26 specialist agents, each assigned a coherent subsystem with a strict *correctness-only* brief (no style, no nitpicks; `prototype*.js` out of scope; unreferenced exports treated as public library surface, not dead code; `assert.*` treated as stripped in production). Every finding requires a concrete failure scenario. The five highest-impact CRITICALs were re-verified by reading the actual source. This document is the synthesis.
+
+---
+
+## 1. Executive summary
+
+The engine is **large, mature, and — in its heavily-exercised numerical cores — genuinely solid.** The recently-hardened subsystems held up under fresh scrutiny: **physics** (solver, narrowphase, fluid — 26k LOC) came back essentially clean (2 low-reach mediums in a 2D demo file and a near-parallel-capsule edge case); the **acoustic simulation core** (Steam-Audio-style sim + Sopra middleware) was verified line-by-line and is clean; the **network core** has had its four previously-known P0 security bugs **fixed** (malformed-packet crashes contained, pending-log bounded, RESUME_HELLO safe, inbound authorization now exists).
+
+The defects concentrate in the **glue and lifecycle code** rather than the algorithms: ECS entity/observer lifecycle, ECS↔render/audio bindings, component copy/clone and JSON-vs-binary serialization, GPU/listener cleanup on teardown, and a long tail of one-character typos that survive because they sit on paths without a regression test. Many are trivial to fix; several corrupt data or crash on common paths.
+
+### Headline counts
+
+| Severity | Count | Character |
+|---|---:|---|
+| **CRITICAL** | ~21 | Crash, data corruption, or wrong result on a common/default path (or a security hole). Mostly small, high-value fixes. |
+| **HIGH** | ~61 | Wrong result or crash on a real path (often a specific-but-normal configuration). |
+| **MEDIUM** | ~97 | Wrong result on an edge case, or a resource leak. |
+
+> A large fraction of the CRITICAL/HIGH items are **one-line or few-line fixes** (a typo, a wrong axis, a `subscribe` that should be `unsubscribe`, a `floor` that should be `ceil`). The volume reflects *breadth of surface*, not systemic rot — the numerical cores are trustworthy; the seams between systems are where correctness leaks.
+
+> **Correction (post-review verification):** an initial group of ~5 "re-entrancy" findings was adversarially re-verified against the actual call graph and largely withdrawn — see **§8**. JavaScript has no threaded concurrency, and *synchronous* re-entrancy (a callback calling back into the same function) turned out to have **no concrete triggering caller** for the ECS cases. The counts above already reflect the corrections (1 critical demoted, 3 highs dropped, 1 high reclassified to medium). The concrete, source-verified criticals below are unaffected.
+
+### Health by subsystem
+
+| Subsystem | Verdict |
+|---|---|
+| physics (solver / narrowphase / fluid) | **Solid.** Cores clean; only a 2D-demo bounds bug + one capsule edge case. |
+| sound (acoustic sim + Sopra) | **Solid.** Sim/render/serialization clean; a few edge-case runtime mediums. |
+| network (core + transport) | **Good.** Prior P0s fixed; 1 residual auth-default HIGH, a few mediums. |
+| interpolation, animation curve math | **Solid.** Easing/Hermite/binary-search correct; bugs are in serialization & playback wrapping. |
+| **ecs (core)** | **Concern.** 1 critical (observer-lifecycle leak) + several high-severity lifecycle/serialization bugs. (A re-entrant-scratch "critical" was withdrawn on verification — see §8.) |
+| **graphics (ecs bindings, texture, particles)** | **Concern.** Multiple criticals (atlas lookup, particle buffer, decal/light bindings). |
+| **gameplay glue (control/input, attachment, grid, terrain/fow)** | **Concern.** Criticals in wall sensors, input sort, attachment queue, fog-of-war, terrain seams, grid rounding. |
+| MikkTSpace tangent/weld | **Concern.** 2 criticals defeat tangent smoothing & vertex welding for real meshes. |
+| asset loaders | **Concern.** Preloader hang + several decode/round-trip bugs. |
+
+---
+
+## 2. Recurring patterns (fix the class, not just the instance)
+
+The same mistakes recur across unrelated subsystems. Each is worth a targeted sweep:
+
+1. **`copy()` / `clone()` drops fields.** `Camera.copy` (fov, clip planes), `GridPosition2Transform.copy` (flags), `Transform.copy` (propagates a cleared auto-update flag). Cloned entities silently revert to defaults. → *Audit every `copy()`/`clone()` against its field list; add round-trip tests.*
+2. **JSON vs binary (de)serialization diverge.** AnimationGraph state `name`/`tags` dropped; `startingSate` typo; POINT-light `distance` binary-only; `SerializationMetadata` flags truncated to 8 bits; `Team` sentinel aliasing; `ViewportPosition.resolveGuiCollisions` dropped; `AnimationClip.repeatCount` defaults to ∞ in JSON but 1 in the field; sound-material `type` always `undefined`. → *Every component needs a JSON↔binary↔field round-trip test.*
+3. **subscribe/unsubscribe asymmetry & wrong-signal binding.** Decal `unlink` re-subscribes instead of unsubscribing; `LightBinding` binds the scale handler to `rotation.onChanged`; `TransformAttachmentBinding` never watches its local transform; `ForwardPlusRenderingPlugin.shutdown` removes from the wrong signal; `WaterSystem.shutdown` dereferences a non-existent field. → *Every `link/startup` subscription must have a matching `unlink/shutdown` removal on the same signal.*
+4. **GPU / listener leaks on teardown.** `GraphicsEngine.stop`, `GUIEngine.shutdown`, `SceneManager.clear`, `DomElementProcessorManager.unlink`, `Water`/`CameraSystem.rebuild`, `set_environment_texture`, virtual-atlas eviction. → *Teardown paths need the same rigor as setup.*
+5. **Shared instance state reused across a sequential loop.** `SimulationStepCurlNoiseVelocity` reuses one step instance for every emitter and accumulates `this.time` per call → curl-noise animates ∝ emitter count. → *Derive phase from a per-emitter/global clock, not an accumulator on the shared step.* *(This is the one surviving instance of what was originally framed as a broader "shared-scratch re-entrancy" pattern; the ECS re-entrancy findings were withdrawn on verification — see §8.)*
+6. **Axis / plane-index confusion.** FogOfWar width/height swap; HUD `z *= scale.y`; frustum near/far indexed as `[0]`/`[5]` inconsistently; sensor right-vector sign; ortho `bottom - top`. → *Centralize frustum-plane index constants; unit-test coordinate transforms with non-square / non-uniform inputs.*
+7. **Array mutation during iteration / bad sort comparators.** `SGMeshSystem` splices while modulo-indexing; `ParticleGroup.deleteIndices` uses a lexicographic sort; `optimizeCommandQueue` and `InputControllerSystem` comparators are non-antisymmetric/typo'd; `InputControllerSystem.remove` splices index `-1`. → *Snapshot before mutating; always pass a numeric comparator.*
+8. **Log-and-fall-through (missing `return` after an error).** `SoundControllerSystem`, `SoundEmitterSystem`, `ParticleVolume.fromJSON`, terrain `obtainTileAtWorldPosition2D` log or warn, then dereference the thing they just reported missing.
+9. **Default-value divergence between field init and `fromJSON`.** `repeatCount` (1 vs ∞), `screenEdgeWidth` (10 vs 0).
+
+---
+
+## 3. Critical findings
+
+Ranked by blast radius on common/default paths. **✔ = re-verified against source by the lead reviewer.**
+
+| # | Subsystem | Location | Defect | One-line fix |
+|---|---|---|---|---|
+| C1 ✔ | ecs core | `ecs/EntityObserver.js:130` | `isConnected` returns `dataset === null` — **inverted**; `EntityManager.detachDataset` then skips `removeObserver` for every live observer → `System.unlink` never runs on detach → resources leak, re-attach double-links. | `return this.dataset !== null;` |
+| C3 ✔ | grid | `grid/transform2grid/Transform2GridPositionSystem.js:56` | `Ceil` mode calls `v2.floor()` (copy-paste) → Ceil-mode entities placed in the **wrong grid cell**; pathing/occupancy read the wrong tile. | `v2.ceil();` |
+| C4 ✔ | ecs attachment | `ecs/attachment/AttachmentSystem.js:80` | `clearAllWaitRecordsFor` shadows the param then tests `if (entity === entity)` (always true) → **wipes the entire attachment wait-queue** on any unlink. | Compare `waiting[i]` against the parameter. |
+| C5 ✔ | graphics/ecs | `graphics/ecs/decal/v2/FPDecalSystem.js:216` | `unlink()` calls `transform.subscribe(...)` (should be `unsubscribe`) after nulling `__fp_decal` → next transform change calls `.setTransform` on `null` → **crash** + listener leak. | `transform.unsubscribe(...)` |
+| C6 | control | `control/first-person/sensors/FirstPersonSensorsSystem.js:131` | Body-right vector is the **negation** of the controller's own convention → `wallLeft`/`wallRight` swapped → wall-run tilts the camera the wrong way, all wall logic mirrored. | `rx = -cos(yaw); rz = sin(yaw);` |
+| C7 | input | `input/ecs/systems/InputControllerSystem.js:100` | Priority comparator reads `b.priotity` (typo; field doesn't exist) → `NaN` comparator → **non-deterministic input dispatch order**; exclusive bindings cut the wrong handler. | `b.priority - a.priority` + define the field. |
+| C8 | particles | `particular/group/ParticleGroup.js:466` | `indices.sort()` (lexicographic) feeds a compaction that assumes ascending numeric order → with any index ≥ 10, **corrupts the particle buffer & reference maps**. | `indices.sort((a,b)=>a-b)` |
+| C9 | particles | `particular/engine/emitter/ParticlePool.js:507` | `updateRange.count = n` (particles) not `n*itemSize` (elements) → only the first `1/itemSize` of particles get multi-component attribute updates uploaded (e.g. ¾ of colors stale). | `attribute.updateRange.count = n * itemSize;` |
+| C10 | graphics texture | `graphics/texture/atlas/AtlasLookupTexture.js:80` | Writes patch **height into the width channel** (`size.y` twice, `size.x` never) → non-square atlas patches sample a wrong-width sub-rect → garbled sprites. | `data[address + 2] = size.x;` |
+| C11 | graphics texture | `graphics/texture/sampler/resize/sampler2d_scale_down_lanczos.js:93` | `rcp_ratio_y = 2 / ratio_x` → non-uniform Lanczos downscale uses the wrong support in Y (ships broken; its spec is `describe.skip`). | `2 / ratio_y` |
+| C12 | ecs fow | `ecs/fow/FogOfWar.js:562` | `rebuildSampler` swaps width/height → **transposed fog grid** for any non-square map; all reveal/conceal indexing uses the wrong stride and resize corrupts. | `samplerWidth = size.x+2; samplerHeight = size.y+2;` |
+| C13 | ecs terrain | `ecs/terrain/tiles/TerrainTileManager.js:562` | Seam-stitch uses `floor(size/tileSize)` but tiles are created with `ceil` → partial edge tiles **never seam-stitched** → lighting crease on every non-multiple terrain boundary. | Use `ceil` in `stitchTile`. |
+| C14 | asset | `preloader/AssetPreloader.js:291` | `assetLoadFailed` lacks the level-completion check `assetLoadSuccess` has → if a **failure is the last completion** in a level, `levelFinished` never fires → **the whole preload hangs**. | Dispatch `levelFinished` on `loaded+failed >= batch_size`. |
+| C15 | navigation | `navigation/ecs/path_following/PathFollower.js:160` | `fromJSON` gates on `json.loop` but writes `json.active` into the Loop flag → a one-shot mover deserializes as looping → teleports to start forever, never fires `EndReached`. | `writeFlag(Loop, json.loop)` |
+| C16 | animation | `animation/curve/actionProcessorOperations/curveActions.js:118` | `MoveKeyframeAction` aliases live curve keyframes to its undo snapshots then mutates them in place → **undo/redo corrupts the curve**. | Copy values into existing keyframes; don't reassign references. |
+| C17 | geometry | `graphics/geometry/MikkT/BuildNeighborsFast.js:116` | Edge-neighbor pairing reads the wrong array slots (compares a vertex index against an edge number) → neighbors never found for real meshes → **per-face (faceted) tangents** → normal-map seams everywhere. | Read `temp_edge_B[0],[1],[2]`; drop the bogus flip. |
+| C18 | geometry | `graphics/geometry/MikkT/GenerateSharedVerticesIndexList.js:79` | Radix-sort insertion has an operator-precedence bug (`&0xff` masks the whole sum) → multi-byte vertex hashes mis-sorted → **vertex welding fails** (duplicates survive). | `pass*257 + ((key>>shift)&0xff)` |
+| C19 | logging | `logging/elastic/ElasticSearchLogger.js:82` | Constructor sets `__timeout_ms` but the scheduler reads `__timeout` (undefined) → the timed flush is **never armed** → any session logging < 500 records loses **all** buffered logs on unload. | Unify the field name. |
+| C20 | ecs core | `ecs/EntityComponentDataset.js:1886` | `dropData` clears `__entityEventListeners` but not `__entityAnyEventListeners`; entity ids recycle → a new entity inherits the **previous scene's** any-listeners with a dangling context → crash/corruption on fast scene swap. | Also clear `__entityAnyEventListeners`. |
+| C21 ✔ | ecs core | `ecs/EntityManager.js:357` | `detachDataset` calls `system.handleDatasetAttached(dataset)` while tearing the dataset down (should be `handleDatasetDetached`) → dataset-switching systems re-run attach logic on detach. | `handleDatasetDetached(dataset)` |
+| C22 | sound | `sound/material/concrete/json/serializeSoundMaterialToJSON.js:3` | Reads `typeName` off the prototype but it's a **static** on the constructor → always `undefined` → every composite sound-material serializes `type: undefined` → deserialize throws. | `material.constructor.typeName` |
+
+> **`C2` is intentionally absent** — the original C2 (`traverseEntities` scratch re-entrancy) was demoted to a LOW latent-hazard on verification and moved to §8. Numbering C3–C22 is preserved for traceability with the working notes.
+
+---
+
+## 4. High-severity findings by subsystem
+
+### ECS core & lifecycle
+- **`Entity.promiseEvent`** (`:327`): calls `removeEventListener(EntityRemoved, reject)` instead of `add` → the promise never rejects on entity removal → **awaiter hangs forever**.
+- Binary entity-id delta encoding (`BinaryBufferSerializer.js:174`) relies on ascending traversal order guarded only by a stripped assert → silent corruption if order ever breaks.
+- *(Two "re-entrant event dispatch / removeEntity" items previously listed here were withdrawn on verification — the dispatch path is deliberately recursion-safe, and no caller triggers the removeEntity hazard. See §8.)*
+
+### Graphics — ECS bindings
+- **`LightBinding`** (`graphics/ecs/light/binding/LightBinding.js:51`): scale handler bound to `rotation.onChanged` → spot-light range goes stale on scale.
+- **`WaterSystem.shutdown`** (`:61`): dereferences non-existent `graphicsEngine.size` → TypeError on teardown; real `preRender` hook leaked.
+- **`auto_set_camera_clipping_planes`** (`:44,100`): reads `old_near/far` *after* overwriting them with the outer bounds → autoClip hysteresis never tightens → persistent z-fighting.
+- **`set_camera_aspect_ratio`** (`:26`): ortho `h = bottom - top` (negative) → mirrored/inverted frustum on resize.
+- **`ForwardPlusRenderingPlugin.shutdown`** (`:80`): unsubscribes from the wrong signal → `__prepare_for_render` keeps firing on **disposed** GPU textures.
+- **`sg_hierarchy_compute_bounding_box_via_parent_entity`** (`:19`) & **`SGMeshSystem.update`** (`:281`): the former ignores its `entity` arg (empty AABB → wrong LPV probes); the latter splices its wait-queue while modulo-indexing → skips entities & dereferences `undefined`.
+
+### Graphics — texture / particles / geometry
+- Managed atlases serve **stale, atlas-evicted patches** from a TTL-∞ loader cache (`ManagedTextureAtlas.js`); `CachingTextureAtlas.__evict_all` leaves index 0 behind (`:152`).
+- `sampler2d_scale_down_linear` (`:53`) mis-indexes on non-integer ratios; `sampler2d_copy_with_margins` (`:124`) uses `width` for a vertical bound → non-square seams.
+- *(MEDIUM)* Curl-noise simulation time advances **once per emitter** on a shared step instance → noise animates ∝ emitter count (`SimulationStepCurlNoiseVelocity.js:22`). *Shared-sequential-state (a per-emitter loop reusing one instance), not re-entrancy.*
+- `ParticleEmitter` hash/equals disagree on flags; `ShaderManager` leaks a disposed emitter after a graveyard round-trip.
+- `equal_attribute_structure` returns truthy `-1` on name mismatch → **merges incompatible geometries** (`merge_geometry_hierarchy.js:92`); `InstancedMeshGroup.build` retains stale per-instance colors on shrink+regrow.
+- **`bvh32_geometry_nearest`** (`graphics/geometry/buffered/query/bvh32_geometry_nearest.js:188`): the denormalize block is **duplicated verbatim** → normalized (quantized-GLTF) vertex buffers are divided by 65535 **twice** → nearest-point/normal computed against a triangle collapsed to the origin.
+- **`ensureGeometryBoundingSphere`** (`:15`): returns the stale `null` on the first (compute) call — assigns the sphere to the geometry but not the local it returns → `s.radius` TypeError for any caller using the documented return value.
+
+### Graphics — water is broken three ways
+Water rendering is currently non-functional on the pinned three r136, via three independent defects — worth fixing as a unit:
+1. **`WaterShader.js`** (`:22,112,142`) references ShaderChunk symbols removed in r136 (`lights_pars`, `linear_to_gamma_fragment`) and the renamed `BRDF_Diffuse_Lambert` → **GLSL compile failure** → water surface throws / renders nothing.
+2. **`WaterSystem.shutdown`** (`:61`) dereferences a non-existent `graphicsEngine.size` → **TypeError on teardown**.
+3. **`Water`/`WaterSystem`** never dispose the per-terrain height `DataTexture`, plane geometry, or shader material → **GPU leak** on every water create/destroy.
+
+### Control / input
+- `phaseCrossed` misses exactly-on-boundary landings → dropped footstep/breath events; `PointerDevice.observeTap` leaks a shared move handler under multi-touch; `InputControllerSystem.remove` splices `-1` (deletes an unrelated pending binding); `TouchDevice` never attaches its handlers (pinch is dead).
+
+### ECS gui / actions / terrain / parent
+- `HeadsUpDisplaySystem` scales world-offset Z by `scale.y` (`:88`); `obtainTileAtWorldPosition2D` dereferences an out-of-bounds tile (crash in prod). *(A `DynamicActorSystem.match` re-entrancy item was withdrawn on verification — see §8.)*
+
+### Asset loaders
+- 1-bit and sub-8-bit palette PNGs decode to garbage (wrong byte index + bit order); `SVGAssetLoader` hangs on any non-200; the worker image decoder **detaches a cached ArrayBuffer** asset's buffer → second request gets an empty/garbage image.
+
+### Animation / navigation / intelligence
+- `AnimationTrackPlayback.advance` wraps with `%= timeEnd` (ignores `timeStart`) and re-fires `on.ended` **every frame** past the end; `estimatePathViaIterativeIntegral` never terminates (infinite loop); GLTF CUBICSPLINE tangents imported without `/Δt` denormalization; grid A* uses an **inadmissible** squared-distance heuristic → non-shortest paths; `OverrideContextBehavior` initializes its source twice (first with the wrong context); `ConditionalBehavior` abandons a running source without finalizing it (leak).
+
+### Root engine / UI / logging (supporting)
+- **`Ticker.pause()`** doesn't pause the clock → `resume()` emits the whole paused span as one `delta` → variable-rate systems jump seconds in a frame; `Ticker.start()` discards the initial rAF handle → double-start isn't caught and `stop()` can't cancel it → a self-perpetuating "stopped" loop.
+- **`SceneManager.clear()`** leaves the old scene's clock speed-modifiers applied (wrong sim speed next scene) + listener leak.
+- **ElasticSearchLogger**: even once armed, it POSTs a JSON array (not NDJSON) → ES rejects everything; `@timestamp = performance.now()` → all docs land in 1970.
+- `GraphicsEngine.stop()`/`GUIEngine.shutdown()`/`set_environment_texture` leak framebuffers/tickers/PMREM targets and viewport listeners.
+
+### Graphics GI (sh3)
+- **LPV GI vertex shader walks the tetrahedral mesh in object space, not world space** (`gi/material/space_vertex/build_vertex_shader.js:18`) → any mesh with a non-identity model matrix gets **wrong or missing indirect light** — and this is the *default* GI resolution stage.
+- Path-tracer material conversion never copies texture wrap mode → all baked/traced textures are force-clamped → tiled surfaces sample one stretched edge texel; tint is linearized twice (textured albedo ~7× too dark); emissive color/intensity dropped.
+
+### Network
+- **`ServerAuthoritativeServer`** applies remote actions with **no inbound authorization by default** (`authorize` stays `null` = permissive) — only the higher-level `NetworkSession` Host wires ownership enforcement, so a game built directly on this public primitive lets any peer drive another's entities. *(The four prior P0s — parse-crash, RESUME_HELLO, unbounded pending, missing auth mechanism — are otherwise fixed.)*
+- Receiver reassembly cap (64 KiB) is far below the sender's fragment capacity (~302 KiB) → large `INITIAL_SYNC`/`STATE_BURST` snapshots are **silently dropped** (client never gets initial state).
+
+---
+
+## 5. What is clean / solid (do not re-open)
+
+- **Physics** — solver core (TGS split-impulse, friction cone, warm-start, soft-step, determinism), narrowphase (SAT/GJK/EPA, all primitive pairs), fluid MAC solver (staggered indexing, exact adjoint projection, MacCormack), and the physics↔ECS bridge (wake/sleep, ABA windows). Only 2 low-reach mediums.
+- **Sound** — the acoustic simulator (energy trace, RT60/Sabine, air absorption, reflection-IR + FOA directional reverb, corner-leak pathing, probe-visibility recheck), all probe-graph indexing, and all 24 binary adapters verified clean.
+- **Network** — seq/ack wrap math, quantization round-trip, slot tables, ledger repack, snapshot bounds-checking, time-sync — all correct; the parse boundary is hardened.
+- **Animation/interpolation math** — Hermite/Bézier eval, easing, keyframe binary search (before/after/exact/duplicate), interpolation-log ring/bloom, pose nlerp shortest-arc.
+- Most **serialization round-trips** are symmetric; the bugs are specific divergences (§2.2), not a broken framework.
+
+---
+
+## 6. Remediation plan
+
+### Phase 0 — Immediate (hours): trivial, high-value, data-loss / crash on common paths
+These are one-line/few-line fixes; each has an unambiguous correct value. Land them first, each with a regression test.
+
+`C1` isConnected · `C3` grid Ceil · `C4` attachment queue · `C5` decal unsubscribe · `C7` input priority typo · `C8` particle sort · `C9` particle itemSize · `C10` atlas lookup · `C11` lanczos ratio · `C14` preloader hang · `C15` path-follower loop flag · `C19` ES logger timer · `C21` detach hook · `C22` sound-material type · plus `HUD scale.z`, `LightBinding scale signal`, `Ticker.pause clock`.
+
+### Phase 1 — Short (days): correctness with slightly wider blast radius
+- ECS lifecycle: `C20` any-listener clear on `dropData` (real id-recycling bug — **not** re-entrancy), and the `F5` curl-noise per-emitter time (§2.5).
+- The two **MikkTSpace** criticals (`C17`, `C18`) — normal-mapped meshes render wrong until fixed; add a multi-triangle tangent-continuity + weld test.
+- `C6` wall sensors, `C12` fog-of-war transpose, `C13` terrain seam — add **non-square / non-uniform** test fixtures (they hide behind square/identity inputs).
+- Teardown-leak sweep (pattern §2.4): `GraphicsEngine.stop`, `GUIEngine.shutdown`, `SceneManager.clear`, `ForwardPlusRenderingPlugin.shutdown`, `WaterSystem`, `DomElementProcessorManager`.
+
+### Phase 2 — Medium (days–weeks): higher-effort or design-touching
+- **LPV GI world-space fix** (verify against LPG chunk) — restores correct indirect lighting on transformed meshes.
+- Path-tracer wrap-mode / gamma / emissive fixes — improve every bake.
+- `AnimationTrackPlayback` loop/`ended` latching; asset PNG sub-8-bit decode; A* admissible heuristic.
+- Network: default `ServerAuthoritativeServer.authorize`, reconcile the fragment-reassembly cap, investigate the flagged client action-log overwrite caveat.
+
+### Cross-cutting (do alongside)
+1. **Serialization round-trip test harness** — for every component, assert `field-init == fromJSON(toJSON()) == fromBinary(toBinary())`. This catches the entire §2.2 class at once.
+2. **`copy()`/`clone()` field audit** (§2.1) — mechanical grep + review.
+3. **subscribe/unsubscribe pairing lint** (§2.3) — every `startup/link` subscription needs a matching removal on the same signal.
+4. Prefer numeric comparators everywhere (`(a,b)=>a-b`); grep for bare `.sort()`.
+
+---
+
+## 7. Coverage & confidence
+
+- **Reviewed:** all non-spec/non-prototype source across every subsystem. The five highest-impact CRITICALs were re-read and confirmed against source; agent reliability sampled at 5/5.
+- **Verification pass:** the "re-entrancy" finding class was singled out for a dedicated adversarial re-check against the actual call graph (§8) — one instance was confirmed-but-not-reachable (demoted), three had no triggering caller (dropped), one was a mislabelled real bug (reclassified). This is the honest calibration: *concrete* findings (a wrong value on a direct code path) held up; *mechanism-only* findings that assumed a triggering caller did not.
+- **Confidence markers:** each finding in the source reports carries Confirmed / Likely / Possible. "Latent" (public library surface with no in-repo caller) items are still real bugs — meep is a library — and are called out where relevant.
+- **Excluded by design:** `prototype*.js` (internal tools), `*.spec.js`, hand-written `.d.ts`.
+- **Gap-fill passes (complete, folded in):** shaders/shadows/geometry-buffered/bvh (3 HIGH — WaterShader r136 compile failure, `bvh32_geometry_nearest` double-denormalize, `ensureGeometryBoundingSphere` null-return; + a point-light VSM-shadow medium); render gizmo/view/AO (4 MEDIUM — AO `ShaderMaterial` leak on shutdown, stale `projectionMatrixInverse` after projection-modifier, `DepthLimitedBlur` dropped `format`, `NormalFrameBuffer` shared-material wrong-normals); sh3/lightmap (clean apart from 1 MEDIUM — T-junction shading-normal carry). **No new CRITICALs surfaced in any gap-fill.** The lightmap baker and the AO shader math were verified clean.
+
+---
+
+## 8. Corrections — the "re-entrancy" re-examination
+
+The first synthesis of this review flagged ~5 findings under a "shared-scratch re-entrancy" banner. That framing was challenged and re-verified against the actual call graph. **Note on terminology:** JavaScript has no threaded/preemptive concurrency, but *synchronous* re-entrancy (a callback calling back into the same function on one call stack) is real — so the deciding question was never "can JS re-enter" but "does a concrete caller in this codebase actually re-enter these functions." Adversarial verification (instructed to *refute* each and to hunt for a real triggering caller):
+
+| Finding | Was | Now | Verified reason |
+|---|---|---|---|
+| `traverseEntities` module-static scratch (`EntityComponentDataset.js:1331/1373`) | CRITICAL | **LOW (latent)** | Mechanism real (statics read after `visitor.apply`), but an exhaustive lexical + transitive search found **no** visitor that nests a `traverseEntities` call. `getComponent`/`hasComponent` are O(1) non-traversing; the only real nested traversal (`FluidObstacleSystem.js:140/174`) nests `traverseComponents`, which uses locals. Cheap optional hardening: use per-call locals like `traverseEntitiesExact` (`:1407/:1418`). |
+| Event-dispatch proxy stack (`EntityComponentDataset.js:2139/2186`) | HIGH | **LOW** | The dispatcher is **deliberately recursion-safe** (comment at `:2126`): each nested dispatch reserves a disjoint region via a saved/restored pointer, so a handler that synchronously fires another event does **not** corrupt the outer dispatch. The only real residue: no `try/finally`, so a *throwing* handler skips the pointer restore (`:2176`) → a slow monotonic growth (leak) of `entityListenersProxy`, not corruption. Fix: wrap the handler loop in `try/finally`. |
+| `removeEntity` reentrant component-add (`:980`) | HIGH | **dropped** | No production `ComponentRemoved` listeners exist, and no `System.unlink` adds a component to its own dying entity. No triggering caller — can't-happen. |
+| `DynamicActorSystem.match` shared `DataScope` (`DynamicActorSystem.js:523`) | HIGH | **dropped** | `match()`'s only caller is the dataset event listener; all actions defer side-effects to `BehaviorSystem.update` (a separate call stack), and the synchronous build emits events only on transient non-`DynamicActor` entities. No synchronous re-entry path. (`requestBestActors`'s per-call scope exists for a different reason — it traverses all actors during a tick.) |
+| Curl-noise `this.time` accumulation (`SimulationStepCurlNoiseVelocity.js:22`) | HIGH (mislabelled re-entrancy) | **MEDIUM (reclassified)** | A **real** bug but it is **shared-sequential-state**, not re-entrancy: one shared step instance is reused across a sequential per-emitter loop, so `this.time` advances ∝ emitter count. Kept in §2.5 / §4 with the correct label. |
+
+**Net:** 1 critical demoted (latent), 3 highs dropped as can't-happen, 1 high reclassified to a real medium. This aligns with the project's convention against flagging conditions that cannot occur. The lesson applied going forward: a mechanism-only finding is not reported unless a concrete triggering caller is demonstrated.
+
+---
+*Detailed per-finding failure scenarios and fixes are preserved in the review working notes; each table/section entry cites `file:line` for direct navigation.*