@reicek/neataptic-ts 0.1.21 → 0.1.23

package/src/neat/neat.evolve.population.utils.ts

@@ -11,6 +11,10 @@ import type {
   GenomeWithMetadata,
   NeatControllerForEvolution,
 } from './neat.evolve.types';
+import {
+  promoteGenomeToFeedForwardIntentWhenEligible,
+  usesFeedForwardMutationPolicy,
+} from './neat.topology-intent.utils';
 
 /**
  * Build the next population (elitism, provenance, offspring).
@@ -99,16 +103,36 @@ export function applyProvenance(
     0,
     Math.min(internal.options.provenance || 0, remainingSlotsAfterElites),
   );
+  const shouldPromoteFeedForwardIntent = usesFeedForwardMutationPolicy(
+    internal.options.mutation,
+  );
+
   // Step 2: Insert provenance genomes.
   for (let index = 0; index < provenanceCount; index++) {
     if (internal.options.network) {
-      nextPopulation.push(Network.fromJSON(internal.options.network.toJSON()));
+      const provenanceGenome = Network.fromJSON(
+        internal.options.network.toJSON(),
+      );
+
+      // Step 2.1: Preserve feed-forward intent when the seed topology is eligible.
+      promoteGenomeToFeedForwardIntentWhenEligible(
+        provenanceGenome,
+        shouldPromoteFeedForwardIntent,
+      );
+
+      nextPopulation.push(provenanceGenome);
     } else {
-      nextPopulation.push(
-        new Network(internal.input, internal.output, {
-          minHidden: internal.options.minHidden,
-        }),
+      const provenanceGenome = new Network(internal.input, internal.output, {
+        minHidden: internal.options.minHidden,
+      });
+
+      // Step 2.2: Promote fresh provenance genomes when FFW is the active contract.
+      promoteGenomeToFeedForwardIntentWhenEligible(
+        provenanceGenome,
+        shouldPromoteFeedForwardIntent,
       );
+
+      nextPopulation.push(provenanceGenome);
     }
   }
 }

package/src/neat/neat.helpers.ts

@@ -1,5 +1,9 @@
 import type { NeatLike } from './neat.types';
 import Network from '../architecture/network';
+import {
+  promoteGenomeToFeedForwardIntentWhenEligible,
+  usesFeedForwardMutationPolicy,
+} from './neat.topology-intent.utils';
 
 /**
  * Genome with NEAT-specific metadata and methods.
@@ -13,6 +17,9 @@ interface GenomeWithMetadata {
   clone?: () => GenomeWithMetadata;
   toJSON?: () => Record<string, unknown>;
   mutate?: (method: MutationMethod) => void;
+  setTopologyIntent?: (
+    topologyIntent: 'feed-forward' | 'unconstrained',
+  ) => void;
   [key: string]: unknown;
 }
 
@@ -261,6 +268,9 @@ export function createPool(
     // Step 1: Reset population container.
     internal.population = [];
     const poolSize = internal.options?.popsize ?? 50;
+    const shouldPromoteFeedForwardIntent = usesFeedForwardMutationPolicy(
+      internal.options?.mutation,
+    );
 
     // Step 2: Generate each initial genome.
     for (let genomeIndex = 0; genomeIndex < poolSize; genomeIndex++) {
@@ -276,6 +286,12 @@ export function createPool(
       // Step 2a: Ensure no stale scoring information.
       genomeCopy.score = undefined;
 
+      // Step 2a.1: Promote feed-forward topology intent when the policy and topology agree.
+      promoteGenomeToFeedForwardIntentWhenEligible(
+        genomeCopy,
+        shouldPromoteFeedForwardIntent,
+      );
+
       // Step 2b: Attempt structural invariant enforcement (best effort).
       try {
         internal.ensureNoDeadEnds?.(genomeCopy);

package/src/neat/neat.topology-intent.utils.ts

@@ -0,0 +1,160 @@
+import * as methods from '../methods/methods';
+
+/**
+ * Minimal mutation descriptor used by topology-intent helpers.
+ */
+export interface TopologyIntentMutationMethod {
+  /** Optional mutation name used for canonical pool comparison. */
+  name?: string;
+  /** Additional mutation metadata. */
+  [key: string]: unknown;
+}
+
+/**
+ * Minimal genome surface required to promote feed-forward intent safely.
+ */
+export interface TopologyIntentGenome {
+  /** Runtime node array in current graph order. */
+  nodes?: unknown[];
+  /** Runtime directed connection list. */
+  connections?: Array<{ from: unknown; to: unknown }>;
+  /** Runtime gated connection list. */
+  gates?: unknown[];
+  /** Runtime self-connection list. */
+  selfconns?: unknown[];
+  /** Public topology intent setter exposed by `Network`. */
+  setTopologyIntent?: (
+    topologyIntent: 'feed-forward' | 'unconstrained',
+  ) => void;
+}
+
+/**
+ * Determine whether the configured mutation policy communicates feed-forward intent.
+ *
+ * @param mutationConfig Configured mutation option.
+ * @returns True when the option expresses canonical FFW intent.
+ */
+export function usesFeedForwardMutationPolicy(
+  mutationConfig:
+    | TopologyIntentMutationMethod
+    | TopologyIntentMutationMethod[]
+    | unknown,
+): boolean {
+  // Step 1: Accept the canonical direct FFW reference.
+  if (mutationConfig === methods.mutation.FFW) {
+    return true;
+  }
+
+  // Step 2: Accept nested legacy `[methods.mutation.FFW]` wrappers.
+  if (
+    Array.isArray(mutationConfig) &&
+    mutationConfig.length === 1 &&
+    mutationConfig[0] === methods.mutation.FFW
+  ) {
+    return true;
+  }
+
+  // Step 3: Accept flattened pools that match the canonical FFW operator names.
+  if (!Array.isArray(mutationConfig)) {
+    return false;
+  }
+
+  return matchesCanonicalFeedForwardPool(
+    mutationConfig as TopologyIntentMutationMethod[],
+    methods.mutation.FFW as TopologyIntentMutationMethod[],
+  );
+}
+
+/**
+ * Promote a genome to feed-forward topology intent when the structure is eligible.
+ *
+ * @param genome Genome candidate being inserted into a population.
+ * @param shouldPromote Whether the active NEAT options request FFW semantics.
+ * @returns Nothing.
+ */
+export function promoteGenomeToFeedForwardIntentWhenEligible(
+  genome: TopologyIntentGenome,
+  shouldPromote: boolean,
+): void {
+  // Step 1: Skip work when the configured mutation policy is not FFW.
+  if (!shouldPromote) {
+    return;
+  }
+
+  // Step 2: Skip work when the genome cannot safely adopt feed-forward intent.
+  if (!isGenomeEligibleForFeedForwardIntentPromotion(genome)) {
+    return;
+  }
+
+  // Step 3: Apply the public topology contract through the network API.
+  genome.setTopologyIntent?.('feed-forward');
+}
+
+/**
+ * Check whether a configured mutation pool matches the canonical FFW pool.
+ *
+ * @param configuredPool Mutation pool configured on the NEAT instance.
+ * @param canonicalPool Canonical feed-forward mutation pool.
+ * @returns True when both pools align by operator name and order.
+ */
+function matchesCanonicalFeedForwardPool(
+  configuredPool: TopologyIntentMutationMethod[],
+  canonicalPool: TopologyIntentMutationMethod[],
+): boolean {
+  // Step 1: Reject shape mismatches early.
+  if (configuredPool.length !== canonicalPool.length) {
+    return false;
+  }
+
+  // Step 2: Ensure the flattened pool matches the canonical FFW ordering.
+  return configuredPool.every((configuredMethod, methodIndex) => {
+    return configuredMethod?.name === canonicalPool[methodIndex]?.name;
+  });
+}
+
+/**
+ * Check whether a genome can safely adopt feed-forward topology intent.
+ *
+ * Eligibility is intentionally conservative: the graph must already be free of
+ * gates/self-connections and all normal connections must follow the current
+ * node ordering. This avoids reinterpreting arbitrary legacy seeds as ordered
+ * feed-forward graphs when that would change structural semantics.
+ *
+ * @param genome Genome candidate.
+ * @returns True when the genome can safely adopt feed-forward intent.
+ */
+function isGenomeEligibleForFeedForwardIntentPromotion(
+  genome: TopologyIntentGenome,
+): boolean {
+  // Step 1: Validate that topology collections exist and that no recurrent-only
+  // features are currently active.
+  if (
+    !Array.isArray(genome.nodes) ||
+    !Array.isArray(genome.connections) ||
+    !Array.isArray(genome.gates) ||
+    !Array.isArray(genome.selfconns)
+  ) {
+    return false;
+  }
+
+  if (genome.gates.length > 0 || genome.selfconns.length > 0) {
+    return false;
+  }
+
+  // Step 2: Require every connection to follow the current node ordering.
+  const nodeIndexByReference = new Map<unknown, number>();
+  genome.nodes.forEach((node, nodeIndex) => {
+    nodeIndexByReference.set(node, nodeIndex);
+  });
+
+  return genome.connections.every((connection) => {
+    const sourceNodeIndex = nodeIndexByReference.get(connection.from);
+    const targetNodeIndex = nodeIndexByReference.get(connection.to);
+
+    return (
+      sourceNodeIndex !== undefined &&
+      targetNodeIndex !== undefined &&
+      sourceNodeIndex < targetNodeIndex
+    );
+  });
+}

