@reicek/neataptic-ts 0.1.25 → 0.1.26

package/test/examples/asciiMaze/mazeMovement/README.md

@@ -13,6 +13,14 @@ 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.
 
+### DirectionSelectionStats
+
+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.
+
 ### MazeMovementBufferPools
 
 Initialized pooled buffers shared across maze movement simulations.
@@ -28,13 +36,13 @@ 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.
 
-### DirectionSelectionStats
+### MazeMovementSimulationResult
 
-Diagnostic telemetry produced when selecting a direction from network logits.
+Result shape returned by `MazeMovement.simulateAgent`.
 
-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.
+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.
 
 ### SimulationState
 
@@ -49,14 +57,6 @@ Notes:
 - This interface remains internal to the mazeMovement module boundary.
 - Property descriptions are explicit to surface helpful tooltips in editors.
 
-### MazeMovementSimulationResult
-
-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.
-
 ## mazeMovement/mazeMovement.ts
 
 ### MazeMovement
@@ -202,6 +202,16 @@ 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.
 
+### getMazeMovementBufferMetadata
+
+```ts
+getMazeMovementBufferMetadata(): { cachedWidth: number; cachedHeight: number; }
+```
+
+Read the currently cached maze dimensions for bounds and index helpers.
+
+Returns: Cached width and height for the active pooled buffers.
+
 ### getMazeMovementRunServiceState
 
 ```ts
@@ -212,15 +222,22 @@ Expose the shared mutable run-scoped state used across helper categories.
 
 Returns: The singleton mutable run-state object for the current process.
 
-### resetMazeMovementRunServiceState
+### indexMazeMovementCell
 
 ```ts
-resetMazeMovementRunServiceState(): MazeMovementRunServiceState
+indexMazeMovementCell(
+  x: number,
+  y: number,
+): number
 ```
 
-Reset the shared mutable run-scoped state before a new simulation begins.
+Convert a cell coordinate into the pooled linear grid index.
 
-Returns: The reused singleton state after reset.
+Parameters:
+- `x` - - Zero-based maze column.
+- `y` - - Zero-based maze row.
+
+Returns: Linearized index used by pooled grid buffers.
 
 ### initializeMazeMovementBufferPools
 
@@ -241,42 +258,20 @@ Parameters:
 
 Returns: The initialized pooled buffer surface.
 
-### requireMazeMovementBufferPools
-
-```ts
-requireMazeMovementBufferPools(): MazeMovementBufferPools
-```
-
-Return the initialized pooled buffer surface for the current run.
-
-Returns: The shared buffer pools.
-
-### getMazeMovementBufferMetadata
-
-```ts
-getMazeMovementBufferMetadata(): { cachedWidth: number; cachedHeight: number; }
-```
-
-Read the currently cached maze dimensions for bounds and index helpers.
-
-Returns: Cached width and height for the active pooled buffers.
-
-### indexMazeMovementCell
+### materializeMazeMovementPath
 
 ```ts
-indexMazeMovementCell(
-  x: number,
-  y: number,
-): number
+materializeMazeMovementPath(
+  length: number,
+): [number, number][]
 ```
 
-Convert a cell coordinate into the pooled linear grid index.
+Materialize the active pooled path buffers into a fresh tuple array.
 
 Parameters:
-- `x` - - Zero-based maze column.
-- `y` - - Zero-based maze row.
+- `length` - - Number of active path entries to copy.
 
-Returns: Linearized index used by pooled grid buffers.
+Returns: A newly allocated materialized path snapshot.
 
 ### randomMazeMovementUnit
 
@@ -303,6 +298,26 @@ Parameters:
 
 Returns: Sanitized output history or `undefined` when absent or invalid.
 
+### requireMazeMovementBufferPools
+
+```ts
+requireMazeMovementBufferPools(): MazeMovementBufferPools
+```
+
+Return the initialized pooled buffer surface for the current run.
+
+Returns: The shared buffer pools.
+
+### resetMazeMovementRunServiceState
+
+```ts
+resetMazeMovementRunServiceState(): MazeMovementRunServiceState
+```
+
+Reset the shared mutable run-scoped state before a new simulation begins.
+
+Returns: The reused singleton state after reset.
+
 ### writeMazeMovementOutputHistory
 
 ```ts
