@reicek/neataptic-ts 0.1.21 → 0.1.22

package/test/examples/asciiMaze/mazeMovement/mazeMovement.services.ts

@@ -0,0 +1,230 @@
+/**
+ * Shared mutable services for the dedicated mazeMovement module.
+ *
+ * This module owns the pooled buffers, PRNG state, output-history plumbing,
+ * and shared run-scoped counters used by the legacy MazeMovement facade while
+ * Step 2 incrementally moves helper categories into the dedicated boundary.
+ */
+
+import type { INetwork } from '../interfaces';
+import type {
+  MazeMovementBufferPools,
+  MazeMovementRunServiceState,
+} from './mazeMovement.types';
+import {
+  isFiniteNumberArray,
+  materializePath,
+  nextPowerOfTwo,
+} from './mazeMovement.utils';
+
+interface InternalMazeMovementBufferPools {
+  visitedFlags: Uint8Array | null;
+  visitCounts: Uint16Array | null;
+  pathX: Int32Array | null;
+  pathY: Int32Array | null;
+  gridCapacity: number;
+  pathCapacity: number;
+  cachedWidth: number;
+  cachedHeight: number;
+}
+
+const BUFFER_POOLS: InternalMazeMovementBufferPools = {
+  visitedFlags: null,
+  visitCounts: null,
+  pathX: null,
+  pathY: null,
+  gridCapacity: 0,
+  pathCapacity: 0,
+  cachedWidth: 0,
+  cachedHeight: 0,
+};
+
+const RUN_SERVICE_STATE: MazeMovementRunServiceState = {
+  saturations: 0,
+  noMoveStreak: 0,
+  prevDistanceStep: undefined,
+};
+
+const PRNG_STATE = {
+  value: null as Uint32Array | null,
+};
+
+/**
+ * Expose the shared mutable run-scoped state used across helper categories.
+ *
+ * @returns The singleton mutable run-state object for the current process.
+ */
+export function getMazeMovementRunServiceState(): MazeMovementRunServiceState {
+  return RUN_SERVICE_STATE;
+}
+
+/**
+ * Reset the shared mutable run-scoped state before a new simulation begins.
+ *
+ * @returns The reused singleton state after reset.
+ */
+export function resetMazeMovementRunServiceState(): MazeMovementRunServiceState {
+  RUN_SERVICE_STATE.saturations = 0;
+  RUN_SERVICE_STATE.noMoveStreak = 0;
+  RUN_SERVICE_STATE.prevDistanceStep = undefined;
+  return RUN_SERVICE_STATE;
+}
+
+/**
+ * Ensure the pooled grid and path buffers are initialized for a run.
+ *
+ * @param width - Maze width in cells.
+ * @param height - Maze height in cells.
+ * @param maxSteps - Maximum path length expected for the run.
+ * @returns The initialized pooled buffer surface.
+ */
+export function initializeMazeMovementBufferPools(
+  width: number,
+  height: number,
+  maxSteps: number,
+): MazeMovementBufferPools {
+  const requiredCellCount = width * height;
+
+  if (
+    BUFFER_POOLS.visitedFlags == null ||
+    requiredCellCount > BUFFER_POOLS.gridCapacity
+  ) {
+    const newCellCapacity = nextPowerOfTwo(requiredCellCount);
+    BUFFER_POOLS.visitedFlags = new Uint8Array(newCellCapacity);
+    BUFFER_POOLS.visitCounts = new Uint16Array(newCellCapacity);
+    BUFFER_POOLS.gridCapacity = newCellCapacity;
+  } else {
+    BUFFER_POOLS.visitedFlags.fill(0, 0, requiredCellCount);
+    BUFFER_POOLS.visitCounts!.fill(0, 0, requiredCellCount);
+  }
+
+  const requiredPathEntries = maxSteps + 1;
+  if (
+    BUFFER_POOLS.pathX == null ||
+    requiredPathEntries > BUFFER_POOLS.pathCapacity
+  ) {
+    const newPathCapacity = nextPowerOfTwo(requiredPathEntries);
+    BUFFER_POOLS.pathX = new Int32Array(newPathCapacity);
+    BUFFER_POOLS.pathY = new Int32Array(newPathCapacity);
+    BUFFER_POOLS.pathCapacity = newPathCapacity;
+  }
+
+  BUFFER_POOLS.cachedWidth = width;
+  BUFFER_POOLS.cachedHeight = height;
+
+  return requireMazeMovementBufferPools();
+}
+
+/**
+ * Return the initialized pooled buffer surface for the current run.
+ *
+ * @returns The shared buffer pools.
+ * @throws Error when a caller reaches the pools before initialization.
+ */
+export function requireMazeMovementBufferPools(): MazeMovementBufferPools {
+  if (
+    BUFFER_POOLS.visitedFlags == null ||
+    BUFFER_POOLS.visitCounts == null ||
+    BUFFER_POOLS.pathX == null ||
+    BUFFER_POOLS.pathY == null
+  ) {
+    throw new Error(
+      'Maze movement buffer pools were used before initialization.',
+    );
+  }
+
+  return BUFFER_POOLS as MazeMovementBufferPools;
+}
+
+/**
+ * Read the currently cached maze dimensions for bounds and index helpers.
+ *
+ * @returns Cached width and height for the active pooled buffers.
+ */
+export function getMazeMovementBufferMetadata(): {
+  cachedWidth: number;
+  cachedHeight: number;
+} {
+  return {
+    cachedWidth: BUFFER_POOLS.cachedWidth,
+    cachedHeight: BUFFER_POOLS.cachedHeight,
+  };
+}
+
+/**
+ * Convert a cell coordinate into the pooled linear grid index.
+ *
+ * @param x - Zero-based maze column.
+ * @param y - Zero-based maze row.
+ * @returns Linearized index used by pooled grid buffers.
+ */
+export function indexMazeMovementCell(x: number, y: number): number {
+  return Math.imul(y, BUFFER_POOLS.cachedWidth) + x;
+}
+
+/**
+ * Generate a pseudo-random number in the range `[0, 1)`.
+ *
+ * @returns A deterministic or host-random unit float for exploration logic.
+ */
+export function randomMazeMovementUnit(): number {
+  const pooledState = PRNG_STATE.value;
+  if (pooledState == null || pooledState.length === 0) {
+    return Math.random();
+  }
+
+  const current = (pooledState[0] + 0x6d2b79f5) >>> 0;
+  pooledState[0] = current;
+
+  let mixed = current;
+  mixed = Math.imul(mixed ^ (mixed >>> 15), mixed | 1) >>> 0;
+  mixed =
+    (mixed ^ (mixed + Math.imul(mixed ^ (mixed >>> 7), mixed | 61))) >>> 0;
+
+  const final32 = (mixed ^ (mixed >>> 14)) >>> 0;
+  return final32 / 4_294_967_296;
+}
+
+/**
+ * Read the reflected `_lastStepOutputs` network history when present.
+ *
+ * @param network - Network that may carry the reflected output history.
+ * @returns Sanitized output history or `undefined` when absent or invalid.
+ */
+export function readMazeMovementOutputHistory(
+  network: INetwork,
+): number[][] | undefined {
+  const historyCandidate = Reflect.get(network as object, '_lastStepOutputs');
+  if (!Array.isArray(historyCandidate)) return undefined;
+  return historyCandidate.every(isFiniteNumberArray)
+    ? (historyCandidate as number[][])
+    : undefined;
+}
+
+/**
+ * Persist the reflected `_lastStepOutputs` network history.
+ *
+ * @param network - Network receiving the reflected output history.
+ * @param history - Bounded output-history payload to persist.
+ */
+export function writeMazeMovementOutputHistory(
+  network: INetwork,
+  history: number[][],
+): void {
+  Reflect.set(network as object, '_lastStepOutputs', history);
+}
+
+/**
+ * Materialize the active pooled path buffers into a fresh tuple array.
+ *
+ * @param length - Number of active path entries to copy.
+ * @returns A newly allocated materialized path snapshot.
+ */
+export function materializeMazeMovementPath(
+  length: number,
+): [number, number][] {
+  const bufferPools = requireMazeMovementBufferPools();
+  return materializePath(length, bufferPools.pathX, bufferPools.pathY);
+}
+
+export {};