package/src/utils/README.md

@@ -20,7 +20,7 @@ Design principles:
 
 ### memoryStats
 
-`(targetNetworks: import("C:/NeatapticTS/src/utils/memory").NetworkView | import("C:/NeatapticTS/src/utils/memory").NetworkView[] | undefined) => import("C:/NeatapticTS/src/utils/memory").MemoryStats`
+`(targetNetworks: import("src/utils/memory").NetworkView | import("src/utils/memory").NetworkView[] | undefined) => import("src/utils/memory").MemoryStats`
 
 ### MemoryStats
 
@@ -41,7 +41,7 @@ enabling typed local variables instead of `any` everywhere.
 
 ### registerTrackedNetwork
 
-`(network: import("C:/NeatapticTS/src/utils/memory").NetworkView | null | undefined) => void`
+`(network: import("src/utils/memory").NetworkView | null | undefined) => void`
 
 ### resetMemoryTracking
 
@@ -54,13 +54,13 @@ include additional fields; we only rely on fresh/pooled counts.
 
 ### unregisterTrackedNetwork
 
-`(network: import("C:/NeatapticTS/src/utils/memory").NetworkView) => void`
+`(network: import("src/utils/memory").NetworkView) => void`
 
 ## utils/memory.utils.ts
 
 ### accumulateCapacitySlices
 
