@woosh/meep-engine 2.168.0 → 2.169.0

package/src/REVIEW_2026_08_06/engine-ai-nav.md

@@ -0,0 +1,279 @@
+# Correctness review — `engine/intelligence`, `engine/navigation`, `engine/grid`
+
+Reviewed every non-spec source file under the three trees. Findings below are correctness only;
+each has a concrete failure scenario. Several were confirmed by running the real code
+(probe scripts under `scratchpad/probe/`).
+
+---
+
+### AI-1 `ParallelBehavior` double-finalizes its children on every early-exit path
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/intelligence/behavior/composite/ParallelBehavior.js:215-226` (and the call sites at `:143`, `:158`, `:164`, `:232`)
+- **Defect**: `__finalizeActiveChildren()` walks the set bits of `activeSet` and calls `finalize()` on each child, but never clears those bits. On the `RequireOne` early-exit paths `tick()` calls it and returns a terminal status; the parent then calls `ParallelBehavior.finalize()`, which calls `__finalizeActiveChildren()` again over the *same still-set bits*. Every child that was still running is finalized twice.
+- **Failure scenario**: default policies (`ParallelBehavior.from([...])` → success `RequireAll`, failure `RequireOne`).
+
+  ```js
+  const wr  = WeightedRandomBehavior.from([WeightedElement.from(DelayBehavior.from(5), 1)]);
+  const par = ParallelBehavior.from([wr, FailingBehavior.INSTANCE]);
+  const seq = SequenceBehavior.from([par]);
+  seq.initialize({});
+  seq.tick(0.1);   // -> Failed  (FailingBehavior trips the RequireOne failure policy)
+  seq.finalize();  // TypeError: Cannot read properties of undefined (reading 'finalize')
+  ```
+  `WeightedRandomBehavior.finalize()` nulls `__selected` on the first call and dereferences it on the second. Verified by running the above — it throws. In `BehaviorSystem.unlink()` the `finalize()` call is *not* wrapped in a try/catch, so the throw escapes entity teardown.
+  Even where the second finalize does not throw, it is still a double `finalize()` on every subtree — e.g. `WaitForEventBehavior` unregisters its listener twice, `AbstractDecoratorBehavior` propagates the double-finalize down its source chain.
+- **Fix**: clear the bit as each child is finalized inside `__finalizeActiveChildren`:
+  ```js
+  for (let i = activeSet.nextSetBit(0); i !== -1; i = activeSet.nextSetBit(i + 1)) {
+      activeSet.set(i, false);
+      children[i].finalize();
+  }
+  ```
+  (`nextSetBit(i + 1)` still advances correctly after clearing bit `i`.)
+- **Confidence**: Confirmed
+
+---
+
+### AI-2 `ConditionalBehavior` re-initializes its condition on every tick — a long-running condition can never complete
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/intelligence/behavior/util/ConditionalBehavior.js:28`
+- **Defect**: `tick()` unconditionally calls `condition.initialize(this.context)` before ticking it. Any condition whose evaluation spans more than one tick has its state reset every frame, so it re-starts from scratch forever. The `else { //waiting? return s; }` branch shows a `Running` condition is meant to be supported. Additionally the per-tick `initialize` is unpaired — the `Running` branch never calls `condition.finalize()`.
+- **Failure scenario**:
+  ```js
+  const c = ConditionalBehavior.from(DelayBehavior.from(1), someAction);
+  c.initialize({});
+  c.tick(0.25) // Running   (elapsed reset to 0, then 0.25)
+  c.tick(0.25) // Running   (elapsed reset to 0 again)
+  ...          // never succeeds
+  ```
+  Verified: 100 ticks of 0.25 s against a 1 s `DelayBehavior` condition still returns `Running` (4 ticks should suffice). With `WaitForEventBehavior` as the condition it is worse — `initialize` calls `ecd.addEntityEventListener(...)` once per frame, so the listener list on the target entity grows without bound.
+- **Fix**: initialize the condition once, in `ConditionalBehavior.initialize(context)`, and re-initialize it only after it has resolved and been finalized (i.e. track a `#condition_running` state, or move the init into the `Succeeded`/`Failed` branches that already call `condition.finalize()`).
+- **Confidence**: Confirmed
+
+---
+
+### AI-3 `StateNode.traverse` leaves the shared stack pointer below its entry value
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/intelligence/mcts/StateNode.js:335-363`
+- **Defect**: the loop condition `while (stack_pointer-- > stackOffset)` decrements once more on the failing test, so on exit the module-static `stack_pointer` is `stackOffset - 1`, not `stackOffset`. Two consequences: (a) every completed traversal shifts the shared pointer one slot further negative, permanently retaining a `StateNode` reference at that (string-keyed) index — an unbounded leak that pins whole MCTS subtrees via `parent`/`moves`; (b) a nested traversal corrupts the enclosing one.
+- **Failure scenario**: root with three materialised children `a`, `b`, `c`; the visitor calls `a.traverse(...)` when it reaches the root (a natural pattern — e.g. summarising a subtree while walking the tree).
+  ```
+  observed outer visit order: root, c, b     // 'a' is silently skipped
+  expected:                   root, a, b, c
+  ```
+  Verified by running it. The inner traversal returns with the pointer one below where the outer loop left it, so the outer loop's next push overwrites a pending entry.
+- **Fix**: restore the pointer explicitly. Replace the loop with
+  ```js
+  while (stack_pointer > stackOffset) {
+      n = stack[--stack_pointer];
+      ...
+  }
+  stack_pointer = stackOffset;
+  ```
+  and clear (`stack[stack_pointer] = null`) as entries are consumed so references are not retained.
+- **Confidence**: Confirmed
+
+---
+
+### AI-4 `RepeatBehaviorSerializationAdapter` cannot encode the default `limit = Infinity`; it round-trips to `0`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/intelligence/behavior/decorator/RepeatBehaviorSerializationAdapter.js:20`
+- **Defect**: `buffer.writeUintVar(value.limit)` is called with `Infinity` for every default-constructed `RepeatBehavior` (`RepeatBehavior.from(source)` → `limit = Infinity`, and `BehaviorComponent.loop(action)` builds exactly that). `writeUintVar` narrows via `ToInt32`: `Infinity & 0x7f === 0` and `Infinity >> 7 === 0`, so it emits a single `0x00` byte and `readUintVar` returns `0`.
+- **Failure scenario**:
+  ```js
+  new Entity().add(BehaviorComponent.loop(dt => tickSomething(dt))).build(ecd);
+  // save game, reload
+  ```
+  After the round-trip `limit === 0`. `RepeatBehavior.tick` then does `__iterator++` → `1 >= 0` → returns `Succeeded`, so the "run forever" loop runs its body exactly once and the `BehaviorComponent` is flagged `Resolved` — the entity's per-frame logic silently stops after one frame. (In a development build the stripped-in-production `assert.isNonNegativeInteger` in `writeUintVar` turns this into an outright serialization throw instead; both builds are broken, differently.)
+- **Fix**: encode the unbounded case explicitly, e.g. write a one-byte flag (`0 = unbounded`, `1 = bounded` followed by the `uintVar`), and reconstruct `Infinity` on read. `RepeatUntilSuccessBehavior` has the same `Infinity` default and would need the same treatment if it gains an adapter.
+- **Confidence**: Confirmed
+
+---
+
+### AI-5 `PathFollower` save upgrade drops the position/rotation write masks — pre-v3 saves load a follower that never moves
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/navigation/ecs/path_following/PathFollowerSerializationUpgrader_2_3.js:13-14` (root cause also visible at `PathFollowerSerializationUpgrader_0_1.js:22-23`)
+- **Defect**: in formats 0–2 the write masks lived in two separate bytes (`rotationAlignment`, `positionWriting`) alongside a `uint8 flags` that could only hold bits 1–8. The 2→3 upgrader widens `flags` to `uint16` and then *discards* both mask bytes ("now in flags") without folding them in. Nothing else supplies those bits, and `PathFollowerSerializationAdapter.deserialize` assigns `value.flags` directly, so the constructor's `DEFAULT_FLAGS` never applies.
+- **Failure scenario**: load a save written at component version ≤ 2. The upgraded `flags` contains only `Active` (bit 1) — every `WritePositionX/Y/Z` (16/32/64) and `WriteRotationX/Y/Z` (128/256/512) bit is clear. In `performStep` all three `if (!getFlag(WritePosition*)) nextPosition.set*(position.*)` branches fire, so `nextPosition.equals(position)` is true and the whole write block (including `position.copy(nextPosition)`) is skipped. The follower's `position` scalar advances and `EndReached` eventually fires, but the entity's `Transform` is never touched — the moving object stands still and then "arrives".
+- **Fix**: in `PathFollowerSerializationUpgrader_2_3`, translate the two legacy bytes into the new flag bits before writing:
+  ```js
+  const legacy_flags = source.readUint8();
+  const rot  = source.readUint8();   // was read after the floats; keep the field order
+  const pos  = source.readUint8();
+  let flags = legacy_flags;
+  if (pos & 1) flags |= PathFollowerFlags.WritePositionX;
+  if (pos & 2) flags |= PathFollowerFlags.WritePositionY;
+  if (pos & 4) flags |= PathFollowerFlags.WritePositionZ;
+  if (rot & 1) flags |= PathFollowerFlags.WriteRotationX;
+  ... etc
+  ```
+  (the byte order in the v2 stream is flags, speed, rotationSpeed, rotationAlignment, positionWriting, maxMoveDistance — read them in that order and emit the combined `uint16` first).
+- **Confidence**: Confirmed (by reading; the flag-value/`performStep` interaction is unambiguous)
+
+---
+
+### AI-6 `RepeatBehavior` / `RepeatUntilSuccessBehavior` re-initialize the source without finalizing it
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/intelligence/behavior/decorator/RepeatBehavior.js:82`; same at `RepeatUntilSuccessBehavior.js:72`
+- **Defect**: on each loop iteration the decorator calls `source.initialize(this.context)` without first calling `source.finalize()`. Over `N` iterations the source receives `N` initializes and exactly one finalize (from `AbstractDecoratorBehavior.finalize`). Every behaviour that acquires a resource in `initialize` and releases it in `finalize` leaks one acquisition per iteration.
+- **Failure scenario**: measured with an instrumented source —
+  ```js
+  RepeatBehavior.from(probe, 3);  // -> probe.initialize called 3 times, probe.finalize called 1 time
+  ```
+  Concretely with a `SelectorBehavior` source: the selector's *successful* child is deliberately left un-finalized by `SelectorBehavior.tick` (the parent is expected to finalize it). `RepeatBehavior` instead calls `selector.initialize(...)`, which resets `__currentBehaviour` to child 0 — so the previously-successful child is never finalized at all. If that child is a `WaitForEventBehavior` the `ecd` listener registered by its `initialize` is never removed, and one stale listener accumulates per loop iteration.
+- **Fix**: `source.finalize(); source.initialize(this.context);` in both decorators.
+- **Confidence**: Confirmed
+
+---
+
+### AI-7 Blackboard proxy is not enumerable — `Object.keys`/`for..in`/spread/`JSON.stringify` all see an empty object
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/intelligence/blackboard/make_blackboard_proxy.js:41-45`
+- **Defect**: the handler defines `ownKeys` but no `getOwnPropertyDescriptor`. Every enumeration operation follows `ownKeys` with a `[[GetOwnProperty]]` on each key; with no trap that forwards to the target `Blackboard` instance, which has no such own property, so the key is filtered out as non-existent. The proxy's stated purpose — "connecting blackboard to systems that are not explicitly designed to work with a blackboard" — fails for exactly those systems.
+- **Failure scenario**:
+  ```js
+  const bb = new Blackboard();
+  bb.acquireNumber('hp', 10);
+  bb.acquireString('name', 'bob');
+  const p = bb.getValueProxy();
+  p.hp                  // 10        (get trap works)
+  bb.getKeys()          // ["hp","name"]
+  Object.keys(p)        // []        <-- wrong
+  JSON.stringify(p)     // "{}"      <-- wrong
+  ({...p})              // {}        <-- wrong
+  for (const k in p){}  // no iterations
+  ```
+  Verified by running it. Any consumer that snapshots the blackboard by spreading/stringifying the proxy silently persists or transmits an empty object.
+- **Fix**: add a `getOwnPropertyDescriptor` trap:
+  ```js
+  getOwnPropertyDescriptor(target, p) {
+      if (!target.contains(p, DataType.Any)) return undefined;
+      return { value: target.acquire(p, DataType.Any).getValue(), enumerable: true, configurable: true, writable: true };
+  }
+  ```
+  (`configurable: true` is required — the target is extensible and does not actually own the key.)
+- **Confidence**: Confirmed
+
+---
+
+### AI-8 `FilterBehavior.from` evaluates conditions in reverse order
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/intelligence/behavior/util/FilterBehavior.js:18` + `:34`
+- **Defect**: `addCondition` uses `unshift`, so `from(conditions, actions)` inserts each condition at the head in turn and the list ends up reversed. `FilterBehavior` extends `SequenceBehavior`, which runs children in array order and short-circuits on the first failure, so the author-declared guard order is inverted.
+- **Failure scenario**: the standard guard idiom breaks —
+  ```js
+  FilterBehavior.from(
+      [ new ConditionBehavior(() => ctx.target !== null),
+        new ConditionBehavior(() => ctx.target.hp > 0) ],   // depends on the first guard
+      [ attackAction ]
+  );
+  ```
+  measured execution order is `c2 -> c1 -> a1`, so the `.hp` guard runs first and throws `TypeError: Cannot read properties of null` when `ctx.target` is null — which `ActionBehavior`/`BehaviorSystem` swallow into a `Failed`, silently disabling the branch. Verified by running an instrumented version.
+- **Fix**: keep conditions in declaration order — insert at the boundary between conditions and actions, e.g. track `#condition_count` and `this.__children.splice(this.#condition_count++, 0, condition)`.
+- **Confidence**: Confirmed
+
+---
+
+### AI-9 `StateGraphSystem.link` calls `addEntityEventListener()` with no arguments
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/intelligence/controller/graph/StateGraphSystem.js:13`
+- **Defect**: `this.entityManager.dataset.addEntityEventListener();` — no entity, event name, or listener. The asserts in `addEntityEventListener` are compiled out in production, so control reaches `if (!this.entityExists(undefined)) throw new Error(...)`.
+- **Failure scenario**: register `StateGraphSystem` and add a `StateGraph` component to any entity → `link` throws `Error: Entity 'undefined' does not exist` out of the ECS link path, aborting entity construction. The system is unusable as shipped.
+- **Fix**: the file is an unfinished stub (`unlink` is empty, `StateGraphDescription.build()` is empty and the class is not even exported). Either implement the listener registration from `StateGraph.inputs` (`for (const [state, events] of ...) dataset.addEntityEventListener(entity, event, handler, this)`) with the matching `removeEntityEventListener` in `unlink`, or remove the system rather than shipping a link that throws.
+- **Confidence**: Confirmed
+
+---
+
+### AI-10 `WaitForEventBehavior.target` is dropped by serialization and permanently overwritten by `initialize`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/intelligence/behavior/ecs/WaitForEventBehaviorSerializationAdapter.js:15,24` and `WaitForEventBehavior.js:74-76`
+- **Defect**: two related problems with the `target` field.
+  1. The adapter serializes only `event`. `target` is silently reset to its class-field default `-1` ("listen on self") on load.
+  2. `initialize` does `if (this.target < 0) { this.target = this.entity; }` — it *mutates* the configured field instead of resolving into a local. Once initialized the behaviour is permanently bound to the first entity it ran on.
+- **Failure scenario**: (1) a behaviour authored as `WaitForEventBehavior.fromJSON({ event: 'gate_opened', target: 42 })` — a cutscene actor waiting on a gate entity — round-trips through a save and comes back listening for `'gate_opened'` on *itself*. The event never arrives; `WaitForEventBehavior` is documented as having no failure condition, so the containing sequence hangs on that node for the rest of the session. (2) if a prebuilt tree object is reused to build a second entity (e.g. a cached prefab tree), the second entity's `WaitForEventBehavior` still registers its listener on the *first* entity's id.
+- **Fix**: serialize `target` (`writeInt32`/`readInt32`, or a one-byte "self" flag plus the id), and in `initialize` resolve into a private field — `this.#resolved_target = this.target < 0 ? this.entity : this.target;` — used by the listener add/remove, leaving `this.target` as pure configuration.
+- **Confidence**: Confirmed
+
+---
+
+### AI-11 `GridObstacle.traverseMask` passes `index + 1` to the visitor
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/grid/obstacle/GridObstacle.js:80-84`
+- **Defect**: `index++` runs before the visitor call, so the fourth argument is always one greater than the cell's actual index into `this.data`.
+- **Failure scenario**: cell `(0,0)` (`data[0]`) is reported to the visitor as `index = 1`. A visitor that uses the index to write back — `(x, y, value, index) => obstacle.data[index] = 0` to clear a footprint — clears cell `(1,0)` for every cell it visits and writes one element past the end of `data` for the last cell (a silent no-op on a `Uint8Array`, so the last cell is never cleared). No in-repo caller uses the 4th argument today, but it is public API and the documented contract (`@param index`) is violated.
+- **Fix**: pass the pre-increment value: `visitor.call(thisArg, j + offsetX, i + offsetY, value, index++)` (or hoist `const cell_index = index++;` before the call).
+- **Confidence**: Confirmed
+
+---
+
+### AI-12 `GridPosition2Transform.flags` is not copied by `copy()`/`clone()` and not serialized
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/grid/grid2transform/GridPosition2Transform.js:80-84`, `:60-74`; `GridPosition2TransformSerializationAdapter.js:15-67`
+- **Defect**: `copy`, `toJSON`, `fromJSON`, `equals`, `hash` and the binary adapter all handle only `offset`. `flags` reverts to `DEFAULT_FLAGS` (which includes `Immediate`) on clone or load.
+- **Failure scenario**: `CharacterMoveAsynchronousAction` clears `GridPosition2TransformFlags.Immediate` while a character is animating between cells (`CharacterMoveAsynchronousAction.js:357`), precisely so the transform is *not* snapped to the grid cell. Save while a move is in flight (or clone the component) → the flag comes back set → `GridPosition2TransformSystem.link` runs `sync()` immediately and teleports the character to the destination cell centre, discarding the interpolated position.
+- **Fix**: serialize `flags` (one byte, packed into the existing header's spare bits or written separately with a version bump) and add `this.flags = other.flags;` to `copy()`; include it in `equals`/`hash`.
+- **Confidence**: Confirmed
+
+---
+
+### AI-13 `ResourceAllocationSolver.addResource` mutates the caller's `Resource` objects
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/intelligence/resource/ResourceAllocationSolver.js:64-74`
+- **Defect**: the first `Resource` seen for a given type is stored by reference; a later resource of the same type is folded in with `existingResource.amount += resource.amount`, writing into the caller's object. `solve()` carefully clones before spending, showing the intent not to mutate inputs.
+- **Failure scenario**:
+  ```js
+  const pool = [new Resource(5, 'gold'), new Resource(3, 'gold')];
+  await allocator.allocate(pool);  // solver sees 8 gold; pool[0].amount is now 8
+  await allocator.allocate(pool);  // solver now sees 11 gold, then 14, ...
+  ```
+  Each `allocate` call inflates the caller's pool, so tactical modules are granted resources that do not exist.
+- **Fix**: store a clone — `this.resources.set(type, resource.clone())` — and keep the `+=` on that owned copy.
+- **Confidence**: Confirmed
+
+---
+
+### AI-14 `Transform2GridPositionSystem` never performs an initial synchronisation on link
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/grid/transform2grid/Transform2GridPositionSystem.js:107-119` (`Synchronizer.link`, `:74-76`)
+- **Defect**: `link()` only subscribes to `transform.position.onChanged`. The `GridPosition` is left at whatever it was until the transform is *next* written. Compare `GridPosition2TransformSystem`, which has an explicit `Immediate` flag for this; `Transform2GridPositionFlags` is an empty object, suggesting the counterpart was never implemented.
+- **Failure scenario**:
+  ```js
+  new Entity()
+      .add(new Transform().position.set(10, 0, 10) && transform)
+      .add(new GridPosition())            // (0,0)
+      .add(new Transform2GridPosition())
+      .build(ecd);
+  ```
+  The entity sits at world (10, 10) but its `GridPosition` stays `(0,0)`. `GridPositionSystem` indexes it into the quadtree at cell (0,0), so `getEntitiesAt(result, 10, 10)` misses it and `getEntitiesAt(result, 0, 0)` returns a phantom. The spec (`Transform2GridPositionSystem.spec.js:39`) only ever exercises the post-link write path, so this is untested.
+- **Fix**: call `synchronizer.write()` at the end of `Synchronizer.link()` (mirroring `Vector2.process`, which `GridPositionSystem` already uses for exactly this reason).
+- **Confidence**: Confirmed
+
+---
+
+### AI-15 `PathFollowerFlags.Finished` and `PathFollower.position` are never reset by the library
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/navigation/ecs/path_following/PathFollowingSystem.js:56-57`, `:162-168`
+- **Defect**: `performStep` sets `Finished` and pins `position = path_length`; nothing in the library ever clears either. `__visit_entity` then tests `Finished` after *every* `performStep`, not just when this frame set it.
+- **Failure scenario**: reuse a follower — assign a new `Path` component and re-set `PathFollowerFlags.Active`. On the very next update `performStep` starts from the stale `position` (`= old path length`), so `next_offset >= path_length` immediately, and `__visit_entity` sees the still-set `Finished`, clears `Active` and fires a spurious `PathFollowerEventType.EndReached` before the entity has moved a single unit. The only in-repo consumer works around this by clearing the flag by hand (`CharacterMoveAsynchronousAction.js:600`); library users have no documented reset protocol.
+- **Fix**: clear `Finished` (and reset `position` to 0) when the follower transitions to active, e.g. in `__visit_entity` gate on a per-frame local (`const finished_now = performStep(...)`) rather than the persistent flag, and expose a `PathFollower.restart()` that clears `Finished` and zeroes `position`.
+- **Confidence**: Confirmed
+
+---
+
+## Status of the two "already known, unconfirmed" items
+
+- **grid A\* inadmissible squared-distance heuristic** — **FIXED**. `find_path_on_grid_astar.js:170-186` now returns Manhattan distance, with a comment explaining the admissibility argument (min step cost 1 on a 4-connected grid); `find_path_on_grid_astar.spec.js:60-91` pins the previously non-optimal weighted-grid route to the Dijkstra cost of 8.
+- **`OverrideContextBehavior` initialising its source twice with the wrong context first** — **FIXED**. `OverrideContextBehavior.js:29-38` now calls `this.__source.initialize(child_context)` and then `Behavior.prototype.initialize.call(this, context)` directly, deliberately bypassing `AbstractDecoratorBehavior.initialize`, with a comment stating why.
+
+## Checked and found clean (no finding)
+
+- `find_path_on_grid_astar` open/closed handling, lazy-push duplicate skipping, blocked-cell closing, `compute_path` gradient descent and bend-only waypoint reconstruction, start-equals-goal, unreachable-goal termination.
+- `Path` sampling (`find_index_and_normalized_distance` avoids the 0/0 on duplicate points; the catmull-rom index clamping and the `computeLength`/`getLowIndexOfNearestPoint` buffer swaps are all correct).
+- `SequenceBehavior` / `SelectorBehavior` initialize/finalize pairing on every reachable exit path; empty-composite handling.
+- `clip_soup_against_overhangs`: half-plane decomposition, scratch-buffer capacity bounds, BVH height-band vs. exact band test agreement, barycentric reconstruction and winding preservation.
+- `optimize_cyclic_sequence_pairwise`: the move/undo pair is self-inverse and the removal+insertion gain exactly equals the true (directed) cyclic edge-set delta, including the wrap cases.
+- MCTS `computeNodeSelectionScore` UCB1 term (no `log(0)`, no divide-by-zero — every materialised node is on the backpropagation path), `backpropagate` sign and walk, `expand`'s no-moves terminal caching.
+- `Blackboard.copy`/`clone`/`reset` coalescence and garbage sweep; `BlackboardStack` lookup order; `AbstractBlackboard.incrementNumber` (`Vector1._add` does dispatch `onChanged`, so the storage adapter is notified).
+- `GridObstacle.resize` (old-width stride is used for the source rows) and `isPointAdjacent` bounds handling.
+- `Transform2GridPositionSystem.write` — the `default:` clause sits above `case Continuous:` in source order but `switch` matches cases before `default`, so `Continuous` is handled correctly.
+- All `Path` and `GridPosition` serialization upgrader chains (field order and widths line up end to end); only the `PathFollower` chain is broken (AI-5).

package/src/REVIEW_2026_08_06/engine-animation.md

@@ -0,0 +1,167 @@
+# Correctness review — `engine/animation/` + `engine/interpolation/`
+
+Scope: every non-spec source file under
+`meep/src/engine/animation/` and `meep/src/engine/interpolation/`
+(plus the prioritised `core/math/spline/spline3_hermite_reverse.js`,
+`spline3_hermite_apply_transform.js`, `spline3_hermite_bounds.js`).
+
+Specs were read as evidence only.
+
+---
+
+## Findings
+
+### ANIM-1 `animation_curve_nearest_point` minimises in normalized-time space but selects in real-time space
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/curve/animation_curve_nearest_point.js:44-60`
+- **Defect**: The per-segment search is handed `ref_t = inverseLerp(key0.time, key1.time, ref_time)` — the reference point re-expressed with its x-axis squeezed into `[0,1]` — while the value axis is left in real units. `spline3_hermite_nearest_point` therefore minimises `(t − ref_t)² + (p(t) − ref_value)²`, a distance in a distorted metric, but the winner is then scored at line 60 with `v2_distance_sqr(curve_time, curve_value, …)` in real `(time, value)` units. The two metrics only coincide when the segment duration is exactly 1, which is the only case the spec file exercises.
+- **Failure scenario**: `const c = AnimationCurve.linear(0, 0, 10, 10);` (keys `(0,0,in 0,out 1)` and `(10,10,in 1,out 0)`, a straight line `y = x`). Call `animation_curve_nearest_point(c, 10, 0)`. In normalized space the segment is `p(t) = 10t`, so minimising `(t−1)² + (10t)²` gives `t = 1/101 ≈ 0.0099`; that maps back to `curve_time ≈ 0.099`, whose real distance² to `(10,0)` is `98.05` — better than the `100` of the seeded candidate `(0,0)`, so it wins. **Returned `0.099`.** The true nearest point on `y = x` to `(10,0)` is `(5,5)` at distance² `50`, i.e. **time `5`**. Downstream, `detectClosestCurveTimePoint` (`curve/draw/isInjectedKeyframeInBounds.js:56`) turns this into a user-visible failure: on any curve whose keys are not ~1 apart, clicking directly on the plotted line reports a curve point tens of pixels away, `mousePosition.distanceTo(...) <= 10` fails, and a keyframe cannot be injected by clicking the curve.
+- **Fix**: Search in a space where both axes carry the same unit. Divide the value axis by `time_delta` as well, then de-normalize:
+  ```js
+  const inv = time_delta === 0 ? 0 : 1 / time_delta;
+  const t = spline3_hermite_nearest_point(
+      ref_t, ref_value * inv,
+      key0.value * inv, key1.value * inv,
+      key0.outTangent, key1.inTangent   // == m0*inv, m1*inv
+  );
+  ```
+  and keep line 58 evaluating the *unscaled* `spline3_hermite(t, key0.value, key1.value, m0, m1)`. (Scaling the whole plane by `1/time_delta` scales every distance by the same factor, so the argmin is preserved and now matches the real-space metric used at line 60.)
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-2 `AnimationTrackPlayback` constructor seeks to absolute 0, not `track.timeStart`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/keyed2/AnimationTrackPlayback.js:36`
+- **Defect**: Line 16 correctly sets `this.position = track.timeStart`, then line 36 overwrites it with `this.setPosition(0)`. For a track whose first key is not at t=0, `setPosition(0)` runs `keyLowerBoundIndexAt(0)`, which returns `-1` ("no key at or before this time"). `__lastKeyIndex` is then `-1`, and `readKeyValues(-1, result)` computes `offset = -propertyCount` and reads off the front of `keyValues`, producing `undefined` → `NaN` in the `Float64Array` value buffer. `reset()` (line 70) and `AnimationBehavior.initialize` (`keyed2/behavior/AnimationBehavior.js:37`) both use `track.timeStart`, so the constructor is the odd one out.
+- **Failure scenario**:
+  ```js
+  const t = new AnimationTrack(['alpha']);
+  t.addKey(1, [10]);            // timeStart = 1
+  t.addKey(2, [20]);            // timeEnd   = 2
+  t.addTransition(0, TransitionFunctions.Linear);
+
+  const p = new AnimationTrackPlayback(t, cb, null);
+  // __lastKeyIndex === -1, __lastTransitionIndex === -1, __nextKeyTime === 1
+  p.update();                   // cb(NaN)   <-- expected cb(10)
+  p.advance(0.016);             // cb(NaN)
+  ```
+  This is reached on the shipping paths that call `update()` before the first tick: `playTrackRealTime.js:26` ("tick animation to make sure the state is synchronized") and `GUIEngine.js:535` ("force view status to initial key of animation"). With such a track the latter writes `el.style.opacity = NaN` and `view.scale.set(NaN, NaN)`. Playbacks driven through `AnimationBehavior` are shielded because `initialize()` re-seeks to `timeStart`; `playAnimationTrack`/direct `advance()` are not.
+- **Fix**: Change line 36 to `this.setPosition(track.timeStart);` (line 16 then becomes redundant). Note the existing spec `"playback starts at position 0 by default"` only covers a track whose `timeStart` is already 0, so it stays green.
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-3 `advanceKey()` leaves a stale `__lastTransitionIndex` when the transition scan runs off the end
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/keyed2/AnimationTrackPlayback.js:135-146`
+- **Defect**: The scan
+  ```js
+  for (let i = this.__lastTransitionIndex + 1; i < transitionCount; i++) { … }
+  ```
+  only writes `__lastTransitionIndex = -1` in the `startKeyIndex > __lastKeyIndex` branch. If the loop exhausts without entering either branch — which happens whenever the new key is at or past the last entry in `transitionKeys` — the previous transition index survives. `readCurrentValues` then takes the transition branch for a key that has no transition, interpolating where `setPosition` (via `transitionIndexAt`, which returns `-1` for the same time) would hold. The loop-wrap case at lines 112-117 has the same root: `__lastKeyIndex` rewinds to `0` but the scan cursor is never rewound to `0`, so a transition on key 0 is missed after the first loop.
+- **Failure scenario A (no loop)**:
+  ```js
+  const t = new AnimationTrack(['scale']);
+  t.addKey(0, [1]); t.addKey(1, [0]); t.addKey(2, [5]);
+  t.addTransition(0, TransitionFunctions.Linear);   // transitionKeys = [0]
+  const p = new AnimationTrackPlayback(t, cb, null); // __lastTransitionIndex = 0
+  p.advanceKey();   // __lastKeyIndex = 1; loop runs from i=1, transitionCount=1 → no iterations
+  p.update();
+  ```
+  `__lastTransitionIndex` is still `0`, so the segment key1→key2 is Linear-interpolated from `0` toward `5`; seeking to the same time with `setPosition(1.0)` yields `__lastTransitionIndex === -1` and holds `0`. Two different poses for the same time on the same track.
+- **Failure scenario B (loop wrap)**: same track plus `t.addTransition(1, TransitionFunctions.EaseOut)` and `p.setLoop(true)`. Advance to the last key (`__lastTransitionIndex === 1`), then `advanceKey()` wraps `__lastKeyIndex` to `0`; the scan starts at `i = 2 >= transitionCount`, so `__lastTransitionIndex` stays `1`. The key0→key1 segment is now driven by `transitionFunctions[1]` (EaseOut) instead of `transitionFunctions[0]` (Linear) — the second and every later loop iteration eases differently from the first.
+- **Fix**: Clear the cursor before scanning and rewind it on wrap:
+  ```js
+  if (wrapped) { this.__lastTransitionIndex = -1; }        // in the loop branch, before += 1
+  const scan_start = this.__lastTransitionIndex + 1;
+  this.__lastTransitionIndex = -1;                          // default: no transition
+  for (let i = scan_start; i < transitionCount; i++) {
+      const startKeyIndex = transitionKeys[i];
+      if (startKeyIndex === this.__lastKeyIndex) { this.__lastTransitionIndex = i; break; }
+      if (startKeyIndex > this.__lastKeyIndex) { break; }
+  }
+  ```
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-4 `AnimationClipBinding.bind()` cannot bind any clip the engine actually produces
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/clip/AnimationClipBinding.js:64-76`
+- **Defect**: Two independent breaks on the same path.
+  1. `binding_registry[track.type]` keys off `AnimationTrack.type`, which defaults to `""` (`clip/AnimationTrack.js:31`). The only producer of `AnimationClip`/`AnimationTrack` in the tree is `convert_three_clip` → `AnimationTrack.from(curves, track_name)` (`clip/ecd_bind_animation_curve.js:106`), which sets `curves` and `name` and **never sets `type`**. Every track therefore looks up `""`.
+  2. Even with a populated registry, the contract is `new WriterClass()` followed by `writer.bind(root, track.path)`. The only writers that can express a vector/quaternion target — `BoundVector3Writer` and `BoundQuaternionWriter` — take their target in the *constructor* and do not override `bind()`, so they inherit `BoundValueWriter.bind` which unconditionally `throw new Error('Not Implemented')` (`curve/binding/BoundValueWriter.js:19`). The one writer that does implement `bind()`, `BoundPlainNumericPropertyWriter`, writes a single scalar (`this.parent[this.property_name] = data[0]`), so it cannot carry a 3- or 4-component track.
+- **Failure scenario**: Import a glTF, get `const cb = convert_three_clip(node, threeClip)` (this is what `SGMeshAnimationControllerSystem.js:78` does), then retarget it to a second skeleton, which is exactly what `bind()` exists for:
+  ```js
+  cb.bind(other_node, { position: BoundVector3Writer, quaternion: BoundQuaternionWriter });
+  ```
+  → throws `No binding class in registry for track type ''` on the first track. Supply `{ "": BoundVector3Writer }` to get past that and it throws `Not Implemented` from `writer.bind`. Note that `bind()` also `splice`s `this.tracks` empty *before* the throw (line 54), so the binding is left destroyed — a clip that rendered fine before the retarget attempt now writes nothing.
+- **Fix**: (a) set `type` in `convert_three_clip` from the property name it already computes (`three_track.name.split('.')` last part, or `three_track.ValueTypeName`) before `AnimationTrack.from(...)`; (b) give `BoundVector3Writer`/`BoundQuaternionWriter` no-arg constructors plus a real `bind(root, path)` that resolves the target the way `bind_property_writer` does, so they satisfy the registry contract; and (c) build the new track list into a local array and only assign it over `this.tracks` once every track bound, so a failure leaves the previous binding intact.
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-5 CUBICSPLINE quaternion tracks are not hemisphere-aligned
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/clip/ecd_bind_animation_curve.js:66-67`
+- **Defect**: The alignment guard is `interpolation === AnimationInterpolationKind.Linear && track.ValueTypeName === 'quaternion'`. A glTF `CUBICSPLINE` rotation track resolves to `AnimationInterpolationKind.CubicTangents` (line 26/32) and so skips `hemisphere_align_quaternion_values` entirely, yet it is still decomposed into four independent scalar Hermite curves (line 74-89) and reassembled by `BoundQuaternionWriter.write` → `fromArray` + `normalize`. Component-wise interpolation across a key pair with a negative dot product takes the long arc. (This is *not* the already-fixed LINEAR case; the in-code comment acknowledges the CubicTangents path as "not yet aligned".)
+- **Failure scenario**: A Blender-exported glTF with `CUBICSPLINE` rotation on a bone, with adjacent keys `q0 = (0, 0, 0, 1)` (identity) and `q1 = (0, 0, −0.0872, −0.9962)` (a −10° Z rotation written in the negative hemisphere; `dot = −0.9962`). Per-component Hermite at the midpoint gives roughly `(0, 0, −0.0436, 0.0019)`; after `normalize()` that is ≈ `(0, 0, −0.999, 0.044)`, i.e. ~175° of Z rotation. The bone whips through nearly a full turn between two keys that are 10° apart, and passes through a near-degenerate quaternion where the normalize is numerically unstable.
+- **Fix**: Align CubicTangents quaternion tracks too, but negate the *whole key triple* — a CUBICSPLINE key is `[inTangent, value, outTangent]` per component, so a sign flip on the value must flip that key's in- and out-tangents as well or the tangents will fight the values. That needs a CubicTangents-aware variant of `hemisphere_align_quaternion_values` operating on a stride of `3 * component_count` and deciding the flip from the value sub-block.
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-6 `acquireInjectedKeyframePosition` uses `time === 0` / `time >= 0` as "unset" sentinels
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/curve/draw/isInjectedKeyframeInBounds.js:76-86`
+- **Defect**: `prevKeyframeRef` and `nextKeyframeRef` are `new Keyframe()`, i.e. `time = 0, value = 0`. The bracketing scan then uses those zeros as sentinels: `kf.time >= prevKeyframeRef.time` treats "0" as "nothing found yet", and `nextKeyframeRef.time === 0` is the "still unset" test. Both are wrong for a curve that has keys at or before t = 0 — `0` is a legitimate keyframe time, and a legitimate keyframe time can be negative.
+- **Failure scenario**: A curve with keys at times `−2, −1, 0, 1` (the editor's frame pans freely into negative time, and `position_canvas_to_curve` maps whatever is on screen). The user clicks on the curve at `timeSplicePosition = −1.5`, which passes the `curveTimePos > curve.keys[0].time` gate. The scan then:
+  - `kf(−2)`: `−2 <= −1.5` ✓ but `−2 >= 0` ✗ → **prev is never captured**, stays the phantom `(0, 0)`;
+  - `kf(−1)`: `−1 >= −1.5` ✓ and `next.time === 0` ✓ → next = `kf(−1)`.
+
+  `segmentTimeDiff = −1 − 0 = −1`, `segmentTimeTravel = −1.5 − 0 = −1.5`, `segmentTimeSplitRatio = 1.5`. `animation_curve_subdivide` is then called with `t = 1.5` (its `assert.ok(t >= 0 && t <= 1)` is compiled out in prod) between the phantom `(0,0)` and `kf(−1)`, so the injected keyframe gets an extrapolated value computed from a keyframe that does not exist. The key lands on the curve at the right time with a visibly wrong value and wrong tangents.
+  A second, independent instance of the same sentinel: with keys at `−1, 0, 1` and a splice at `−0.5`, `kf(0)` is copied into `nextKeyframeRef` but leaves `nextKeyframeRef.time === 0`, so `kf(1)` overwrites it — the "next" key is two keys away.
+- **Fix**: Drop the sentinels and bracket by index, e.g. `const i = curve.getKeyIndexLow(timeSplicePosition);` then `prev = curve.keys[i]`, `next = curve.keys[i + 1]` (with an early-out when `i + 1 >= curve.length`). `getKeyIndexLow` already does this correctly and handles duplicate times.
+- **Confidence**: Confirmed
+
+---
+
+### ANIM-7 `isNotAlreadyAligned` is never called, and the comparison it makes is inverted
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/engine/animation/curve/draw/build_tangent_editor.js:243, 254`
+- **Defect**: Two errors that partially mask each other.
+  1. Line 254: `if (enableTangentAlignment.getValue() === true && isNotAlreadyAligned)` tests the *function object*, not its result. A function is always truthy, so the guard is a no-op.
+  2. Line 243: the predicate itself is `!(keyframe.inTangent === -keyframe.outTangent)`. Alignment in this editor means `inTangent === outTangent` — that is what the drag-time alignment branch produces (`updateTangentValues`, lines 55-63, sets `inTangent = outTangent`) and what `AnimationCurve.alignTangents` produces for a smooth key. The `-` makes the predicate report a *corner* (`in = 1, out = −1`) as "already aligned" and a correctly aligned key (`in = out = 2`) as "not aligned".
+- **Failure scenario**: Select a keyframe whose tangents are already equal, e.g. `Keyframe.from(0.5, 1, 2, 2)`, and tick the "align tangents" checkbox. `modifyTangentAlignmentPosition` runs, computes `avgTangent = 2`, writes the same values back, and still calls `actionProcessor.mark('auto move tangents')` + `actionProcessor.do(new TangentChangeAction(...))`. An undo entry that changes nothing is pushed onto the stack; Ctrl+Z afterwards consumes a step with no visible effect. Conversely, if the missing `()` is added without also fixing the `-`, a corner key (`in = 1, out = −1`) would silently refuse to align — the checkbox would appear to do nothing.
+- **Fix**: `… && isNotAlreadyAligned()` **and** change the predicate body to `return keyframe.inTangent !== keyframe.outTangent;`. (Separately, `Math.abs(newTangent) > Infinity` on line 249 is never true; if a non-finite guard is wanted it should be `!Number.isFinite(newTangent)`.)
+- **Confidence**: Confirmed
+
+---
+
+## Status of the "already known, unconfirmed" items
+
+| Item | Status |
+| --- | --- |
+| `AnimationGraph` JSON dropping state `name`/`tags` | **FIXED** — `writeAnimationGraphDefinitionToJSON.js:69-71` now emits `name` and `tags` for states (and `name`/`tags` for clips); `readAnimationGraphDefinitionFromJSON.js:80-88` destructures `{ motion, type, name, tags = [] }` and assigns both back. |
+| `startingSate` typo | **STILL PRESENT** — the misspelling is load-bearing across the field (`AnimationGraphDefinition.js:29`), the JSON key (`writeAnimationGraphDefinitionToJSON.js:100` / `readAnimationGraphDefinitionFromJSON.js:25,130`), the binary adapter (`AnimationGraphDefinitionSerializationAdapter.js:154,295`) and both readers (`AnimationGraph.js:160,350`). Consistent everywhere, so no behavioural defect — renaming requires a JSON migration. |
+| `AnimationClip.repeatCount` default | **FIXED** — `engine/ecs/animation/AnimationClip.js:9` initialises `new ObservedInteger(1)` and `fromJSON` (lines 83-87) falls back to `this.repeatCount.set(1)` when the field is absent. `toJSON`/`toBinaryBuffer`/`fromBinaryBuffer` all carry the field, so the three paths agree. |
+
+---
+
+## Areas checked and found clean
+
+- **`engine/interpolation/` (whole package)** — `InterpolationSystem` link/unlink is symmetric, `snap` is consumed exactly once per set, per-source playout windows are sampled once per frame and cleared each update, `PoseInterpolationAdapter` does hemisphere-corrected nlerp with renormalize and reduces correctly when `first_offset === second_offset`, `TransformPoseSerializationAdapter` round-trips the same 7 × Float64 layout it declares, `InterpolationLog.interpolate` never reads a stale scratch offset for a tick it failed to locate, and `locate`'s page walk matches the page layout `begin_tick`/`begin_record` write.
+- **`spline3_hermite_reverse`** — verified against `R(u) = H(1−u)`: `R(0) = p1`, `R(1) = p0`, `R'(0) = −m1`, `R'(1) = −m0`; the written order `[p1, p0, −m1, −m0]` matches the `[p0, p1, m0, m1]` layout, and double-reversal is exactly the identity.
+- **`spline3_hermite_apply_transform`** — column-major indexing is right (`m4[0,4,8,12]` for x′), endpoints take the translation column and tangents do not, and the 12 outputs are in the declared `p0/p1/m0/m1` order.
+- **`spline3_hermite_bounds`** (scale-relative change) — the derivative quadratic `a = 3(m0+m1+2p0−2p1)`, `b = −2(2m0+m1+3p0−3p1)`, `c = m0` matches `H′(t)` exactly; the relative `epsilon = max3(|a|,|b|,|c|)·1e-12` correctly degrades to the linear branch without losing interior extrema on small-coordinate curves.
+- **`spline3_hermite_nearest_point`** quintic coefficients — expanded by hand, all six match `(t − ref_t) + (p(t) − ref_p)·p′(t)`. The bug in ANIM-1 is entirely at the call site.
+- **`curve_from_track_data_discrete`** — the reverse `splice` produces `[(t0,v0),(t1,v0),(t1,v1),(t2,v1),(t2,v2)]`; walked through `getKeyIndexLow`/`evaluate` at `t < t1`, `t = t1`, `t1 < t < t2`, `t = t2` and every case gives correct step behaviour with no zero-span division.
+- **`curve_from_track_data_linear`** + `alignTangents` — for each segment `k0.outTangent == k1.inTangent == (v1−v0)/(t1−t0)`, so the Hermite degenerates to exactly the straight line; coincident keys are handled by the `time_span === 0 → 0` branch.
+- **`Tween`** ping-pong turnaround — at `timeElapsed = N·duration`, `cycleWhole = N` and `cycleFraction = 0` give `state = 1` for odd `N` and `0` for even `N`, which is the correct reversal at both ends; the non-oscillating branch fires `ended` once (`destroy()` removes the driving entity in the same call).
+- **`AnimationTrackPlayback.advance`** event semantics — `ended` fires exactly once per forward crossing for a delta larger than the whole clip, and does not re-fire while parked past `timeEnd`; the negative-delta branch correctly avoids the one-shot.
+- **`downsample_float_array_curve_by_error`** — ping-pong buffer sizes (`n/2` and `n/4`) are never overrun as `current_size` halves, and the `target_samples === 1` special case stops the loop before `downsample_float_array` can be handed an odd size.
+- **`animation_curve_optimize`** — the `i--; key_count--` removal step keeps the cursor correct, and the first/last keys are structurally protected.
+- **`animation_curve_fit`** — `calculateTangent` boundary/interior cases are consistent with the tangent convention `evaluate_two_key_curve` uses (`slope × segment duration`), the recursion strictly shrinks, and `splitIndex === -1` is unreachable when `maxSegmentError > maxError`.
+- **`table_find_min_index_in_ordered_column`** — returns the correct lower bound (`minIndex − 1`) on a miss and `−1` before the first sample, which `findLowSampleIndexByTime` clamps.
+- **`AnimationCurveView.draw_key_tangents`** — `in_angle = −atan2(inTangent, −1)` is the angle of `(−1, −m)`, correct for a backward-pointing handle in curve space before the y-flipping transform; `build_tangent_editor.handleTangentUpdate`'s screen-space angles (`π − atan2(in,1)`, `−atan2(out,1)`) are the correct y-down equivalents.