@reicek/neataptic-ts 0.1.23 → 0.1.25

package/test/examples/asciiMaze/evolutionEngine/populationPruning.ts

@@ -17,6 +17,7 @@
 
 import type { Neat, Network } from '../../../../src/neataptic';
 import type { EngineState } from './engineState';
+import type { NetworkConnection, NetworkNode } from './evolutionEngine.types';
 import { drawFastRandom, resolveRngParameters } from './rngAndTiming';
 
 /** Weight initialization minimum value for warm-start connections. */
@@ -35,8 +36,20 @@ const OUTPUT_BIAS_CLAMP = 5;
  */
 const PRUNE_BULK_INSERTION_MAX = 64;
 
-/** Empty shared vector reused when a fallback empty array is required. */
-const EMPTY_VECTOR: Array<Record<string, unknown>> = [];
+interface OutputBiasStats {
+  mean: number;
+  std: number;
+}
+
+interface NetworkWithWarmStartSurface {
+  nodes?: NetworkNode[];
+  connections?: NetworkConnection[];
+  connect: (from: NetworkNode, to: NetworkNode, weight?: number) => unknown;
+}
+
+interface NetworkWithOutputBiasStats extends NetworkWithWarmStartSurface {
+  _outputBiasStats?: OutputBiasStats;
+}
 
 /**
  * Parameters for applying simplify pruning to a population.
@@ -132,8 +145,10 @@ export const applyCompassWarmStart = ({
     // Step 1: defensive guards
     if (!network) return;
 
-    const nodesRef = network.nodes ?? EMPTY_VECTOR;
-    const connectionsRef = network.connections ?? EMPTY_VECTOR;
+    const runtimeNetwork = network as unknown as NetworkWithWarmStartSurface;
+
+    const nodesRef = runtimeNetwork.nodes ?? [];
+    const connectionsRef = runtimeNetwork.connections ?? [];
 
     // Determine counts for input/output nodes using the engine helper that populates
     // the pooled node index buffer with indices by type.
@@ -160,9 +175,7 @@ export const applyCompassWarmStart = ({
       if (!inputNode || !outputNode) continue; // nothing to wire for this direction
 
       // Find existing connection input→output (linear scan; avoids allocations)
-      // Type assertion: conn is a connection object with from/to properties
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      let existingConn: any = undefined;
+      let existingConn: NetworkConnection | undefined;
       for (let ci = 0, cLen = connectionsRef.length; ci < cLen; ci++) {
         const conn = connectionsRef[ci];
         if (conn.from === inputNode && conn.to === outputNode) {
@@ -174,7 +187,8 @@ export const applyCompassWarmStart = ({
       // Small random initialization in [wInitMin, wInitMin + wInitRange)
       const initWeight =
         drawFastRandom(state, randomParameters) * W_INIT_RANGE + W_INIT_MIN;
-      if (!existingConn) network.connect(inputNode, outputNode, initWeight);
+      if (!existingConn)
+        runtimeNetwork.connect(inputNode, outputNode, initWeight);
       else existingConn.weight = initWeight;
     }
 
@@ -190,9 +204,7 @@ export const applyCompassWarmStart = ({
       if (!outNode) continue;
 
       // Find existing connection compass→outNode
-      // Type assertion: conn is a connection object with from/to properties
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      let existingConn: any = undefined;
+      let existingConn: NetworkConnection | undefined;
       for (let ci = 0, cLen = connectionsRef.length; ci < cLen; ci++) {
         const conn = connectionsRef[ci];
         if (conn.from === compassNode && conn.to === outNode) {
@@ -202,7 +214,8 @@ export const applyCompassWarmStart = ({
       }
 
       const baseWeight = OUTPUT_BIAS_BASE + outIndex * OUTPUT_BIAS_STEP;
-      if (!existingConn) network.connect(compassNode, outNode, baseWeight);
+      if (!existingConn)
+        runtimeNetwork.connect(compassNode, outNode, baseWeight);
       else existingConn.weight = baseWeight;
     }
   } catch {
@@ -239,7 +252,8 @@ export const centerOutputBiases = ({
   network,
 }: CenterOutputBiasesParams): void => {
   try {
-    const nodeList = network?.nodes ?? EMPTY_VECTOR;
+    const runtimeNetwork = network as unknown as NetworkWithOutputBiasStats;
+    const nodeList = runtimeNetwork.nodes ?? [];
     const totalNodeCount = nodeList.length | 0;
     if (totalNodeCount === 0) return;
 
@@ -274,9 +288,7 @@ export const centerOutputBiases = ({
     }
 
     // Step 4: Persist stats for optional telemetry.
-    // Type assertion: dynamic property assignment for telemetry data
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    (network as any)._outputBiasStats = { mean: meanBias, std: stdBias };
+    runtimeNetwork._outputBiasStats = { mean: meanBias, std: stdBias };
   } catch {
     // swallow errors (best-effort maintenance routine)
   }
@@ -312,9 +324,7 @@ const pruneWeakConnectionsForGenome = (
     if (rawFraction <= 0) return; // nothing requested
 
     // Step 2: Collect enabled connections.
-    // Type assertion: connections array elements have connection properties
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const allConnections = genome.connections as any[];
+    const allConnections = genome.connections as unknown as NetworkConnection[];
     let candidateConnections = collectEnabledConnections(allConnections);
     const enabledConnectionCount = candidateConnections.length;
     if (enabledConnectionCount === 0) return; // no work
@@ -357,18 +367,16 @@ const pruneWeakConnectionsForGenome = (
  * const enabled = collectEnabledConnections(genome.connections);
  * const stableCopy = enabled.slice(); // only if retention needed
  */