-`(accumulators: import("C:/NeatapticTS/src/utils/memory.utils").Accumulators, network: import("C:/NeatapticTS/src/utils/memory").NetworkView, heuristics: import("C:/NeatapticTS/src/utils/memory.utils").HeuristicBytes) => void`
+`(accumulators: import("src/utils/memory.utils").Accumulators, network: import("src/utils/memory").NetworkView, heuristics: import("src/utils/memory.utils").HeuristicBytes) => void`
 
 Track reserved vs used bytes based on connection capacity slices.
 
@@ -71,7 +71,7 @@ Parameters:
 
 ### accumulateSlabArrays
 
-`(accumulators: import("C:/NeatapticTS/src/utils/memory.utils").Accumulators, typedArrays: (Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Uint8Array<ArrayBufferLike> | Int32Array<ArrayBufferLike>)[]) => void`
+`(accumulators: import("src/utils/memory.utils").Accumulators, typedArrays: (Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Uint8Array<ArrayBufferLike> | Int32Array<ArrayBufferLike>)[]) => void`
 
 Sum slab-backed array counts and byte sizes into the accumulator.
 
@@ -86,7 +86,7 @@ Accumulates counts, slab byte totals, and reserved vs used capacity snapshots.
 
 ### aggregateNetworkStats
 
