@reicek/neataptic-ts 0.1.21 → 0.1.22

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

@@ -26,7 +26,12 @@ import {
   isProfilingDetailsEnabled,
   profilingStartTimestamp,
 } from './rngAndTiming';
-import type { NetworkNode, NetworkConnection } from '../interfaces';
+import type {
+  EvolutionGenomeLike,
+  MutationOperationLike,
+  NetworkConnection,
+  NetworkNode,
+} from './evolutionEngine.types';
 
 /** Shared empty array to avoid repeated allocations for missing/invalid arrays. */
 // Type assertion: Empty array for generic fallback when arrays are invalid
@@ -51,32 +56,11 @@ const BIAS_RESET_HALF_RANGE = 0.1;
 /** Half-range for connection weight reset in anti-collapse recovery (±0.2). */
 const CONN_WEIGHT_RESET_HALF_RANGE = 0.2;
 
-// ========== Type Definitions for Runtime Network Structures ==========
-
-/** Network genome with dynamic runtime properties */
-interface RuntimeGenome {
-  nodes?: NetworkNode[];
-  connections?: NetworkConnection[];
-  clone?: () => RuntimeGenome;
-  mutate?: (method: unknown) => void;
-  _id?: number;
-  _parentId?: number;
-  [key: string]: unknown;
-}
-
-/** Mutation operation from NEAT driver */
-interface MutationOperation {
-  length?: number;
-  [key: string]: unknown;
-}
-
 /** Typed or array-based index buffer for sorting */
 type IndexBuffer = Uint32Array | Int32Array | number[];
 
-// ========== End Type Definitions ==========
-
 /** Cached reference to mutation ops array (invalidated if driver replaces the reference). */
-let cachedMutationOps: MutationOperation[] | null = null;
+let cachedMutationOps: MutationOperationLike[] | null = null;
 
 /**
  * Update plateau state based on current fitness vs baseline.
@@ -601,7 +585,7 @@ export const registerClone = (
 
     // Optionally track parent ID.
     if (parentId != null) {
-      const runtimeClone = clone as RuntimeGenome;
+      const runtimeClone = clone as EvolutionGenomeLike;
       runtimeClone._parentId = parentId;
     }
   } catch {
@@ -664,7 +648,7 @@ export const createChildFromParent = (
     if (!clone && typeof parent.clone === 'function') {
       clone = parent.clone();
       if (clone) {
-        const runtimeParent = parent as RuntimeGenome;
+        const runtimeParent = parent as EvolutionGenomeLike;
         registerClone(neat, clone, runtimeParent?._id);
       }
     }
@@ -984,15 +968,15 @@ const getMutationOps = (
 
     if (candidate && cachedMutationOps !== candidate) {
       if (Array.isArray(candidate)) {
-        cachedMutationOps = candidate as MutationOperation[];
+        cachedMutationOps = candidate as MutationOperationLike[];
       } else if (candidate && typeof candidate === 'object') {
-        const maybeMutation = candidate as MutationOperation;
+        const maybeMutation = candidate as MutationOperationLike;
         const maybeLen = maybeMutation.length;
         if (maybeLen != null && Number.isFinite(maybeLen) && maybeLen >= 0) {
-          cachedMutationOps = candidate as MutationOperation[];
+          cachedMutationOps = candidate as MutationOperationLike[];
         } else {
           cachedMutationOps = Object.values(
-            candidate as Record<string, MutationOperation>,
+            candidate as Record<string, MutationOperationLike>,
           );
         }
       } else {
@@ -1038,7 +1022,7 @@ export const ensureOutputIdentity = (
       genomeIndex < populationRef.length;
       genomeIndex++
     ) {
-      const genome = populationRef[genomeIndex] as RuntimeGenome;
+      const genome = populationRef[genomeIndex] as EvolutionGenomeLike;
       if (!genome) continue;
 
       const nodesRef: NetworkNode[] = Array.isArray(genome.nodes)
@@ -1300,7 +1284,7 @@ export const pruneSaturatedHiddenOutputs = (
   try {
     const pruneProfilingEnabled = isProfilingDetailsEnabled(state);
     const startProfile = pruneProfilingEnabled ? profilingStartTimestamp() : 0;
-    const runtimeGenome = genome as RuntimeGenome;
+    const runtimeGenome = genome as EvolutionGenomeLike;
     const nodesRef = runtimeGenome?.nodes ?? EMPTY_VEC;
 
     const outputCount = getNodeIndicesByType(nodesRef, 'output');
@@ -1465,7 +1449,7 @@ export const antiCollapseRecovery = (
     let totalBiasResets = 0;
 
     for (let sampleIndex = 0; sampleIndex < sampledCount; sampleIndex++) {
-      const genome = pooledSampleBuffer[sampleIndex] as RuntimeGenome;
+      const genome = pooledSampleBuffer[sampleIndex] as EvolutionGenomeLike;
       if (!genome) continue;
 
       try {
@@ -1515,7 +1499,7 @@ export const reinitializeGenomeOutputsAndWeights = (
   genome: unknown,
 ): { connReset: number; biasReset: number } => {
   try {
-    const runtimeGenome = genome as RuntimeGenome;
+    const runtimeGenome = genome as EvolutionGenomeLike;
     const nodesList: NetworkNode[] = Array.isArray(runtimeGenome?.nodes)
       ? runtimeGenome.nodes
       : [];

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

@@ -16,7 +16,7 @@
  */
 
 import type { Neat, Network } from '../../../../src/neataptic';
