@woosh/meep-engine 2.168.0 → 2.169.0

package/src/REVIEW_2026_08_06/prior-criticals.md

@@ -0,0 +1,49 @@
+# REVIEW_2026_07_03 §3 "Critical findings" — re-verification against current source
+
+Source root: `H:/git/moh/app/src/mir-engine/meep/src/`
+Verified: 2026-08-06. Line numbers below are **current**, not the ones in the review.
+
+C1/C3/C4/C10/C22 (FIXED) and C5 (OPEN) carried forward from the lead reviewer; C5 re-confirmed with a current line.
+C2 does not exist (intentionally absent from the review).
+
+| ID | Status | Current file:line | Evidence | Spec exists? |
+|---|---|---|---|---|
+| C1 | **FIXED** | `engine/ecs/EntityObserver.js` | carried forward from lead reviewer | — |
+| C3 | **FIXED** | `engine/grid/transform2grid/Transform2GridPositionSystem.js` | carried forward from lead reviewer | — |
+| C4 | **FIXED** | `engine/ecs/attachment/AttachmentSystem.js` | carried forward from lead reviewer | — |
+| C5 | **OPEN** | `engine/graphics/ecs/decal/v2/FPDecalSystem.js:216` | in `unlink()`, after `this.__fp_decal = null;`: `transform.subscribe(this.__update_transform, this);` — identical call to the one in `link()` at :162; no `unsubscribe` anywhere in the file | **No** — `graphics/ecs/decal/v2/Decal.spec.js` exists but does not exercise unlink/transform-change |
+| C6 | **FIXED** | `engine/control/first-person/sensors/FirstPersonSensorsSystem.js:135-136` | `const rx = -Math.cos(yaw);` / `const rz = Math.sin(yaw);` — matches the prescribed fix; comment at :132 now documents the controller convention | **Yes** — `FirstPersonSensorsSystem.spec.js:117` `"side wall on the player's right (world -X at yaw 0) fires wallRight (C6)"`; also referenced from `control/first-person/WallRunScenarios.spec.js:32` |
+| C7 | **FIXED** | `engine/input/ecs/systems/InputControllerSystem.js:106` | `return b.priority - a.priority;` (typo `priotity` gone). Field is now real: `input/ecs/components/InputBinding.js:11` `constructor({ path, listener, exclusive = false, priority = 0 })` and `:36` `this.priority = priority;` | **Yes** — `InputControllerSystem.spec.js:5` `"bindings on the same path dispatch in descending priority order (C7)"` |
+| C8 | **FIXED** | `engine/graphics/particles/particular/group/ParticleGroup.js:467` | `indices.sort((a, b) => a - b);` with comment "sort indices ascending numerically (the compaction below walks the deleted tail block and assumes ascending numeric order)". (File moved: `particular/…` → `graphics/particles/particular/…`) | **Yes** — `ParticleGroup.spec.js:114` `"deleteIndices() compacts correctly when a deleted index >= 10 outranks lower ones (C8)"` |
+| C9 | **FIXED** | `engine/graphics/particles/particular/engine/emitter/ParticlePool.js:507` | `attribute.updateRange.count = n * itemSize;` — and the sibling site at `:177` `attribute.updateRange.count = activeParticleLimit * attribute.itemSize;` | **Yes** — `ParticlePool.spec.js:227` `"writeAttributeForAllArray marks updateRange.count in elements, not particles (C9)"` |
+| C10 | **FIXED** | `engine/graphics/texture/atlas/AtlasLookupTexture.js` | carried forward from lead reviewer | — |
+| C11 | **FIXED** | `engine/graphics/texture/sampler/resize/sampler2d_scale_down_lanczos.js:93-94` | `const rcp_ratio_y = 2 / ratio_y;` / `const rcp_ratio_x = 2 / ratio_x;` | **Yes** — `sampler2d_scale_down_lanczos.spec.js:33` `"non-uniform downscale is transpose-symmetric (C11)"`, written **outside** the still-present `describe.skip("currently broken")` block at :4 (those three legacy tests remain skipped) |
+| C12 | **FIXED** | `engine/ecs/fow/FogOfWar.js:707-713` | `const samplerWidth = this.size.x + 2;` / `const samplerHeight = this.size.y + 2;` / `new Sampler2D(uint8Array, 1, samplerWidth, samplerHeight);` — no transposition | **Yes** — `ecs/fow/FogOfWar.spec.js:16` `"resize builds a sampler with non-transposed dimensions (C12)"` |
+| C13 | **OPEN** | `engine/ecs/terrain/tiles/TerrainTileManager.js:566` | `stitchTile()` still floors: `const gridSize = this.totalSize.clone(); gridSize.divide(this.tileSize); gridSize.floor();` while `initializeTiles()` at `:352-353` creates tiles with `gridSize.divide(time_size); gridSize.ceil();`. The floored `gridSize` then gates every neighbour lookup (`if (x < gridSize.x - 1)` at :577/:586/:593, `if (y < gridSize.y - 1)` at :581), so the partial edge tiles that `ceil` created are never given top/right/bottom neighbours. `computeTileIndex` (:405) and `getRaw` (:422) already use `Math.ceil` — `stitchTile` is the lone floor. | **No** — no spec anywhere in `engine/` matches `stitch`/C13; `ecs/terrain/tiles/TerrainTile.spec.js` exists but does not cover manager-level seam stitching |
+| C14 | **FIXED** | `engine/asset/preloader/AssetPreloader.js:297-301` | `assetLoadFailed` now has the completion check: `//monitor completion (a failure counts toward the level batch, and //may be the last completion in it — see assetLoadSuccess)` then `if ((batchElementLoadedCount + batchElementFailedCount) >= batch_size) { this.on.levelFinished.dispatch(level); }` — mirrors `assetLoadSuccess` at :284. (File moved: `preloader/` → `asset/preloader/`) | **Yes** — `AssetPreloader.spec.js:89` `"a failing asset in an earlier level still advances the preload (C14)"` |
+| C15 | **FIXED** | `engine/navigation/ecs/path_following/PathFollower.js:160-162` | `if (typeof json.loop === "boolean") { this.writeFlag(PathFollowerFlags.Loop, json.loop); }` — and `json.active` is separately routed to `PathFollowerFlags.Active` at :156-158 | **Yes** — `PathFollower.spec.js:8` `"fromJSON reads the loop flag from json.loop, not json.active (C15)"` |
+| C16 | **FIXED** | `engine/animation/curve/actionProcessorOperations/curveActions.js:118-133` | `MoveKeyframeAction.apply` now copies in place: `this.actionContext.refCurve.keys[i].copy(this.curveValueEnd.keys[i]);` with comment "do NOT reassign the live curve's keyframe to the snapshot object … (C16)"; `revert` mirrors it with `.copy(this.curveValueStart.keys[i])`. Snapshots are taken by `.clone()` in the constructor (:110, :113). | **Yes** — `curveActions.spec.js:13` `"MoveKeyframeAction applies end values without aliasing live keyframes to its snapshot (C16)"` |
+| C17 | **OPEN** | `engine/graphics/geometry/MikkT/BuildNeighborsFast.js:116-118` | The B-side edge unpack is still wrong: `const i0_B = temp_edge_B[1];` / `const i1_B = temp_edge_B[2];` / `const edgenum_B = temp_edge_B[2];` — `i1_B` and `edgenum_B` read the **same slot**, and the "flip" comment at :115 is still there. `GetEdge` (`MikkT/GetEdge.js:22-42`) documents the layout as `out[0]=i0, out[1]=i1, out[2]=edgenum`, and the A-side at :85-87 reads it correctly (`temp_edge_A[0]/[1]/[2]`). So the pairing test `if (i0_A === i0_B && i1_A === i1_B …)` at :123 compares a vertex index against an edge number and effectively never matches. | **No** — `MikkT/MikkTSpace.spec.js` only has `'empty geometry'` (:3) and `'single triangle'` (:12); a single triangle has no neighbours, so the pairing path is untested |
+| C18 | **OPEN** | `engine/graphics/geometry/MikkT/GenerateSharedVerticesIndexList.js:79` | Insertion pass still has the precedence bug: `const bin_index = pass * 257 + (_comp_0[i] >> shift) & 0xff;` — `+` binds tighter than `&`, so this masks the whole sum, not just the byte. The **counting** pass at :59 was written correctly (`const index = pass * 257 + ((key >> shift) & 0xff) + 1;`), so counts and insertion now disagree about bin identity. | **No** — no spec references radix sorting or shared-vertex welding; `MikkTSpace.spec.js` does not reach multi-vertex welding |
+| C19 | **FIXED** | `engine/logging/elastic/ElasticSearchLogger.js:61, 82, 141-142` | Field names unified: the config is `this.__flush_timeout = 2000;` (:61) and the handle is `this.__timeout = -1;` (:82). `__prod()` arms it correctly: `} else if (this.__timeout === -1) { this.__timeout = setTimeout(this.__bound_flush, this.__flush_timeout); }`, and `flush()` clears the same field (:95-97). No `__timeout_ms` remains. | **Yes** — `ElasticSearchLogger.spec.js:4` `"logging fewer than flush_size records arms a deferred flush timer (C19)"` |
+| C20 | **FIXED** | `engine/ecs/EntityComponentDataset.js:1881-1882` | `dropData()` now clears both: `this.__entityEventListeners = []; this.__entityAnyEventListeners = [];`. `removeEntity` also purges both (:980-981). | **Yes** — `EntityComponentDataset.spec.js:1019` `"dropData clears any-event listeners so a recycled entity id does not inherit them (C20)"` |
+| C21 | **FIXED** | `engine/ecs/EntityManager.js:357` | Inside `detachDataset()` (:334): `system.handleDatasetDetached(dataset);`. The `handleDatasetAttached` calls remain only on the genuine attach paths (:316 in attach, :714 on system startup). | No dedicated spec found (behaviour is exercised indirectly by the ECS lifecycle suite) |
+| C22 | **FIXED** | `engine/sound/material/concrete/json/serializeSoundMaterialToJSON.js` | carried forward from lead reviewer | — |
+
+## Tally
+
+- **FIXED: 17** — C1, C3, C4, C6, C7, C8, C9, C10, C11, C12, C14, C15, C16, C19, C20, C21, C22
+- **OPEN: 4** — C5, C13, C17, C18
+- **MOVED/UNCLEAR: 0**
+
+Three files moved since the review but were located and verified (no ambiguity about identity):
+
+- `particular/group/ParticleGroup.js` → `graphics/particles/particular/group/ParticleGroup.js`
+- `particular/engine/emitter/ParticlePool.js` → `graphics/particles/particular/engine/emitter/ParticlePool.js`
+- `preloader/AssetPreloader.js` → `asset/preloader/AssetPreloader.js`
+
+## Notes on the OPEN items
+
+- **None of the four OPEN items has a regression spec.** Every FIXED item except C21 shipped with a spec that names its finding ID, so the absence of one is a reliable signal that C5/C13/C17/C18 were never worked.
+- **C17 and C18 are both in `graphics/geometry/MikkT/`** and both sit on the tangent-generation path. The only spec in that directory covers empty geometry and a single triangle — neither case reaches edge pairing or vertex welding.
+- No fix for any of the four is implemented as an `assert.*` (which would not count, since asserts are stripped in production) — the defective lines are plain unguarded logic.