-`(networksToSummarize: import("C:/NeatapticTS/src/utils/memory").NetworkView[], heuristics: import("C:/NeatapticTS/src/utils/memory.utils").HeuristicBytes) => import("C:/NeatapticTS/src/utils/memory.utils").Accumulators`
+`(networksToSummarize: import("src/utils/memory").NetworkView[], heuristics: import("src/utils/memory.utils").HeuristicBytes) => import("src/utils/memory.utils").Accumulators`
 
 Aggregate per-network counters and slab metrics into a single accumulator.
 
@@ -98,7 +98,7 @@ Returns: Accumulated summary of network metrics.
 
 ### buildFlagSnapshot
 
-`(configSnapshot: import("C:/NeatapticTS/src/utils/memory.utils").ConfigSnapshot, allocationStats: import("C:/NeatapticTS/src/utils/memory").SlabAllocStats) => { warnings: unknown; float32Mode: unknown; deterministicChainMode: unknown; enableGatingTraces: unknown; poolMaxPerBucket: number | null; poolPrewarmCount: number | null; enableNodePooling: boolean; allocStats: unknown; }`
+`(configSnapshot: import("src/utils/memory.utils").ConfigSnapshot, allocationStats: import("src/utils/memory").SlabAllocStats) => { warnings: unknown; float32Mode: unknown; deterministicChainMode: unknown; enableGatingTraces: unknown; poolMaxPerBucket: number | null; poolPrewarmCount: number | null; enableNodePooling: boolean; allocStats: unknown; }`
 
 Build flag snapshot derived from config and allocator stats.
 
@@ -115,7 +115,7 @@ Bundles precomputed accumulators, environment info, allocator stats, and flags.
 
 ### buildMemoryStatsSnapshot
 
-`(input: import("C:/NeatapticTS/src/utils/memory.utils").BuildMemoryStatsInput) => import("C:/NeatapticTS/src/utils/memory").MemoryStats`
+`(input: import("src/utils/memory.utils").BuildMemoryStatsInput) => import("src/utils/memory").MemoryStats`
 
 Build the full MemoryStats snapshot from precomputed components.
 
@@ -126,7 +126,7 @@ Returns: Complete MemoryStats snapshot.
 
 ### buildSlabStats
 
-`(accumulators: import("C:/NeatapticTS/src/utils/memory.utils").Accumulators, networksToSummarize: import("C:/NeatapticTS/src/utils/memory").NetworkView[], allocationStats: import("C:/NeatapticTS/src/utils/memory").SlabAllocStats) => { slabBytes: number; slabArrayCount: number; fragmentationPct: number | null; reservedBytes: number | null; usedBytes: number | null; slabVersion: number | null; asyncBuilds: number; pooledFraction: number | null; }`
+`(accumulators: import("src/utils/memory.utils").Accumulators, networksToSummarize: import("src/utils/memory").NetworkView[], allocationStats: import("src/utils/memory").SlabAllocStats) => { slabBytes: number; slabArrayCount: number; fragmentationPct: number | null; reservedBytes: number | null; usedBytes: number | null; slabVersion: number | null; asyncBuilds: number; pooledFraction: number | null; }`
 
 Assemble slab-related statistics for the MemoryStats payload.
 
@@ -139,7 +139,7 @@ Returns: Structured slab metrics block.
 
 ### calculateFragmentation
 