-import { EngineState } from './engineState';
+import type { EngineState } from './engineState';
 import { drawFastRandom, resolveRngParameters } from './rngAndTiming';
 
 /** Weight initialization minimum value for warm-start connections. */

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

@@ -5,9 +5,8 @@
  * shared state without relying on class statics.
  */
 
+import type { EngineState, RngCacheParameters } from './engineState.types';
 import {
-  EngineState,
-  RngCacheParameters,
   DEFAULT_RNG_CACHE_BATCH_SIZE,
   ensureRngCacheBatch,
   reseedRngState,

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

@@ -7,7 +7,7 @@
  * 3. Centralise RNG parameter resolution for sampling paths to keep behaviour deterministic under shared state.
  */
 
-import { EngineState } from './engineState';
+import type { EngineState } from './engineState.types';
 import { drawFastRandom, resolveRngParameters } from './rngAndTiming';
 import { MazeUtils } from '../mazeUtils';
 

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

@@ -5,11 +5,8 @@
  * shared {@link EngineState}. They keep the façade lean by encapsulating heuristics for logits
  * ring sizing, telemetry scratch sizing, and connection flag pooling.
  */
-import {
-  EngineState,
-  TelemetryScratchRequest,
-  initialiseTelemetryScratch,
-} from './engineState';
+import type { EngineState, TelemetryScratchRequest } from './engineState.types';
+import { initialiseTelemetryScratch } from './engineState';
 
 /**
  * Shape describing the parameters used when ensuring the logits ring capacity.

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

@@ -1,36 +1,14 @@
+import type { EvolutionHostAdapter } from './evolutionEngine.types';
+
 /**
- * setupHelpers.ts
+ * Setup helpers for the ASCII maze evolution engine.
  *
- * Environment and setup utilities for the evolution engine.
-   // Return  return async (): Promise<void> => {
-    // Polling loop: after each tick, if the cooperative pause flag is set, wait another tick.
-    // This keeps CPU usage minimal while allowing the host to pause/resume the evolution loop.
-    while (true) {
-      await preferredTick();
-      // Note: using a permissive read of the global pause flag; undefined => not paused.
-      if (!(globalThis as Record<string, unknown>).asciiMazePaused) return;
-      // otherwise continue and await another tick before re-checking
-    }
-  };
-};flush function used by the evolution loop.
-  return async (): Promise<void> => {
-    // Polling loop: after each tick, if the cooperative pause flag is set, wait another tick.
-    // This keeps CPU usage minimal while allowing the host to pause/resume the evolution loop.
-    while (true) {
-      await preferredTick();
-      // Note: using a permissive read of the global pause flag; undefined => not paused.
-      if (!(globalThis as Record<string, unknown>).asciiMazePaused) return;
-      // otherwise continue and await another tick before re-checking
-    }
-  };
-};ibilities:
- * - Create cooperative frame-yielding functions for async evolution loops
- * - Initialize Node.js filesystem persistence helpers (fs, path)
- * - Build resilient logging writers with fallback chains
+ * Responsibilities:
+ * - Create cooperative frame-yielding helpers for async evolution loops.
+ * - Initialize Node.js persistence helpers when available.
+ * - Build resilient logging writers with dashboard and console fallbacks.
  *
- * All functions are pure/side-effect-free except where explicitly documented.
- *
- * @module setupHelpers
+ * @module evolutionEngine/setupHelpers
  */
 
 /**
@@ -66,22 +44,24 @@ export interface DashboardManagerLike {
  * Behaviour:
  * - Prefers `requestAnimationFrame` when available (browser hosts)
  * - Falls back to `setImmediate` when available (Node) or `setTimeout(...,0)` otherwise
- * - Respects a cooperative pause flag (`globalThis.asciiMazePaused`) by polling between ticks
- *   without busy-waiting. The returned function resolves once a single new frame/tick is available
- *   and the pause flag is not set
+ * - Respects an optional host adapter pause callback by polling between ticks without busy-waiting
+ * - Resolves once a single new frame or tick is available and the host is not paused
  *
  * Steps:
  * 1. Choose the preferred tick function based on the host runtime
- * 2. When called, await the preferred tick; if `asciiMazePaused` is true poll again after the tick
+ * 2. When called, await the preferred tick; if the host adapter reports pause, poll again after the tick
  * 3. Resolve once a tick passed while not paused
  *
+ * @param hostAdapter - Optional host adapter that owns cooperative pause state.
  * @returns A function that yields cooperatively to the next animation frame / tick.
  *
  * @example
  * const flushToFrame = makeFlushToFrame();
  * await flushToFrame(); // yields to next frame/tick
  */
-export const makeFlushToFrame = (): (() => Promise<void>) => {
+export const makeFlushToFrame = (
+  hostAdapter?: EvolutionHostAdapter,
+): (() => Promise<void>) => {
   // Helper factories for the three tick primitives; each returns a Promise that resolves on the next tick.
   const rafTick = () =>
     new Promise<void>((resolve) =>
@@ -117,13 +97,26 @@ export const makeFlushToFrame = (): (() => Promise<void>) => {
     // This keeps CPU usage minimal while allowing the host to pause/resume the evolution loop.
     while (true) {
       await preferredTick();
-      // Note: using a permissive read of the global pause flag; undefined => not paused.
-      if (!(globalThis as Record<string, unknown>).asciiMazePaused) return;
+      if (!isPauseRequested(hostAdapter)) return;
       // otherwise continue and await another tick before re-checking
     }
   };
 };
 
+/**
+ * Read host-controlled pause state without letting host errors break the engine.
+ *
+ * @param hostAdapter - Optional host adapter implementing pause polling.
+ * @returns True when the host asks the engine to remain paused.
+ */
+function isPauseRequested(hostAdapter?: EvolutionHostAdapter): boolean {
+  try {
+    return hostAdapter?.isPauseRequested?.() === true;
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Initialize persistence helpers (Node `fs` & `path`) when available and ensure the target
  * directory exists. This helper intentionally does nothing in browser-like hosts.

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

@@ -7,56 +7,18 @@
  */
 import type { Neat, Network } from '../../../../src/neataptic';
 import type { GenomeDetailed } from '../../../../src/neat/neat.types';
+import type { EngineState } from './engineState.types';
+import type {
+  EvolutionGenomeLike,
+  NetworkNode,
+  TelemetryNeatLike,
+} from './evolutionEngine.types';
 import {
-  EngineState,
   ensureVisitedHashCapacity,
   initialiseTelemetryScratch,
 } from './engineState';
 import { getTail, sampleIntoScratch } from './sampling';
 
-/**
- * Runtime type for NEAT instance with dynamic properties.
- * NEAT instances may have population, getTelemetry and other runtime methods.
- */
-interface RuntimeNeat {
-  population?: unknown[];
-  getTelemetry?: () => unknown;
-  [key: string]: unknown;
-}
-
-/**
- * Runtime type for network connection with dynamic properties.
- * Connections may have enabled, weight, and other runtime-added fields.
- */
-interface RuntimeConnection {
-  enabled?: boolean;
-  weight?: number;
-  [key: string]: unknown;
-}
-
-/**
- * Runtime type for NEAT genome/network with dynamic properties.
- * Genomes may have nodes, connections, score, species and runtime tracking fields.
- */
-interface RuntimeGenome {
-  nodes?: RuntimeNode[];
-  connections?: RuntimeConnection[];
-  score?: number;
-  species?: number | null;
-  _lastStepOutputs?: unknown[];
-  [key: string]: unknown;
-}
-
-/**
- * Runtime type for network node with dynamic properties.
- * Nodes may have type, bias, and other runtime-added fields.
- */
-interface RuntimeNode {
-  type?: string;
-  bias?: number;
-  [key: string]: unknown;
-}
-
 /**
  * Telemetry tag emitted when logging action-entropy statistics.
  * @example
@@ -122,8 +84,6 @@ type TelemetryWriter = (message: string) => void;
 interface GenerationResult {
   /** Path taken by the agent (array of [x, y] coordinate pairs). */
   path?: ReadonlyArray<[number, number]>;
-  /** Additional properties may exist but are not strongly typed. */
-  [key: string]: unknown;
 }
 
 /**
@@ -208,7 +168,7 @@ export const logOutputBiasStats = ({
 }: LogOutputBiasParams): void => {
   if (typeof safeWrite !== 'function') return;
 
-  const runtimeFittest = fittest as RuntimeGenome | undefined;
+  const runtimeFittest = fittest as EvolutionGenomeLike | undefined;
   const nodeList = runtimeFittest?.nodes ?? [];
 
   try {
@@ -279,7 +239,7 @@ export const logLogitsAndCollapse = ({
 
   try {
     // Step 1: Obtain the recent logits history from the fittest candidate.
-    const runtimeFittest = fittest as RuntimeGenome | undefined;
+    const runtimeFittest = fittest as EvolutionGenomeLike | undefined;
     const logitsHistory: number[][] =
       (runtimeFittest?._lastStepOutputs as number[][]) ?? EMPTY_VECTOR;
     if (logitsHistory.length === 0) return;
@@ -414,7 +374,7 @@ export const logDiversity = ({
   sampleSize = DEFAULT_SAMPLE_SIZE,
 }: LogDiversityParams): void => {
   if (typeof safeWrite !== 'function') return;
-  const runtimeNeat = neat as RuntimeNeat | undefined;
+  const runtimeNeat = neat as TelemetryNeatLike | undefined;
   if (!runtimeNeat || !Array.isArray(runtimeNeat.population)) return;
 
   try {
@@ -452,7 +412,7 @@ export const collectTelemetryTail = (
   tailLength = 10,
 ): unknown => {
   // Step 1: Guard against missing telemetry providers so callers can skip optional handling.
-  const runtimeNeat = neat as RuntimeNeat | undefined;
+  const runtimeNeat = neat as TelemetryNeatLike | undefined;
   if (!runtimeNeat || typeof runtimeNeat.getTelemetry !== 'function')
     return undefined;
 
@@ -671,7 +631,7 @@ const countDistinctCoordinatesHashed = (
  */
 const computeDiversityMetrics = (
   state: EngineState,
-  neat: RuntimeNeat,
+  neat: TelemetryNeatLike,
   sampleSize: number,
 ): { speciesUniqueCount: number; simpson: number; weightStd: number } => {
   // Step 1: Normalise the population reference to a safe array view.
@@ -700,7 +660,7 @@ const computeDiversityMetrics = (
   let speciesUniqueCount = 0;
   let individualCount = 0;
   for (let genomeIndex = 0; genomeIndex < populationLength; genomeIndex++) {
-    const genome = population[genomeIndex] as RuntimeGenome | undefined;
+    const genome = population[genomeIndex] as EvolutionGenomeLike | undefined;
     const speciesId =
       (genome && genome.species != null ? genome.species : -1) | 0;
 
@@ -751,16 +711,14 @@ const computeDiversityMetrics = (
   for (let sampleIndex = 0; sampleIndex < sampledLength; sampleIndex++) {
     const genome = sampleBuffer[sampleIndex] as GenomeDetailed | undefined;
     const connections = Array.isArray(genome?.connections)
-      ? (genome.connections as RuntimeConnection[])
+      ? genome.connections
       : EMPTY_VECTOR;
     for (
       let connectionIndex = 0;
       connectionIndex < connections.length;
       connectionIndex++
     ) {
-      const connection = connections[connectionIndex] as
-        | RuntimeConnection
-        | undefined;
+      const connection = connections[connectionIndex];
       if (connection && connection.enabled !== false) {
         const weight = Number.isFinite(connection.weight)
           ? connection.weight!
@@ -786,7 +744,7 @@ const computeDiversityMetrics = (
 /** Gather indices of nodes matching `nodeType` into the pooled scratch buffer. */
 const collectNodeIndicesByType = (
   state: EngineState,
-  nodes: RuntimeNode[] | undefined,
+  nodes: NetworkNode[] | undefined,
   nodeType: string,
 ): number => {
   // Step 1: Exit early when the node list is absent or already empty.
@@ -818,7 +776,7 @@ const collectNodeIndicesByType = (
 /** Compute mean, standard deviation and CSV string for output-node biases. */
 const computeOutputBiasStats = (
   state: EngineState,
-  nodes: RuntimeNode[],
+  nodes: NetworkNode[],
   outputCount: number,
 ): { mean: number; std: number; biasesStr: string } => {
   // Step 1: Initialise telemetry scratch sized to the output-node count.

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

@@ -17,8 +17,8 @@
 
 import type { Neat, Network } from '../../../../src/neataptic';
 import { methods } from '../../../../src/neataptic';
-import type { RngCacheParameters } from './engineState';
-import { EngineState, initialiseTelemetryScratch } from './engineState';
+import type { EngineState, RngCacheParameters } from './engineState.types';
+import { initialiseTelemetryScratch } from './engineState';
 import { drawFastRandom, readHighResolutionTime } from './rngAndTiming';
 import { sampleArray } from './sampling';
 

package/test/examples/asciiMaze/evolutionEngine.ts

@@ -29,52 +29,19 @@ import {
   prepareLoopHelpers,
   emitProfileSummary,
 } from './evolutionEngine/evolutionLoop';
+import { resolveMazeEvolutionPhaseOutcome as resolveMazeEvolutionPhaseOutcomeImpl } from './evolutionEngine/curriculumPhase';
 import { printNetworkStructure } from './evolutionEngine/networkInspection';
-import { INetwork, IRunMazeEvolutionOptions } from './interfaces';
+import type { INetwork } from './interfaces';
+import type {
+  IRunMazeEvolutionOptions,
+  MazeEvolutionCurriculumPhaseOutcome,
+  MazeEvolutionRunResult,
+  NetworkConnection,
+  NetworkNode,
+  SpeciesHistoryHost,
+} from './evolutionEngine/evolutionEngine.types';
 import type Network from '../../../src/architecture/network';
 
-/**
- * Runtime type for network node with dynamic properties.
- * Nodes may have type, connections, and other runtime-added fields.
- */
-interface RuntimeNetworkNode {
-  type?: string;
-  connections?: {
-    out?: RuntimeNetworkConnection[];
-    [key: string]: unknown;
-  };
-  [key: string]: unknown;
-}
-
-/**
- * Runtime type for network connection with dynamic properties.
- * Connections track from/to nodes and enabled state.
- */
-interface RuntimeNetworkConnection {
-  from?: RuntimeNetworkNode;
-  to?: RuntimeNetworkNode;
-  enabled?: boolean;
-  [key: string]: unknown;
-}
-
-/**
- * Runtime type for evolution result with dynamic exit reason.
- * Results may include exitReason from simulation outcomes.
- */
-interface RuntimeEvolutionResult {
-  exitReason?: string;
-  [key: string]: unknown;
-}
-
-/**
- * Runtime type for EvolutionEngine class with dynamic properties.
- * Engine may have _speciesHistory for telemetry tracking.
- */
-interface RuntimeEvolutionEngine {
-  _speciesHistory?: unknown[];
-  [key: string]: unknown;
-}
-
 /**
  * EvolutionEngine: Thin façade for NEAT-based maze solving.
  *
@@ -91,6 +58,7 @@ interface RuntimeEvolutionEngine {
  *
  * Public API (frozen entry points):
  * - `runMazeEvolution(options)`: Main entry point for maze solving
+ * - `resolveMazeEvolutionPhaseOutcome(result, previousBest, minProgressToPass)`: Shared curriculum-phase interpretation helper
  * - `printNetworkStructure(network)`: Debug utility for network topology
  * - `setDeterministic(seed?)`: Enable deterministic mode
  * - `clearDeterministic()`: Disable deterministic mode
@@ -195,7 +163,7 @@ export class EvolutionEngine {
    * @internal - Small helper used by various engine methods; retained for internal use.
    */
   static #getNodeIndicesByType(
-    nodes: RuntimeNetworkNode[] | undefined,
+    nodes: NetworkNode[] | undefined,
     type: string,
   ): number {
     if (!Array.isArray(nodes) || nodes.length === 0) return 0;
@@ -221,10 +189,10 @@ export class EvolutionEngine {
    * @internal - Small helper used by network analysis methods; retained for internal use.
    */
   static #collectHiddenToOutputConns(
-    hiddenNode: RuntimeNetworkNode,
-    nodesRef: RuntimeNetworkNode[],
+    hiddenNode: NetworkNode,
+    nodesRef: NetworkNode[],
     outputCount: number,
-  ): RuntimeNetworkConnection[] {
+  ): NetworkConnection[] {
     if (
       !hiddenNode?.connections ||
       !Array.isArray(nodesRef) ||
@@ -243,9 +211,7 @@ export class EvolutionEngine {
     hiddenOutBuffer.length = 0;
     const outgoing = hiddenNode.connections.out ?? EvolutionEngine.#EMPTY_VEC;
     for (let outIndex = 0; outIndex < outgoing.length; outIndex++) {
-      const candidate = outgoing[
-        outIndex
-      ] as unknown as RuntimeNetworkConnection;
+      const candidate = outgoing[outIndex] as unknown as NetworkConnection;
       if (!candidate || candidate.enabled === false) continue;
       for (
         let outputIndex = 0;
@@ -295,7 +261,9 @@ export class EvolutionEngine {
    * console.log(`Best score: ${result.bestResult.score}`);
    * EvolutionEngine.printNetworkStructure(result.bestNetwork);
    */
-  static async runMazeEvolution(options: IRunMazeEvolutionOptions) {
+  static async runMazeEvolution(
+    options: IRunMazeEvolutionOptions,
+  ): Promise<MazeEvolutionRunResult> {
     // 1) Normalise and validate options (descriptive names, defaulting).
     const opts = normalizeRunOptions(
       options,
@@ -443,7 +411,7 @@ export class EvolutionEngine {
         REDUCED_TELEMETRY: EvolutionEngine.#STATE.toggles.reducedTelemetry,
         DISABLE_BALDWIN: EvolutionEngine.#STATE.toggles.disableBaldwinPhase,
       },
-      ((EvolutionEngine as unknown as RuntimeEvolutionEngine)
+      ((EvolutionEngine as unknown as SpeciesHistoryHost)
         ._speciesHistory as unknown as number[]) ??
         (EvolutionEngine.#EMPTY_VEC as unknown as number[]),
     );
@@ -484,9 +452,7 @@ export class EvolutionEngine {
       bestNetwork,
       bestResult,
       neat,
-      exitReason:
-        (bestResult as unknown as RuntimeEvolutionResult).exitReason ??
-        'incomplete',
+      exitReason: bestResult?.exitReason ?? 'incomplete',
     };
   }
 
@@ -520,3 +486,37 @@ export class EvolutionEngine {
     printNetworkStructure(EvolutionEngine.#STATE, network);
   }
 }
+
+/**
+ * Stable curriculum-phase compatibility surface exposed from the engine facade.
+ *
+ * @remarks
+ * The implementation lives in `evolutionEngine/curriculumPhase.ts`, but
+ * callers that already import from `./evolutionEngine` should keep using this
+ * façade export so the dedicated engine folder retains ownership without
+ * forcing import churn across browser-entry, tests, or downstream examples.
+ *
+ * @param evolutionResult - Stable engine result returned by `runMazeEvolution()`.
+ * @param previousBestNetwork - Previously carried curriculum winner, if one exists.
+ * @param minProgressToPass - Progress threshold required before the curriculum advances.
+ * @returns Shared curriculum outcome describing solve status and next carry-over winner.
+ *
+ * @example
+ * ```ts
+ * const phaseOutcome = resolveMazeEvolutionPhaseOutcome(result, previousBest, 95);
+ * if (phaseOutcome.solved) {
+ *   previousBest = phaseOutcome.nextBestNetwork;
+ * }
+ * ```
+ */
+export const resolveMazeEvolutionPhaseOutcome = (
+  evolutionResult: MazeEvolutionRunResult,
+  previousBestNetwork: INetwork | undefined,
+  minProgressToPass: number,
+): MazeEvolutionCurriculumPhaseOutcome => {
+  return resolveMazeEvolutionPhaseOutcomeImpl(
+    evolutionResult,
+    previousBestNetwork,
+    minProgressToPass,
+  );
+};

package/test/examples/asciiMaze/fitness.ts

@@ -1,10 +1,10 @@
 // Fitness evaluation logic for maze solving
 // Exports: FitnessEvaluator class with static methods
 
-import { INetwork } from './interfaces'; // Added INetwork import
+import type { INetwork } from './interfaces';
 import { MazeUtils } from './mazeUtils';
 import { MazeMovement } from './mazeMovement';
-import { IFitnessEvaluationContext } from './interfaces';
+import type { IFitnessEvaluationContext } from './fitness.types';
 
 /**
  * The `FitnessEvaluator` class is responsible for calculating the fitness of a neural network