package/src/REVIEW_2026_08_06/prior-highs.md

@@ -0,0 +1,138 @@
+# REVIEW_2026_07_03 §2 + §4 — re-verification against current source (2026-08-06)
+
+Root: `H:/git/moh/app/src/mir-engine/meep/src/`
+Rule applied: an `assert.*` is stripped in production, so an assert-only guard is **not** a fix.
+
+**Tally: 34 FIXED / 32 OPEN / 1 MOVED-UNCLEAR — 67 items checked.**
+
+---
+
+## §4 — ECS core & lifecycle
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| `Entity.promiseEvent` uses `removeEventListener` instead of `add` | **FIXED** | `engine/ecs/Entity.js:327` | `this.addEventListener(EventType.EntityRemoved, reject);` — matching `removeEventListener` cleanup at :320 |
+| `BinaryBufferSerializer` entity-id delta ordering guarded only by a stripped assert | **OPEN** | `engine/ecs/storage/BinaryBufferSerializer.js:180` | `assert.ok(entity >= lastEntity, ...)` is still the only guard on `const step = entity - lastEntity;` |
+| `EntityComponentDataset` event dispatch: no `try/finally` around the handler loop → throwing handler skips the proxy-pointer restore (§8 LOW) | **OPEN** | `engine/ecs/EntityComponentDataset.js:2161` (and :2203) | `entityListenersProxyPointer = pointerOffset;` restored after a bare loop in both `dispatchEventListenersByHash` and `dispatchAnyEventListenersByHash` |
+
+## §4 — Graphics: ECS bindings
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| `LightBinding` scale handler bound to `rotation.onChanged` | **FIXED** | `engine/graphics/ecs/light/binding/LightBinding.js:51` | `this.__c_transform.scale.onChanged.add(this.__apply_scale, this);` (unlink mirrors at :89) |
+| `WaterSystem.shutdown` dereferences `graphicsEngine.size`; preRender hook leaked | **FIXED** | `engine/graphics/ecs/water/WaterSystem.js:68` | `if (this.__preRenderHook !== null) { this.graphicsEngine.on.preRender.remove(this.__preRenderHook);` — no `.size` deref remains |
+| `auto_set_camera_clipping_planes` reads `old_near/far` after overwriting | **FIXED** | `engine/graphics/ecs/camera/auto_set_camera_clipping_planes.js:45` | `const old_near = camera.near;` captured **before** `camera.near = c.clip_near` (:51) |
+| `set_camera_aspect_ratio` ortho `h = bottom - top` | **FIXED** | `engine/graphics/ecs/camera/set_camera_aspect_ratio.js:25` | `const h = c.top - c.bottom;` |
+| `ForwardPlusRenderingPlugin.shutdown` removes from the wrong signal | **FIXED** | `engine/graphics/render/forward_plus/plugin/ForwardPlusRenderingPlugin.js:81` | `graphics.main_view.on.preRender.remove(this.__prepare_for_render, this);` matches the add at :65 |
+| `sg_hierarchy_compute_bounding_box_via_parent_entity` ignores `entity` | **FIXED** | `engine/graphics/ecs/mesh-v2/sg_hierarchy_compute_bounding_box_via_parent_entity.js:19` | `const sg = ecd.getComponent(entity, ShadedGeometry);` — unioned into `result` at :24 |
+| `SGMeshSystem.update` splices its wait-queue while modulo-indexing | **OPEN** | `engine/graphics/ecs/mesh-v2/aggregate/SGMeshSystem.js:283` | `const index = pointer % l;` with `waiting.splice(index, 1);` at :295 and `l` captured before the loop, never decremented |
+
+## §4 — Graphics: texture / particles / geometry
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| `ManagedTextureAtlas` serves stale atlas-evicted patches from a TTL-∞ loader cache | **OPEN** | `engine/graphics/texture/atlas/ManagedTextureAtlas.js:148` | `patch = await this.#patch_loader.get(url);` — `#remove_from_lookup` (:91) never invalidates the loader cache (`DEFAULT_TIME_TO_LIVE = Infinity`) |
+| `CachingTextureAtlas.__evict_all` leaves index 0 | **FIXED** | `engine/graphics/texture/atlas/CachingTextureAtlas.js:153` | `for (let i = this.__cached_patches.length - 1; i >= 0; i--) {` |
+| `sampler2d_scale_down_linear` mis-indexes on non-integer ratios | **OPEN** | `engine/graphics/texture/sampler/resize/sampler2d_scale_down_linear.js:54` | `const row_index = (sampleOffsetY + j) * iW;` with fractional `sampleOffsetY = y * sH`; only `assert.ok(sW >= 1, …)` guards it |
+| `sampler2d_copy_with_margins` uses `width` for a vertical bound | **FIXED** | `engine/graphics/texture/sampler/sampler2d_copy_with_margins.js:138` | `for (y = destinationY + height, yMax = Math.min(destination.height, y + marginBottom); ...` (commit `90bcf672a`) |
+| `SimulationStepCurlNoiseVelocity` shared `this.time` accumulates per emitter | **OPEN** | `engine/graphics/particles/particular/engine/simulator/SimulationStepCurlNoiseVelocity.js:22` | `this.time += this.timeDelta;` on the single shared instance held by `ParticularEngine.steps` |
+| `ParticleEmitter` hash/equals disagree on flags | **FIXED** | `engine/graphics/particles/particular/engine/emitter/ParticleEmitter.js:694` | `&& (this.flags & SERIALIZABLE_FLAGS) === (other.flags & SERIALIZABLE_FLAGS);` — same mask `#computeHash()` folds in at :664 |
+| `ShaderManager` leaks a disposed emitter after a graveyard round-trip | **OPEN** | `engine/graphics/particles/particular/engine/shader/ShaderManager.js:399` | `this.recordGraveyard.set(emitter, entry);` — the `entry.count <= 0` branch never splices the emitter out of `entry.emitters` |
+| `equal_attribute_structure` returns truthy `-1` on name mismatch | **FIXED** | `engine/graphics/geometry/optimization/merge/merge_geometry_hierarchy.js:91` | `if (b_attribute_index === -1) { return false; }`; caller uses `if (!equal_attribute_structure(...)) continue;` |
+| `InstancedMeshGroup.build` stale per-instance colors on shrink+regrow | **FIXED** | `engine/graphics/geometry/instancing/InstancedMeshGroup.js:575` | `newColorArray.fill(255, this.count * 4);` |
+| `bvh32_geometry_nearest` duplicated denormalize block | **FIXED** | `engine/graphics/geometry/buffered/query/bvh32_geometry_nearest.js:189` | `if (vertex_data_normalized) { ax = typed_array_value_denormalize(ax, vertices);` — block appears exactly once |
+| `ensureGeometryBoundingSphere` returns stale `null` on first call | **FIXED** | `engine/graphics/geometry/buffered/ensureGeometryBoundingSphere.js:15` | `boundingSphere = geometry.boundingSphere = new ThreeSphere(...)` — chained assignment before `return boundingSphere;` |
+
+## §4 — Water (broken three ways)
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| `WaterShader.js` references r136-removed ShaderChunk symbols | **OPEN** | `engine/graphics/shaders/WaterShader.js:22` | `THREE.ShaderChunk["lights_pars"],` — plus `BRDF_Diffuse_Lambert` (:112, :124) and `linear_to_gamma_fragment` (:142) |
+| `WaterSystem.shutdown` TypeError | **FIXED** | (see bindings table) | — |
+| `Water`/`WaterSystem` never dispose height `DataTexture` / geometry / material | **OPEN** | `engine/graphics/ecs/water/WaterSystem.js:215` | `unlink(component, entity) { component.bvh.unlink();` — no `dispose()` on the `PlaneBufferGeometry` (:187), material (:165), or the `DataTexture` in `Water.updateShaderForTerrain` |
+
+## §4 — Control / input
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| `phaseCrossed` misses exactly-on-boundary landings | **FIXED** | `engine/control/first-person/FirstPersonPlayerControllerSystem.js:2022` | `return prev < boundary && next >= boundary;` (inclusive in both branches) |
+| `PointerDevice.observeTap` shared move handler under multi-touch | **OPEN** | `engine/input/devices/PointerDevice.js:121` | `up.addOne(handleUp);` / `move.add(handleMove);` — one closure for all pointer ids; `reset(id)` removes the other pointer's registration |
+| `InputControllerSystem.remove` splices index `-1` | **OPEN** | `engine/input/ecs/systems/InputControllerSystem.js:140` | `this.deferred.splice(i_d, 1);` with no `i_d !== -1` guard |
+| `TouchDevice` never attaches its handlers | **OPEN** | `engine/input/devices/touch/TouchDevice.js:53` | `#eventHandlerGlobalTouchEnd = (event) => {` — no `addEventListener`/attach anywhere in the file |
+
+## §4 — ECS gui / terrain
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| `HeadsUpDisplaySystem` `z *= scale.y` | **FIXED** | `engine/ecs/gui/hud/HeadsUpDisplaySystem.js:88` | `z *= transform_scale.z;` |
+| `obtainTileAtWorldPosition2D` dereferences an out-of-bounds tile | **OPEN** | `engine/ecs/terrain/tiles/TerrainTileManager.js:489` | `return this.obtain(tile.gridPosition.x, tile.gridPosition.y);` — `getTileByWorldPosition2D` returns `undefined` out of bounds and there is no guard |
+
+## §4 — Asset loaders
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| 1-bit / sub-8-bit palette PNGs decode to garbage | **OPEN** | `engine/asset/loaders/image/png/PNG.js:199` | `const i = this.colors * this.bitDepth / 8 * (y * this.width + x);` — fractional byte index, no shift/mask unpack (also `getUint8Data_case3` :346) |
+| `SVGAssetLoader` hangs on non-200 | **OPEN** | `engine/asset/loaders/SVGAssetLoader.js:10` | `if (xhr.readyState === xhr.DONE && xhr.status === 200) {` — no `else`, so a 404/500 settles nothing |
+| Worker image decoder detaches a cached `ArrayBuffer` | **FIXED** | `engine/asset/loaders/image/codec/ThreadedImageDecoder.js:52` | `return this.worker.request('decode', [data.buffer]);` — `WorkerProxy.trySendMessage` posts with **no** transfer list, so the buffer is cloned |
+
+## §4 — Animation / navigation / intelligence
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| `AnimationTrackPlayback.advance` `%= timeEnd` wrap + repeated `on.ended` | **OPEN** (partly fixed) | `engine/animation/keyed2/AnimationTrackPlayback.js:171` | `newPosition %= this.track.timeEnd;` still ignores `timeStart`. The repeated-`ended` half **is** fixed: `else if (this.position < this.track.timeEnd)` latch at :172 |
+| `estimatePathViaIterativeIntegral` infinite loop | **FIXED** | `engine/graphics/ecs/path/tube/build/estimatePathViaIterativeIntegral.js:28` | `if (!on_path) { break; }` |
+| GLTF CUBICSPLINE tangents missing `/Δt` | **OPEN** | `engine/animation/clip/curve_from_track_data_cubic_tangents.js:30` | `curve.add(Keyframe.from(time, value, inTangent, outTangent));` — no division by the keyframe delta anywhere in the file |
+| Grid A* inadmissible squared-distance heuristic | **FIXED** | `engine/navigation/grid/find_path_on_grid_astar.js:185` | `return Math.abs(dx) + Math.abs(dy);` with a comment naming the old squared-euclidean estimate |
+| `OverrideContextBehavior` double init | **FIXED** | `engine/intelligence/behavior/decorator/OverrideContextBehavior.js:37` | `Behavior.prototype.initialize.call(this, context);` with a comment explaining the deliberate skip of `super.initialize()` |
+| `ConditionalBehavior` abandons a running source without finalizing | **OPEN** | `engine/intelligence/behavior/util/ConditionalBehavior.js:41` | `} else if (s === BehaviorStatus.Failed) { condition.finalize(); return s;` — `this.__source` is never finalized on that branch; file unchanged since before the review |
+
+## §4 — Root engine / UI / logging
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| `Ticker.pause()` doesn't pause the clock | **FIXED** | `engine/simulation/Ticker.js:269` | `this.clock.pause();` (commit `53a45db88`) |
+| `Ticker.start()` discards the initial rAF handle | **OPEN** | `engine/simulation/Ticker.js:250` | `requestAnimationFrame(animationFrameCallback);` — handle not stored, so `#isUpdateLoopActive()` is false right after start and `stop()` cannot cancel it (`animate()` then re-arms rAF forever) |
+| `SceneManager.clear()` leaves clock speed-modifiers | **FIXED** | `engine/scene/SceneManager.js:159` | `this.deactivateScene(this.#current_scene);` with a comment on removing the modifiers |
+| ElasticSearchLogger POSTs a JSON array, not NDJSON | **FIXED** | `engine/logging/elastic/ElasticSearchLogger.js:123` | `const body = lines.join('\n') + '\n';` with action lines and a `_bulk` endpoint |
+| ElasticSearchLogger `@timestamp = performance.now()` | **OPEN** | `engine/logging/elastic/ElasticSearchLogger.js:151` | `record.time = performance.now();` written as `'@timestamp': record.time` (:117) |
+| `GraphicsEngine.stop()` leaks framebuffers / listeners | **OPEN** | `engine/graphics/GraphicsEngine.js:642` | `stop() { this.context.detach(); ... }` — no `frameBuffers` teardown and the three `context_monitor.on.lost/restored/failed.add(...)` from `start()` (:521-523) are never removed; `initializeFrameBuffers()` re-`add`s buffers on every start |
+| `GUIEngine.shutdown()` leaks tickers / viewport listeners | **OPEN** | `engine/ui/GUIEngine.js:501` | `shutdown() { this.windows.reset(); ... }` — never calls `this.ticker.stop()` (started at :470) and leaves `engine.gameView.size.process(...)` / `this.cursor.process(...)` bound. Localization listener removal **is** now present (:508) |
+| `set_environment_texture` leaks the PMREM target | **FIXED** | `engine/graphics/GraphicsEngine.js:415` | `if (previous_target !== null) { previous_target.dispose(); }` |
+| `DomElementProcessorManager.unlink` leak | **OPEN** | `engine/ui/bindings/DomElementProcessorManager.js:303` | `unlink() { this.__mutation_observer.disconnect(); ... }` — every `DomElementBinding` in `__element_to_bindings` stays bound (no `binding.unbind()`); file unchanged since 2023. The `preRender` listener removal (:309) **is** paired |
+
+## §4 — Graphics GI (sh3)
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| LPV GI vertex shader walks the tet mesh in object space | **OPEN** | `engine/graphics/sh3/gi/material/space_vertex/build_vertex_shader.js:18` | `lpv_walk_to_tetrahedron(position, nearest_tet, tet, barycentric_coordinates);` — `position` is object space while :12/:14 use `worldPosition.xyz` |
+| Path tracer: texture wrap mode never copied | **FIXED** | `engine/graphics/sh3/path_tracer/material/MaterialConverter.js:59` | `st.wrapS = texture.wrapS;` / `st.wrapT = texture.wrapT;` |
+| Path tracer: tint linearized twice | **OPEN** | `engine/graphics/sh3/path_tracer/material/MaterialConverter.js:111` | `sRGB_to_linear(tint, 0, tint, 0);` — the linear tint is multiplied into the still-sRGB-encoded sampler, whose clone keeps `decode_sRGB = true` (`StandardTexture.js:39, :97`), so it is decoded again at sample time |
+| Path tracer: emissive color / intensity dropped | **OPEN** | `engine/graphics/sh3/path_tracer/material/MaterialConverter.js:96` | `} else if (name === "emissive") { result.emissive = sampler;` — only the map; `material.emissive` / `emissiveIntensity` are never read and `StandardMaterial` has no such field |
+
+## §4 — Network
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| `ServerAuthoritativeServer` default-null `authorize` | **FIXED** | `engine/network/orchestrator/ServerAuthoritativeServer.js:130` | `this.executor.authorize = make_owner_authorization({ world, identity_class, server_peer_id });` — secure by default |
+| Receiver reassembly cap 64 KiB vs sender ~302 KiB | **OPEN** | `engine/network/transport/fragments/FragmentAssembler.js:59` | `max_message_size = 65536,` and `NetworkPeer.js:457` uses `new FragmentAssembler()` with no override, while `packet_size.js:59` gives `MAX_LOGICAL_MESSAGE_BYTES = 1186 * 255 ≈ 302 KiB` |
+
+---
+
+## §2 — Recurring patterns
+
+| Item | Status | Current file:line | Evidence |
+|---|---|---|---|
+| §2.1 `Camera.copy` drops fov / clip planes | **FIXED** | `engine/graphics/ecs/camera/Camera.js:127` | `this.fov.copy(other.fov); this.clip_near = other.clip_near; this.clip_far = other.clip_far;` |
+| §2.1 `GridPosition2Transform.copy` drops flags | **OPEN** | `engine/grid/grid2transform/GridPosition2Transform.js:80` | `copy(other) { this.offset.copy(other.offset); return this; }` — `flags` (:18) is never copied |
+| §2.1 `Transform.copy` propagates a cleared auto-update flag | **OPEN** | `engine/ecs/transform/Transform.js:278` | `this.flags = other.flags;` after `this.clearFlag(TransformFlags.AutomaticChangeDetection)` — unchanged since 2023 |
+| §2.2 AnimationGraph JSON state `name` / `tags` dropped | **FIXED** | `writeAnimationGraphDefinitionToJSON.js:73-74`, `readAnimationGraphDefinitionFromJSON.js:89-90` | `name: s.name, tags: s.tags,` written; `state.name = name; state.tags = tags;` read |
+| §2.2 `startingSate` typo | **FIXED** (as a divergence) | `writeAnimationGraphDefinitionToJSON.js:100`, `readAnimationGraphDefinitionFromJSON.js:25` | `startingSate: states.indexOf(graph.startingSate)` / `startingSate = 0` — symmetric write/read plus a round-trip spec; the misspelling survives as the field name only |
+| §2.2 POINT-light `distance` binary-only | **FIXED** | `engine/graphics/ecs/light/Light.js:174` | `if (actual_type === LightType.SPOT \|\| actual_type === LightType.POINT) { result.distance = this.distance.toJSON(); }` with the matching read at :141 |
+| §2.2 `SerializationMetadata` flags truncated to 8 bits | **OPEN** | `engine/ecs/components/SerializationMetadataSerializationAdapter.js:15` | `buffer.writeUint8(value.flags);` / `value.flags = buffer.readUint8();` |
+| §2.2 `Team` sentinel aliasing | **OPEN** | `engine/ecs/team/TeamSerializationAdapter.js:22` | `//TODO it's possible to write encoded Infinity values by accident` — `2147483647` round-trips as `Infinity` (same in `ObservedInteger.toBinaryBuffer`) |
+| §2.2 `ViewportPosition.resolveGuiCollisions` dropped | **FIXED** | `engine/ecs/gui/position/ViewportPosition.js:114` | `resolveGuiCollisions: this.resolveGuiCollisions,` in `toJSON`, read at :103, binary at `ViewportPositionSerializationAdapter.js:21/38` |
+| §2.9 `AnimationClip.repeatCount` 1 vs ∞ | **FIXED** | `engine/ecs/animation/AnimationClip.js:9` / `:86` | field `repeatCount = new ObservedInteger(1);`; `fromJSON` else-branch `this.repeatCount.set(1);` |
+| §2.9 `screenEdgeWidth` 10 vs 0 | **FIXED** | `engine/ecs/gui/position/ViewportPosition.js:46` / `:95` | field `screenEdgeWidth = 10;`; `fromJSON` default `screenEdgeWidth = 10,` |
+| §2.8 `SoundControllerSystem` missing `return` after error | **OPEN** | `engine/sound/ecs/SoundControllerSystem.js:82` | `console.error("Entity " + entity + " has no SoundEmitter to control");` (:68) then `emitter.tracks.add(track);` (:82) |
+| §2.8 `SoundEmitterSystem` missing `return` after error | **MOVED-UNCLEAR** | `engine/sound/ecs/emitter/SoundEmitterSystem.js` | The file now contains no `console.*`/logger call and no `=== undefined` fall-through; the described log-and-fall-through site no longer exists, so the item cannot be mapped to current code |
+| §2.8 `ParticleVolume.fromJSON` missing `return` after error | **FIXED** | `engine/graphics/particles/particular/engine/utils/volume/ParticleVolume.js:336` | `throw new Error(\`Unsupported sampling function type '${sampling_function}', ...\`);` — a real throw, not a log |