-`(accumulators: import("C:/NeatapticTS/src/utils/memory.utils").Accumulators) => number | null`
+`(accumulators: import("src/utils/memory.utils").Accumulators) => number | null`
 
 Compute fragmentation percentage from reserved vs used connection bytes.
 
@@ -150,7 +150,7 @@ Returns: Fragmentation percent (0-100) or null when undefined.
 
 ### calculatePooledFraction
 
-`(allocationStats: import("C:/NeatapticTS/src/utils/memory").SlabAllocStats) => number | null`
+`(allocationStats: import("src/utils/memory").SlabAllocStats) => number | null`
 
 Calculate pooled fraction from allocator stats with four-decimal precision.
 
@@ -169,7 +169,7 @@ Returns: Environment metrics structure for the snapshot.
 
 ### captureVersionMetadata
 
-`(accumulators: import("C:/NeatapticTS/src/utils/memory.utils").Accumulators, network: import("C:/NeatapticTS/src/utils/memory").NetworkView) => void`
+`(accumulators: import("src/utils/memory.utils").Accumulators, network: import("src/utils/memory").NetworkView) => void`
 
 Capture slab metadata (version and async builds) once across all networks.
 
@@ -179,7 +179,7 @@ Parameters:
 
 ### collectConnectionTypedArrays
 
-`(network: import("C:/NeatapticTS/src/utils/memory").NetworkView) => (Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Uint8Array<ArrayBufferLike> | Int32Array<ArrayBufferLike>)[]`
+`(network: import("src/utils/memory").NetworkView) => (Float32Array<ArrayBufferLike> | Float64Array<ArrayBufferLike> | Uint32Array<ArrayBufferLike> | Uint8Array<ArrayBufferLike> | Int32Array<ArrayBufferLike>)[]`
 
 Gather all typed arrays that represent connection-parallel data on a network.
 
@@ -190,7 +190,7 @@ Returns: Typed arrays aligned to connections.
 
 ### computeCounts
 
-`(network: import("C:/NeatapticTS/src/utils/memory").NetworkView) => CountSnapshot`
+`(network: import("src/utils/memory").NetworkView) => CountSnapshot`
 
 Capture simple counts for nodes and connections on a network view.
 
@@ -208,7 +208,7 @@ Keeps only the flags relevant to the memory snapshot to avoid leaking full confi
 
 ### createEmptyAccumulators
 
-`() => import("C:/NeatapticTS/src/utils/memory.utils").Accumulators`
+`() => import("src/utils/memory.utils").Accumulators`
 
 Initialize a fresh accumulator snapshot for memory summaries.
 
@@ -216,7 +216,7 @@ Returns: Zeroed accumulators ready for aggregation.
 
 ### describeConnectionBytes
 
-`(network: import("C:/NeatapticTS/src/utils/memory").NetworkView, heuristics: import("C:/NeatapticTS/src/utils/memory.utils").HeuristicBytes) => number`
+`(network: import("src/utils/memory").NetworkView, heuristics: import("src/utils/memory.utils").HeuristicBytes) => number`
 
 Determine bytes per connection using typed-array width or heuristic fallback.
 
@@ -237,7 +237,7 @@ These numbers represent typical JS object footprints, not exact runtime measurem
 
 ### normalizeNetworks
 
-`(targets: import("C:/NeatapticTS/src/utils/memory").NetworkView | import("C:/NeatapticTS/src/utils/memory").NetworkView[] | undefined, trackedNetworks: import("C:/NeatapticTS/src/utils/memory").NetworkView[]) => import("C:/NeatapticTS/src/utils/memory").NetworkView[]`
+`(targets: import("src/utils/memory").NetworkView | import("src/utils/memory").NetworkView[] | undefined, trackedNetworks: import("src/utils/memory").NetworkView[]) => import("src/utils/memory").NetworkView[]`
 
 Normalize provided targets to an array of networks, falling back to tracked registry.
 
@@ -249,7 +249,7 @@ Returns: Array of networks to summarize.
 
 ### safeGetSlabAllocationStats
 