package/test/examples/asciiMaze/mazeMovement/mazeMovement.ts

@@ -0,0 +1,299 @@
+/**
+ * Public MazeMovement facade for the dedicated mazeMovement module boundary.
+ *
+ * The folder now owns runtime helpers, policy helpers, shaping helpers, and
+ * finalization logic. This file keeps the user-facing API in one place while
+ * the implementation stays split into focused helpers.
+ */
+
+import type { INetwork } from '../interfaces';
+import type {
+  DirectionSelectionStats,
+  MazeMovementSimulationResult,
+  SimulationState,
+} from './mazeMovement.types';
+import { MAZE_MOVEMENT_CONSTANTS } from './mazeMovement.constants';
+import {
+  decideMazeMovementDirection,
+  selectMazeMovementDirection,
+  applyMazeMovementEpsilonExploration,
+  applyMazeMovementForcedExploration,
+  applyMazeMovementProximityGreedy,
+} from './policy/mazeMovement.policy';
+import {
+  applyMazeMovementPostActionPenalties,
+  executeMazeMovementAndRewards,
+  maybeTerminateMazeMovementDeepStagnation,
+} from './shaping/mazeMovement.shaping';
+import {
+  finalizeFailedMazeMovementRun,
+  finalizeSuccessfulMazeMovementRun,
+} from './finalization/mazeMovement.finalization';
+import {
+  buildMazeMovementVisionAndDistance,
+  createMazeMovementRunState,
+  isMazeMovementCellOpen,
+  recordMazeMovementVisitAndPenalties,
+} from './runtime/mazeMovement.runtime';
+
+const C = MAZE_MOVEMENT_CONSTANTS;
+
+/**
+ * Maze movement entry surface used by fitness evaluation and evolution runs.
+ *
+ * The public API intentionally remains class-based so existing example imports
+ * do not change while the implementation lives under the dedicated module.
+ */
+export class MazeMovement {
+  /** Reused integer coordinate scratch for hot-path movement helpers. */
+  static #COORDINATE_SCRATCH = new Int32Array(2);
+
+  /**
+   * Determine whether a candidate target cell is inside bounds and not a wall.
+   *
+   * @param encodedMaze - Maze grid to inspect.
+   * @param position - Candidate `[x, y]` position.
+   * @returns True when the target cell can be entered.
+   */
+  static isValidMove(
+    encodedMaze: ReadonlyArray<ReadonlyArray<number>>,
+    position: readonly [number, number],
+  ): boolean;
+
+  /**
+   * Determine whether a candidate target cell is inside bounds and not a wall.
+   *
+   * @param encodedMaze - Maze grid to inspect.
+   * @param x - Candidate maze column.
+   * @param y - Candidate maze row.
+   * @returns True when the target cell can be entered.
+   */
+  static isValidMove(
+    encodedMaze: ReadonlyArray<ReadonlyArray<number>>,
+    x: number,
+    y: number,
+  ): boolean;
+
+  static isValidMove(
+    encodedMaze: ReadonlyArray<ReadonlyArray<number>>,
+    positionOrX: readonly [number, number] | number,
+    yMaybe?: number,
+  ): boolean {
+    if (typeof positionOrX === 'number') {
+      const candidateColumn = positionOrX | 0;
+      const candidateRow = (yMaybe ?? 0) | 0;
+      return isMazeMovementCellOpen(
+        encodedMaze,
+        candidateColumn,
+        candidateRow,
+        MazeMovement.#COORDINATE_SCRATCH,
+      );
+    }
+
+    if (!Array.isArray(positionOrX) || positionOrX.length !== 2) return false;
+
+    const [candidateColumn, candidateRow] = positionOrX;
+    return isMazeMovementCellOpen(
+      encodedMaze,
+      candidateColumn,
+      candidateRow,
+      MazeMovement.#COORDINATE_SCRATCH,
+    );
+  }
+
+  /**
+   * Move the agent one step in the requested direction when the target cell is open.
+   *
+   * @param encodedMaze - Maze grid used for collision checks.
+   * @param position - Current agent position.
+   * @param direction - Direction index in the action space.
+   * @returns New position when the move is valid, otherwise the original position.
+   * @example
+   * const moved = MazeMovement.moveAgent(encodedMaze, [3, 2], 1);
+   */
+  static moveAgent(
+    encodedMaze: ReadonlyArray<ReadonlyArray<number>>,
+    position: readonly [number, number],
+    direction: number,
+  ): [number, number] {
+    if (direction === C.NO_MOVE) {
+      return [position[0], position[1]];
+    }
+
+    const nextPosition: [number, number] = [position[0], position[1]];
+    if (direction >= 0 && direction < C.ACTION_DIM) {
+      const [deltaColumn, deltaRow] = C.DIRECTION_DELTAS[direction];
+      nextPosition[0] += deltaColumn;
+      nextPosition[1] += deltaRow;
+    }
+
+    return MazeMovement.isValidMove(encodedMaze, nextPosition)
+      ? nextPosition
+      : [position[0], position[1]];
+  }
+
+  /**
+   * Convert raw network outputs into a chosen action plus diagnostics.
+   *
+   * @param outputs - Raw action logits for the four maze directions.
+   * @returns Chosen direction plus softmax and entropy diagnostics.
+   * @example
+   * const stats = MazeMovement.selectDirection([0.2, 1.4, -0.1, 0]);
+   */
+  static selectDirection(outputs: number[]): DirectionSelectionStats {
+    return selectMazeMovementDirection(outputs);
+  }
+
+  /**
+   * Simulate one full maze episode for a network-controlled agent.
+   *
+   * @param network - Policy network used to choose actions.
+   * @param encodedMaze - Maze grid for the active episode.
+   * @param startPos - Start coordinate.
+   * @param exitPos - Exit coordinate.
+   * @param distanceMap - Optional precomputed distance map.
+   * @param maxSteps - Maximum allowed step count before termination.
+   * @returns Final simulation result including path, fitness, and progress.
+   */
+  static simulateAgent(
+    network: INetwork,
+    encodedMaze: number[][],
+    startPos: readonly [number, number],
+    exitPos: readonly [number, number],
+    distanceMap?: number[][],
+    maxSteps: number = C.DEFAULT_MAX_STEPS,
+  ): MazeMovementSimulationResult {
+    const simulationState = createMazeMovementRunState(
+      encodedMaze,
+      startPos,
+      distanceMap,
+      maxSteps,
+    );
+
+    while (simulationState.steps < maxSteps) {
+      simulationState.steps++;
+
+      // Step 1: refresh visit bookkeeping, perception, and policy choice.
+      MazeMovement.#processPerceptionAndPolicy(
+        simulationState,
+        network,
+        encodedMaze,
+        exitPos,
+        distanceMap,
+      );
+
+      // Step 2: execute the chosen action, apply shaping, and stop if needed.
+      const shouldStop = MazeMovement.#processMovementAndShaping(
+        simulationState,
+        encodedMaze,
+        distanceMap,
+      );
+      if (shouldStop) break;
+
+      // Step 3: finalize immediately when the exit is reached.
+      if (MazeMovement.#hasReachedExit(simulationState, exitPos)) {
+        return finalizeSuccessfulMazeMovementRun(simulationState, maxSteps);
+      }
+    }
+
+    return finalizeFailedMazeMovementRun(
+      simulationState,
+      encodedMaze,
+      startPos,
+      exitPos,
+      distanceMap,
+    );
+  }
+
+  /**
+   * Refresh visit bookkeeping, perception state, and direction policy.
+   *
+   * @param simulationState - Mutable run state for the active episode.
+   * @param network - Policy network used for action selection.
+   * @param encodedMaze - Maze grid used for the run.
+   * @param exitPos - Exit coordinate for the run.
+   * @param distanceMap - Optional precomputed distance map.
+   */
+  static #processPerceptionAndPolicy(
+    simulationState: SimulationState,
+    network: INetwork,
+    encodedMaze: number[][],
+    exitPos: readonly [number, number],
+    distanceMap?: number[][],
+  ): void {
+    recordMazeMovementVisitAndPenalties(simulationState);
+    buildMazeMovementVisionAndDistance(
+      simulationState,
+      encodedMaze,
+      exitPos,
+      distanceMap,
+    );
+    decideMazeMovementDirection(
+      simulationState,
+      network,
+      MazeMovement.#COORDINATE_SCRATCH,
+    );
+    applyMazeMovementProximityGreedy(
+      simulationState,
+      encodedMaze,
+      distanceMap,
+      MazeMovement.#COORDINATE_SCRATCH,
+    );
+    applyMazeMovementEpsilonExploration(
+      simulationState,
+      encodedMaze,
+      MazeMovement.#COORDINATE_SCRATCH,
+    );
+    applyMazeMovementForcedExploration(
+      simulationState,
+      encodedMaze,
+      MazeMovement.#COORDINATE_SCRATCH,
+    );
+  }
+
+  /**
+   * Execute the selected move, apply post-action shaping, and evaluate stop rules.
+   *
+   * @param simulationState - Mutable run state for the active episode.
+   * @param encodedMaze - Maze grid used for movement and distance lookup.
+   * @param distanceMap - Optional precomputed distance map.
+   * @returns True when the episode should stop after this step.
+   */
+  static #processMovementAndShaping(
+    simulationState: SimulationState,
+    encodedMaze: number[][],
+    distanceMap?: number[][],
+  ): boolean {
+    executeMazeMovementAndRewards(
+      simulationState,
+      encodedMaze,
+      distanceMap,
+      MazeMovement.#COORDINATE_SCRATCH,
+    );
+    applyMazeMovementPostActionPenalties(
+      simulationState,
+      MazeMovement.#COORDINATE_SCRATCH,
+    );
+    return maybeTerminateMazeMovementDeepStagnation(
+      simulationState,
+      MazeMovement.#COORDINATE_SCRATCH,
+    );
+  }
+
+  /**
+   * Determine whether the current state has reached the maze exit.
+   *
+   * @param simulationState - Mutable run state for the active episode.
+   * @param exitPos - Exit coordinate for the run.
+   * @returns True when the agent position matches the exit coordinate.
+   */
+  static #hasReachedExit(
+    simulationState: SimulationState,
+    exitPos: readonly [number, number],
+  ): boolean {
+    return (
+      simulationState.position[0] === exitPos[0] &&
+      simulationState.position[1] === exitPos[1]
+    );
+  }
+}

