@woosh/meep-engine 3.1.0 → 3.2.0

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

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