-`(getSlabAllocationStats: () => unknown) => import("C:/NeatapticTS/src/utils/memory").SlabAllocStats`
+`(getSlabAllocationStats: () => unknown) => import("src/utils/memory").SlabAllocStats`
 
 Safely read slab allocation stats, guarding against provider errors.
 

package/test/examples/asciiMaze/README.md

@@ -32,59 +32,59 @@ Use this as a reference architecture when building your own task-specific neuroe
 ### Core runtime
 
 - `evolutionEngine.ts`
-	- Public façade entry point: `EvolutionEngine.runMazeEvolution(options)`.
-	- Delegates to modular files under `evolutionEngine/`.
+  - Public façade entry point: `EvolutionEngine.runMazeEvolution(options)`.
+  - Delegates to modular files under `evolutionEngine/`.
 - `evolutionEngine/`
-	- `optionsAndSetup.ts`: normalize options, prepare maze/distance map, create NEAT instance.
-	- `evolutionLoop.ts`: generation loop, cancellation, stop conditions, telemetry flow.
-	- `populationDynamics.ts`: pruning, simplify phase, anti-collapse, dynamic population.
-	- `trainingWarmStart.ts`: warm-start + Lamarckian/Baldwinian helpers.
-	- `telemetryMetrics.ts`: generation metrics collection/log formatting.
-	- `rngAndTiming.ts`, `scratchPools.ts`, `sampling.ts`, etc.: performance + deterministic helpers.
+  - `optionsAndSetup.ts`: normalize options, prepare maze/distance map, create NEAT instance.
+  - `evolutionLoop.ts`: generation loop, cancellation, stop conditions, telemetry flow.
+  - `populationDynamics.ts`: pruning, simplify phase, anti-collapse, dynamic population.
+  - `trainingWarmStart.ts`: warm-start + Lamarckian/Baldwinian helpers.
+  - `telemetryMetrics.ts`: generation metrics collection/log formatting.
+  - `rngAndTiming.ts`, `scratchPools.ts`, `sampling.ts`, etc.: performance + deterministic helpers.
 
 ### Maze simulation pipeline
 
 - `mazeVision.ts`
-	- Builds 6D inputs for the policy network.
+  - Builds 6D inputs for the policy network.
 - `mazeMovement.ts`
-	- Simulates one episode with action selection, movement, penalties/rewards, and final run result.
+  - Simulates one episode with action selection, movement, penalties/rewards, and final run result.
 - `fitness.ts`
-	- Converts simulation outcomes into scalar fitness.
+  - Converts simulation outcomes into scalar fitness.
 - `mazeUtils.ts`
-	- Encoding, BFS distance, progress calculations, coordinate utilities.
+  - Encoding, BFS distance, progress calculations, coordinate utilities.
 
 ### Visualization and UX
 
 - `dashboardManager.ts`
-	- Rich per-generation dashboard with telemetry history, archive of solved mazes, and trend snapshots.
+  - Rich per-generation dashboard with telemetry history, archive of solved mazes, and trend snapshots.
 - `mazeVisualization.ts`
-	- Colorized maze rendering and summary stats.
+  - Colorized maze rendering and summary stats.
 - `networkVisualization.ts`
-	- Network topology formatting/inspection.
+  - Network topology formatting/inspection.
 - `terminalUtility.ts` / `browserTerminalUtility.ts`
-	- Rendering primitives for Node terminal and browser DOM.
+  - Rendering primitives for Node terminal and browser DOM.
 - `browserLogger.ts`
-	- Browser-target logging utility.
+  - Browser-target logging utility.
 
 ### Scenario definitions and adapters
 
 - `mazes.ts`
-	- Static mazes (`tiny`, `small`, `medium`, `large`, `minotaur`) plus procedural `MazeGenerator`.
+  - Static mazes (`tiny`, `small`, `medium`, `large`, `minotaur`) plus procedural `MazeGenerator`.
 - `interfaces.ts`