@@ -318,21 +333,6 @@ Parameters:
 - `network` - - Network receiving the reflected output history.
 - `history` - - Bounded output-history payload to persist.
 
-### materializeMazeMovementPath
-
-```ts
-materializeMazeMovementPath(
-  length: number,
-): [number, number][]
-```
-
-Materialize the active pooled path buffers into a fresh tuple array.
-
-Parameters:
-- `length` - - Number of active path entries to copy.
-
-Returns: A newly allocated materialized path snapshot.
-
 ## mazeMovement/mazeMovement.constants.ts
 
 Frozen tuning surface for the dedicated mazeMovement module.
@@ -349,20 +349,24 @@ tables in one place so the public facade can stay focused on orchestration.
 
 ## mazeMovement/mazeMovement.utils.ts
 
-### nextPowerOfTwo
+### computeActionEntropyFromCounts
 
 ```ts
-nextPowerOfTwo(
-  n: number,
+computeActionEntropyFromCounts(
+  directionCounts: number[],
+  logActions: number,
+  scratch: Float64Array<ArrayBufferLike>,
 ): number
 ```
 
-Return the smallest power-of-two integer greater than or equal to `n`.
+Compute normalized action entropy from direction counts.
 
 Parameters:
-- `n` - - Target minimum integer capacity.
+- `directionCounts` - - Number of moves taken in each direction.
+- `logActions` - - Precomputed normalization factor for the action space.
+- `scratch` - - Single-value floating-point scratch buffer reused by the caller.
 
-Returns: The smallest power of two greater than or equal to `n`.
+Returns: Normalized entropy in the range `[0, 1]`.
 
 ### isFiniteNumberArray
 
@@ -379,54 +383,54 @@ Parameters:
 
 Returns: True when the input is an array of finite numbers.
 
-### readOutputHistory
+### materializePath
 
 ```ts
-readOutputHistory(
-  network: INetwork,
-): number[][] | undefined
+materializePath(
+  length: number,
+  pathX: Int32Array<ArrayBufferLike>,
+  pathY: Int32Array<ArrayBufferLike>,
+): [number, number][]
 ```
 
-Read the optional `_lastStepOutputs` history stored on a network.
+Materialize the active prefix of pooled path buffers into a fresh array.
 
 Parameters:
-- `network` - - Network instance that may expose a reflected outputs history.
+- `length` - - Number of path entries to materialize.
+- `pathX` - - Pooled X-coordinate buffer.
+- `pathY` - - Pooled Y-coordinate buffer.
 
-Returns: Sanitized history buffer or `undefined` when absent or invalid.
+Returns: A newly allocated array of path tuples.
 
-### writeOutputHistory
+### nextPowerOfTwo
 
 ```ts
-writeOutputHistory(
-  network: INetwork,
-  history: number[][],
-): void
+nextPowerOfTwo(
+  n: number,
+): number
 ```
 
-Persist a bounded outputs history on the network via reflection.
+Return the smallest power-of-two integer greater than or equal to `n`.
 
 Parameters:
-- `network` - - Target network to mutate.
-- `history` - - Updated history buffer.
+- `n` - - Target minimum integer capacity.
 
-### materializePath
+Returns: The smallest power of two greater than or equal to `n`.
+
+### readOutputHistory
 
 ```ts
-materializePath(
-  length: number,
-  pathX: Int32Array<ArrayBufferLike>,
-  pathY: Int32Array<ArrayBufferLike>,
-): [number, number][]
+readOutputHistory(
+  network: INetwork,
+): number[][] | undefined
 ```
 
-Materialize the active prefix of pooled path buffers into a fresh array.
+Read the optional `_lastStepOutputs` history stored on a network.
 
 Parameters:
-- `length` - - Number of path entries to materialize.
-- `pathX` - - Pooled X-coordinate buffer.
-- `pathY` - - Pooled Y-coordinate buffer.
+- `network` - - Network instance that may expose a reflected outputs history.
 
-Returns: A newly allocated array of path tuples.
+Returns: Sanitized history buffer or `undefined` when absent or invalid.
 
 ### sumVisionGroup
 
@@ -449,21 +453,17 @@ Parameters:
 
 Returns: Numeric sum of the selected group.
 