package/src/REVIEW_2026_08_06/test-gaps.md

@@ -0,0 +1,364 @@
+# meep — functional test-gap analysis
+
+Question answered: **where would a real defect ship undetected because no test would fail?**
+
+Baseline taken as given (1542 suites green, 9337 tests). Everything below is evidence-backed by reading
+the source *and* the specs that exist. Raw coverage counts are used only to size a gap, never as the argument.
+
+Ranked by blast radius.
+
+---
+
+### TG-1 Save/load durability layer has no test of any kind
+- **Severity**: CRITICAL
+- **Area**: `H:/git/moh/app/src/mir-engine/meep/src/engine/save/**` (6 files, 0 specs)
+- **Gap**: `Storage.js` (the abstract contract + all `promise*` wrappers + `contains` implemented on top of `list`),
+  `storage/IndexedDBStorage.js` (the only real browser backend), `storage/InMemoryStorage.js`,
+  `StorageBackedList.js` (exports class `StorageBackedSet` — the serialized read-modify-write queue behind
+  achievements and options), and `GameStateLoader.js` (the `save`/`load`/`exists`/`count` engine plugin with a
+  legacy-format fallback) are collectively untested. Nothing asserts the `Storage` contract for *any*
+  implementation, and nothing asserts that a backend failure produces a rejection rather than a hang.
+- **What could ship broken**:
+  - Every `IndexedDBStorage` method settles purely from DOM events (`success`/`error` listeners). Drop or
+    mis-wire one `error` listener and a save/load promise **never settles** — the game sits on a spinner
+    forever instead of surfacing an error. No test would notice.
+  - The file already carries the divergence this gap predicts: `list()` builds its transaction with the legacy
+    `IDBTransaction.READ_ONLY` constant (removed from the spec, evaluates to `undefined`) while every other
+    method uses `IndexedDBTransactionMode.ReadOnly`. It works today only because `transaction(name, undefined)`
+    defaults to `readonly`. A latent inconsistency survived in the one class that touches player saves.
+  - `QuotaExceededError` handling is an explicit in-file `TODO`: a full disk silently loses the save.
+  - `StorageBackedSet.remove()` calls `storage.store(key, list, resolve, reject)` with **no** `progress`
+    argument while `add()` passes `noop`. A backend that invokes `progress(...)` unconditionally throws on
+    remove only. Its `lastPromise` serialization chain (interleaved `add`/`remove`/`contains`) is never
+    exercised, so a lost-update race would be invisible.
+  - `GameStateLoader.count()` never calls `reject`; `load()` silently falls through to the deprecated
+    `legacyLoad` path when no metadata matches — a metadata regression degrades to the legacy path silently
+    instead of failing.
+- **Cheapest closing test**: one `Storage`-contract suite parameterised over `InMemoryStorage` and a
+  deliberately-failing stub backend (store/load/list/contains/remove/`promise*`, plus "backend error rejects,
+  never hangs"), and one `StorageBackedSet` spec for interleaved mutation ordering. **~6 files**, and it gives
+  `IndexedDBStorage` a contract to be checked against the day a fake-IDB backend is added.
+
+---
+
+### TG-2 Only one component in the engine has ever round-tripped through the binary save format
+- **Severity**: CRITICAL
+- **Area**: `engine/ecs/storage/**` + all `*SerializationAdapter.js`
+- **Gap**: The sole end-to-end serializer test is `engine/ecs/storage/BinaryBufferSerializer.spec.js` — 44 lines,
+  one entity, one component (`Name`, a single string), one adapter. There are **77** `BinaryClassSerializationAdapter`
+  subclasses; **46 have no spec**, including every graphics ECS component (`Mesh`, `Light`, `Camera`,
+  `TopDownCameraController`, `Decal`, `Water`, `Highlight`, `AnimationController`, `AnimationGraph`,
+  `ParticleEmitter`, `Sampler2D`), `FogOfWar`/`FogOfWarRevealer`, `Terrain`, `GUIElement`, `HeadsUpDisplay`,
+  `ViewportPosition`, `Team`, `Tooltip`, `InverseKinematics`, `PropertySet`, `Animation`, `TransformPose`,
+  `GridPosition2Transform`, `GridObstacle`, all six acoustic-simulation adapters, and all eight behaviour-tree
+  node adapters. (The `sopra` audio adapters are the exception — all 13 are specced.)
+- **What could ship broken**: any field silently dropped, reordered, or read with the wrong width. This is not
+  hypothetical — reading the code turned one up immediately:
+  `engine/graphics/ecs/light/LightSerializationAdapter.js` writes `distance` **only when `type === SPOT`**,
+  but `Light.js` documents and `Light.toJSON()` persists `distance` for **SPOT and POINT**, and neither the
+  binary path nor `Light.toJSON` for a POINT light carries `maxShadowDistance`. Consequence: **every point
+  light loaded from a binary save has its radius reset to `DEFAULT_DISTANCE = 1`**, and every directional
+  light loses its shadow-range tuning. The suite is green.
+  Worse than a wrong value: because adapters are read back-to-back out of one collection buffer, a
+  read/write length mismatch does not fail locally — it desynchronises the cursor and corrupts every
+  subsequent component of that type in the file.
+- **Cheapest closing test**: one table-driven harness — for each adapter, construct an instance with every
+  field set to a non-default value, `serialize` → rewind → `deserialize` into a fresh instance, assert field
+  equality, and assert the buffer cursor advanced by exactly the bytes written. **~77 adapter classes in a
+  single spec file.**
+
+---
+
+### TG-3 The JSON authoring path and the binary save path disagree about the field set, and nothing compares them
+- **Severity**: CRITICAL
+- **Area**: cross-cutting — 121 classes implement both `toJSON` and `fromJSON`; ~77 of those also have a binary adapter
+- **Gap**: No test anywhere asserts the three-way contract `field-init == fromJSON(toJSON(x)) == fromBinary(toBinary(x))`.
+  The two formats are maintained by hand in separate files and drift independently. This is distinct from TG-2:
+  even a perfect binary round-trip test would not catch it.
+- **What could ship broken**: a component authored in a JSON blueprint and the same component restored from a
+  save file end up with **different state**. Confirmed live example:
+  `engine/graphics/ecs/water/Water.js` — `toJSON()` emits only `level` and `color`, and `fromJSON` reads only
+  those two. `WaterSerializationAdapter` persists **nine** fields (`level`, `color`, `shoreDepthTransition.min/max`,
+  `shoreColor`, `waveSpeed`, `waveAmplitude`, `waveFrequency`, `scattering`). So a water body authored in a
+  blueprint silently gets default waves and shore colour, while the same entity saved and reloaded keeps them —
+  meaning the water looks *different after a save/load cycle than it did on first load of the level*.
+  `Light` diverges the same way (TG-2). Nothing distinguishes "field deliberately runtime-only" from
+  "field forgotten in one of the two writers".
+- **Cheapest closing test**: one parameterised triple-round-trip harness driven by the registered-class list,
+  with an explicit opt-out list for genuinely transient fields. **~121 classes**, and it permanently pins the
+  two formats to each other.
+
+---
+
+### TG-4 21 binary format upgraders, zero specs — the backward-compatibility path for old saves is unverified
+- **Severity**: CRITICAL
+- **Area**: all `*SerializationUpgrader_*.js` / `*SerializationUpdater_*.js`
+- **Gap**: `Tag_0_1`, `ClingToTerrain_0_1`, `Terrain_0_1`, `Terrain_1_2`, `Transform_0_1`,
+  `TopDownCameraController_0_1`, `Highlight_0_1`, `Water_0_1`, `ParticleEmitter_0_1`,
+  `GridPosition2Transform_0_1`, `GridPosition_0_1`, `Path_0_1`, `Path_1_2`, `PathFollower_0_1`, `_1_2`, `_2_3`,
+  `_3_4`, `RigidBody_0_1`, `SoundEmitter_0_1`, `_1_2` — none has a spec.
+  The *mechanism* is covered: `BinarySerializationRegistry.spec.js` tests chain search/shortest-path and
+  `BinaryCollectionSerialization.spec.js` runs a two-step chain, both with synthetic upgraders. **Not one real
+  upgrader is ever fed real old-version bytes.**
+- **What could ship broken**: an upgrader's only contract is "read exactly the old layout, write exactly what
+  the *current* adapter's `deserialize` expects". That contract spans two files that are edited months apart.
+  Example: `GridPosition2TransformSerializationUpgrader_0_1` reads two `Float64`s and re-encodes them into the
+  v1 header+`Float32` form. The day the v1 adapter layout changes, the upgrader keeps emitting the old shape;
+  the adapter mis-parses it, the collection cursor desynchronises, and **every remaining component in the save
+  file is garbage**. Players with pre-existing saves get corruption or a load crash; CI is green because CI
+  only ever writes and reads the current version.
+- **Cheapest closing test**: per-upgrader golden-bytes test — hand-construct the old-version buffer, run the
+  registered chain, deserialize with the current adapter, assert fields. **21 files, one table-driven spec.**
+
+---
+
+### TG-5 Transient-entity and non-serializable-component exclusion is structurally unreachable by the suite
+- **Severity**: CRITICAL
+- **Area**: `engine/ecs/storage/BinaryBufferSerializer.js`, `engine/ecs/components/SerializationMetadata.js`
+- **Gap**: `SerializationMetadata` appears in **zero** spec files anywhere in the tree. The serializer has two
+  gates: `isEntityTransient()` (skips entities flagged `SerializationFlags.Transient`, and components carrying
+  the `@serialization_transient` magic field) and `isComponentClassSerializable()` (`componentClass.serializable !== false`,
+  relied on by **15** classes: `Renderable`, `Input`, `InputController`, `Script`, `Timer`, `Attachment`,
+  `AttachmentSockets`, `ParentEntity`, `DynamicActor`, `Voice`, `PathDisplay`, `Trail2D`, `Trail3D`,
+  `ShadedGeometry`, `Transform2GridPosition`). The single end-to-end spec has neither a `SerializationMetadata`
+  component nor a `serializable = false` component, so **both predicates are constant over the entire suite**.
+- **What could ship broken**: invert or short-circuit either gate and you get one of two silent catastrophes —
+  (a) every save file comes out empty or missing most entities, or (b) transient UI/preview/effect entities and
+  runtime-only components get baked into every save and **resurrect on load** (ghost HUD entities, orphaned
+  trails, duplicated input controllers), with save files growing every cycle. Neither turns a test red.
+  Also unreachable in the same 44-line spec: the multi-type path. With exactly one component type, the
+  "rewind and skip a type that wrote 0 components" branch and the `numTypesWritten` header patch-up at the end
+  of `process()` never execute, and the entity-delta encoding (`step = entity - lastEntity`) is only ever
+  exercised with a single entity, so any regression in gap encoding across sparse entity ids is invisible.
+- **Cheapest closing test**: grow the existing end-to-end spec to ~6 cases — transient entity excluded,
+  `@serialization_transient` component excluded, `serializable = false` type excluded, a type with zero
+  surviving instances (header rewind), multiple types, and sparse entity ids. **1 file**, closes the whole
+  save-file-shape contract.
+
+---
+
+### TG-6 Engine startup/shutdown: the only test is "constructor does not throw"
+- **Severity**: CRITICAL
+- **Area**: `engine/Engine.js` (682 lines) / `engine/Engine.spec.js` (15 lines), `engine/plugin/EnginePluginManager.js` (319 lines, no spec), `engine/EngineHarness.js` (548 lines, referenced by zero specs)
+- **Gap**: `Engine.start()` and `Engine.stop()` are **never invoked by any test**. `EngineHarness` — the
+  in-repo helper built for exactly this — is used only by `editor/prototype*` files and `LevelGenerator.js`,
+  never by a spec. `EnginePluginManager` (dependency-ordered plugin startup/shutdown, recursive dependency
+  transition, reference counting) has no spec at all; only the `EnginePlugin` base class does.
+- **What could ship broken**:
+  - `start()` fans out four concurrent branches (`sound.start().then(entityManager.startup)`,
+    `staticKnowledge.load`, `gui.startup`, `plugins.startup`) and its rejection handler is
+    `function (e) { logger.error('Engine Failed to start: ' + e); }` — **the returned promise resolves on
+    failure**. Any branch regressing to a rejection leaves a half-started engine while every caller proceeds
+    as though startup succeeded. Nothing asserts that `start()` rejects on failure.
+  - `stop()` never cancels the `requestAnimationFrame` loop that `start()` begins, so rendering continues
+    after shutdown against torn-down state. Nothing asserts otherwise.
+  - The shutdown *ordering* (entityManager → plugins → gui → assetManager, and ticker paused first) is pure
+    convention. Reordering it — e.g. shutting down `assetManager` before plugins that still hold assets — is
+    a green change.
+  - `EnginePluginManager` carries an in-code `TODO address cyclic dependencies, these can cause a deadlock`.
+    A cyclic plugin graph hangs startup forever, and because `start()` swallows, it hangs *silently* with no
+    error anywhere.
+- **Cheapest closing test**: one spec on the already-imported `InMemoryEnginePlatform` with stub plugins:
+  `start()` resolves only once every plugin reaches Running; `start()` **rejects** when a plugin's startup
+  throws; `stop()` transitions plugins in reverse and stops the frame loop; a cyclic plugin dependency fails
+  rather than hangs. **~5 files** (`Engine`, `EnginePluginManager`, `PluginReferenceContext`, `EngineBootstrapper`,
+  `EngineConfiguration`), and it makes `EngineHarness` a tested entry point for everything downstream.
+
+---
+
+### TG-7 `link`/`unlink` symmetry is never asserted for any System, despite the base class documenting it as the contract
+- **Severity**: MAJOR
+- **Area**: `engine/ecs/System.js` and 70 `*System.js` implementations (28 have an adjacent spec)
+- **Gap**: `System.js`'s class JSDoc spells the contract out with a worked example — whatever `link()` attaches,
+  `unlink()` must detach. No test anywhere enforces it. The 42 systems with no spec include precisely the ones
+  that mutate the three.js scene graph, the DOM, or long-lived signal lists on link:
+  `engine/ecs/renderable/RenderSystem.js`, `engine/graphics/ecs/mesh/MeshSystem.js`,
+  `engine/graphics/ecs/mesh-v2/aggregate/SGMeshSystem.js`, `engine/graphics/ecs/light/LightSystem.js`,
+  `engine/graphics/ecs/camera/CameraSystem.js` and `topdown/TopDownCameraControllerSystem.js`,
+  `engine/graphics/ecs/water/WaterSystem.js`, `engine/ecs/gui/GUIElementSystem.js`,
+  `engine/ecs/terrain/ecs/TerrainSystem.js`, `engine/ecs/fow/FogOfWarSystem.js`,
+  `engine/ecs/transform-attachment/TransformAttachmentSystem.js`, `engine/ecs/systems/AnimationSystem.js`,
+  `engine/graphics/ecs/animation/AnimationControllerSystem.js` and `animator/AnimationGraphSystem.js`,
+  `engine/ecs/tooltip/TooltipComponentSystem.js`, `engine/ecs/ik/InverseKinematicsSystem.js`,
+  `engine/input/ecs/systems/InputSystem.js`, `engine/sound/ecs/SoundListenerSystem.js`,
+  `engine/grid/position/GridPositionSystem.js`, `engine/grid/grid2transform/GridPosition2TransformSystem.js`.
+- **What could ship broken**: delete a single `signal.remove(...)`, `scene.remove(object3d)`, or
+  `map.delete(entity)` from any `unlink` and the suite stays green while the game leaks one listener or one
+  scene-graph node **per entity per spawn**. That is the classic long-session symptom set — memory growth,
+  ghost geometry that keeps rendering after the entity dies, and stale callbacks firing against destroyed
+  components — and it is exactly the failure mode a unit suite is supposed to catch cheaply. Currently
+  nothing does; it only becomes visible in a soak.
+- **Cheapest closing test**: one generic harness — for a given system, build a real `EntityComponentDataset`,
+  create an entity carrying the system's declared `dependencies` tuple, snapshot `hasHandlers()` on every
+  `Signal` reachable from the component instances plus the sizes of the system's own containers, link, then
+  remove a component and assert the snapshot is restored. One table entry per system.
+  **Covers the 42 currently unspecced systems**, and pins the contract for the 28 that do have specs.
+
+---
+
+### TG-8 `AbstractContextSystem`'s pooled per-entity context is never recycled under test — and it does not reset
+- **Severity**: MAJOR
+- **Area**: `engine/ecs/system/AbstractContextSystem.js`, `engine/ecs/system/SystemEntityContext.js` (both 0 specs)
+- **Gap**: These two classes implement the pooled per-entity context used by 7 systems (`LightSystem`,
+  `ParentEntitySystem`, `DynamicActorSystem`, `VoiceSystem`, `FPDecalSystem`, `PathDisplaySystem`,
+  `SpriteSystemPE`). No test links an entity, unlinks it, and links a *second* entity on one of these systems,
+  so the pool never actually recycles anywhere in the suite — the reuse path is structurally unreachable.
+- **What could ship broken**: the `ObjectPoolFactory` reset hook is an empty `// TODO` and the destroy hook is
+  `(ctx) => { //ctx.unlink(); }`. `ctx.components` is never truncated on release, so a context recycled from a
+  3-component tuple onto a 2-component tuple still holds the **previous entity's** third component at
+  `components[2]`. Any context that reads a positional component defensively operates on a live object
+  belonging to a dead entity — mis-attributed lights, decals bound to the wrong transform, voices playing at
+  a stale position. `SystemEntityContext.link()` is also guarded by `__is_linked`; if a release path ever
+  skips `unlink()`, the recycled context silently **never links at all** and the entity is invisible to the
+  system with no error.
+- **Cheapest closing test**: one spec with a trivial context class — link A, unlink A, link B with a shorter
+  tuple, assert the recycled context carries no state from A and is properly linked. **Base class + 7 subclasses.**
+
+---
+
+### TG-9 `view/View.spec.js` is a 6-line smoke test standing in for the entire view lifecycle
+- **Severity**: MAJOR
+- **Area**: `view/View.js` (804 lines) and 54 `View` subclasses
+- **Gap**: The whole spec is `test("constructor does not throw", ...)`. `View.js` implements a real lifecycle:
+  `link()`/`unlink()` walk both `bindings` and `children`; `addChild` links eagerly if the parent is already
+  linked; `removeChild` detaches the element **and** unlinks the child; `destroy()` asserts not-linked and
+  cascades to children; `addBinding`/`removeBinding` link and unlink `SignalBinding`s. None of it is asserted.
+  Zero specs across `view/elements` (34 files), `view/minimap` (12), `view/controller` (10), `view/common` (9 of 10),
+  `view/currency` (6), `view/interaction` (5).
+  This is **not** a "the DOM isn't testable here" situation: `jest-environment-jsdom@29.7.0` is installed and
+  **34 specs already opt in** via the `@jest-environment jsdom` docblock — including `engine/Engine.spec.js` itself.
+- **What could ship broken**: break the unlink cascade over `children` (an early return, a wrong loop bound,
+  an exception in one child aborting the rest) and every nested view keeps its signal subscriptions alive
+  after being removed from the DOM. That is the "HUD updates a panel that no longer exists" crash and a leak
+  of one subscription tree per screen transition. Equally invisible: `addChild` on an already-linked parent
+  failing to link the child, so a view renders but never updates.
+- **Cheapest closing test**: one jsdom spec on the base `View` — link/unlink symmetry over bindings and
+  children, addChild/removeChild while linked and while unlinked, binding add/remove, destroy-while-linked
+  assertion. **Pins the contract for all 54 subclasses** in one file.
+
+---
+
+### TG-10 Eleven of twelve asset loaders are untested; the AssetManager contract is only ever proven against stubs
+- **Severity**: MAJOR
+- **Area**: `engine/asset/loaders/**`
+- **Gap**: `engine/asset/AssetManager.spec.js` is a genuine strength — 33 tests covering loader failure and
+  retry, missing loader type, throwing requester, transformers (throwing / invalid result), nested loads,
+  dependency recording, cycles, `load_concurrency=1` deadlock, `skip_queue`, priority, insert-during-in-flight,
+  alias resolution, idle executor, and graceful vs immediate shutdown. **Every one of those tests uses a stub
+  loader.** No real loader is ever checked against that contract: `ArrayBufferLoader`, `GLTFAssetLoader`,
+  `JsonAssetLoader`, `TextAssetLoader`, `SVGAssetLoader`, `SoundAssetLoader`, `JavascriptAssetLoader`,
+  `FontAssetLoader`, `TextureAssetLoader`, `AttachmentSocketsAssetLoader`,
+  `AnimationGraphDefinitionAssetLoader` (only `ImageRGBADataLoader` has a spec).
+- **What could ship broken**: the contract AssetManager relies on is "call exactly one of `callback`/`failure`,
+  exactly once". `TextAssetLoader` passes `failure` straight through to `xhr`; `JsonAssetLoader` catches
+  `JSON.parse` errors and calls `failure`. Drop the `failure` argument in either — a one-token change — and a
+  404 or a truncated JSON file produces a request that **never settles**: the loading screen hangs at N% with
+  no error, forever. AssetManager's excellent hang-detection tests cannot see it because they never run a real
+  loader. `resolvePath` / rootPath-applied-once is likewise only asserted for the stub.
+- **Cheapest closing test**: one spec per loader with a mocked `xhr`/`fetch` asserting exactly one settlement
+  for each of success, HTTP error, and malformed payload. **11 files.**
+
+---
+
+### TG-11 Signal has nine hand-copied dispatch implementations; only `dispatch()` is behaviourally tested
+- **Severity**: MAJOR
+- **Area**: `core/events/signal/Signal.js` (818 lines) / `Signal.spec.js`
+- **Gap**: `dispatch`, `send0`, `send1`, `send2`, `send3`, `send4`, `send6`, `send8` (and the internal variant)
+  each **independently re-implement** the same three behaviours: the `SignalFlags.Silent` early-out (13
+  occurrences), the `generation` guard that skips handlers added during the current dispatch (9 occurrences),
+  and the `RemoveAfterExecution` removal that makes `addOne` fire once (10 occurrences).
+  `Signal.spec.js` tests once-semantics, mute/unmute, and the add-during-dispatch guard **exclusively through
+  `dispatch()`**. `send0`–`send8` are covered only for argument forwarding (`expect(call_param_list).toEqual([...])`).
+- **What could ship broken**: delete the `RemoveAfterExecution` branch from `send1` and every `addOne` handler
+  on a one-argument signal fires forever — that includes the engine tick path (`engine.ticker.onTick.send1(dt)`),
+  so a "run once next frame" callback becomes a permanent per-frame callback. Delete the `Silent` check from
+  `send2` and muting stops working for two-argument signals. Both are green.
+  Two further contracts are asserted nowhere at all, for any variant:
+  (a) **removal during dispatch** — each loop caches `const next = _h.next` *before* invoking the handler, so a
+  handler that removes the next entry of a same-function/different-context chain still causes it to be invoked;
+  (b) **error isolation** — every loop wraps the handler call in `try { … } catch (e) { console.error(…) }`.
+  "One throwing listener must not stop the remaining listeners" is load-bearing engine-wide (Signal is *the*
+  eventing primitive) and no test pins it, so removing or narrowing that catch would let a single bad listener
+  silently kill every downstream listener for that frame.
+- **Cheapest closing test**: one parameterised spec running the same five behavioural assertions across all
+  nine dispatch entry points. **1 file, 9 divergent code paths.**
+
+---
+
+### TG-12 Grid↔world conversion: only one direction is tested, and the round trip never is
+- **Severity**: MAJOR
+- **Area**: `engine/grid/**` (19 files, 4 specs)
+- **Gap**: `transform2grid/Transform2GridPositionSystem.spec.js` covers world→grid. The inverse —
+  `grid2transform/GridPosition2Transform.js` and `GridPosition2TransformSystem.js` — has no spec, and no test
+  anywhere composes the two. `area/AreaTrigger.js`, `TriggerAction.js` and `TriggerActionType.js` have none either.
+- **What could ship broken**: a half-cell offset, an axis swap, or a sign error in `GridPosition2TransformSystem`
+  places every unit's mesh away from the cell the simulation believes it occupies. The logical grid stays
+  perfectly self-consistent, so pathfinding, obstacle and combat tests all still pass — but click-selection,
+  move targets and range indicators all address the wrong tile. It is visible only on screen.
+  `AreaTrigger` is a `BitSet` mask plus a `size` and an action list: a trigger that fires every frame instead
+  of once on entry, or that misses the last row/column because of an off-by-one in the mask index, ships green.
+- **Cheapest closing test**: a `grid → world → grid` identity spec over a **non-square** grid with a non-zero
+  `offset` (1 file), plus an `AreaTrigger` enter/exit edge + mask-bounds spec (2 files).
+
+---
+
+### TG-13 `ObservedValue` and `ObservedEnum` have no spec while their narrower siblings do
+- **Severity**: MAJOR
+- **Area**: `core/model/`
+- **Gap**: `ObservedBoolean`, `ObservedInteger`, `ObservedString` and `BooleanVector3` all have specs.
+  The generic `ObservedValue.js` — used for `System.state`, plugin process state, and pervasively across
+  graphics and UI — plus `ObservedEnum.js` (e.g. `Light.type`) and `DebouncedObservedBoolean.js` have none.
+  They are separate classes, not subclasses, so the sibling specs give them no coverage.
+- **What could ship broken**: `ObservedValue.set` guards on `this.__value !== value` before
+  `onChanged.send2(value, oldValue)`. Remove the guard and every no-op write re-dispatches — systems that
+  react to state changes by relinking (the plugin state machine; `LightSystem` rebuilding a three.js light
+  when `Light.type` changes) start thrashing every frame, a pure-performance regression with no functional
+  symptom to trip a test. Drop `oldValue` from the dispatch and every two-argument observer silently receives
+  `undefined` for the previous value — the "changed from X to Y" branches all take the wrong path.
+  `setSilent`'s no-dispatch guarantee, and `process()`'s fire-immediately-then-on-change behaviour, are
+  likewise unasserted.
+- **Cheapest closing test**: one shared behavioural suite (equal-value set does not dispatch; set dispatches
+  `(new, old)`; `setSilent` does not dispatch; `process` fires immediately and on change; unsubscribe stops
+  delivery) run over all six observed types. **6 files.**
+
+---
+
+### TG-14 Sampler rectangle/blit operations behind the texture atlas and terrain overlay have no tests
+- **Severity**: MAJOR
+- **Area**: `engine/graphics/texture/sampler/`
+- **Gap**: Worth stating what is *not* wrong here first: the resize family is well covered and its specs
+  deliberately use asymmetric `3×1` and `1×3` inputs (`resize/sampler2d_scale.spec.js`,
+  `sampler2d_scale_down_linear.spec.js`), so width/height transpositions in the scaling path **would** be caught.
+  The rectangle-copy family has no spec at all: `sampler2d_sub_copy_same_item_size.js` (used by
+  `engine/graphics/texture/atlas/TextureAtlas.js` and `engine/graphics/material/optimization/MaterialOptimizationContext.js`),
+  `sampler2d_copy_channel_data.js` (same optimizer), `sampler2d_paint.js` (used by
+  `engine/ecs/terrain/overlay/TerrainOverlay.js`), `sampler2d_copy_rectangle.js`, and `sampler2d_combine.js`.
+- **What could ship broken**: an x/y or width/height transposition, or an off-by-one in the destination stride,
+  in `sampler2d_sub_copy_same_item_size` writes every atlas tile rotated, offset, or bleeding into its
+  neighbour. Every material that passes through atlas optimisation then renders with wrong texture content —
+  and the only thing that would notice is a human looking at the screen. The same class of defect in
+  `sampler2d_paint` corrupts terrain overlay brushes.
+- **Cheapest closing test**: one spec per op using a **non-square** source, a differently-shaped destination,
+  and an off-origin destination rectangle. **5 files.**
+
+---
+
+## Considered and deliberately not reported
+
+- **`engine/metrics` (0/6)** — `GlobalMetrics`/`ProxyMetricsGateway`/`GoogleAnalyticsMetrics`/`NullMetricsGateway`
+  are analytics plumbing. A break loses telemetry, not gameplay or data. Low blast radius; not worth a test.
+- **`core/debug` (2/23), `core/function` (2/15)** — matcher/description helpers and one-line combinators
+  (`noop`, `returnTrue`, `passThrough`). Trivial pure helpers, explicitly out of scope.
+- **Behaviour trees (`engine/intelligence/behavior`)** — looks thin by package count but is actually well
+  covered: `Behavior`, `SelectorBehavior`, `ParallelBehavior`, `SequenceBehavior`, `RepeatBehavior`,
+  `OverrideContextBehavior`, `ActionBehavior`, `BranchBehavior`, `ConditionBehavior`, `WeightedRandomBehavior`,
+  `DieBehavior`, `SendEventBehavior`, `BehaviorComponent` and `BehaviorSystem` all have specs. Status
+  propagation is genuinely exercised. Not a gap.
+- **`engine/animation` curve/clip layer** — 17 specs covering curves, keyframes, tracks, clip bindings,
+  fitting, subdivision, optimisation, compression and quaternion hemisphere alignment. Solid.
+- **`AssetManager` itself** — see TG-10; the manager is one of the best-tested things in the tree. The gap is
+  strictly the concrete loaders underneath it.
+- **`EntityManager` / `EntityComponentDataset` / `EntityObserver`** — 31, 55 and 9 tests respectively, covering
+  startup/shutdown states, dataset attach/detach, observer link/unlink, exception handling in update, fixed-step
+  catch-up capping, and dependency-less systems. Genuinely strong; the ECS *core* is not the gap — the systems
+  built on it are (TG-7, TG-8).