-	- Canonical contracts: run options, telemetry contracts, network/visualization types.
+  - Canonical contracts: run options, telemetry contracts, network/visualization types.
 - `index.ts` and `asciiMaze.ts`
-	- Re-exports for easier imports.
+  - Re-exports for easier imports.
 
 ### Demo and test entry points
 
 - `browser-entry.ts`
-	- Public `start(...)` API for browser demo lifecycle.
+  - Public `start(...)` API for browser demo lifecycle.
 - `index.html`
-	- Simple host page loading `docs/assets/ascii-maze.bundle.js`.
+  - Simple host page loading `docs/assets/ascii-maze.bundle.js`.
 - `asciiMaze.e2e.test.ts`
-	- Curriculum-style end-to-end evolution in test form.
+  - Curriculum-style end-to-end evolution in test form.
 - `networkRefinement.ts` and `refineWinner.ts`
-	- Two refinement helpers (class-based and functional style).
+  - Two refinement helpers (class-based and functional style).
 
 ---
 
@@ -168,15 +168,15 @@ At a high level, `EvolutionEngine.runMazeEvolution` performs:
 2. Maze preparation (encoding, start/exit detection, distance map)
 3. NEAT creation and optional warm-start seeding
 4. Generation loop:
-	 - evaluate population
-	 - apply adaptive/population dynamics
-	 - apply optional refinement phases
-	 - log/update dashboard/telemetry
+   - evaluate population
+   - apply adaptive/population dynamics
+   - apply optional refinement phases
+   - log/update dashboard/telemetry
 5. Stop when one of these occurs:
-	 - solved threshold reached
-	 - stagnation cap hit
-	 - max generations reached
-	 - cancellation/abort requested
+   - solved threshold reached
+   - stagnation cap hit
+   - max generations reached
+   - cancellation/abort requested
 
 The engine supports deterministic mode, telemetry toggles, persistence intervals, and dynamic population controls.
 
@@ -241,25 +241,25 @@ import { DashboardManager } from './dashboardManager';
 import { TerminalUtility } from './terminalUtility';
 
 const dashboard = new DashboardManager(
-	TerminalUtility.createTerminalClearer(),
-	(...args) => console.log(...args),
+  TerminalUtility.createTerminalClearer(),
+  (...args) => console.log(...args),
 );
 
 const result = await EvolutionEngine.runMazeEvolution({
-	mazeConfig: { maze: new MazeGenerator(24, 24).generate() },
-	agentSimConfig: { maxSteps: 2000 },
-	evolutionAlgorithmConfig: {
-		popSize: 40,
-		maxGenerations: 100,
-		maxStagnantGenerations: 50,
-		minProgressToPass: 95,
-		allowRecurrent: true,
-	},
-	reportingConfig: {
-		dashboardManager: dashboard,
-		logEvery: 1,
-		label: 'demo-24x24',
-	},
+  mazeConfig: { maze: new MazeGenerator(24, 24).generate() },
+  agentSimConfig: { maxSteps: 2000 },
+  evolutionAlgorithmConfig: {
+    popSize: 40,
+    maxGenerations: 100,
+    maxStagnantGenerations: 50,
+    minProgressToPass: 95,
+    allowRecurrent: true,
+  },
+  reportingConfig: {
+    dashboardManager: dashboard,
+    logEvery: 1,
+    label: 'demo-24x24',
+  },
 });
 
 console.log(result.exitReason, result.bestResult?.progress);
@@ -272,17 +272,17 @@ console.log(result.exitReason, result.bestResult?.progress);
 If you’re teaching or experimenting, these knobs are typically most impactful first:
 
 1. `agentSimConfig.maxSteps`
-	 - increase for larger/harder mazes
+   - increase for larger/harder mazes
 2. `evolutionAlgorithmConfig.popSize`
-	 - larger population improves search breadth but costs compute
+   - larger population improves search breadth but costs compute
 3. `evolutionAlgorithmConfig.maxGenerations`