-### computeActionEntropyFromCounts
+### writeOutputHistory
 
 ```ts
-computeActionEntropyFromCounts(
-  directionCounts: number[],
-  logActions: number,
-  scratch: Float64Array<ArrayBufferLike>,
-): number
+writeOutputHistory(
+  network: INetwork,
+  history: number[][],
+): void
 ```
 
-Compute normalized action entropy from direction counts.
+Persist a bounded outputs history on the network via reflection.
 
 Parameters:
-- `directionCounts` - - Number of moves taken in each direction.
-- `logActions` - - Precomputed normalization factor for the action space.
-- `scratch` - - Single-value floating-point scratch buffer reused by the caller.
-
-Returns: Normalized entropy in the range `[0, 1]`.
+- `network` - - Target network to mutate.
+- `history` - - Updated history buffer.

package/test/examples/asciiMaze/mazeMovement/finalization/README.md

@@ -20,22 +20,20 @@ pile of counters.
 
 ## mazeMovement/finalization/mazeMovement.finalization.ts
 
-### finalizeSuccessfulMazeMovementRun
+### computeMazeMovementActionEntropy
 
 ```ts
-finalizeSuccessfulMazeMovementRun(
-  state: SimulationState,
-  maxSteps: number,
-): MazeMovementSimulationResult
+computeMazeMovementActionEntropy(
+  directionCounts: number[],
+): number
 ```
 
-Build the finalized payload for a successful maze run.
+Compute the normalized action-entropy summary for a finished run.
 
 Parameters:
-- `state` - - Completed simulation state for the successful run.
-- `maxSteps` - - Maximum allowed step budget for the run.
+- `directionCounts` - - Per-direction action counts recorded during the run.
 
-Returns: Success result with fitness, path, and diagnostic summaries.
+Returns: Normalized entropy in the range `[0, 1]`.
 
 ### finalizeFailedMazeMovementRun
 
@@ -60,17 +58,19 @@ Parameters:
 
 Returns: Failure result with shaped fitness, path, and diagnostic summaries.
 
-### computeMazeMovementActionEntropy
+### finalizeSuccessfulMazeMovementRun
 
 ```ts
-computeMazeMovementActionEntropy(
-  directionCounts: number[],
-): number
+finalizeSuccessfulMazeMovementRun(
+  state: SimulationState,
+  maxSteps: number,
+): MazeMovementSimulationResult
 ```
 
-Compute the normalized action-entropy summary for a finished run.
+Build the finalized payload for a successful maze run.
 
 Parameters:
-- `directionCounts` - - Per-direction action counts recorded during the run.
+- `state` - - Completed simulation state for the successful run.
+- `maxSteps` - - Maximum allowed step budget for the run.
 
-Returns: Normalized entropy in the range `[0, 1]`.
+Returns: Success result with fitness, path, and diagnostic summaries.

package/test/examples/asciiMaze/mazeMovement/policy/README.md

@@ -18,57 +18,39 @@ trainer judges the consequences of that choice.
 
 ## mazeMovement/policy/mazeMovement.policy.ts
 
-### computeMazeMovementEpsilon
-
-```ts
-computeMazeMovementEpsilon(
-  stepNumber: number,
-  stepsSinceImprovement: number,
-  distHere: number,
-  saturations: number,
-): number
-```
-
-Compute the adaptive epsilon used for policy exploration.
-
-Parameters:
-- `stepNumber` - - Global step number inside the active simulation.
-- `stepsSinceImprovement` - - Number of steps without improvement.
-- `distHere` - - Current distance to goal for the active position.
-- `saturations` - - Rolling saturation count from the shared run state.
-
-Returns: Exploration epsilon in the range `[0, 1]`.
-
-### selectMazeMovementDirection
+### applyMazeMovementEpsilonExploration
 
 ```ts
-selectMazeMovementDirection(
-  outputs: number[],
-): DirectionSelectionStats
+applyMazeMovementEpsilonExploration(
+  state: SimulationState,
+  encodedMaze: number[][],
+  coordinateScratch: Int32Array<ArrayBufferLike>,
+): void
 ```
 
-Convert raw network outputs into a chosen direction plus diagnostics.
+Apply epsilon-greedy exploration to the current action choice.
 
 Parameters:
-- `outputs` - - Raw action logits for the four maze directions.
-
-Returns: Chosen direction plus softmax and entropy diagnostics.
+- `state` - - Mutable simulation state for the active run.
+- `encodedMaze` - - Maze grid used for move validity checks.
+- `coordinateScratch` - - Reused coordinate scratch buffer.
 
-### decideMazeMovementDirection
+### applyMazeMovementForcedExploration
 
 ```ts
-decideMazeMovementDirection(
+applyMazeMovementForcedExploration(
   state: SimulationState,
-  network: INetwork,
+  encodedMaze: number[][],
   coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Activate the network, record output history, and choose the next direction.
+Force a random valid move when the policy has stalled with repeated no-move outputs.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `network` - - Policy network used for the current step.
+- `encodedMaze` - - Maze grid used for move validity checks.
+- `coordinateScratch` - - Reused coordinate scratch buffer.
 
 ### applyMazeMovementProximityGreedy
 
@@ -89,55 +71,73 @@ Parameters:
 - `distanceMap` - - Optional precomputed distance map.
 - `coordinateScratch` - - Reused coordinate scratch buffer.
 
-### applyMazeMovementEpsilonExploration
+### applyMazeMovementSaturationAndBiasAdjust
 
 ```ts
-applyMazeMovementEpsilonExploration(
+applyMazeMovementSaturationAndBiasAdjust(
   state: SimulationState,
-  encodedMaze: number[][],
+  outputs: number[],
+  network: INetwork,
   coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Apply epsilon-greedy exploration to the current action choice.
+Detect saturation and optionally damp output-node biases.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `encodedMaze` - - Maze grid used for move validity checks.
-- `coordinateScratch` - - Reused coordinate scratch buffer.
+- `outputs` - - Raw network logits for the current step.
+- `network` - - Policy network that produced the logits.
+- `coordinateScratch` - - Reused scratch buffer for temporary penalties.
 
-### applyMazeMovementForcedExploration
+### computeMazeMovementEpsilon
 
 ```ts
-applyMazeMovementForcedExploration(
-  state: SimulationState,
-  encodedMaze: number[][],
-  coordinateScratch: Int32Array<ArrayBufferLike>,
-): void
+computeMazeMovementEpsilon(
+  stepNumber: number,
+  stepsSinceImprovement: number,
+  distHere: number,
+  saturations: number,
+): number
 ```
 
-Force a random valid move when the policy has stalled with repeated no-move outputs.
+Compute the adaptive epsilon used for policy exploration.
 
 Parameters:
-- `state` - - Mutable simulation state for the active run.
-- `encodedMaze` - - Maze grid used for move validity checks.
-- `coordinateScratch` - - Reused coordinate scratch buffer.
+- `stepNumber` - - Global step number inside the active simulation.
+- `stepsSinceImprovement` - - Number of steps without improvement.
+- `distHere` - - Current distance to goal for the active position.
+- `saturations` - - Rolling saturation count from the shared run state.
 
-### applyMazeMovementSaturationAndBiasAdjust
+Returns: Exploration epsilon in the range `[0, 1]`.
+
+### decideMazeMovementDirection
 
 ```ts
-applyMazeMovementSaturationAndBiasAdjust(
+decideMazeMovementDirection(
   state: SimulationState,
-  outputs: number[],
   network: INetwork,
   coordinateScratch: Int32Array<ArrayBufferLike>,
 ): void
 ```
 
-Detect saturation and optionally damp output-node biases.
+Activate the network, record output history, and choose the next direction.
 
 Parameters:
 - `state` - - Mutable simulation state for the active run.
-- `outputs` - - Raw network logits for the current step.
-- `network` - - Policy network that produced the logits.
-- `coordinateScratch` - - Reused scratch buffer for temporary penalties.
+- `network` - - Policy network used for the current step.
+
+### selectMazeMovementDirection
+
+```ts
+selectMazeMovementDirection(
+  outputs: number[],
+): DirectionSelectionStats
+```
+
+Convert raw network outputs into a chosen direction plus diagnostics.
+
+Parameters:
+- `outputs` - - Raw action logits for the four maze directions.
+
+Returns: Chosen direction plus softmax and entropy diagnostics.