@woosh/meep-engine 3.0.2 → 3.2.0

package/src/REVIEW_2026_08_06/test-gaps.md

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