-	 - higher cap for difficult layouts
+   - higher cap for difficult layouts
 4. `evolutionAlgorithmConfig.minProgressToPass`
-	 - solved threshold sensitivity
+   - solved threshold sensitivity
 5. `lamarckianIterations` and `lamarckianSampleSize`
-	 - adjust local supervised-style refinement pressure
+   - adjust local supervised-style refinement pressure
 6. `deterministic` + `randomSeed`
-	 - reproducibility for educational comparisons
+   - reproducibility for educational comparisons
 
 Then, for advanced learners:
 
@@ -297,15 +297,15 @@ Then, for advanced learners:
 Try these in order:
 
 1. **Perception ablation**
-	 - Remove one input channel from `MazeVision` and observe learning degradation.
+   - Remove one input channel from `MazeVision` and observe learning degradation.
 2. **Reward shaping experiment**
-	 - Reduce exploration bonus and track effects on dead-end behavior.
+   - Reduce exploration bonus and track effects on dead-end behavior.
 3. **Curriculum comparison**
-	 - Train directly on big mazes vs phased growth with transfer.
+   - Train directly on big mazes vs phased growth with transfer.
 4. **Determinism study**
-	 - Fix seed and compare run-to-run variance when toggling certain heuristics.
+   - Fix seed and compare run-to-run variance when toggling certain heuristics.
 5. **Refinement impact**
-	 - Compare before/after `NetworkRefinement.refineWinnerWithBackprop` on transfer tasks.
+   - Compare before/after `NetworkRefinement.refineWinnerWithBackprop` on transfer tasks.
 
 ---
 

package/test/examples/asciiMaze/asciiMaze.e2e.test.ts

@@ -1,11 +1,12 @@
-import Network from '../../../src/architecture/network'; // Correct import for Network
 import { MazeGenerator } from './mazes';
 import { colors } from './colors';
 import { DashboardManager } from './dashboardManager';
 import { TerminalUtility } from './terminalUtility';
 import { IDashboardManager } from './interfaces';
-import { EvolutionEngine } from './evolutionEngine';
-import { NetworkRefinement } from './networkRefinement';
+import {
+  EvolutionEngine,
+  resolveMazeEvolutionPhaseOutcome,
+} from './evolutionEngine';
 
 /**
  * Forces console output for this test by writing directly to stdout/stderr.
@@ -30,6 +31,9 @@ const dashboardManagerInstance: IDashboardManager = new DashboardManager(
   forceLog,
 );
 
+/** Minimum progress required before the curriculum treats a phase as solved. */
+const CURRICULUM_MIN_PROGRESS_TO_PASS = 95;
+
 jest.setTimeout(3600000); //
 
 /**
@@ -137,7 +141,7 @@ describe('ASCII Maze Solver using Neuro-Evolution', () => {
           popSize: 40,
           autoPauseOnSolve: false,
           maxStagnantGenerations: 50,
-          minProgressToPass: 95,
+          minProgressToPass: CURRICULUM_MIN_PROGRESS_TO_PASS,
           // hard cap per phase (browser DEFAULT_MAX_GENERATIONS)
           maxGenerations: 100,
           lamarckianIterations: 4,
@@ -150,11 +154,12 @@ describe('ASCII Maze Solver using Neuro-Evolution', () => {
           label: `procedural-curriculum-${dim}x${dim}`,
         },
       });
-      proceduralPrevBest = result
-        ? NetworkRefinement.refineWinnerWithBackprop(
-            result.bestNetwork as Network,
-          )
-        : undefined;
+      const phaseOutcome = resolveMazeEvolutionPhaseOutcome(
+        result,
+        proceduralPrevBest,
+        CURRICULUM_MIN_PROGRESS_TO_PASS,
+      );
+      proceduralPrevBest = phaseOutcome.nextBestNetwork;
 
       expect(!!result?.bestNetwork).toBe(true);
     });