package/test/examples/asciiMaze/mazeMovement/mazeMovement.types.ts

@@ -0,0 +1,185 @@
+/**
+ * Shared type surface for the dedicated mazeMovement module.
+ *
+ * Step 2 moves internal simulation contracts here first so later helper files
+ * can depend on one narrow typed surface.
+ */
+
+/**
+ * Initialized pooled buffers shared across maze movement simulations.
+ *
+ * These pools are reused between runs to keep the hot path allocation-light
+ * while preserving a narrow typed seam for service helpers.
+ */
+export interface MazeMovementBufferPools {
+  /** Reused per-cell visited flags aligned to the current maze dimensions. */
+  visitedFlags: Uint8Array;
+  /** Reused per-cell visit counters aligned to the current maze dimensions. */
+  visitCounts: Uint16Array;
+  /** Reused X-coordinate path buffer for the active simulation. */
+  pathX: Int32Array;
+  /** Reused Y-coordinate path buffer for the active simulation. */
+  pathY: Int32Array;
+  /** Cached maze width used by index helpers. */
+  cachedWidth: number;
+  /** Cached maze height used by bounds helpers. */
+  cachedHeight: number;
+}
+
+/**
+ * Mutable run-scoped service state shared by the mazeMovement facade.
+ *
+ * The dedicated services module owns these counters so later runtime, policy,
+ * and shaping helpers can depend on one explicit mutable surface instead of
+ * directly reaching into class-private state.
+ */
+export interface MazeMovementRunServiceState {
+  /** Rolling saturation counter used by adaptive penalties and epsilon logic. */
+  saturations: number;
+  /** Consecutive no-move counter used to force exploration. */
+  noMoveStreak: number;
+  /** Previous distance value fed into the next vision-builder call. */
+  prevDistanceStep: number | undefined;
+}
+
+/**
+ * Diagnostic telemetry produced when selecting a direction from network logits.
+ *
+ * Encapsulates the chosen direction along with entropy and probability data so
+ * downstream helpers can apply shaping rewards and penalties without
+ * rederiving softmax statistics on hot paths.
+ */
+export interface DirectionSelectionStats {
+  /** Chosen action index (0..#ACTION_DIM-1) or -1 when no move is selected. */
+  direction: number;
+  /** Defensive copy of per-action softmax probabilities. */
+  softmax: number[];
+  /** Normalised entropy of the action distribution in [0,1]. */
+  entropy: number;
+  /** Probability assigned to the chosen action. */
+  maxProb: number;
+  /** Probability assigned to the runner-up action. */
+  secondProb: number;
+}
+
+/**
+ * Internal aggregate state used during a single agent simulation run.
+ *
+ * Purpose:
+ * - Hold all derived runtime values, counters and diagnostic stats used by the
+ *   MazeMovement simulation helpers. This shape is intentionally rich so tests
+ *   and visualisers can inspect intermediate state when debugging.
+ *
+ * Notes:
+ * - This interface remains internal to the mazeMovement module boundary.
+ * - Property descriptions are explicit to surface helpful tooltips in editors.
+ */
+export interface SimulationState {
+  /** Current mutable agent position as [x, y]. */
+  position: [number, number];
+
+  /** Number of simulation steps executed so far (increments each loop). */
+  steps: number;
+
+  /** Number of entries in the recorded path (index into pooled PathX/PathY). */
+  pathLength: number;
+
+  /** Count of distinct cells visited during this run. */
+  visitedUniqueCount: number;
+
+  /** True when a precomputed distance map was supplied to the simulation. */
+  hasDistanceMap: boolean;
+
+  /** Optional precomputed distance map (rows × cols) used for fast heuristics. */
+  distanceMap?: number[][];
+
+  /** Minimum observed distance-to-exit reached so far (lower is better). */
+  minDistanceToExit: number;
+
+  /** Accumulated shaping reward derived from forward progress signals. */
+  progressReward: number;
+
+  /** Bonus accumulated when entering previously unvisited cells. */
+  newCellExplorationBonus: number;
+
+  /** Accumulated penalty from invalid moves, loops and other negative signals. */
+  invalidMovePenalty: number;
+
+  /** Index of the previous action/direction taken (-1 for no-move). */
+  prevAction: number;
+
+  /** Steps elapsed since the last observed improvement toward the goal. */
+  stepsSinceImprovement: number;
+
+  /** Last global distance-to-exit used for long-term improvement checks. */
+  lastDistanceGlobal: number;
+
+  /** Number of steps flagged as 'saturated' (network overconfident/flat outputs). */
+  saturatedSteps: number;
+
+  /** Recent positions sliding window used to detect local oscillation/stagnation. */
+  recentPositions: [number, number][];
+
+  /** Penalty applied when agent is oscillating in a tight local region. */
+  localAreaPenalty: number;
+
+  /** Counters of moves taken per direction index (N,E,S,W). */
+  directionCounts: number[];
+
+  /** Ring buffer storing recent visited cell indices for A↔B loop detection. */
+  moveHistoryRing: Int32Array;
+
+  /** Current number of populated entries in `moveHistoryRing`. */
+  moveHistoryLength: number;
+  /** Index pointer (head) into the circular moveHistoryRing. */
+  moveHistoryHead: number;
+  /** Current linearized cell index for the agent position. */
+  currentCellIndex: number;
+  /** Penalty accumulated for short A<->B oscillation detection. */
+  loopPenalty: number;
+  /** Penalty applied for returning to any recent cell (memory-based). */
+  memoryPenalty: number;
+  /** Dynamic revisit penalty scaled by per-cell visit counts. */
+  revisitPenalty: number;
+  /** Visit count at the current cell (derived from VisitCounts pool). */
+  visitsAtCurrent: number;
+  /** Current distance-to-goal measured at agent position. */
+  distHere: number;
+  /** Per-step perception/vision vector built for the network. */
+  vision: number[];
+  /** Network action statistics (softmax, entropy, etc.) populated each step. */
+  actionStats: DirectionSelectionStats | null;
+  /** Currently selected direction index (0..3) or #-NO_MOVE. */
+  direction: number;
+  /** Whether the agent moved on the last executed action. */
+  moved: boolean;
+  /** Distance value measured before executing the current action (previous step). */
+  prevDistance: number;
+
+  /** When true the simulation loop should terminate early due to safety triggers. */
+  earlyTerminate: boolean;
+}
+
+/**
+ * Result shape returned by `MazeMovement.simulateAgent`.
+ *
+ * This contract matches the legacy inline return annotation so callers can
+ * keep depending on the current fields while the dedicated module boundary is
+ * being extracted.
+ */
+export interface MazeMovementSimulationResult {
+  /** Whether the run reached the maze exit. */
+  success: boolean;
+  /** Number of steps executed before success or failure finalization. */
+  steps: number;
+  /** Materialized path snapshot for the finished run. */
+  path: readonly [number, number][];
+  /** Final shaped fitness for the run. */
+  fitness: number;
+  /** Progress percentage toward the exit. */
+  progress: number;
+  /** Optional fraction of saturated steps observed during the run. */
+  saturationFraction?: number;
+  /** Optional action-entropy summary derived from direction counts. */
+  actionEntropy?: number;
+}