@woosh/meep-engine 2.168.0 → 2.169.0

package/src/REVIEW_2026_08_06/engine-ecs.md

@@ -0,0 +1,920 @@
+# Correctness review — `engine/ecs`
+
+Scope: every non-spec source file under `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/`
+(208 source files). Reviewed 2026-08-06.
+
+Findings marked **Confirmed** were either reproduced by executing the code or read directly
+off the source with an unambiguous trace. `assert.*` is treated as absent (stripped in prod).
+
+---
+
+## Core (Entity / EntityComponentDataset / EntityManager / System)
+
+### ECS-1 `Entity.readFromDataset` never watches destruction, so a stale `Built` flag corrupts recycled entity ids
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/Entity.js:508-525`
+- **Defect**: `build()` registers `#handleEntityDestroyed` on `EventType.EntityRemoved` when the
+  `WatchDestruction` flag is set (line 487-489), which is on by default. `readFromDataset` sets
+  `EntityFlags.Built` and binds the reference but registers no such listener, so the returned
+  `Entity` keeps reporting `isBuilt === true` forever after the underlying entity is removed.
+  Since `EntityComponentDataset.createEntity` recycles ids (`entityOccupancy.nextClearBit(0)`),
+  every subsequent operation on that `Entity` lands on a *different* entity.
+- **Failure scenario** (reproduced):
+  ```js
+  const ds = new EntityComponentDataset();
+  ds.setComponentTypeMap([A, B]);
+  const id = ds.createEntity();          // id = 0
+  ds.addComponentToEntity(id, new A());
+  const e = Entity.readFromDataset(id, ds);
+  ds.removeEntity(id);
+  const recycled = ds.createEntity();    // id = 0 again, generation 1
+  e.isBuilt        // => true   (should be false)
+  e.add(new B());  // => writes B onto `recycled`, an unrelated entity
+  e.destroy();     // => destroys `recycled`
+  ```
+  Output observed: `recycled entity now has B: true`, `after e.destroy(), recycled entity exists: false`.
+  The `EntityReference` already carries the generation needed to detect this (`e.generation === 0`
+  vs `ds.getEntityGeneration(recycled) === 1`) but nothing consults it.
+- **Fix**: in `readFromDataset`, mirror `build()` — after setting the `Built` flag, do
+  `if (r.getFlag(EntityFlags.WatchDestruction)) dataset.addEntityEventListener(entity, EventType.EntityRemoved, r.#handleEntityDestroyed, r);`
+  (needs a small private accessor since `#handleEntityDestroyed` is instance-private).
+- **Confidence**: Confirmed
+
+### ECS-2 `setComponentTypeMap` leaves the dataset permanently corrupted when observer rebuild throws
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/EntityComponentDataset.js:674-731`
+- **Defect**: `setComponentTypeMap` mutates state in four steps — `updateComponentOccupancy` (716),
+  `updateComponentStores` (718), `updateObservers` (720), then `componentTypeMap` / `componentTypeCount`
+  (722, 730). `updateObservers` calls `observer.build(map)` for every observer sitting in a *surviving*
+  component's store; `EntityObserver.build` **throws** if any of that observer's component types is
+  absent from the new map (`EntityObserver.js:102-104`). Because occupancy and the component stores
+  have already been re-strided at that point, the throw leaves the dataset with the new stride but the
+  old `componentTypeMap` / `componentTypeCount` / `__type_to_index_map`.
+- **Failure scenario** (reproduced):
+  ```js
+  ds.setComponentTypeMap([A, B]);
+  ds.addObserver(new EntityObserver([A, B], onComplete, onBroken), false);
+  ds.unregisterComponentType(A);   // A has no live instances, so the removal check passes
+  ```
+  Observed: throws `Component type[0] was not found in the supplied map`, then
+  `componentTypeMap = ['A','B']`, `componentTypeCount = 2`, but `components.length = 1`.
+  The next `ds.addComponentToEntity(e, new B())` throws
+  `TypeError: Cannot read properties of undefined (reading '0')` — `components[1]` no longer exists.
+  The dataset cannot be used again.
+- **Fix**: validate first, mutate second. Before touching occupancy/stores, iterate every registered
+  observer and check `map` contains all of `observer.componentTypes`; throw there (dataset untouched).
+  Observers that watch only removed types should be disconnected explicitly (`observer.dataset = null`)
+  rather than silently dropped from the stores.
+- **Confidence**: Confirmed
+
+### ECS-3 `traverseEntitiesCompactedFiltered` uses `-1` as a component index for unregistered classes
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/EntityComponentDataset.js:1990-2020`
+- **Defect**: `componentIndices[i] = this.computeComponentTypeIndex(klass)` stores `-1` for a class
+  that is not registered in this dataset, and nothing filters it out. The loop then does
+  `componentOccupancy.get(entityOccupancyAddress + (-1))` — reading the *last* component bit of the
+  *previous* entity — and, when that bit happens to be set, `this.components[-1][i]`.
+  `this.components[-1]` is `undefined`. (In production `BitSet.get`'s `assert.isNonNegativeInteger`
+  is stripped, so it silently returns the neighbouring entity's bit instead of throwing.)
+- **Failure scenario** (reproduced): dataset registered with `[A, B]`; entity 0 has both A and B;
+  entity 1 has A. `ds.traverseEntitiesCompactedFiltered([C, A], visitor)` where `C` was never
+  registered. With asserts on it throws `bitIndex must be >= 0, instead was -1`. With asserts stripped,
+  entity 1 reads bit `2 - 1 = 1` (entity 0's B bit, which is set) and then dereferences
+  `this.components[-1][1]` → `TypeError: Cannot read properties of undefined`.
+- **Fix**: skip unregistered classes when building `componentIndices` (build a compacted array of
+  valid indices only), the same way `traverseEntities` returns early on `-1`.
+- **Confidence**: Confirmed
+
+### ECS-4 Bare `.sort()` on component indices is lexicographic
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/EntityComponentDataset.js:1996`
+- **Defect**: `componentIndices.sort()` with no comparator sorts numbers as strings. The comment
+  says "sort component indices array for faster traversal"; with 10 or more registered component
+  types the array is not sorted at all, and the `components` array handed to the visitor comes out
+  in a scrambled, size-dependent order.
+- **Failure scenario** (reproduced): 12 registered component types; an entity holds instances of
+  type index 2 and type index 10. The visitor receives `[K10, K2]` instead of `[K2, K10]`. Any
+  consumer of this "main utility … to facilitate serialization" method that depends on a stable
+  component ordering (e.g. a byte-for-byte save comparison or a diff) sees the order flip as soon
+  as the dataset crosses 10 component types.
+- **Fix**: `componentIndices.sort((a, b) => a - b);`
+- **Confidence**: Confirmed
+
+### ECS-5 `Entity.getComponentSafe` throws `ReferenceError` — its helper is neither imported nor exported
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/Entity.js:256`
+- **Defect**: The error path calls `computeComponentClassName(klass)`, but `Entity.js` imports only
+  `assert`, `Signal`, `EntityFlags`, `EntityReference`, `EventType`. Worse,
+  `computeComponentClassName.js` declares the function without any `export` statement at all, so
+  there is nothing to import.
+- **Failure scenario** (reproduced): `new Entity().getComponentSafe(SomeClass)` throws
+  `ReferenceError: computeComponentClassName is not defined` instead of the documented
+  `Error: Component of given class 'SomeClass' not found`. The diagnostic naming the missing
+  component — the entire point of the method over `getComponent` — is lost.
+- **Fix**: add `export` to `computeComponentClassName.js` and import it in `Entity.js`.
+- **Confidence**: Confirmed
+
+### ECS-6 Re-`build()`ing an `Entity` whose components drifted orphans the old entity and mis-aims its destruction watcher
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/Entity.js:442-493`
+- **Defect**: `build()` returns early only when `checkExistingComponents` passes. Otherwise it falls
+  through and calls `dataset.createEntity()` **without** removing the entity it was previously bound
+  to and without unregistering the `EntityRemoved` listener registered on the old id at line 488.
+- **Failure scenario** (reproduced):
+  ```js
+  const e = new Entity(); e.add(new A());
+  const id1 = e.build(ds);              // 0
+  ds.removeComponentFromEntity(id1, A); // a system strips the component directly
+  const id2 = e.build(ds);              // 1  -- entity 0 is now orphaned, entityCount = 2
+  ds.removeEntity(id1);                 // fires the stale watcher
+  e.isBuilt                             // => false, although entity 1 is alive
+  e.destroy()                           // => false; entity 1 leaks permanently
+  ```
+- **Fix**: when the early-return check fails but `EntityFlags.Built` is set, call `this.destroy()`
+  first so the previous entity and its listener are released before rebinding.
+- **Confidence**: Confirmed
+
+### ECS-7 `EntityManager.removeSystem` never clears `system.entityManager`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/EntityManager.js:590-631`
+- **Defect**: `startSystem` refuses to start a system whose `entityManager` is set to a different
+  manager (`EntityManager.js:739-741`). Neither `removeSystem` nor `stopSystem` resets the field.
+- **Failure scenario**: `em1.removeSystem(s)` then `em2.addSystem(s); em2.startup()` →
+  `startSystem` throws `System is bound to another EntityManager`, caught at line 763, so
+  `errorCallback` fires and `em2.state` becomes `EntityManagerState.Failed`; the whole manager
+  never reaches `Running`. Reusing a system instance across manager instances (level reload, test
+  fixtures) is impossible.
+- **Fix**: set `system.entityManager = null` in `removeSystem` after `stopSystem` resolves.
+- **Confidence**: Confirmed
+
+### ECS-8 `system_validate_class` duplicate-component backtrace is off by one
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/system_validate_class.js:49`
+- **Defect**: `for (let j = 0; j < i - 1; j++)` never compares `components_used[i]` against
+  `components_used[i - 1]`, so adjacent duplicate resource specifications slip through.
+- **Failure scenario**: `components_used = [Spec(Transform, Read), Spec(Transform, Write)]` passes
+  validation. `System.getAccessForComponent` (`System.js:110-117`) `break`s at the first match, so
+  the `Write` access is silently discarded, and `EntityManager.updateExecutionOrder`'s `scoreSystem`
+  scores the system as a reader (`attached_edge_count` instead of `× 2`) — the system is scheduled
+  after the systems that should run after it.
+- **Fix**: `for (let j = 0; j < i; j++)`.
+- **Confidence**: Confirmed
+
+### ECS-48 `EntityManager.startup` reports `Running` while a system added during startup is still `STARTING`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/EntityManager.js:795,814,567-574`
+- **Defect**: `startup()` captures `expectedReadyCount = systems.length` before the start loop, then
+  `finalizeStartup()` fires when `readyCount === expectedReadyCount`. A system's own `startup()` may
+  call `entityManager.addSystem(...)`, which pushes onto the same `systems` array the `for…of` loop is
+  walking, so the loop does start the newcomer — but the target count is stale by one. Separately,
+  `addSystem` only auto-starts when `this.state === EntityManagerState.Running`; during
+  `EntityManagerState.Starting` it returns `Promise.resolve()` and never calls `startSystem`, so a
+  system added after the loop has drained is never started at all.
+- **Failure scenario**: `SGMeshSystem.startup(em)` does
+  `if (!em.hasSystem(TransformAttachmentSystem)) await em.addSystem(new TransformAttachmentSystem());`
+  (`engine/graphics/ecs/mesh-v2/aggregate/SGMeshSystem.js:94-96`). With N systems registered,
+  `expectedReadyCount = N`; once the original N have reported ready, `finalizeStartup()` sets
+  `state = Running` and invokes `readyCallback()` while `TransformAttachmentSystem` is still in
+  `STARTING`. The caller begins `simulate()`; `updateExecutionOrder` skips non-`RUNNING` systems and its
+  observer has not been added to the dataset, so attachments silently do not update for those frames.
+  If the same `addSystem` were made from after an `await` (once the start loop has drained) the system
+  would never start at all, while its promise still resolves.
+- **Fix**: read `systems.length` live at each `systemReady` (`readyCount === systems.length`) instead of
+  a captured count, and treat `EntityManagerState.Starting` like `Running` in `addSystem`'s auto-start
+  branch.
+- **Confidence**: Confirmed
+
+---
+
+## Fog of war
+
+### ECS-9 `FogOfWarSystem.shutdown` removes none of the three render-loop subscriptions it made in `startup`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/fow/FogOfWarSystem.js:162-219`
+- **Defect**: `startup` registers three anonymous closures on `graphics.on.preRender`,
+  `graphics.on.buffersRendered` and `graphics.on.postRender`. `shutdown` only calls
+  `this.graphics.layerComposer.remove(this.compositLayer)`. Because the handlers are inline
+  functions with no retained reference, they can never be removed even by a caller.
+- **Failure scenario**: `entityManager.shutdown()` (or `removeSystem(fogOfWarSystem)`) removes the
+  composit layer, but on the very next frame the `preRender` handler still runs
+  `compositerLayer.enable()` on the removed layer and `depthFrameBuffer.referenceCount++`, and
+  `buffersRendered` still runs `fogOfWarRenderer.render(renderer, camera, scene, compositerLayer.renderTarget)`
+  into a render target that is no longer composited — burning a full-screen pass every frame for the
+  lifetime of the `GraphicsEngine`. The closures also pin `entityManager`, `graphics` and the
+  `FogOfWarRenderer` (its `ShaderMaterial`, `Mesh` and `Scene` are never disposed). Starting a second
+  `FogOfWarSystem` — e.g. a level reload on a shared `GraphicsEngine` — stacks a second set of handlers,
+  so each frame renders the fog twice.
+- **Fix**: hoist the three handlers into named fields (or wrap them in `SignalBinding`s) in `startup`,
+  `remove` them in `shutdown`, and dispose `fogOfWarRenderer.material` / `fogOfWarRenderer.quad`.
+- **Confidence**: Confirmed
+
+### ECS-10 A revealer on the *wrong* team still reveals fog whenever its radius changes
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/fow/FogOfWarRevealerSystem.js:52-97`
+- **Defect**: The team check lives only in `attemptToWatch`, which gates the *position* watcher.
+  `update()` itself contains no team test, and `radiusWatcher` (line 93-97) is linked
+  unconditionally for every linked entity regardless of team.
+- **Failure scenario**: `new FogOfWarRevealerSystem(/* team */ 1)`. An enemy unit with
+  `Team = 2`, `Transform`, `FogOfWarRevealer` links: `attemptToWatch(2)` correctly leaves
+  `positionWatcher` unlinked, but `radiusWatcher.link()` runs anyway. The enemy then receives a
+  vision buff (`revealer.radius.set(8)`) — `revealer.radius.onChanged` fires `update()`, which maps
+  the *enemy's* position to the grid and calls `fow.reveal(...)` on the player's fog. The player's
+  map is permanently uncovered at the enemy's location.
+- **Fix**: put the team check inside `update()` (`if (team.getValue() !== visibilityTeam) return;`),
+  or link/unlink `radiusWatcher` from `attemptToWatch` alongside `positionWatcher`.
+- **Confidence**: Confirmed
+
+### ECS-11 `computeRevealedGridBoundingRectangle` returns an inverted AABB when nothing is revealed
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/fow/FogOfWar.js:532-563`
+- **Defect**: `x0`/`y0` seed to `width - 1` / `height - 1` and `x1`/`y1` to `0`. If no cell differs
+  from 255 the loop body never runs and those seeds are written out unchanged, producing
+  `x0 > x1` and `y0 > y1`.
+- **Failure scenario**: a freshly resized 64×64 fog (sampler 66×66, all 255) →
+  `result.set(65, 65, 0, 0)`. `MinimapFogOfWar.updateFocusArea`
+  (`view/minimap/gl/MinimapFogOfWar.js:87`) then does `bounds.grow(2)`, `bounds.move(-0.5, 0.5)`
+  and multiplies by the scale, feeding a negative-extent rectangle into `enforceAspectRatio` — the
+  minimap focus area is garbage on the first frame of any map before the first reveal.
+- **Fix**: track a `found` flag and, when nothing is revealed, emit an explicitly empty rectangle
+  (`result.set(0, 0, 0, 0)`) or leave `result` untouched and return a boolean.
+- **Confidence**: Confirmed
+
+### ECS-12 `getWorldClearance` reads the distance sampler unclamped
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/fow/FogOfWar.js:677-684`
+- **Defect**: Its sibling `computeAABBVisibility` clamps the sample position before
+  `distanceSampler.readChannel` (line 628-629); `getWorldClearance` does not.
+  `Sampler2D.readChannel` computes `(y * width + x) * itemSize + channel` with no bounds check
+  (the `assert`s are stripped), so an x outside `[0, width)` silently indexes into an adjacent row.
+- **Failure scenario**: `FogOfWarVisibilityPredicate.test(x, y, z)` (line 41) is called with an
+  object's world position. For a 64×64 fog with `scale = 1`, an object one cell east of the map at
+  grid row 20 produces `sampleX = 65`, `sampleY = 21`, giving index `21 * 66 + 65 = 1451` — which is
+  cell `(1, 22)`, the *west* border of the row below. The object's visibility is decided by an
+  unrelated cell; where that cell is revealed, an off-map object that should be hidden renders.
+- **Fix**: clamp exactly as `computeAABBVisibility` does, using the sampler's own dimensions.
+- **Confidence**: Confirmed
+
+### ECS-13 `computeAABBVisibility` clamps to `size - 1` but the distance sampler is `size + 2` wide
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/fow/FogOfWar.js:628-629`
+- **Defect**: `worldToSamplePosition` emits sampler-space coordinates with the +1 border offset
+  baked in, so the real world area occupies sampler columns `[1, size.x]`. The clamp bound is
+  `this.size.x - 1`, two cells short of the valid maximum.
+- **Failure scenario**: 64×64 fog, `scale = 1`. `worldToSamplePosition` maps the world extent onto
+  sample coordinates `[1, 64]`, but the clamp caps at `63`. An object at the far eastern edge maps to
+  `sampleX = 64` and is read at column `63` instead — the outermost column/row of the map takes its
+  clearance from the cell one step inward. An unexplored strip along the east/south map edge therefore
+  reports the clearance of the explored cell beside it, and objects standing there are drawn through
+  the fog.
+- **Fix**: clamp against the sampler, not the logical size: `clamp(sampleX, 0, this.sampler.width - 1)`.
+- **Confidence**: Confirmed
+
+---
+
+## Terrain
+
+### ECS-14 `getTileByWorldPosition2D` reads the vertical axis as the grid row
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/tiles/TerrainTileManager.js:461-472`
+- **Defect**: The point is packed as `Float32Array.of(x, 0, y)` — so the top-down Y lands at index
+  **2** — inverse-transformed, and then passed as `getRawTileByPosition(v3[0], v3[1])`. `v3[1]` is
+  the vertical component. Separately, `getRawTileByPosition` divides by `tileSize`, which is in grid
+  units, while `v3` is in object units, so `this.scale` must be divided out first.
+- **Failure scenario**: 64×64 terrain, `gridScale = 1`, tile size 32 → a 2×2 tile grid, identity
+  transform. `getTileByWorldPosition2D(40, 40)` → `getRawTileByPosition(40, 0)` →
+  `tileX = 1, tileY = floor(0 / 32) = 0` → tile **(1,0)** instead of **(1,1)**. With an identity
+  transform the row is *always* 0, so every lookup collapses onto the top row of tiles.
+  `obtainTileAtWorldPosition2D` then builds the wrong tile.
+- **Fix**: `return this.getRawTileByPosition(v3[0] / this.scale.x, v3[2] / this.scale.y);`
+- **Confidence**: Confirmed
+
+### ECS-15 `traverseVisibleTiles` sums per-frustum hit counts but always writes at offset 0
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/ecs/TerrainSystem.js:265-290`
+- **Defect**: `tile_count` is initialised to 0 and passed as the `result_offset` to
+  `bvh_query_user_data_intersects_frustum` on every iteration but never advanced, so each frustum
+  overwrites the previous frustum's results from index 0. `found_tiles` meanwhile accumulates the
+  per-frustum counts, and the consumer loop iterates to that sum.
+- **Failure scenario**: two active `Camera` components (`CameraSystem.getActiveFrustums` yields one
+  frustum per active camera). Frustum A returns 6 tiles, frustum B returns 4 → `tiles` holds 6
+  entries but `found_tiles = 10`. Indices 6..9 are `undefined` →
+  `tileManager.tiles[undefined] === undefined` → the callback dereferences `tile.isBuilt` /
+  `tile.gridPosition` → `TypeError` out of `TerrainSystem.update` every frame.
+- **Fix**: `tile_count += bvh_query_user_data_intersects_frustum(tiles, tile_count, ...)` and iterate
+  to `tile_count`.
+- **Confidence**: Confirmed
+
+### ECS-16 `TerrainOverlay.paintSampler` passes the overlay instead of its sampler
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/overlay/TerrainOverlay.js:321`
+- **Defect**: `sampler2d_paint(this, scaled_source, ...)` supplies the `TerrainOverlay` as the
+  destination `Sampler2D`. The pixel data lives on `this.sampler`.
+- **Failure scenario**: `sampler2d_paint` computes
+  `_w = Math.min(width, source.width - 0, undefined - dx)` → `NaN`, so `for (x = 0; x < NaN; ...)`
+  never executes. Nothing is written and no error is raised — `paintImage`/`paintSampler` are silent
+  no-ops, while `texture.needsUpdate = true` re-uploads unchanged pixels every call.
+- **Fix**: `sampler2d_paint(this.sampler, scaled_source, 0, 0, dx, dy, dWidth, dHeight);`
+- **Confidence**: Confirmed
+
+### ECS-17 Tile rebuild leaks the previous `BufferGeometry`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/tiles/TerrainTile.js:551,586`
+- **Defect**: `build()` assigns `this.geometry = g` / `mesh.geometry = g` without disposing the
+  geometry it replaces. The only disposal path, `dispose()`, early-returns on `if (!this.isBuilt) return;`
+  — and `TerrainTileManager.rebuildTilesByUV` (`tiles/TerrainTileManager.js:300`) clears `isBuilt`
+  while the geometry is still attached, so the old geometry can never be released.
+- **Failure scenario**: terrain height editing calls `rebuildTilesByUV`, clearing `isBuilt` on every
+  overlapping tile; `TerrainSystem.update` then re-invokes `tile.build(tileData)`, installing a fresh
+  geometry and orphaning the old VBO/IBO. For a 4-tile region at `resolution = 4` with 32×32 tiles
+  (16 384 verts, ~590 KB of attributes each) that is ~2.4 MB of VRAM per edit, never reclaimed.
+  `destroyTiles()` hits the same early return.
+- **Fix**: dispose the previous geometry at the top of `build()`, and replace the `!isBuilt` early
+  return in `dispose()` with a `geometry !== null` check.
+- **Confidence**: Confirmed
+
+### ECS-18 `TerrainTile.stitching` flags are never reset, so re-stitched seams copy instead of average
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/tiles/TerrainTile.js:99-110` (consumed at `:279`, `:333`)
+- **Defect**: Neither `build()`, `dispose()`, nor `TerrainTileManager.rebuildTilesByUV` clears the
+  per-neighbour `stitching` state. `stitchHorizontal`/`stitchVertical` branch on those flags: when one
+  side is already marked stitched, the other side's normals are *copied* wholesale rather than averaged.
+- **Failure scenario**: tiles A(0,0) and B(1,0) built and stitched, so `A.stitching.right === true`.
+  A height edit clears `isBuilt` on both but leaves the flags. A rebuilds first — `stitchTile` sees B
+  unbuilt and skips. B rebuilds — `stitchHorizontal(A, B)` finds the stale
+  `left.stitching.right === true` and takes the copy branch, writing A's one-sided edge normals into B.
+  The shared edge now carries normals computed from A's triangles only: a visible lighting crease down
+  every rebuilt tile boundary after any terrain edit.
+- **Fix**: reset all eight `stitching` fields in `TerrainTile.build()` and `dispose()`, and clear the
+  neighbours' matching flags in `rebuildTilesByUV`.
+- **Confidence**: Confirmed
+
+### ECS-19 `ClingToTerrain.fromJSON` defaults `rotationSpeed` to `Infinity`; the field initialiser is `3`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/ecs/cling/ClingToTerrain.js:54`
+- **Defect**: The class field is `rotationSpeed = 3`, and `ClingToTerrainSerializationUpgrader_0_1.js:22`
+  explicitly writes `3`, calling it "the default value from the ClingToTerrain class". `fromJSON`
+  destructures with `Number.POSITIVE_INFINITY` as the default.
+- **Failure scenario**: a blueprint carrying `{"ClingToTerrain": {"normalAlign": true}}` with no
+  `rotationSpeed` → `rotationSpeed = Infinity`. In `ClingToTerrainSystem.processRaycastHit:272`
+  `Number.isFinite` is false → `angularLimit = Infinity` → `alignToVector` computes
+  `t = clamp01(Infinity / angle) = 1` → the entity snaps to the terrain normal instantly every frame
+  instead of easing at 3 rad/s. The same entity constructed in code, or loaded from binary v0 through
+  the upgrader, eases correctly — the behaviour differs by load path.
+- **Fix**: use `3` as the `fromJSON` destructuring default.
+- **Confidence**: Confirmed
+
+### ECS-20 `Terrain` JSON and binary paths persist disjoint field sets, and disagree on a default
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/ecs/Terrain.js:930,981`;
+  `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/serialization/TerrainSerializationAdapter.js:29,144`
+- **Defect**: Three fields are handled by exactly one of the two paths.
+  `gridTransformKind` and `lightMapURL` are written into `extra` by `serialize`/`deserialize` but are
+  absent from `toJSON`/`fromJSON`. `overlay.baseTileImage` is written by `toJSON` (as
+  `overlayTileImage`) and restored by `fromJSON`, but is absent from the binary adapter. The two paths
+  also disagree on the `gridTransformKind` default: `deserialize` falls back to
+  `GridTransformKind.Legacy` (`:144`) while the class field initialiser is `GridTransformKind.Direct`
+  (`Terrain.js:76`), which `fromJSON` leaves in place.
+- **Failure scenario**: a terrain with `gridTransformKind = Legacy`, `size = (64,64)`, `gridScale = 1`,
+  saved via `toJSON` and reloaded. `fromJSON` leaves it at `Direct`, so `buildGridTransform` produces
+  `scale = 1, offset = 0.5` instead of `scale = 64/63 ≈ 1.0159, offset = 0`. `mapPointGrid2World(63, 63)`
+  returns `(63.5, ·, 63.5)` instead of `(64, ·, 64)` — every grid-anchored entity, marker and combat
+  cell is displaced, growing to more than half a cell at the far edge. The same round-trip drops
+  `lightMapURL`, so `build()` skips the `aoMap` load and the terrain renders unshadowed. Symmetrically,
+  a custom `overlay.baseTileImage` saved to binary reloads as the default `WHITE_PIXEL_DATA_URL`.
+- **Fix**: add `gridTransformKind` and `lightMapURL` to `toJSON`/`fromJSON` (with the same default the
+  binary path uses), and write `overlay.baseTileImage` into the binary adapter's `extra` blob.
+- **Confidence**: Confirmed
+
+### ECS-21 `convertHeightMap2NormalMap` returns normals tilted uphill — both gradients unnegated
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/grid/HeightSampler2NormalSamplerSoft.js:54-56`
+- **Defect**: For a height field `h(x, y)` the surface normal is `normalize(-∂h/∂x, -∂h/∂y, k)`. The
+  Sobel gradients `dX`/`dY` are computed with the correct sign but written out unnegated
+  (`_x = dX / magnitude`, `_y = dY / magnitude`).
+- **Failure scenario**: a ramp `h(x, y) = x`. At an interior texel `dX = 8`, `dY = 0`,
+  `magnitude = sqrt(64.25) ≈ 8.0156` → the function returns `(+0.998, 0, +0.0624)`. The true normal for
+  a surface rising in `+x` leans toward `−x`: `(−0.998, 0, +0.0624)`. Every slope gets a normal pointing
+  up-slope, so any lighting or slope test built on this map is exactly reversed on both horizontal
+  axes. Flat regions are unaffected, which is why it is not obvious.
+- **Fix**: `const _x = -dX / magnitude; const _y = -dY / magnitude;`
+- **Confidence**: Likely (no in-repo consumer — public library surface; the maths is unambiguous)
+
+### ECS-22 `Terrain.heightTexture` receives the `Sampler2D` object as its `height` argument
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/ecs/Terrain.js:145`
+- **Defect**: `new DataTexture(this.samplerHeight.data, this.samplerHeight.width, this.samplerHeight, RedFormat, FloatType)`
+  — the third parameter of `DataTexture(data, width, height, …)` gets the sampler instance rather than
+  `this.samplerHeight.height`. Compare `graphics/ecs/water/Water.js:138`.
+- **Failure scenario**: immediately after `new Terrain()`, `terrain.heightTexture.image` is
+  `{data: Float32Array(1), width: 1, height: <Sampler2D>}`. Any consumer that binds `heightTexture`
+  before `build()` runs `updateHeightTexture()` (which repairs `image.width`/`image.height` at
+  `:721-722`) uploads with a non-numeric height — `gl.texImage2D` raises `GL_INVALID_VALUE`.
+- **Fix**: pass `this.samplerHeight.height`.
+- **Confidence**: Confirmed
+
+### ECS-23 `heightMap2AOMap` leaks the intermediate denoise source texture
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/grid/HeightMap2AOMap.js:77`
+- **Defect**: `filter_result_to_texture(raw_ao.array, width, height)` creates a `DataTexture` that is
+  uploaded by the denoise `ImageFilter` pass and then dropped without `.dispose()`. The sibling
+  `pyramid_texture` *is* disposed at `:91`, so the omission is unintentional.
+- **Failure scenario**: `terrain.buildLightMap()` runs per generated map. For a 256×256 terrain at the
+  default `quality = 4` the AO resolution is 1024×1024, so each bake orphans a 1024×1024 RGBA8 GPU
+  texture (~4 MB VRAM) for the lifetime of the WebGL context. Each new run accumulates another.
+- **Fix**: hold the texture in a local and `.dispose()` it after the `smooth_ao` `ImageFilter` returns.
+- **Confidence**: Confirmed
+
+### ECS-24 `loadVisibleTerrainTiles` does not reset its counters on retry, and can report success early
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/util/loadVisibleTerrainTiles.js:70-84`
+- **Defect**: `handleFailedTile` bumps `attempt` and re-runs `init()`, which recomputes `totalTiles` and
+  restarts `start_time`, but `loadedTiles` and `failedTiles` carry over from the aborted attempt. The
+  `attemptId !== attempt` guard only suppresses *stale* callbacks; it does not roll back what they
+  already counted.
+- **Failure scenario**: 20 visible tiles; 12 resolve, then one rejects
+  (`'Original tile was destroyed during build process'`). `init()` re-runs with `totalTiles = 20` and
+  `loadedTiles = 12`. The 12 already-built tiles resolve on the next microtask → `loadedTiles = 24 ≥ 20`
+  → `cycleFunction` returns `TaskSignal.EndSuccess` while 8 tiles are still mid-build. The loading
+  screen closes and the scene shows 8 tiles with no geometry.
+- **Fix**: reset `loadedTiles = 0` and `failedTiles = 0` at the top of `init()`.
+- **Confidence**: Confirmed
+
+### ECS-25 `TerrainSystem.mapPointGrid2World` hardcodes the Legacy transform and drops the offset
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/terrain/ecs/TerrainSystem.js:81-87,186-187`
+- **Defect**: `link()` computes `gridScaleX = g_w * gridScale / (g_w - 1)` unconditionally — the
+  `GridTransformKind.Legacy` formula — ignoring `component.gridTransformKind`, and
+  `mapPointGrid2World` applies no offset. `Terrain.mapPointGrid2World` (`Terrain.js:555`) uses
+  `gridTransform`, whose `Direct` branch (the class default) is `scale = gridScale, offset = gridScale / 2`.
+- **Failure scenario**: 64×64 terrain, `gridScale = 1`, default `Direct` kind.
+  `terrain.mapPointGrid2World(0, 0, v3)` → `(0.5, ·, 0.5)`; `terrainSystem.mapPointGrid2World(0, 0, v3)`
+  → `(0, ·, 0)`. At `x = 63`: `63.5` vs `64.0`. Two public methods documented to perform the same
+  mapping differ by half a cell at the origin and diverge with distance. `gridScaleX/Y` are also
+  system-global, so with two `Terrain` entities they hold whichever linked last.
+- **Fix**: delete `TerrainSystem.mapPointGrid2World`/`gridScaleX`/`gridScaleY` and route callers to
+  `Terrain.mapPointGrid2World`, or read `terrain.gridTransform` directly.
+- **Confidence**: Confirmed
+
+---
+
+## Animation / dynamic actions / evaluation
+
+### ECS-26 `AnimationOptimizer` writes its results to itself — optimization is a silent no-op
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/animation/AnimationOptimizer.js:109-114`
+- **Defect**: `optimizeTrack(track)` is a port of three.js `KeyframeTrack.prototype.optimize()`, where
+  `this` *is* the track. Here `this` is the `AnimationOptimizer`, so the compacted arrays are assigned
+  to `this.times` / `this.values` on the optimizer; the `track` (whose arrays were only *copied* at
+  lines 108-109) is never modified, and the method returns `this`.
+- **Failure scenario**: `GLTFAssetLoader.js:426` calls `animationOptimizer.optimize(animation)` on
+  every animation of every loaded GLTF, using the module-level singleton. Load a GLTF whose track has
+  1000 keyframes of which 900 are redundant: the track still has 1000 keyframes afterwards. The
+  singleton also permanently retains `this.times`/`this.values` — full copies of the last-optimized
+  track's typed arrays, megabytes for a skeletal clip — for the module's lifetime.
+- **Fix**: write back to the track (`track.times = ...; track.values = ...;`) and return `track`.
+- **Confidence**: Confirmed
+
+### ECS-27 `AnimationOptimizer`: `time[0]` should be `times[0]`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/animation/AnimationOptimizer.js:36`
+- **Defect**: `if (time !== timeNext && (i !== 1 || time !== time[0]))` — `time` is a number, so
+  `time[0]` is `undefined` and the sub-condition is always true. three.js has `times[0]`.
+- **Failure scenario**: a track with `times = [0, 0, 1, 2]` and distinct values at index 1. three.js
+  drops keyframe 1 as a duplicate of the keyframe at t=0; this code keeps it, leaving two keyframes
+  scheduled at t=0 in the "optimized" output.
+- **Fix**: `time !== times[0]`.
+- **Confidence**: Confirmed
+
+### ECS-28 `DynamicRuleDescription.equals` calls `.equals` on a primitive string
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/dynamic_actions/rules/DynamicRuleDescription.js:55`
+- **Defect**: `id` is a primitive string (`UUID.string()` returns `UUID.v4().toString()`, and
+  `fromJSON` assigns the JSON string directly), but `equals` does `return this.id.equals(other.id)`.
+  `String.prototype.equals` does not exist.
+- **Failure scenario**:
+  `DynamicRuleDescription.fromJSON({id:"combat.long-idle.ai", ...}).equals(otherRule)` →
+  `TypeError: this.id.equals is not a function`. Any container relying on the `equals` protocol
+  (a default-configured `HashMap`/`HashSet` keyed by rules) throws on the first lookup.
+  `DynamicActorSystem` only escapes because `__global_last_used_times` supplies a custom
+  `keyEqualityFunction`.
+- **Fix**: `return this.id === other.id;`
+- **Confidence**: Confirmed
+
+### ECS-29 Pooled `DynamicActorSystem` context keeps the previous entity's `RuleExecution`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/dynamic_actions/DynamicActorSystem.js:43,74-90`
+- **Defect**: `Context` instances are pooled by `AbstractContextSystem`, and the pool's reset callback
+  is an empty `// TODO` (`system/AbstractContextSystem.js:37-42`). `Context.link()` resets
+  `next_idle_event_time` but never resets `execution`, so a recycled context arrives carrying the
+  previous entity's `execution.rule` and `execution.executor`. `Context.unlink()` also never terminates
+  the still-running executor.
+- **Failure scenario**: unit A executes a `SpeakLine` rule, whose executor tree is
+  `ParallelBehavior([WaitForEventBehavior(FinishedSpeakingLine on A), SendEventBehavior])`. A is killed
+  and removed; `removeEntity` deletes A's event listeners, so `FinishedSpeakingLine` can never arrive,
+  the parallel never completes, `DieBehavior` never runs, and the executor `Entity` keeps
+  `EntityFlags.Built` forever. A's context is released to the pool still pointing at that immortal
+  executor. Unit B spawns and pops the same context. On B's first event, `attemptRuleExecution`
+  (lines 193-199) sees `execution.executor.getFlag(Built) === true` and tests
+  `rule.priority <= execution.rule.priority`. Every rule in
+  `app/data/database/dynamic-actions/data.json` uses the default `priority = 0`, so `0 <= 0` →
+  `return false`: **B never executes any rule for the rest of the session.** If a higher-priority rule
+  ever does get through, `terminateActiveExecution` destroys entity A's executor from B's context.
+- **Fix**: reset execution state at the context boundary — in `Context.link()` set
+  `this.execution.rule = null; this.execution.executor = null;`, and in `Context.unlink()` destroy a
+  still-built executor before clearing.
+- **Confidence**: Confirmed
+
+### ECS-30 `match()` hands actions a live view of a shared scope stack that it unwinds before the action runs
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/dynamic_actions/DynamicActorSystem.js:536-551`;
+  `.../actions/definition/WriteToBlackboardActionDescription.js:24-35`
+- **Defect**: `match()` passes `this.scope.proxy` — a proxy over the system-wide, mutable `DataScope` —
+  as the action `context`, then calls `this.scope.unwind(top)` on line 551, dropping every frame it
+  just pushed (blackboards, `{now, entity}`, the event frame, the entity proxy scope).
+  `WriteToBlackboardActionDescription` captures that proxy in an `ActionBehavior` closure and only
+  calls `expression.evaluate(context)` when the behavior ticks. `BehaviorSystem.link()` only calls
+  `behavior.initialize()`; behaviors are first ticked in `BehaviorSystem.update()`, i.e. no earlier
+  than the next frame.
+- **Failure scenario**: a rule with `"action": {"type":"Write", "name":"last_bark_time", "value":"now"}`.
+  `match()` pushes `{now: 12.5, entity}`, matches, builds the executor, then unwinds. Next frame the
+  `ActionBehavior` ticks and evaluates `now` against an empty scope → `undefined`, so
+  `blackboard.acquire("last_bark_time", …).set(undefined)` instead of `12.5`. With two actors handling
+  events in the same frame the deferred read can also resolve against the *other* actor's frames if
+  those are still on the stack.
+- **Fix**: snapshot the scope before handing it to an action — materialise the proxy into a plain
+  object in `executeRule` (as `SendRequestActionDescription` already does eagerly for
+  `action_context`), or have `WriteToBlackboardActionDescription.execute` evaluate the expression
+  eagerly and defer only the blackboard write.
+- **Confidence**: Confirmed
+
+### ECS-31 `PointFitnessGaussianBlur` serializes a `quality` field that is never stored
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/evaluation/json/serializeToJSON_PointFitnessFunction.js:61`
+- **Defect**: The serializer writes `quality: value.quality`, but `PointFitnessGaussianBlur` never
+  stores it — `from()` consumes it only to compute `samples_x/y/z = size * quality` and discards it.
+  The deserializer (`deserializeFromJSON_PointFitnessFunction.js:45,51`) destructures `quality` with no
+  default and forwards it to `from()`, whose own default `quality = 5` then applies.
+- **Failure scenario**: `PointFitnessGaussianBlur.from(src, 4, 4, 4, 1)` → `samples = 4,4,4`
+  (64 source evaluations per point). Serialize → `{size_x:4, size_y:4, size_z:4, quality: undefined}`
+  (and `undefined` is dropped entirely by `JSON.stringify`). Deserialize → `quality = 5` →
+  `samples = 20,20,20`, i.e. 8000 source evaluations per point and a numerically different blur.
+- **Fix**: store the value in `from()` (`r.quality = quality;`) with a matching class field, or derive
+  it on serialize as `value.samples_x / value.size_x`.
+- **Confidence**: Confirmed
+
+### ECS-32 `PointFitnessGaussianBlur` kernel is offset by half a sample on every axis
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/evaluation/complex/PointFitnessGaussianBlur.js:67-69,80,89,99`
+- **Defect**: `half_samples_x = samplesX / 2` with `local_x = ix - half_samples_x` gives taps at
+  `-n/2 … n/2 - 1`, which is not centred on the sample point. A centred kernel needs `(samplesX - 1) / 2`.
+- **Failure scenario**: `samples_x = 5, size_x = 10`. Taps land at
+  `local_x ∈ {-2.5,-1.5,-0.5,0.5,1.5}` → spatial offsets `{-5,-3,-1,1,3}` instead of
+  `{-5,-2.5,0,2.5,5}`. Both the gaussian weights and the sample positions are biased by half a tap, so
+  blurring a step edge shifts it by 1 world unit in −x on each axis, and the point being blurred is
+  never itself sampled.
+- **Fix**: `const half_samples_x = (samplesX - 1) / 2;` (and likewise for y, z).
+- **Confidence**: Confirmed
+
+### ECS-33 `Animation.flags` is in neither serialization path, so a paused animation resumes after load
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/animation/Animation.js:40,153-158`;
+  `.../animation/AnimationSerializationAdapter.js:15-28`
+- **Defect**: `flags` (carrying `Playing` and `MeshSizeCulling`) is written by neither `toJSON` nor
+  `serialize`, and the field initialiser unconditionally sets `Playing | MeshSizeCulling`.
+  `equals()`/`hash()` also ignore `flags` while including `debtTime`.
+- **Failure scenario**: `animation.isPlaying = false` (a supported setter, covered by
+  `Animation.spec.js:58-62`), save via `BinaryBufferSerializer`, reload → `flags` is back to the
+  constructor default and the animation plays again. Two `Animation` components differing only in
+  `isPlaying` also report `equals() === true` and identical `hash()`.
+- **Fix**: add `flags` to the binary adapter (bumping `version`) and to `toJSON`/`fromJSON`
+  (defaulting to `MeshSizeCulling | Playing`), and include it in `equals`/`hash`.
+- **Confidence**: Confirmed
+
+### ECS-34 `AnimationSystem` re-subscribes to clip signals on every mesh change and never unsubscribes
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/systems/AnimationSystem.js:116-117,150,221-230`
+- **Defect**: `updateAnimationState` unconditionally does `clips.on.added.add(initAnimationClip)` and
+  `clips.on.removed.add(...)` with fresh closures each time. It runs from `registerAnimation` (line 150),
+  which runs both from `link()` and from every `MeshEvents.DataSet` event. `unlink()` removes only the
+  `MeshEvents.DataSet` entity listener; the clip-signal handlers are never removed, and `Signal.add`
+  does not deduplicate.
+- **Failure scenario**: `MeshSystem.process` sets a placeholder mesh (DataSet #1) then the real asset
+  (DataSet #2) for every async-loaded mesh with `__use_placeholder_mesh` on — together with `link()`
+  that is 3 registrations. Every later runtime mesh swap adds another. After N mesh sets, a single
+  `animation.clips.add(clip)` invokes `startClip` N times, and the handler list grows without bound for
+  the component's life; unlink/relink cycles accumulate across cycles too.
+- **Fix**: keep references to the two handlers on the component, remove any previous pair at the top of
+  `updateAnimationState`, and remove them in `unlink()`.
+- **Confidence**: Confirmed
+
+### ECS-35 `SerializationMetadata` binary adapter truncates a documented 32-bit flag field to 8 bits
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/components/SerializationMetadataSerializationAdapter.js:15,24`
+- **Defect**: `flags` is documented as a "32 bit bitfield" (`SerializationMetadata.js:19-22`) and
+  `toJSON` writes the full number, but the binary adapter uses `writeUint8`/`readUint8`.
+- **Failure scenario**: a consumer defines a ninth flag `Foo = 1 << 8`. `metadata.setFlag(Foo)` →
+  `flags === 256`. `toJSON()` preserves `256`; the binary path writes `256 & 0xFF === 0` and reads back
+  `flags === 0`, silently losing the flag on save/load.
+- **Fix**: `writeUint32`/`readUint32`, bumping the adapter `version` and adding an upgrader.
+- **Confidence**: Confirmed
+
+---
+
+## Storage / serialization
+
+### ECS-36 Schema back-reference is looked up by address in the schema-*object* map, then dereferenced
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter2.js:416`
+- **Defect**: `#deserializeObject` resolves a `HEADER_TAG_REF_SCHEMA` record with
+  `this.#schema_table.getRecord(schema_address)`. `getRecord(schema)` looks up `#schema_map`, which is
+  keyed by the **schema object** (`#schema_map.set(record.schema, record)`); the address-keyed map is
+  `#address_map`, reachable only via `getSchemaAt(address)`. Passing a number can never hit, so
+  `record` is `undefined` and line 419 (`record.typeName`) throws. The whole `HEADER_TAG_REF_SCHEMA`
+  decode branch can only crash.
+- **Failure scenario**: the `schema` parameter of `serialize(buffer, object, schema)` is a documented
+  optional argument. `const S = {v: undefined}; a2.serialize(buf, {v:1}, S); a2.serialize(buf, {v:2}, S);`
+  — the first object writes `HEADER_TAG_INLINE_SCHEMA` and interns `S`; the second takes the `else`
+  branch at line 375 and writes `HEADER_TAG_REF_SCHEMA` + address. On read, the first decodes fine, the
+  second throws `TypeError: Cannot read properties of undefined (reading 'typeName')`. Same for a single
+  object whose explicit schema reuses one sub-schema object for two fields.
+- **Fix**: `record = this.#schema_table.getSchemaAt(schema_address);`. Also reset `#schema_table` when
+  switching an instance between writing and reading — write-side records are registered at write-buffer
+  positions and never cleared, so they can shadow read-side records at the same address.
+- **Confidence**: Confirmed
+
+### ECS-37 Per-component transient flag is ignored whenever the dataset has no `SerializationMetadata` type
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/storage/BinaryBufferSerializer.js:26-34`
+- **Defect**: `isEntityTransient` returns `false` on `smComponentIndex === -1` **before** checking
+  `componentInstance[COMPONENT_SERIALIZATION_TRANSIENT_FIELD]`. The two mechanisms are independent —
+  the magic field is a per-instance opt-out that does not require a `SerializationMetadata` component
+  to exist — but it is gated behind one.
+- **Failure scenario**: `EntityComponentDataset.computeComponentTypeIndex` returns `-1` for an
+  unregistered type, and a type is only registered once some entity actually receives one. In a dataset
+  where nothing ever adds a `SerializationMetadata`, `smComponentIndex === -1`. Mark any component
+  transient the way the game does (`guiElement[COMPONENT_SERIALIZATION_TRANSIENT_FIELD] = true` in
+  `setupStrategyHeadsUpDisplays.js:98`, `sockets[...] = true` in `CombatUnitEntityDecorator.js:660`,
+  `this.__transform2GridPosition[...] = true` in `CharacterMoveAsynchronousAction.js:236`) and it is
+  written to the save anyway, then resurrected on load as a duplicate of a runtime-only component.
+- **Fix**: move the `COMPONENT_SERIALIZATION_TRANSIENT_FIELD` check above the `smComponentIndex === -1`
+  early return.
+- **Confidence**: Confirmed
+
+### ECS-38 Object adapter resolves class identity through *inherited* `typeName`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/storage/binary/object/BinaryObjectSerializationAdapter.js:59-61`
+- **Defect**: `const typeName = Klass.typeName;` is a normal static lookup, so an ES class that does not
+  declare its own `typeName` silently resolves to its ancestor's. The object-v2 writer explicitly
+  guards this with `Object.prototype.hasOwnProperty.call(ctor, "typeName")`
+  (`BinaryObjectSerializer.js:270`) and has a dedicated regression test, so the v1 adapter is the
+  un-fixed half.
+- **Failure scenario**: `BehaviorComponentSerializationAdapter.serialize`
+  (`engine/intelligence/behavior/ecs/BehaviorComponentSerializationAdapter.js:38`) routes every behavior
+  through `this.objectAdapter.serialize(buffer, behavior)`. `Behavior.js:78` sets
+  `Behavior.typeName = "Behavior"`, while `SelectorBehavior`, `WeightedRandomBehavior`, `BranchBehavior`
+  and `ConditionalBehavior` declare none. Saving an entity whose behavior tree contains a
+  `SelectorBehavior` therefore looks up adapter `"Behavior"` — not registered — and the save aborts with
+  `No adapter found for class 'Behavior'`, naming a class that is not in the tree. If any ancestor *does*
+  have a registered adapter the failure is worse: the subclass is written with the ancestor's payload
+  and read back as the ancestor, dropping all subclass state.
+- **Fix**: require an own `typeName` —
+  `Object.prototype.hasOwnProperty.call(Klass, "typeName") ? Klass.typeName : undefined` — and throw
+  naming the actual constructor when absent, mirroring `BinaryObjectSerializer.writeValue`.
+- **Confidence**: Confirmed
+
+### ECS-39 The last component type in a stream is never finalized on load
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/storage/BinaryBufferDeSerializer.js:117-127`
+- **Defect**: `cycleFunction` finalizes the *previous* type at the top of the next loop iteration
+  (`if (typesDecoded > 0) collectionDeSerializer.finalize();`), but the `typesLeft === 0` exit at
+  line 117 returns `TaskSignal.EndSuccess` first. So `BinaryCollectionDeSerializer.finalize()` — and
+  hence `adapter.finalize()` — never runs for the final type. The write path
+  (`BinaryBufferSerializer.js:194`) finalizes every type correctly.
+- **Failure scenario**: load a buffer containing types `[Name, CombatUnit]`. `CombatUnit` elements are
+  read to exhaustion, `typesLeft` is `0`, the task ends, and
+  `CombatUnitSerializationAdapter.finalize()`
+  (`model/game/ecs/component/unit/serialization/CombatUnitSerializationAdapter.js:51`) is never invoked,
+  so its module-static `serialization_array` is left holding stale entries instead of being spliced
+  empty. The deserializer is also left in `State.Ready`, so a subsequent `initialize()` on the same
+  instance throws `IllegalStateException`. Which adapter is affected depends on which component type
+  happens to be last, so the leak is non-deterministic across saves.
+- **Fix**: finalize the in-flight collection before returning `EndSuccess`, guarding against
+  double-finalize on a re-entered cycle.
+- **Confidence**: Confirmed
+
+---
+
+## GUI / HUD / speaker
+
+### ECS-40 `LineSetDescription.collect` walks the root's children instead of the popped node's — infinite loop
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/speaker/lines/sets/LineSetDescription.js:56`
+- **Defect**: Inside the traversal loop the popped node is `set`, but the child-set expansion reads
+  `const sets = this.sets;` — the *root's* children — on every iteration. The root's children are
+  therefore re-pushed forever and `pointer` never drains.
+- **Failure scenario** (reproduced): a `voice-line-sets` entry with a non-empty `sets` array
+  (schema-supported: `LineSetDescriptionTable.linkOne` reads `sets` from JSON, and `validateOne` exists
+  purely to cycle-check that graph). Root `R{lines:[l-root], sets:[C]}`, `C{lines:[l-child]}` →
+  `collect` writes `l-root, l-child, l-child, l-child, …` without bound; `destination` grows until OOM.
+  `VoiceSystem.sayLineFromSet` calls `set.collect(temp_lines, 0)`, so the tab hangs on the first nested
+  bark set anyone authors.
+- **Fix**: `const sets = set.sets;`
+- **Confidence**: Confirmed
+
+### ECS-41 `GUIElementSystem.unlink` calls `Signal.remove` without the context it subscribed with
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/gui/GUIElementSystem.js:261` (subscribe at `:248`)
+- **Defect**: `link` does `component.visible.onChanged.add(handleComponentVisibilityChange, {el, system, entity})`;
+  `unlink` does `component.visible.onChanged.remove(handleComponentVisibilityChange)` with no `thisArg`.
+  `Signal.remove` matches on `handle === h && context === thisArg`, so it matches nothing and returns
+  `false`.
+- **Failure scenario** (reproduced against the real `Signal`): `add(handler, ctx)` then `remove(handler)`
+  → returns `false`, `hasHandlers()` stays `true`, the next `send1` still runs the handler. Concretely,
+  `ecd.removeComponentFromEntity(entity, GUIElement)` (real caller:
+  `model/game/scenes/combat/UnitStateManager.js:437`) or `Entity.destroy()` → `Entity.build()` leaves
+  the old subscription in place, and the next `link` adds a second. With two handlers,
+  `component.visible.set(true)` runs `attachComponent` twice → `parent.addChild(component.view)` twice
+  → `View.addChild` (`view/View.js:365`) pushes the same child into `parent.children` twice (the
+  `isLinked` assert that would catch it is stripped in production). `removeChild` then drops only the
+  first entry, so `parent.children` keeps a stale entry whose `el` is no longer in the DOM; a later
+  `removeAllChildren` calls `this.el.removeChild(child.el)` on a non-child and throws `NotFoundError`.
+- **Fix**: store the context object (as `ViewportPositionSystem` does in `this.data`) and pass it to
+  `remove`.
+- **Confidence**: Confirmed
+
+### ECS-42 `ViewportPositionSystem.unlink` never unsubscribes from `el.view.size.onChanged`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/gui/position/ViewportPositionSystem.js:154` (unlink at `:167-183`)
+- **Defect**: `link` makes five `onChanged.add(updatePosition, eventContext)` subscriptions —
+  `vp.position`, `vp.offset`, `vp.anchor`, `vp.enabled` and `el.view.size`. `unlink` removes only the
+  first four.
+- **Failure scenario**: `GUIEngine.createModal` (`meep/src/engine/ui/GUIEngine.js:215`) does
+  `window.removeComponent(ViewportPosition)` immediately after `openWindow` built the entity,
+  deliberately freeing the modal from viewport positioning while the `GUIElement` and its
+  `ui-modal-window-container` view stay live on screen. `unlink` runs, but `updatePosition` stays bound
+  to that container's `size.onChanged` with a context holding the now-detached `vp`. Any later size
+  change re-invokes `positionComponent(el, vp)`, overwriting `view.position` from the stale
+  `vp.position`, overwriting `view.transformOrigin` with the stale `vp.anchor` (default `0,0`,
+  discarding the `0.5,0.5` set at `GUIEngine.js:213`), and calling `el.visible.set(...)` — if the stale
+  position is out of bounds and `stickToScreenEdge` is false (the default), `el.visible.set(false)`
+  makes `GUIElementSystem` detach the modal from the DOM and the open modal vanishes.
+- **Fix**: add `el.view.size.onChanged.remove(updatePosition, eventContext);` inside the
+  `eventContext !== undefined` block in `unlink`.
+- **Confidence**: Confirmed
+
+### ECS-43 `HeadsUpDisplay.toJSON` writes `transformPerspectiveRotation`, `fromJSON` reads `perspectiveRotation`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/gui/hud/HeadsUpDisplay.js:86` vs `:90`
+- **Defect**: The JSON key emitted for the `PerspectiveRotation` flag does not match the key the reader
+  destructures, so the reader always falls back to its `false` default.
+- **Failure scenario** (reproduced): a HUD with `PerspectiveRotation` set — exactly what
+  `makeEnemyGroupHud` in `model/game/scenes/strategy/gui/setupStrategyHeadsUpDisplays.js` configures.
+  `toJSON()` yields `{"worldOffset":…,"transformWorldOffset":true,"transformPerspectiveRotation":true}`;
+  `HeadsUpDisplay.fromJSON(that)` yields `flags = 1` instead of `3`,
+  `getFlag(PerspectiveRotation) === false`, and `a.equals(b) === false`. The screen-space billboard
+  rotation is silently dropped on any JSON round-trip. The binary adapter round-trips the flag
+  correctly, so the two persistence paths disagree.
+- **Fix**: emit `perspectiveRotation` in `toJSON`, or rename the `fromJSON` destructure to
+  `transformPerspectiveRotation`. Pick one and keep both sides identical.
+- **Confidence**: Confirmed
+
+### ECS-44 `GUIElementSystem.link` logs "does not have a view" and then dereferences the missing view
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/gui/GUIElementSystem.js:212`
+- **Defect**: The un-managed-with-no-view branch does `console.error(...)` with no `return`. Execution
+  falls through to `if (component.visible.getValue()) this.attachComponent(component, entity)`
+  (`visible` defaults to `true`), and `attachComponent` reaches `parent.addChild(component.view)` with
+  `component.view === null`.
+- **Failure scenario**: `const c = new GUIElement(); c.clearFlag(GUIElementFlag.Managed);` added to an
+  entity — precisely the state the error message describes. `View.addChild(null)` executes
+  `child.parent = this;` (its guarding asserts are stripped in production) →
+  `TypeError: Cannot set properties of null (setting 'parent')` propagates out of `link`, aborting the
+  component-added observer dispatch for that entity so later systems never link.
+- **Fix**: `return;` after the `console.error` at `:212`.
+- **Confidence**: Confirmed
+
+### ECS-45 `ButtonViewEntity.finalize` destroys the structural children created in its constructor
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/gui/view/ButtonViewEntity.js:104-107` (children created at `:17-23`)
+- **Defect**: The constructor adds the `foreground` and `background` `EmptyView`s the button's CSS is
+  built on. `finalize()` calls `removeAllChildren()`, which removes them too — but `ViewEntity.finalize`
+  is documented as bringing the view "to initial state ready to be destroyed **or re-used**", and
+  `GUIElementSystem` implements exactly that re-use contract (`unlink` calls `view.finalize()` and
+  clears `Initialized`; `attachComponent` re-calls `view.initialize(...)` when it sees
+  `Managed && !Initialized`).
+- **Failure scenario**: an entity carrying a `view.Button` `GUIElement` (registered at
+  `model/game/GameClassRegistry.js:89`) goes through link → unlink → link. On the second `initialize`
+  the label is re-added but `.foreground`/`.background` are gone, so the button renders with no
+  background fill and dead hover/press styling. `LocalizedLabelViewEntity` is correct precisely because
+  its constructor adds no children.
+- **Fix**: create the foreground/background children in `initialize()`, or have `finalize()` remove only
+  the label child.
+- **Confidence**: Confirmed
+
+### ECS-46 `LineSetDescriptionTable.validateOne` reports a false circular dependency for a shared child set
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/speaker/lines/sets/LineSetDescriptionTable.js:79`
+- **Defect**: The check treats *any* second visit to a node as a cycle
+  (`if (visited.hasOwnProperty(set.id))`) rather than tracking the current traversal path, so a DAG with
+  a shared child is rejected.
+- **Failure scenario**: `A{sets:[B,C]}`, `B{sets:[D]}`, `C{sets:[D]}` — no cycle. Traversal pops `A`,
+  pushes `B,C`; pops `C`, pushes `D`; pops `D`, marks visited; pops `B`, pushes `D`; pops `D` again →
+  `visited` hit → `errorConsumer("Circular dependency detected: D -> C -> A")` and `return false`. Valid
+  voice-line-set data fails validation at load, and the reported path names the wrong parent.
+- **Fix**: track the recursion stack (mark on entry, unmark on exit) or colour nodes white/grey/black,
+  and only report a cycle on re-entering a grey node.
+- **Confidence**: Confirmed
+
+### ECS-47 `VoiceSystem.sayLineFromSet` dereferences `undefined` when the set yields no lines
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/speaker/VoiceSystem.js:313-315`
+- **Defect**: `weightedRandomFromArray` returns `undefined` when `length === 0`
+  (`core/collection/array/weightedRandomFromArray.js:26-28`), and the result is used unguarded as
+  `selected_line.id`. The neighbouring "set not found" case at `:303` warns and returns, so graceful
+  handling of bad data is the intended contract here.
+- **Failure scenario**: a `voice-line-sets` entry with an empty or omitted `lines` array (`linkOne`
+  defaults `lines = []`) — a placeholder or not-yet-authored bark set.
+  `ecd.sendEvent(entity, VoiceEvents.SpeakSetLine, {id: thatSet})` → `collect` returns `0` →
+  `TypeError: Cannot read properties of undefined (reading 'id')` thrown out of the entity-event dispatch.
+- **Fix**: guard on `selected_line === undefined` after the `weightedRandomFromArray` call.
+- **Confidence**: Confirmed
+
+---
+
+## Attachment / parent / transform / IK
+
+### ECS-49 `EntityNode`'s `parent` setter strips `TransformAttachment` and never re-adds it
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/parent/EntityNode.js:240-270`
+- **Defect**: The setter removes both components up front
+  (`let parent_entity = this_entity.removeComponent(ParentEntity); let attachment = this_entity.removeComponent(TransformAttachment);`)
+  and, in the `node !== null` branch, explicitly re-adds `ParentEntity` via `this_entity.add(parent_entity)`
+  — but the attachment is only put back through `this.__safe_get_attachment()`, which runs **only when
+  `attachment === null`**. When the node already had a `TransformAttachment`, the removed instance is
+  mutated (`attachment.parent = parent_entity_id`) and dropped on the floor.
+- **Failure scenario** (reproduced): three built `EntityNode`s A, B, C each with a `Transform`.
+  ```js
+  A.addChild(C);   // C -> ParentEntity{0}, TransformAttachment{parent:0}
+  C.parent = B;    // public setter, the documented re-parent entry point
+  ```
+  Observed: `ParentEntity.entity` correctly becomes `1`, but
+  `C.entity.getComponent(TransformAttachment)` is `null` and
+  `ds.getComponent(C.entity.id, TransformAttachment)` is `undefined`. `TransformAttachmentSystem` has
+  unlinked C, so C's world transform is no longer driven by any parent — the node visually detaches
+  while still being logically parented (and still gets destroyed when B is destroyed).
+  `addChild` escapes this only because it routes through `removeChild` → `node.parent = null` first,
+  which nulls both.
+- **Fix**: after `attachment.parent = parent_entity_id`, put the component back —
+  `if (this_entity.getComponent(TransformAttachment) === null) this_entity.add(attachment);` — or
+  simply do not remove `TransformAttachment` at the top when `node !== null`.
+- **Confidence**: Confirmed
+
+### ECS-50 `InverseKinematicsSystem` declares read-only access to `Mesh` because of an undefined enum member
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/ik/InverseKinematicsSystem.js:18`
+- **Defect**: `ResourceAccessSpecification.from(Mesh, ResourceAccessKind.Read | ResourceAccessSpecification.Write)`
+  — `Write` is a member of `ResourceAccessKind`, not of `ResourceAccessSpecification`. The latter has no
+  such static, so the expression is `1 | undefined === 1`: the system declares `Read` only, while
+  `TwoBoneInverseKinematicsSolver.solve` actually mutates the mesh's bone quaternions
+  (`boneA.setRotationFromQuaternion(...)`, `TwoBoneInverseKinematicsSolver.js:173-174`).
+- **Failure scenario**: `EntityManager.updateExecutionOrder`'s `scoreSystem` weights a `Write` component
+  at `attached_edge_count * 2` and a `Read` at `* 1`, and `computeSystemComponentDependencyGraph` only
+  emits edges out of a system that declares `Write`/`Create`. With the typo, `InverseKinematicsSystem`
+  contributes no dependency edges and is scored as a pure `Mesh` reader, so it can be ordered *after*
+  the systems that consume mesh/bone state in the same `simulate()` call — IK corrections (feet planted
+  on terrain) are applied one frame late, producing visible foot sliding / ground penetration on the
+  frame a character's pose changes.
+- **Fix**: `ResourceAccessKind.Read | ResourceAccessKind.Write`.
+- **Confidence**: Confirmed
+
+### ECS-51 `OneBoneSurfaceAlignmentSolver` recovers the alignment angle with `asin`, which cannot exceed 90°
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/ecs/ik/OneBoneSurfaceAlignmentSolver.js:170-175`
+- **Defect**: `axis.crossVectors(v3, Vector3.forward); const betaSine = axis.length(); const beta = Math.asin(clamp(betaSine, -1, 1));`
+  — `|a × b| = sin θ` is ambiguous between `θ` and `π − θ`, and `asin` always returns the branch in
+  `[0, π/2]`. The angle between the contact normal and the bone axis is not recoverable this way once it
+  exceeds 90°.
+- **Failure scenario**: bone axis `(0,0,1)` in bone space, contact normal in bone space
+  `(0, 0.9, −0.436)` — 116° apart. `|cross| = 0.9` → `beta = asin(0.9) = 64.2°`. The bone is rotated
+  64° instead of 116°, so instead of squaring up to the surface it ends up 52° off, tilted into the
+  surface. Any surface whose normal is more than 90° from the bone's own axis (steep slopes,
+  overhangs, an inverted foot-bone rig) is aligned to the wrong angle rather than clamped by
+  `constraint.limit`.
+- **Fix**: recover the angle unambiguously — `Math.atan2(axis.length(), v3.dot(Vector3.forward))` —
+  before normalising `axis`.
+- **Confidence**: Likely (the trigonometric limitation is unambiguous; I did not exercise it against a
+  real rig, so how often a live skeleton crosses 90° is unverified)
+
+---
+
+## Status of previously-known items
+
+| Item | Status |
+| --- | --- |
+| `Entity.promiseEvent` calling `removeEventListener` instead of `add` | **FIXED** (`Entity.js:326-327` now `addEventListener`) |
+| `EntityComponentDataset.dropData` not clearing `__entityAnyEventListeners` | **FIXED** (`EntityComponentDataset.js:1882`) |
+| `HeadsUpDisplaySystem` scaling world-offset Z by `scale.y` | **FIXED** (`HeadsUpDisplaySystem.js:88` uses `transform_scale.z`) |
+| `obtainTileAtWorldPosition2D` dereferencing an out-of-bounds tile | **STILL PRESENT** (`TerrainTileManager.js:487-489`; `getTileByWorldPosition2D` can return `undefined`, then `tile.gridPosition`) |
+| `FogOfWar.rebuildSampler` width/height swap | **FIXED** (`FogOfWar.js:707-713`, correct `Sampler2D(data, itemSize, width, height)` order) |
+| `TerrainTileManager.stitchTile` floor-vs-ceil | **STILL PRESENT** (`:566` uses `floor`; `:353`, `:405`, `:408`, `:422` all use `ceil`) |
+| Event-dispatch pointer restore missing `try/finally` | **STILL PRESENT** (`EntityComponentDataset.js:2138-2162` and `2180-2204`) |