-// Type assertion: connections are dynamic objects checked at runtime
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const collectEnabledConnections = (connectionsSource: any[]): any[] => {
+const collectEnabledConnections = (
+  connectionsSource: NetworkConnection[],
+): NetworkConnection[] => {
   // Step 1: Validate input & fast exit.
   if (!Array.isArray(connectionsSource) || connectionsSource.length === 0)
     return [];
 
   // Step 2: Reset pooled buffer (reusing the scratch array from state; needs access via closure or parameter).
   // Note: This is a simplified version; in practice this would access state.scratch.connectionCandidates
-  // Type assertion: buffer holds connection objects
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const candidateBuffer: any[] = [];
+  const candidateBuffer: NetworkConnection[] = [];
 
   // Step 3: Linear scan & collect enabled connections.
   for (
@@ -401,12 +409,9 @@ const collectEnabledConnections = (connectionsSource: any[]): any[] => {
  * sortCandidatesByStrategy(candidates, 'weakRecurrentPreferred');
  */
 const sortCandidatesByStrategy = (
-  // Type assertion: connections are dynamic objects with weight/gater properties
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  candidateConnections: any[],
+  candidateConnections: NetworkConnection[],
   strategyKey: string,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-): any[] => {
+): NetworkConnection[] => {
   // Step 1: Validate input.
   if (!Array.isArray(candidateConnections) || candidateConnections.length === 0)
     return candidateConnections;
@@ -471,9 +476,7 @@ const sortCandidatesByStrategy = (
  * insertionSortByAbsWeight(buf, 0, 10);
  */
 const insertionSortByAbsWeight = (
-  // Type assertion: buffer holds connection objects with weight property
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  connectionsBuffer: any[],
+  connectionsBuffer: NetworkConnection[],
   startIndex: number,
   endExclusive: number,
 ): void => {
@@ -491,17 +494,17 @@ const insertionSortByAbsWeight = (
   for (let scanIndex = from + 1; scanIndex < to; scanIndex++) {
     // 2.1: Extract the candidate and compute its absolute weight (treat non-finite as 0).
     const candidate = connectionsBuffer[scanIndex];
+    const candidateWeight = Number(candidate?.weight);
     const candidateAbs = Math.abs(
-      candidate && Number.isFinite(candidate.weight) ? candidate.weight : 0,
+      Number.isFinite(candidateWeight) ? candidateWeight : 0,
     );
 
     // 2.2: Shift larger elements one slot to the right to make room for the candidate.
     let writePos = scanIndex - 1;
     while (writePos >= from) {
       const probe = connectionsBuffer[writePos];
-      const probeAbs = Math.abs(
-        probe && Number.isFinite(probe.weight) ? probe.weight : 0,
-      );
+      const probeWeight = Number(probe?.weight);
+      const probeAbs = Math.abs(Number.isFinite(probeWeight) ? probeWeight : 0);
       // Preserve stability: stop when probe <= candidate (no swap for equals).
       if (probeAbs <= candidateAbs) break;
       connectionsBuffer[writePos + 1] = probe;
@@ -529,9 +532,7 @@ const insertionSortByAbsWeight = (
  * disableSmallestEnabledConnections(candidates, 5);
  */
 const disableSmallestEnabledConnections = (
-  // Type assertion: buffer holds connection objects with enabled property
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  candidateConnections: any[],
+  candidateConnections: NetworkConnection[],
   pruneCount: number,
 ): void => {
   // Step 0: Defensive validation & normalization.
@@ -563,9 +564,7 @@ const disableSmallestEnabledConnections = (
       candidateConnections
         .slice(0, activeEnabledCount) // sort only active slice; slice() to avoid comparing undefined tail beyond active
         .sort(
-          // Type assertion: comparing connection objects with weight property
-          // eslint-disable-next-line @typescript-eslint/no-explicit-any
-          (firstConnection: any, secondConnection: any) =>
+          (firstConnection, secondConnection) =>
             Math.abs(firstConnection?.weight || 0) -
             Math.abs(secondConnection?.weight || 0),
         )
@@ -588,16 +587,12 @@ const disableSmallestEnabledConnections = (
   while (remainingToDisable > 0 && activeSliceLength > 0) {
     // 3a. Find index of current minimum |weight| in [0, activeSliceLength).
     let minIndex = 0;
-    let minAbsWeight = Math.abs(
-      candidateConnections[0] && Number.isFinite(candidateConnections[0].weight)
-        ? candidateConnections[0].weight
-        : 0,
-    );
+    const firstWeight = Number(candidateConnections[0]?.weight);
+    let minAbsWeight = Math.abs(Number.isFinite(firstWeight) ? firstWeight : 0);
     for (let probeIndex = 1; probeIndex < activeSliceLength; probeIndex++) {
       const probe = candidateConnections[probeIndex];
-      const probeAbs = Math.abs(
-        probe && Number.isFinite(probe.weight) ? probe.weight : 0,
-      );
+      const probeWeight = Number(probe?.weight);
+      const probeAbs = Math.abs(Number.isFinite(probeWeight) ? probeWeight : 0);
       if (probeAbs < minAbsWeight) {
         minAbsWeight = probeAbs;
         minIndex = probeIndex;
@@ -633,9 +628,7 @@ const disableSmallestEnabledConnections = (
  */
 const collectNodeIndicesByType = (
   state: EngineState,
-  // Type assertion: nodes are dynamic objects with type property
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  nodes: any[] | undefined,
+  nodes: NetworkNode[] | undefined,
   nodeType: string,
 ): number => {
   // Step 1: Defensive validation & fast exit.

package/test/examples/asciiMaze/evolutionEngine/sampling.ts

@@ -5,6 +5,10 @@
  * 1. Provide allocation-light array sampling utilities that reuse the shared `EngineState` scratch pools.
  * 2. Expose history helpers that mirror the façade behaviour while keeping pooled buffers centralised.
  * 3. Centralise RNG parameter resolution for sampling paths to keep behaviour deterministic under shared state.
+ *
+ * These helpers look small, but they sit under several hot paths. The main job
+ * is not "random choice" in the abstract; it is random choice without quietly
+ * reintroducing per-generation array churn into long-running experiments.
  */
 
 import type { EngineState } from './engineState.types';
@@ -14,6 +18,10 @@ import { MazeUtils } from '../mazeUtils';
 /**
  * Sample `sampleCount` items (with replacement) from `source` into the pooled scratch buffer.
  *
+ * This helper is for callers that want an ephemeral array view immediately. The
+ * returned array reuses shared scratch storage, so callers should copy it first
+ * if they need the contents to survive another helper call.
+ *
  * Steps:
  * 1. Validate the input array and normalise `sampleCount` to an integer.
  * 2. Grow the shared `sampleResultBuffer` to the next power of two when capacity is insufficient.
@@ -62,6 +70,10 @@ export const sampleArray = <T>(
 /**
  * Sample up to `sampleCount` items (with replacement) into the shared `samplePool` buffer.
  *
+ * Compared with `sampleArray`, this form is for callers that only need a count
+ * plus access to the pooled buffer on `state.scratch.samplePool`. That avoids
+ * one more logical array object on the hottest paths.
+ *
  * Steps:
  * 1. Validate inputs and ensure the pooled buffer exists.
  * 2. Grow the buffer by powers of two when more capacity is required.
@@ -91,9 +103,9 @@ export const sampleIntoScratch = <T>(
   if (sourceLength === 0 || normalisedCount <= 0) return 0;
 
   const scratch = state.scratch;
-  // Type assertion: pool holds T[] at runtime but declared as Array<unknown> for reuse flexibility
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  let pooledBuffer = scratch.samplePool as any as T[];
+  // The shared pool is declared as Array<unknown> because different helpers reuse it
+  // for different element types across generations.
+  let pooledBuffer = scratch.samplePool as T[];
   if (!Array.isArray(pooledBuffer)) {
     pooledBuffer = [];
     scratch.samplePool = pooledBuffer;
@@ -141,6 +153,9 @@ export const sampleIntoScratch = <T>(
 /**
  * Sample from a suffix of `source` starting at `segmentStart` into the pooled buffer.
  *
+ * The common use case is "sample from the non-elite tail" or some later slice
+ * of a population without first allocating `source.slice(segmentStart)`.
+ *
  * Steps:
  * 1. Clamp indices and ensure there is a non-empty segment.
  * 2. Ensure the pooled buffer can store the requested sample count.

package/test/examples/asciiMaze/evolutionEngine/telemetryMetrics.ts

@@ -6,7 +6,7 @@
  * internal error is swallowed so that logging never impacts the evolution loop.
  */
 import type { Neat, Network } from '../../../../src/neataptic';
-import type { GenomeDetailed } from '../../../../src/neat/neat.types';
+import type { GenomeDetailed } from '../../../../src/neat/shared/neat.shared.types';
 import type { EngineState } from './engineState.types';
 import type {
   EvolutionGenomeLike,
@@ -84,6 +84,10 @@ type TelemetryWriter = (message: string) => void;
 interface GenerationResult {
   /** Path taken by the agent (array of [x, y] coordinate pairs). */
   path?: ReadonlyArray<[number, number]>;
+  /** Progress score accumulated during the run. */
+  progress?: number;
+  /** Fraction of the maze saturation reached during the run. */
+  saturationFraction?: number;
 }
 
 /**
@@ -524,12 +528,10 @@ const computeExplorationStats = (
   }
 
   // Step 2: Choose the most efficient distinct-coordinate counter based on path length.
-  let unique = 0;
-  if (pathLength < 32) {
-    unique = countDistinctCoordinatesTiny(state, path!, pathLength);
-  } else {
-    unique = countDistinctCoordinatesHashed(state, path!, pathLength);
-  }
+  const unique =
+    pathLength < 32
+      ? countDistinctCoordinatesTiny(state, path!, pathLength)
+      : countDistinctCoordinatesHashed(state, path!, pathLength);
 
   // Step 3: Aggregate the summary metrics while keeping floating-point ratios guarded.
   return {
@@ -707,12 +709,16 @@ const computeDiversityMetrics = (
   let weightMean = 0;
   let weightM2 = 0;
   let enabledWeights = 0;
-  const sampleBuffer = state.scratch.samplePool ?? EMPTY_VECTOR;
   for (let sampleIndex = 0; sampleIndex < sampledLength; sampleIndex++) {
-    const genome = sampleBuffer[sampleIndex] as GenomeDetailed | undefined;
-    const connections = Array.isArray(genome?.connections)
-      ? genome.connections
-      : EMPTY_VECTOR;
+    const genome = state.scratch.samplePool[sampleIndex] as
+      | GenomeDetailed
+      | undefined;
+    const connections = (
+      Array.isArray(genome?.connections) ? genome.connections : EMPTY_VECTOR
+    ) as Array<{
+      enabled?: boolean;
+      weight?: number;
+    }>;
     for (
       let connectionIndex = 0;
       connectionIndex < connections.length;
@@ -859,15 +865,16 @@ const computeLogitStats = ({
 
   resetLogitScratch(state, actionDimension, reducedTelemetry);
 
-  let entropySum = 0;
+  const entropySum = reducedTelemetry
+    ? accumulateLogitStatsReduced(state, recent, actionDimension)
+    : actionDimension === 4
+      ? accumulateLogitStatsUnrolled4(state, recent, recent.length)
+      : accumulateLogitStatsGeneric(state, recent, actionDimension);
   if (reducedTelemetry) {
-    entropySum = accumulateLogitStatsReduced(state, recent, actionDimension);
     finalizeLogitStatsReduced(state, actionDimension, recent.length);
   } else if (actionDimension === 4) {
-    entropySum = accumulateLogitStatsUnrolled4(state, recent, recent.length);
     finalizeLogitStatsFull(state, actionDimension, recent.length);
   } else {
-    entropySum = accumulateLogitStatsGeneric(state, recent, actionDimension);
     finalizeLogitStatsFull(state, actionDimension, recent.length);
   }
 
@@ -1356,7 +1363,7 @@ const computeDecisionStability = (
   for (let rowIndex = 0; rowIndex < sequenceLength; rowIndex++) {
     const row = recent[rowIndex];
     if (!row || row.length === 0) continue;
-    let argmax = 0;
+    let argmax: number;
     if (unrolled && row.length >= 4) {
       let bestValue = row[0] ?? 0;
       argmax = 0;

package/test/examples/asciiMaze/evolutionEngine/trainingWarmStart.ts

@@ -3,14 +3,21 @@
  *
  * Lamarckian warm-start and population pretraining subsystem.
  *
+ * This module is the part of the ASCII Maze engine that briefly steps outside
+ * pure neuroevolution and asks a pragmatic question: can a small amount of
+ * supervised guidance give the population a better starting shape before the
+ * main search pressure takes over again?
+ *
  * Responsibilities:
- * - Build supervised training datasets for compass-guided navigation
- * - Apply Lamarckian backpropagation training to populations
- * - Adjust output biases after training to maintain exploration
- * - Orchestrate conditional warm-start pretraining with buffer management
+ * - Build a tiny curriculum-style supervised dataset for compass-guided motion
+ * - Apply bounded Lamarckian backpropagation to whole populations
+ * - Re-center output biases after training so exploration does not collapse
+ * - Orchestrate optional warm-start passes without polluting the main loop
  *
- * All functions are pure/side-effect-free except where explicitly documented.
- * Mutations are limited to NEAT population networks and engine scratch buffers.
+ * The important design constraint is restraint. These helpers are not trying to
+ * solve the maze with backprop. They are trying to give evolution a better
+ * first draft while preserving the example's core identity as an evolutionary
+ * system.
  *
  * @module trainingWarmStart
  */
@@ -19,12 +26,44 @@ import type { Neat, Network } from '../../../../src/neataptic';
 import { methods } from '../../../../src/neataptic';
 import type { EngineState, RngCacheParameters } from './engineState.types';
 import { initialiseTelemetryScratch } from './engineState';
+import type { NetworkNode } from './evolutionEngine.types';
 import { drawFastRandom, readHighResolutionTime } from './rngAndTiming';
 import { sampleArray } from './sampling';
 
 /** Empty array constant for defensive fallbacks. */
 const EMPTY_VEC: readonly never[] = [];
 
+/** Small supervised case used during Lamarckian warm-start. */
+interface LamarckianTrainingCase {
+  input: number[];
+  output: number[];
+}
+
+/** The warm-start path trains ordinary runtime networks; this alias keeps intent explicit. */
+type TrainableNetwork = Network;
+
+/**
+ * Narrow NEAT view used by the warm-start helpers.
+ *
+ * These helpers only need population access and a couple of option fields, so
+ * they avoid depending on the entire engine-facing driver surface.
+ */
+type WarmStartNeatLike = Neat & {
+  population: TrainableNetwork[];
+};
+
+/** Callback used when a helper needs to write node indices of a specific role into scratch. */
+type NodeIndexCollector = (nodes: NetworkNode[], nodeType: string) => number;
+
+/** Best-effort post-training hook applied to one network at a time. */
+type WarmStartNetworkCallback = (network: TrainableNetwork) => void;
+
+/** Population-wide warm-start hook used by the public orchestration helper. */
+type PretrainPopulationCallback = (
+  neat: Neat,
+  trainingSet: LamarckianTrainingCase[],
+) => void;
+
 /**
  * Build the supervised training set used for Lamarckian warm-start training.
  *
@@ -190,8 +229,10 @@ export const buildLamarckianTrainingSet = (
 /**
  * Adjust output node biases after training to maintain exploration diversity.
  *
- * This heuristic prevents trained networks from collapsing into deterministic behavior
- * by centering output biases (subtracting mean) and optionally scaling when variance is low.
+ * This heuristic exists because short supervised bursts can make the action
+ * head too confident too early. By re-centering output biases and nudging very
+ * low-variance heads back outward, the engine keeps exploration pressure alive
+ * after warm-start training instead of letting one action dominate forever.
  *
  * Steps:
  * 1. Collect output node biases into scratch buffer
@@ -223,15 +264,15 @@ export const adjustOutputBiasesAfterTraining = (
     DEFAULT_STD_ADJUST_MULT: number;
   },
   scratchNodeIdx: Int32Array,
-  // Type assertion: helper function working with dynamic node arrays
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  getNodeIndicesByType: (nodes: any[], nodeType: string) => number,
+  getNodeIndicesByType: NodeIndexCollector,
 ): void => {
   try {
     // Step 1: Early exit when no network or no nodes exist.
     if (!network) return;
 
-    const nodesRef = network.nodes ?? EMPTY_VEC;
+    const nodesRef: NetworkNode[] = Array.isArray(network.nodes)
+      ? (network.nodes as unknown as NetworkNode[])
+      : [];
     const outputNodeCount = getNodeIndicesByType(nodesRef, 'output');
     if (outputNodeCount <= 0) return;
 
@@ -280,10 +321,14 @@ export const adjustOutputBiasesAfterTraining = (
  * Pretrain the population using a small supervised dataset and apply warm-start heuristics.
  *
  * Behaviour & contract:
- * - Runs a short supervised training pass (backprop) on each network in `neat.population`
- * - Applies lightweight warm-start heuristics after training: compass wiring and output bias centering
- * - Errors are isolated per-network: a failing network does not abort the overall pretrain step
- * - This helper is allocation-light and does not create sizable temporary buffers
+ * - Runs a short supervised training pass on each network in `neat.population`
+ * - Treats the training set as a biasing hint, not as a replacement for later evolution
+ * - Applies lightweight warm-start heuristics after training: compass wiring
+ *   and output-bias centering
+ * - Isolates failures per network so one bad trainer state does not abort the
+ *   rest of the population
+ * - Stays allocation-light so warm-start remains cheap enough to use as a
+ *   tactical assist instead of a second training regime
  *
  * Steps:
  * 1. Validate inputs and obtain `population` (fast-exit on empty populations)
@@ -307,9 +352,7 @@ export const adjustOutputBiasesAfterTraining = (
  */
 export const pretrainPopulationWarmStart = (
   neat: Neat,
-  // Type assertion: training dataset structure
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  lamarckianTrainingSet: any[],
+  lamarckianTrainingSet: LamarckianTrainingCase[],
   constants: {
     PRETRAIN_MAX_ITER: number;
     PRETRAIN_BASE_ITER: number;
@@ -318,22 +361,17 @@ export const pretrainPopulationWarmStart = (
     DEFAULT_PRETRAIN_MOMENTUM: number;
     DEFAULT_TRAIN_BATCH_SMALL: number;
   },
-  // Type assertion: helper functions working with networks
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  applyCompassWarmStart: (network: any) => void,
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  centerOutputBiases: (network: any) => void,
+  applyCompassWarmStart: WarmStartNetworkCallback,
+  centerOutputBiases: WarmStartNetworkCallback,
 ): void => {
   // Step 1: Defensive validation & fast exit.
   if (!neat) return;
-  const population = neat.population ?? EMPTY_VEC;
+  const population = (neat as WarmStartNeatLike).population ?? EMPTY_VEC;
   if (!Array.isArray(population) || population.length === 0) return;
 
   // Step 2: Iterate population and apply supervised training per network (best-effort).
   for (let networkIndex = 0; networkIndex < population.length; networkIndex++) {
-    // Type assertion: network from population array
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    const network: any = population[networkIndex];
+    const network = population[networkIndex];
     try {
       if (!network || typeof network.train !== 'function') continue; // skip non-trainable entries
 
@@ -376,9 +414,11 @@ export const pretrainPopulationWarmStart = (
 /**
  * Apply Lamarckian backpropagation training to the entire population with optional profiling.
  *
- * Runs a bounded supervised training pass on each network in the population, optionally
- * downsampling the training set for efficiency. Collects gradient norm statistics and
- * applies bias adjustment heuristics to maintain exploration after training.
+ * Runs a bounded supervised training pass on each network in the population,
+ * optionally downsampling the training set for efficiency. The intent is to
+ * "tilt" the policy landscape toward obviously sensible moves before the main
+ * evolutionary loop takes over, while still measuring and logging enough to see
+ * whether the warm-start is becoming too aggressive or too weak.
  *
  * Steps:
  * 1. Validate inputs & early exits
@@ -418,9 +458,7 @@ export const pretrainPopulationWarmStart = (
  */
 export const applyLamarckianTraining = (
   neat: Neat,
-  // Type assertion: training dataset structure
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  trainingSet: any[],
+  trainingSet: LamarckianTrainingCase[],
   iterations: number,
   sampleSize: number | undefined,
   safeWrite: (msg: string) => void,
@@ -433,9 +471,7 @@ export const applyLamarckianTraining = (
     DEFAULT_TRAIN_MOMENTUM: number;
     DEFAULT_TRAIN_BATCH_SMALL: number;
   },
-  // Type assertion: helper function working with networks
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  adjustOutputBiases: (network: any) => void,
+  adjustOutputBiases: WarmStartNetworkCallback,
 ): number => {
   // Step 1: Validate inputs & early exits.
   if (
@@ -460,9 +496,7 @@ export const applyLamarckianTraining = (
   // Step 4: Iterate networks performing a bounded training pass.
   let gradientNormSum = 0;
   let gradientNormSamples = 0;
-  // Type assertion: population is Network array from Neat
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const populationRef = neat.population as any[];
+  const populationRef = (neat as WarmStartNeatLike).population;
 
   for (const network of populationRef) {
     if (!network) continue; // defensive guard for sparse arrays
@@ -483,9 +517,7 @@ export const applyLamarckianTraining = (
 
       // 4.3: Collect optional training stats (use optional chaining to avoid errors).
       try {
-        // Type assertion: accessing optional training stats method
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const stats = (network as any).getTrainingStats?.();
+        const stats = network.getTrainingStats?.();
         const gradNorm = stats?.gradNorm;
         if (Number.isFinite(gradNorm)) {
           gradientNormSum += gradNorm;
@@ -545,13 +577,9 @@ export const applyLamarckianTraining = (
  */
 export const warmStartPopulationIfNeeded = (
   neat: Neat,
-  // Type assertion: training dataset structure
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  trainingSet: any[],
+  trainingSet: LamarckianTrainingCase[],
   state: EngineState,
-  // Type assertion: helper function for population pretraining
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  pretrainPopulation: (neat: any, trainingSet: any[]) => void,
+  pretrainPopulation: PretrainPopulationCallback,
 ): void => {
   try {
     // Step 1: Fast-guard invalid inputs – nothing to do when no data or driver.
@@ -561,9 +589,12 @@ export const warmStartPopulationIfNeeded = (
 
     // Step 2: Best-effort ensure pooled buffers exist and have capacity.
     // Determine a sensible sizing target (prefer driver configured popSize when available).
-    const configuredPopulationSize = Number.isFinite(neat?.options?.popSize)
-      ? Math.max(0, Math.floor(neat.options.popSize))
-      : Math.max(8, trainingSet.length);
+    const neatRef = neat as WarmStartNeatLike;
+    const rawPopSize = neatRef.options?.popSize;
+    const configuredPopulationSize =
+      typeof rawPopSize === 'number' && Number.isFinite(rawPopSize)
+        ? Math.max(0, Math.floor(rawPopSize))
+        : Math.max(8, trainingSet.length);
 
     // Helper: next power-of-two >= n
     const nextPowerOfTwo = (n: number) =>