@reicek/neataptic-ts 0.1.21 → 0.1.22

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

@@ -0,0 +1,153 @@
+import type { INetwork } from '../interfaces';
+
+/**
+ * Return the smallest power-of-two integer greater than or equal to `n`.
+ *
+ * @param n - Target minimum integer capacity.
+ * @returns The smallest power of two greater than or equal to `n`.
+ */
+export function nextPowerOfTwo(n: number): number {
+  const requested = Math.max(1, Math.floor(n));
+  if (requested <= 1) return 1;
+
+  if (requested <= 0xffffffff) {
+    const value = (requested - 1) >>> 0;
+    const leadingZeros = Math.clz32(value);
+    const exponent = 32 - leadingZeros;
+    const clampedExponent = Math.min(31, Math.max(0, exponent));
+    const power = 1 << clampedExponent;
+    return power >= requested ? power : power << 1;
+  }
+
+  let power = 1;
+  while (power < requested) power *= 2;
+  return power;
+}
+
+/**
+ * Determine whether the provided value is a finite-number array.
+ *
+ * @param candidate - Value to inspect.
+ * @returns True when the input is an array of finite numbers.
+ */
+export function isFiniteNumberArray(candidate: unknown): candidate is number[] {
+  return (
+    Array.isArray(candidate) &&
+    candidate.every(
+      (value: unknown) => typeof value === 'number' && Number.isFinite(value),
+    )
+  );
+}
+
+/**
+ * Read the optional `_lastStepOutputs` history stored on a network.
+ *
+ * @param network - Network instance that may expose a reflected outputs history.
+ * @returns Sanitized history buffer or `undefined` when absent or invalid.
+ */
+export function readOutputHistory(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 a bounded outputs history on the network via reflection.
+ *
+ * @param network - Target network to mutate.
+ * @param history - Updated history buffer.
+ */
+export function writeOutputHistory(
+  network: INetwork,
+  history: number[][],
+): void {
+  Reflect.set(network as object, '_lastStepOutputs', history);
+}
+
+/**
+ * Materialize the active prefix of pooled path buffers into a fresh array.
+ *
+ * @param length - Number of path entries to materialize.
+ * @param pathX - Pooled X-coordinate buffer.
+ * @param pathY - Pooled Y-coordinate buffer.
+ * @returns A newly allocated array of path tuples.
+ */
+export function materializePath(
+  length: number,
+  pathX: Int32Array,
+  pathY: Int32Array,
+): [number, number][] {
+  const entries = Math.max(0, Math.floor(length));
+  if (entries === 0) return [];
+
+  const output = new Array<[number, number]>(entries);
+  for (let index = 0; index < entries; index++) {
+    output[index] = [pathX[index], pathY[index]];
+  }
+
+  return output;
+}
+
+/**
+ * Sum a contiguous group of entries from a vision vector into a reusable scratch buffer.
+ *
+ * @param vision - Flat perception vector.
+ * @param start - Start index of the group to sum.
+ * @param groupLength - Number of entries in the group.
+ * @param scratch - Reusable scratch buffer populated with copied values.
+ * @returns Numeric sum of the selected group.
+ */
+export function sumVisionGroup(
+  vision: number[],
+  start: number,
+  groupLength: number,
+  scratch: Float64Array,
+): number {
+  const sanitizedStart = Math.max(0, start | 0);
+  const clampedEnd = Math.min(vision.length, sanitizedStart + groupLength);
+  if (sanitizedStart >= clampedEnd) return 0;
+
+  let sumAccumulator = 0;
+  let writeIndex = 0;
+  for (let readIndex = sanitizedStart; readIndex < clampedEnd; readIndex++) {
+    const value = vision[readIndex] ?? 0;
+    scratch[writeIndex++] = value;
+    sumAccumulator += value;
+  }
+
+  return sumAccumulator;
+}
+
+/**
+ * Compute normalized action entropy from direction counts.
+ *
+ * @param directionCounts - Number of moves taken in each direction.
+ * @param logActions - Precomputed normalization factor for the action space.
+ * @param scratch - Single-value floating-point scratch buffer reused by the caller.
+ * @returns Normalized entropy in the range `[0, 1]`.
+ */
+export function computeActionEntropyFromCounts(
+  directionCounts: number[],
+  logActions: number,
+  scratch: Float64Array,
+): number {
+  const totalCount =
+    directionCounts.reduce((sum, value) => sum + (value | 0), 0) || 1;
+
+  scratch[0] = 0;
+  const logFn = Math.log;
+  for (
+    let directionIndex = 0, directionCount = directionCounts.length;
+    directionIndex < directionCount;
+    directionIndex++
+  ) {
+    const count = directionCounts[directionIndex] | 0;
+    if (count === 0) continue;
+    const probability = count / totalCount;
+    scratch[0] -= probability * logFn(probability);
+  }
+
+  return scratch[0] / logActions;
+}

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

@@ -0,0 +1,91 @@
+# mazeMovement/policy
+
+## mazeMovement/policy/mazeMovement.policy.ts
+
+### mazeMovement.policy
+
+Action policy helpers for the dedicated mazeMovement module.
+
+This file owns direction selection, epsilon handling, short-horizon policy
+overrides, and saturation-driven bias control.
+
+### applyMazeMovementEpsilonExploration
+
+`(state: import("test/examples/asciiMaze/mazeMovement/mazeMovement.types").SimulationState, encodedMaze: number[][], coordinateScratch: Int32Array<ArrayBufferLike>) => void`
+
+Apply epsilon-greedy exploration to the current action choice.
+
+Parameters:
+- `state` - - Mutable simulation state for the active run.
+- `encodedMaze` - - Maze grid used for move validity checks.
+- `coordinateScratch` - - Reused coordinate scratch buffer.
+
+### applyMazeMovementForcedExploration
+
+`(state: import("test/examples/asciiMaze/mazeMovement/mazeMovement.types").SimulationState, encodedMaze: number[][], coordinateScratch: Int32Array<ArrayBufferLike>) => void`
+
+Force a random valid move when the policy has stalled with repeated no-move outputs.
+
+Parameters:
+- `state` - - Mutable simulation state for the active run.
+- `encodedMaze` - - Maze grid used for move validity checks.
+- `coordinateScratch` - - Reused coordinate scratch buffer.
+
+### applyMazeMovementProximityGreedy
+
+`(state: import("test/examples/asciiMaze/mazeMovement/mazeMovement.types").SimulationState, encodedMaze: number[][], distanceMap: number[][] | undefined, coordinateScratch: Int32Array<ArrayBufferLike>) => void`
+
+Apply the short-horizon proximity-greedy override near the maze exit.
+
+Parameters:
+- `state` - - Mutable simulation state for the active run.
+- `encodedMaze` - - Maze grid used for move validity checks.
+- `distanceMap` - - Optional precomputed distance map.
+- `coordinateScratch` - - Reused coordinate scratch buffer.
+
+### applyMazeMovementSaturationAndBiasAdjust
+
+`(state: import("test/examples/asciiMaze/mazeMovement/mazeMovement.types").SimulationState, outputs: number[], network: import("test/examples/asciiMaze/interfaces").INetwork, coordinateScratch: Int32Array<ArrayBufferLike>) => void`
+
+Detect saturation and optionally damp output-node biases.
+
+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.
+
+### 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]`.
+
+### decideMazeMovementDirection
+
+`(state: import("test/examples/asciiMaze/mazeMovement/mazeMovement.types").SimulationState, network: import("test/examples/asciiMaze/interfaces").INetwork, coordinateScratch: Int32Array<ArrayBufferLike>) => void`
+
+Activate the network, record output history, and choose the next direction.
+
+Parameters:
+- `state` - - Mutable simulation state for the active run.
+- `network` - - Policy network used for the current step.
+
+### selectMazeMovementDirection
+
+`(outputs: number[]) => import("test/examples/asciiMaze/mazeMovement/mazeMovement.types").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.

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

@@ -0,0 +1,467 @@
+/**
+ * Action policy helpers for the dedicated mazeMovement module.
+ *
+ * This file owns direction selection, epsilon handling, short-horizon policy
+ * overrides, and saturation-driven bias control.
+ */
+
+import type { INetwork, INodeStruct } from '../../interfaces';
+import { MazeUtils } from '../../mazeUtils';
+import { MAZE_MOVEMENT_CONSTANTS } from '../mazeMovement.constants';
+import {
+  getMazeMovementRunServiceState,
+  randomMazeMovementUnit,
+  readMazeMovementOutputHistory,
+  writeMazeMovementOutputHistory,
+} from '../mazeMovement.services';
+import type {
+  DirectionSelectionStats,
+  SimulationState,
+} from '../mazeMovement.types';
+import {
+  getMazeMovementDistance,
+  isMazeMovementCellOpen,
+} from '../runtime/mazeMovement.runtime';
+
+const C = MAZE_MOVEMENT_CONSTANTS;
+const POLICY_SCRATCH_CENTERED = new Float64Array(4);
+const POLICY_SCRATCH_EXPS = new Float64Array(4);
+const POLICY_SOFTMAX = new Float64Array(4);
+
+/**
+ * Compute the adaptive epsilon used for policy exploration.
+ *
+ * @param stepNumber - Global step number inside the active simulation.
+ * @param stepsSinceImprovement - Number of steps without improvement.
+ * @param distHere - Current distance to goal for the active position.
+ * @param saturations - Rolling saturation count from the shared run state.
+ * @returns Exploration epsilon in the range `[0, 1]`.
+ */
+export function computeMazeMovementEpsilon(
+  stepNumber: number,
+  stepsSinceImprovement: number,
+  distHere: number,
+  saturations: number,
+): number {
+  const isWarmup = stepNumber < C.EPSILON_WARMUP_STEPS;
+  const isHighlyStagnant =
+    stepsSinceImprovement > C.EPSILON_STAGNANT_HIGH_THRESHOLD;
+  const isModeratelyStagnant =
+    stepsSinceImprovement > C.EPSILON_STAGNANT_MED_THRESHOLD;
+  const isSaturationTriggered = saturations > C.EPSILON_SATURATION_TRIGGER;
+
+  let chosenEpsilon = 0;
+  switch (true) {
+    case isWarmup:
+      chosenEpsilon = C.EPSILON_INITIAL;
+      break;
+    case isHighlyStagnant:
+      chosenEpsilon = C.EPSILON_STAGNANT_HIGH;
+      break;
+    case isModeratelyStagnant:
+      chosenEpsilon = C.EPSILON_STAGNANT_MED;
+      break;
+    case isSaturationTriggered:
+      chosenEpsilon = C.EPSILON_SATURATIONS;
+      break;
+    default:
+      break;
+  }
+
+  if (distHere <= C.PROXIMITY_SUPPRESS_EXPLOR_DIST) {
+    chosenEpsilon = Math.min(chosenEpsilon, C.EPSILON_MIN_NEAR_GOAL);
+  }
+
+  return chosenEpsilon;
+}
+
+/**
+ * Convert raw network outputs into a chosen direction plus diagnostics.
+ *
+ * @param outputs - Raw action logits for the four maze directions.
+ * @returns Chosen direction plus softmax and entropy diagnostics.
+ */
+export function selectMazeMovementDirection(
+  outputs: number[],
+): DirectionSelectionStats {
+  const actionCount = C.ACTION_DIM;
+  if (!Array.isArray(outputs) || outputs.length !== actionCount) {
+    return {
+      direction: C.NO_MOVE,
+      softmax: Array.from(POLICY_SOFTMAX),
+      entropy: 0,
+      maxProb: 0,
+      secondProb: 0,
+    };
+  }
+
+  let outputSum = 0;
+  for (let actionIndex = 0; actionIndex < actionCount; actionIndex++) {
+    outputSum += outputs[actionIndex];
+  }
+  const meanOutput = outputSum / actionCount;
+
+  let varianceAccumulator = 0;
+  for (let actionIndex = 0; actionIndex < actionCount; actionIndex++) {
+    const delta = outputs[actionIndex] - meanOutput;
+    POLICY_SCRATCH_CENTERED[actionIndex] = delta;
+    varianceAccumulator += delta * delta;
+  }
+  varianceAccumulator /= actionCount;
+  let standardDeviation = Math.sqrt(varianceAccumulator);
+  if (!Number.isFinite(standardDeviation) || standardDeviation < C.STD_MIN) {
+    standardDeviation = C.STD_MIN;
+  }
+
+  const collapseRatio =
+    standardDeviation < C.COLLAPSE_STD_THRESHOLD
+      ? C.COLLAPSE_RATIO_FULL
+      : standardDeviation < C.COLLAPSE_STD_MED
+        ? C.COLLAPSE_RATIO_HALF
+        : 0;
+  const temperature = C.TEMPERATURE_BASE + C.TEMPERATURE_SCALE * collapseRatio;
+
+  let maxCentered = -Infinity;
+  for (let actionIndex = 0; actionIndex < actionCount; actionIndex++) {
+    const centeredValue = POLICY_SCRATCH_CENTERED[actionIndex];
+    if (centeredValue > maxCentered) maxCentered = centeredValue;
+  }
+
+  let expSum = 0;
+  for (let actionIndex = 0; actionIndex < actionCount; actionIndex++) {
+    const expValue = Math.exp(
+      (POLICY_SCRATCH_CENTERED[actionIndex] - maxCentered) / temperature,
+    );
+    POLICY_SCRATCH_EXPS[actionIndex] = expValue;
+    expSum += expValue;
+  }
+  if (expSum === 0) expSum = 1;
+
+  let chosenDirection = 0;
+  let bestProbability = -Infinity;
+  let runnerUpProbability = 0;
+  for (let actionIndex = 0; actionIndex < actionCount; actionIndex++) {
+    const probability = POLICY_SCRATCH_EXPS[actionIndex] / expSum;
+    POLICY_SOFTMAX[actionIndex] = probability;
+    if (probability > bestProbability) {
+      runnerUpProbability = bestProbability;
+      bestProbability = probability;
+      chosenDirection = actionIndex;
+    } else if (probability > runnerUpProbability) {
+      runnerUpProbability = probability;
+    }
+  }
+
+  let entropy = 0;
+  for (let actionIndex = 0; actionIndex < actionCount; actionIndex++) {
+    const probability = POLICY_SOFTMAX[actionIndex];
+    if (probability > 0) entropy += -probability * Math.log(probability);
+  }
+  entropy /= C.LOG_ACTIONS;
+
+  return {
+    direction: chosenDirection,
+    softmax: Array.from(POLICY_SOFTMAX),
+    entropy,
+    maxProb: bestProbability,
+    secondProb: runnerUpProbability,
+  };
+}
+
+/**
+ * Activate the network, record output history, and choose the next direction.
+ *
+ * @param state - Mutable simulation state for the active run.
+ * @param network - Policy network used for the current step.
+ */
+export function decideMazeMovementDirection(
+  state: SimulationState,
+  network: INetwork,
+  coordinateScratch: Int32Array,
+): void {
+  if (state.earlyTerminate) return;
+
+  try {
+    const networkOutputs = network.activate(state.vision);
+    const outputsLength = networkOutputs.length | 0;
+    const outputsHistoryCopy: number[] = new Array(outputsLength);
+    for (let copyIndex = 0; copyIndex < outputsLength; copyIndex++) {
+      outputsHistoryCopy[copyIndex] = networkOutputs[copyIndex];
+    }
+
+    const previousHistory = readMazeMovementOutputHistory(network);
+    const updatedHistory = MazeUtils.pushHistory(
+      previousHistory,
+      outputsHistoryCopy,
+      C.OUTPUT_HISTORY_LENGTH,
+    );
+    writeMazeMovementOutputHistory(network, updatedHistory);
+
+    const selectedActionStats = selectMazeMovementDirection(networkOutputs);
+    state.actionStats = selectedActionStats;
+    applyMazeMovementSaturationAndBiasAdjust(
+      state,
+      networkOutputs,
+      network,
+      coordinateScratch,
+    );
+    state.direction = selectedActionStats.direction;
+  } catch (error: unknown) {
+    console.error('Error activating network:', error);
+    state.direction = C.NO_MOVE;
+  }
+}
+
+/**
+ * Apply the short-horizon proximity-greedy override near the maze exit.
+ *
+ * @param state - Mutable simulation state for the active run.
+ * @param encodedMaze - Maze grid used for move validity checks.
+ * @param distanceMap - Optional precomputed distance map.
+ * @param coordinateScratch - Reused coordinate scratch buffer.
+ */
+export function applyMazeMovementProximityGreedy(
+  state: SimulationState,
+  encodedMaze: number[][],
+  distanceMap: number[][] | undefined,
+  coordinateScratch: Int32Array,
+): void {
+  if (state.earlyTerminate || state.distHere > C.PROXIMITY_GREEDY_DISTANCE) {
+    return;
+  }
+
+  let chosenDirection = state.direction;
+  let minimalNeighborDistance = Infinity;
+
+  for (
+    let directionIndex = 0;
+    directionIndex < C.ACTION_DIM;
+    directionIndex++
+  ) {
+    const [deltaX, deltaY] = C.DIRECTION_DELTAS[directionIndex];
+    const neighbourX = (state.position[0] + deltaX) | 0;
+    const neighbourY = (state.position[1] + deltaY) | 0;
+
+    coordinateScratch[0] = neighbourX;
+    coordinateScratch[1] = neighbourY;
+
+    if (
+      !isMazeMovementCellOpen(
+        encodedMaze,
+        neighbourX,
+        neighbourY,
+        coordinateScratch,
+      )
+    ) {
+      continue;
+    }
+
+    const neighbourDistance = getMazeMovementDistance(
+      encodedMaze,
+      [neighbourX, neighbourY],
+      distanceMap,
+    );
+    if (neighbourDistance < minimalNeighborDistance) {
+      minimalNeighborDistance = neighbourDistance;
+      chosenDirection = directionIndex;
+    }
+  }
+
+  if (chosenDirection !== undefined && chosenDirection !== state.direction) {
+    state.direction = chosenDirection;
+  }
+}
+
+/**
+ * Apply epsilon-greedy exploration to the current action choice.
+ *
+ * @param state - Mutable simulation state for the active run.
+ * @param encodedMaze - Maze grid used for move validity checks.
+ * @param coordinateScratch - Reused coordinate scratch buffer.
+ */
+export function applyMazeMovementEpsilonExploration(
+  state: SimulationState,
+  encodedMaze: number[][],
+  coordinateScratch: Int32Array,
+): void {
+  if (state.earlyTerminate) return;
+
+  const epsilon = computeMazeMovementEpsilon(
+    state.steps,
+    state.stepsSinceImprovement,
+    state.distHere,
+    getMazeMovementRunServiceState().saturations,
+  );
+  if (!(randomMazeMovementUnit() < epsilon)) return;
+
+  const actionCount = C.ACTION_DIM;
+  const previousAction = state.prevAction;
+  const currentPositionX = state.position[0] | 0;
+  const currentPositionY = state.position[1] | 0;
+
+  for (let attemptIndex = 0; attemptIndex < actionCount; attemptIndex++) {
+    const randomDirection = (randomMazeMovementUnit() * actionCount) | 0;
+    if (randomDirection === previousAction) continue;
+
+    const [directionDeltaX, directionDeltaY] =
+      C.DIRECTION_DELTAS[randomDirection];
+    const candidateX = (currentPositionX + directionDeltaX) | 0;
+    const candidateY = (currentPositionY + directionDeltaY) | 0;
+    coordinateScratch[0] = candidateX;
+    coordinateScratch[1] = candidateY;
+
+    if (
+      isMazeMovementCellOpen(
+        encodedMaze,
+        candidateX,
+        candidateY,
+        coordinateScratch,
+      )
+    ) {
+      state.direction = randomDirection;
+      break;
+    }
+  }
+}
+
+/**
+ * Force a random valid move when the policy has stalled with repeated no-move outputs.
+ *
+ * @param state - Mutable simulation state for the active run.
+ * @param encodedMaze - Maze grid used for move validity checks.
+ * @param coordinateScratch - Reused coordinate scratch buffer.
+ */
+export function applyMazeMovementForcedExploration(
+  state: SimulationState,
+  encodedMaze: number[][],
+  coordinateScratch: Int32Array,
+): void {
+  if (state.earlyTerminate) return;
+
+  const runServices = getMazeMovementRunServiceState();
+  if (state.direction === C.NO_MOVE) {
+    runServices.noMoveStreak++;
+  } else {
+    runServices.noMoveStreak = 0;
+  }
+
+  if (runServices.noMoveStreak < C.NO_MOVE_STREAK_THRESHOLD) return;
+
+  const actionCount = C.ACTION_DIM;
+  const currentPositionX = state.position[0] | 0;
+  const currentPositionY = state.position[1] | 0;
+
+  for (let attemptIndex = 0; attemptIndex < actionCount; attemptIndex++) {
+    const candidateDirection = (randomMazeMovementUnit() * actionCount) | 0;
+    const [deltaX, deltaY] = C.DIRECTION_DELTAS[candidateDirection];
+    const candidateX = (currentPositionX + deltaX) | 0;
+    const candidateY = (currentPositionY + deltaY) | 0;
+    coordinateScratch[0] = candidateX;
+    coordinateScratch[1] = candidateY;
+
+    if (
+      isMazeMovementCellOpen(
+        encodedMaze,
+        candidateX,
+        candidateY,
+        coordinateScratch,
+      )
+    ) {
+      state.direction = candidateDirection;
+      break;
+    }
+  }
+
+  runServices.noMoveStreak = 0;
+}
+
+/**
+ * Detect saturation and optionally damp output-node biases.
+ *
+ * @param state - Mutable simulation state for the active run.
+ * @param outputs - Raw network logits for the current step.
+ * @param network - Policy network that produced the logits.
+ * @param coordinateScratch - Reused scratch buffer for temporary penalties.
+ */
+export function applyMazeMovementSaturationAndBiasAdjust(
+  state: SimulationState,
+  outputs: number[],
+  network: INetwork,
+  coordinateScratch: Int32Array,
+): void {
+  const rewardScale = C.REWARD_SCALE;
+  const actionStats = state.actionStats;
+  if (!actionStats) return;
+
+  const maxProbability = actionStats.maxProb ?? 0;
+  const secondProbability = actionStats.secondProb ?? 0;
+  const isOverConfident =
+    maxProbability > C.OVERCONFIDENT_PROB &&
+    secondProbability < C.SECOND_PROB_LOW;
+
+  const actionCount = C.ACTION_DIM;
+  let logitsSum = 0;
+  for (let outputIndex = 0; outputIndex < outputs.length; outputIndex++) {
+    logitsSum += outputs[outputIndex];
+  }
+  const meanLogit = logitsSum / actionCount;
+
+  let varianceAccumulator = 0;
+  for (let outputIndex = 0; outputIndex < outputs.length; outputIndex++) {
+    const delta = outputs[outputIndex] - meanLogit;
+    varianceAccumulator += delta * delta;
+  }
+  const variance = varianceAccumulator / actionCount;
+  const standardDeviation = Math.sqrt(variance);
+  const isFlatCollapsed = standardDeviation < C.LOGSTD_FLAT_THRESHOLD;
+
+  const runServices = getMazeMovementRunServiceState();
+  let saturationCounter = runServices.saturations;
+  if (isOverConfident || isFlatCollapsed) {
+    saturationCounter++;
+    state.saturatedSteps++;
+  } else if (saturationCounter > 0) {
+    saturationCounter--;
+  }
+  runServices.saturations = saturationCounter;
+
+  if (isOverConfident) {
+    coordinateScratch[0] = -C.OVERCONFIDENT_PENALTY * rewardScale;
+    state.invalidMovePenalty += coordinateScratch[0];
+  }
+  if (isFlatCollapsed) {
+    coordinateScratch[0] = -C.FLAT_COLLAPSE_PENALTY * rewardScale;
+    state.invalidMovePenalty += coordinateScratch[0];
+  }
+
+  const shouldAdjustBiases =
+    runServices.saturations > C.SATURATION_ADJUST_MIN &&
+    state.steps % C.SATURATION_ADJUST_INTERVAL === 0;
+  if (!shouldAdjustBiases) return;
+
+  try {
+    const outputNodes = network.nodes?.filter(
+      (node: INodeStruct): node is INodeStruct & { bias: number } =>
+        node.type === C.NODE_TYPE_OUTPUT && typeof node.bias === 'number',
+    );
+    if (!outputNodes || outputNodes.length === 0) return;
+
+    let biasSum = 0;
+    for (let outputIndex = 0; outputIndex < outputNodes.length; outputIndex++) {
+      biasSum += outputNodes[outputIndex].bias;
+    }
+    const meanBias = biasSum / outputNodes.length;
+    for (let outputIndex = 0; outputIndex < outputNodes.length; outputIndex++) {
+      const outputNode = outputNodes[outputIndex];
+      const adjustedBias = outputNode.bias - meanBias * C.BIAS_ADJUST_FACTOR;
+      outputNode.bias = Math.max(
+        -C.BIAS_CLAMP,
+        Math.min(C.BIAS_CLAMP, adjustedBias),
+      );
+    }
+  } catch {
+    // Best-effort only; network shapes vary across tests and demos.
+  }
+}
+
+export {};