@reicek/neataptic-ts 0.1.24 → 0.1.26

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

@@ -14,6 +14,10 @@ arrays and counters through every hot-path helper.
 
 ## evolutionEngine/engineState.types.ts
 
+### EngineProfilingState
+
+Aggregated profiling configuration and accumulators shared across the evolution run.
+
 ### EngineScratchState
 
 Centralised shared state for the ASCII maze evolution façade.
@@ -26,33 +30,29 @@ Responsibilities:
 
 Callers mutate the returned scratch instances in place to avoid per-generation allocations; higher-level modules should treat the helpers as the sole entry point for sizing or resetting shared buffers.
 
-### EngineToggleState
-
-Runtime switches that adjust telemetry verbosity and optional training phases.
-
-### EngineProfilingState
-
-Aggregated profiling configuration and accumulators shared across the evolution run.
-
 ### EngineState
 
 Shared engine state instance combining pooled scratch buffers with toggle flags.
 
-### TelemetryScratchRequest
+### EngineToggleState
 
-Configuration describing which telemetry scratch buffers require capacity guarantees.
+Runtime switches that adjust telemetry verbosity and optional training phases.
 
-### TelemetryScratchHandles
+### RngCacheHandles
 
-Collection of scratch buffers handed back after initialisation for convenience.
+Handles returned after ensuring the RNG cache is ready for consumption.
 
 ### RngCacheParameters
 
 Parameters controlling the RNG cache refill process.
 
-### RngCacheHandles
+### TelemetryScratchHandles
 
-Handles returned after ensuring the RNG cache is ready for consumption.
+Collection of scratch buffers handed back after initialisation for convenience.
+
+### TelemetryScratchRequest
+
+Configuration describing which telemetry scratch buffers require capacity guarantees.
 
 ### VisitedHashScratchHandles
 
@@ -60,25 +60,34 @@ Handles exposed after ensuring the visited-coordinate hash table capacity.
 
 ## evolutionEngine/evolutionEngine.types.ts
 
-### IMazeConfig
+### DistanceMap
 
-Maze configuration used by the ASCII Maze evolution helpers.
+Distance map for maze navigation.
 
-### IAgentSimulationConfig
+### EncodedMaze
 
-Agent simulation configuration.
+Encoded maze representation with cell values.
 
-### IEvolutionAlgorithmConfig
+### EncodedMazeData
 
-Configuration options for the evolutionary algorithm used in the ASCII Maze demos.
+Encoded maze for simulation.
 
-### EvolutionStopReason
+### EvolutionEngineFacadeRuntimeState
 
-Canonical stop reasons reported by the engine to host adapters.
+Mutable runtime state owned by the public EvolutionEngine facade.
 
-### EvolutionHostStopEvent
+The extracted engine modules already share pooled buffers through
+`engineState`. This narrower state exists only for the facade-specific
+logits-ring bookkeeping that must survive across runs while keeping the
+class boundary orchestration-first.
 
-Host-facing stop event emitted by the engine when a run finishes for a concrete reason.
+### EvolutionGenomeLike
+
+Loose genome shape shared by engine telemetry and population-dynamics helpers.
+
+### EvolutionHelpers
+
+Helper functions object passed to evolution loop orchestration.
 
 ### EvolutionHostAdapter
 
@@ -93,167 +102,158 @@ const hostAdapter: EvolutionHostAdapter = {
 };
 ```
 
-### IReportingConfig
-
-Reporting configuration used to control logging, dashboard updates and UI pacing.
-
-### IRunMazeEvolutionOptions
-
-Main options for running a single maze-evolution experiment.
+### EvolutionHostStopEvent
 
-### MazeEvolutionRunResult
+Host-facing stop event emitted by the engine when a run finishes for a concrete reason.
 
-Stable result returned by `EvolutionEngine.runMazeEvolution()`.
+### EvolutionLoopHelpers
 
-### MazeEvolutionCurriculumPhaseOutcome
+Helper functions for evolution.
 
-Shared curriculum-facing summary derived from one completed evolution phase.
+### EvolutionLoopRuntimeContext
 
-### NeatInstance
+Shared runtime buffers and limits consumed by the evolution loop hot path.
 
-Type for Neat class instance from the neataptic library.
+This context keeps the loop and simulation helpers from passing a long list
+of pooled ring buffers, scratch arrays, and capacity limits positionally.
 
-### NetworkInstance
+### EvolutionLoopSupportContext
 
-Type for Network class instance from the neataptic library.
+Shared scratch buffers and helper callbacks used across evolution-loop stages.
 
-### TrackedNetworkInstance
+This context groups the scratch arrays and analysis helpers that travel
+together through generation, simulation, and snapshot paths.
 
-Network instance annotated with telemetry fields during a generation.
+### EvolutionLoopTelemetryContext
 
-### EvolutionGenomeLike
+Shared telemetry thresholds consumed by the evolution loop simulation pass.
 
-Loose genome shape shared by engine telemetry and population-dynamics helpers.
+The loop owns these switches conceptually, but grouping them as one context
+keeps telemetry policy changes from widening hot-path function signatures.
 
-### TelemetryNeatLike
+### EvolutionOptions
 
-NEAT runtime shape needed by telemetry helpers that inspect the population.
+Options object passed to evolution functions.
 
-The telemetry helpers intentionally ask for very little here: access to the
-population plus optional telemetry export. That keeps them portable across the
-engine's internal helpers without binding them to the full driver surface.
+### EvolutionStopReason
 
-### MutationOperationLike
+Canonical stop reasons reported by the engine to host adapters.
 
-Mutation-operation surface read from the NEAT driver at runtime.
+### FileSystem
 
-The engine treats mutation operations as opaque descriptors because the
-concrete driver owns how those operations are interpreted. The helpers only
-need enough structure to cache, count, and hand them back into `mutate(...)`.
+Node.js fs module type for file operations.
 
-### SpeciesHistoryHost
+### IAgentSimulationConfig
 
-Static host used to read optional species-history state from the engine facade.
+Agent simulation configuration.
 
-### EncodedMaze
+### IEvolutionAlgorithmConfig
 
-Encoded maze representation with cell values.
+Configuration options for the evolutionary algorithm used in the ASCII Maze demos.
 
-### Position
+### IMazeConfig
 
-2D position in maze coordinates.
+Maze configuration used by the ASCII Maze evolution helpers.
 
-### DistanceMap
+### IReportingConfig
 
-Distance map for maze navigation.
+Reporting configuration used to control logging, dashboard updates and UI pacing.
 
-### EvolutionOptions
+### IRunMazeEvolutionOptions
 
-Options object passed to evolution functions.
+Main options for running a single maze-evolution experiment.
 
-### EvolutionHelpers
+### LogitsRingState
 
-Helper functions object passed to evolution loop orchestration.
+Ring state for logits tracking.
 
-### ProfilingAccumulators
+### LoopHelpers
 
-Profiling accumulator structure.
+Loop helpers returned by prepareLoopHelpers.
 
-### FileSystem
+### MazeDistanceMap
 
-Node.js fs module type for file operations.
+Distance map for pathfinding.
 
-### PathModule
+### MazeEvolutionCurriculumPhaseOutcome
 
-Node.js path module type.
+Shared curriculum-facing summary derived from one completed evolution phase.
 
-### LoopHelpers
+### MazeEvolutionRunResult
 
-Loop helpers returned by prepareLoopHelpers.
+Stable result returned by `EvolutionEngine.runMazeEvolution()`.
 
-### ScratchBundle
+### MazePosition
 
-Scratch bundle containing reusable buffers.
+Position in maze.
 
-### SnapshotEntry
+### MutationOperationLike
 
-Snapshot entry for persistence.
+Mutation-operation surface read from the NEAT driver at runtime.
 
-### TrainingConstants
+The engine treats mutation operations as opaque descriptors because the
+concrete driver owns how those operations are interpreted. The helpers only
+need enough structure to cache, count, and hand them back into `mutate(...)`.
 
-Training constants used by Lamarckian warm-start and refinement helpers.
+### NeatInstance
 
-### EvolutionLoopHelpers
+Type for Neat class instance from the neataptic library.
 
-Helper functions for evolution.
+### NetworkConnection
 
-### EvolutionLoopRuntimeContext
+Network connection representation used by engine-side runtime adaptation helpers.
 
-Shared runtime buffers and limits consumed by the evolution loop hot path.
+### NetworkInstance
 
-This context keeps the loop and simulation helpers from passing a long list
-of pooled ring buffers, scratch arrays, and capacity limits positionally.
+Type for Network class instance from the neataptic library.
 
-### EvolutionLoopTelemetryContext
+### NetworkNode
 
-Shared telemetry thresholds consumed by the evolution loop simulation pass.
+Network node representation used by engine-side runtime adaptation helpers.
 
-The loop owns these switches conceptually, but grouping them as one context
-keeps telemetry policy changes from widening hot-path function signatures.
+### PathModule
 
-### EvolutionLoopSupportContext
+Node.js path module type.
 
-Shared scratch buffers and helper callbacks used across evolution-loop stages.
+### Position
 
-This context groups the scratch arrays and analysis helpers that travel
-together through generation, simulation, and snapshot paths.
+2D position in maze coordinates.
 
-### NetworkNode
+### ProfilingAccumulators
 
-Network node representation used by engine-side runtime adaptation helpers.
+Profiling accumulator structure.
 
-### NetworkConnection
+### ScratchBundle
 
-Network connection representation used by engine-side runtime adaptation helpers.
+Scratch bundle containing reusable buffers.
 
-### EncodedMazeData
+### SimulationResult
 
-Encoded maze for simulation.
+Simulation result returned by generation evaluation helpers.
 
-### MazePosition
+### SnapshotEntry
 
-Position in maze.
+Snapshot entry for persistence.
 
-### MazeDistanceMap
+### SpeciesHistoryHost
 
-Distance map for pathfinding.
+Static host used to read optional species-history state from the engine facade.
 
-### LogitsRingState
+### TelemetryNeatLike
 
-Ring state for logits tracking.
+NEAT runtime shape needed by telemetry helpers that inspect the population.
 
-### EvolutionEngineFacadeRuntimeState
+The telemetry helpers intentionally ask for very little here: access to the
+population plus optional telemetry export. That keeps them portable across the
+engine's internal helpers without binding them to the full driver surface.
 
-Mutable runtime state owned by the public EvolutionEngine facade.
+### TrackedNetworkInstance
 
-The extracted engine modules already share pooled buffers through
-`engineState`. This narrower state exists only for the facade-specific
-logits-ring bookkeeping that must survive across runs while keeping the
-class boundary orchestration-first.
+Network instance annotated with telemetry fields during a generation.
 
-### SimulationResult
+### TrainingConstants
 
-Simulation result returned by generation evaluation helpers.
+Training constants used by Lamarckian warm-start and refinement helpers.
 
 ## evolutionEngine/sampling.ts
 
@@ -268,38 +268,89 @@ 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.
 
-### sampleArray
+### getTail
 
 ```ts
-sampleArray(
+getTail(
   state: EngineState,
-  source: T[],
-  sampleCount: number,
+  source: T[] | undefined,
+  count: number,
 ): T[]
 ```
 
-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.
+Extract the last `count` items from `source` into the shared tail buffer.
 
 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.
-3. Fill the pooled buffer using the shared fast RNG and truncate the logical length to `sampleCount`.
+1. Validate the source array and clamp the requested tail length.
+2. Grow the pooled tail buffer to the next power of two when necessary.
+3. Copy the suffix into the pooled buffer and trim its logical length.
 
 Parameters:
-- `state` - Shared engine state providing pooled scratch buffers.
-- `source` - Source array to sample from.
-- `sampleCount` - Number of samples to draw (with replacement).
+- `state` - Shared engine state providing the tail history buffer.
+- `source` - Source array reference.
+- `count` - Number of trailing items requested.
 
-Returns: Pooled ephemeral array containing the sampled elements.
+Returns: Pooled array containing the requested tail slice.
 
 Example:
 
-const picks = sampleArray(sharedState, population, 16);
-const safeCopy = [...picks];
+const recent = getTail(sharedState, telemetryLog, 40);
+
+### pushHistory
+
+```ts
+pushHistory(
+  buffer: T[] | undefined,
+  value: T,
+  maxLength: number,
+): T[]
+```
+
+Proxy to {@link MazeUtils.pushHistory} for consistency with the façade API.
+
+Parameters:
+- `buffer` - Existing history buffer (may be undefined).
+- `value` - Value to append to the buffer.
+- `maxLength` - Maximum allowed buffer length.
+
+Returns: Updated history buffer with `value` appended and trimmed to `maxLength`.
+
+Example:
+
+const history = pushHistory(existingHistory, snapshot, 20);
+
+### sampleArray
+
+```ts
+sampleArray(
+  state: EngineState,
+  source: T[],
+  sampleCount: number,
+): T[]
+```
+
+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.
+3. Fill the pooled buffer using the shared fast RNG and truncate the logical length to `sampleCount`.
+
+Parameters:
+- `state` - Shared engine state providing pooled scratch buffers.
+- `source` - Source array to sample from.
+- `sampleCount` - Number of samples to draw (with replacement).
+
+Returns: Pooled ephemeral array containing the sampled elements.
+
+Example:
+
+const picks = sampleArray(sharedState, population, 16);
+const safeCopy = [...picks];
 
 ### sampleIntoScratch
 
@@ -370,57 +421,6 @@ Example:
 const written = sampleSegmentIntoScratch(sharedState, population, elitismCount, 12);
 const genome = sharedState.scratch.samplePool[0];
 
-### getTail
-
-```ts
-getTail(
-  state: EngineState,
-  source: T[] | undefined,
-  count: number,
-): T[]
-```
-
-Extract the last `count` items from `source` into the shared tail buffer.
-
-Steps:
-1. Validate the source array and clamp the requested tail length.
-2. Grow the pooled tail buffer to the next power of two when necessary.
-3. Copy the suffix into the pooled buffer and trim its logical length.
-
-Parameters:
-- `state` - Shared engine state providing the tail history buffer.
-- `source` - Source array reference.
-- `count` - Number of trailing items requested.
-
-Returns: Pooled array containing the requested tail slice.
-
-Example:
-
-const recent = getTail(sharedState, telemetryLog, 40);
-
-### pushHistory
-
-```ts
-pushHistory(
-  buffer: T[] | undefined,
-  value: T,
-  maxLength: number,
-): T[]
-```
-
-Proxy to {@link MazeUtils.pushHistory} for consistency with the façade API.
-
-Parameters:
-- `buffer` - Existing history buffer (may be undefined).
-- `value` - Value to append to the buffer.
-- `maxLength` - Maximum allowed buffer length.
-
-Returns: Updated history buffer with `value` appended and trimmed to `maxLength`.
-
-Example:
-
-const history = pushHistory(existingHistory, snapshot, 20);
-
 ## evolutionEngine/engineState.ts
 
 Centralised shared state for the ASCII maze evolution façade.
@@ -433,57 +433,30 @@ Responsibilities:
 
 Callers mutate the returned scratch instances in place to avoid per-generation allocations; higher-level modules should treat the helpers as the sole entry point for sizing or resetting shared buffers.
 
-### EngineProfilingState
-
-Aggregated profiling configuration and accumulators shared across the evolution run.
-
-### EngineScratchState
-
-Centralised shared state for the ASCII maze evolution façade.
-
-Responsibilities:
-1. Define the scratch-buffer schema consumed by telemetry, population, and inspection helpers.
-2. Expose runtime toggle state (`EngineToggleState`) that drives optional phases and telemetry density.
-3. Provide factory and maintenance helpers (`createEngineState`, `initialiseTelemetryScratch`, `ensureVisitedHashCapacity`, `ensureRngCacheBatch`, `reseedRngState`) that size buffers and keep deterministic RNG state in sync.
-4. Export the project-wide singleton `engineState` so extracted modules can share the façade’s pooled resources while still accepting injected state for testing.
-
-Callers mutate the returned scratch instances in place to avoid per-generation allocations; higher-level modules should treat the helpers as the sole entry point for sizing or resetting shared buffers.
-
-### EngineState
-
-Shared engine state instance combining pooled scratch buffers with toggle flags.
-
-### EngineToggleState
-
-Runtime switches that adjust telemetry verbosity and optional training phases.
-
-### RngCacheHandles
-
-Handles returned after ensuring the RNG cache is ready for consumption.
-
-### RngCacheParameters
-
-Parameters controlling the RNG cache refill process.
-
-### TelemetryScratchHandles
+### createEngineState
 
-Collection of scratch buffers handed back after initialisation for convenience.
+```ts
+createEngineState(): EngineState
+```
 
-### TelemetryScratchRequest
+Fabricates a new {@link EngineState} with pre-sized scratch buffers and default toggle values.
 
-Configuration describing which telemetry scratch buffers require capacity guarantees.
+Returns: Initialized engine state used by the maze evolution façade.
 
-### VisitedHashScratchHandles
+### createProfilingState
 
-Handles exposed after ensuring the visited-coordinate hash table capacity.
+```ts
+createProfilingState(): EngineProfilingState
+```
 
-### DEFAULT_RNG_CACHE_BATCH_SIZE
+Fabricates the profiling state bundle consumed by timing helpers.
 
-Default RNG cache batch size mirroring the façade constant.
+Returns: Profiling configuration and accumulator state.
 
-### DEFAULT_VISITED_HASH_LOAD_FACTOR
+Example:
 
-Default load factor target for the visited coordinate hash table.
+const profiling = createProfilingState();
+console.log(profiling.detailsEnabled); // false unless env flag set
 
 ### createScratchState
 
@@ -515,30 +488,54 @@ Example:
 const toggles = createToggleState();
 console.log(toggles.reducedTelemetry); // false
 
-### createProfilingState
+### DEFAULT_RNG_CACHE_BATCH_SIZE
 
-```ts
-createProfilingState(): EngineProfilingState
-```
+Default RNG cache batch size mirroring the façade constant.
 
-Fabricates the profiling state bundle consumed by timing helpers.
+### DEFAULT_VISITED_HASH_LOAD_FACTOR
 
-Returns: Profiling configuration and accumulator state.
+Default load factor target for the visited coordinate hash table.
 
-Example:
+### EngineProfilingState
 
-const profiling = createProfilingState();
-console.log(profiling.detailsEnabled); // false unless env flag set
+Aggregated profiling configuration and accumulators shared across the evolution run.
 
-### createEngineState
+### EngineScratchState
+
+Centralised shared state for the ASCII maze evolution façade.
+
+Responsibilities:
+1. Define the scratch-buffer schema consumed by telemetry, population, and inspection helpers.
+2. Expose runtime toggle state (`EngineToggleState`) that drives optional phases and telemetry density.
+3. Provide factory and maintenance helpers (`createEngineState`, `initialiseTelemetryScratch`, `ensureVisitedHashCapacity`, `ensureRngCacheBatch`, `reseedRngState`) that size buffers and keep deterministic RNG state in sync.
+4. Export the project-wide singleton `engineState` so extracted modules can share the façade’s pooled resources while still accepting injected state for testing.
+
+Callers mutate the returned scratch instances in place to avoid per-generation allocations; higher-level modules should treat the helpers as the sole entry point for sizing or resetting shared buffers.
+
+### EngineState
+
+Shared engine state instance combining pooled scratch buffers with toggle flags.
+
+### EngineToggleState
+
+Runtime switches that adjust telemetry verbosity and optional training phases.
+
+### ensureRngCacheBatch
 
 ```ts
-createEngineState(): EngineState
+ensureRngCacheBatch(
+  parameters: RngCacheParameters,
+  state: EngineState,
+): RngCacheHandles
 ```
 
-Fabricates a new {@link EngineState} with pre-sized scratch buffers and default toggle values.
+Ensure the RNG cache contains fresh samples before consumption.
 
-Returns: Initialized engine state used by the maze evolution façade.
+Parameters:
+- `parameters` - Congruential generator parameters and cache batch size.
+- `state` - Optional engine state container (defaults to the shared singleton).
+
+Returns: Handles exposing the cache and its batch size.
 
 ### ensureVisitedHashCapacity
 
@@ -589,23 +586,6 @@ Parameters:
 
 Returns: Handles referencing the ensured scratch buffers for immediate use.
 
-### ensureRngCacheBatch
-
-```ts
-ensureRngCacheBatch(
-  parameters: RngCacheParameters,
-  state: EngineState,
-): RngCacheHandles
-```
-
-Ensure the RNG cache contains fresh samples before consumption.
-
-Parameters:
-- `parameters` - Congruential generator parameters and cache batch size.
-- `state` - Optional engine state container (defaults to the shared singleton).
-
-Returns: Handles exposing the cache and its batch size.
-
 ### reseedRngState
 
 ```ts
@@ -623,6 +603,27 @@ Parameters:
 
 Returns: Unsigned seed stored in scratch state for diagnostics.
 
+### RngCacheHandles
+
+Handles returned after ensuring the RNG cache is ready for consumption.
+
+### RngCacheParameters
+
+Parameters controlling the RNG cache refill process.
+
+### setBaldwinPhaseDisabledFlag
+
+```ts
+setBaldwinPhaseDisabledFlag(
+  isDisabled: boolean,
+): void
+```
+
+Enable or disable the Baldwin-phase warm-start pipeline.
+
+Parameters:
+- `isDisabled` - When true, skips the Lamarckian training stage.
+
 ### setReducedTelemetryFlag
 
 ```ts
@@ -649,60 +650,21 @@ Toggle the minimal telemetry mode for JSON output.
 Parameters:
 - `isMinimal` - When true, disables verbose telemetry capture.
 
-### setBaldwinPhaseDisabledFlag
+### TelemetryScratchHandles
 
-```ts
-setBaldwinPhaseDisabledFlag(
-  isDisabled: boolean,
-): void
-```
-
-Enable or disable the Baldwin-phase warm-start pipeline.
-
-Parameters:
-- `isDisabled` - When true, skips the Lamarckian training stage.
-
-## evolutionEngine/rngAndTiming.ts
-
-RNG and timing helpers extracted from the evolution façade.
-
-### readHighResolutionTime
-
-```ts
-readHighResolutionTime(): number
-```
-
-Obtain a monotonic-ish timestamp suitable for profiling.
-
-Returns: Timestamp in milliseconds, preferring `performance.now` when available.
-
-Example:
-
-const timestamp = readHighResolutionTime();
-
-### profilingStartTimestamp
-
-```ts
-profilingStartTimestamp(): number
-```
-
-Return a profiling start timestamp that mirrors the historic `#PROFILE_T0` helper.
-
-Returns: Millisecond timestamp representing the profiling start time.
+Collection of scratch buffers handed back after initialisation for convenience.
 
-### resolveRngParameters
+### TelemetryScratchRequest
 
-```ts
-resolveRngParameters(): RngCacheParameters
-```
+Configuration describing which telemetry scratch buffers require capacity guarantees.
 
-Provide cached congruential parameters used by the shared fast RNG helper.
+### VisitedHashScratchHandles
 
-Returns: Immutable  {@link RngCacheParameters} reference reused across draws.
+Handles exposed after ensuring the visited-coordinate hash table capacity.
 
-Example:
+## evolutionEngine/rngAndTiming.ts
 
-const parameters = resolveRngParameters();
+RNG and timing helpers extracted from the evolution façade.
 
 ### accumulateProfilingDuration
 
@@ -723,6 +685,21 @@ Parameters:
 
 Returns: void.
 
+### clearDeterministicMode
+
+```ts
+clearDeterministicMode(
+  state: EngineState,
+): void
+```
+
+Disable deterministic RNG mode.
+
+Parameters:
+- `state` - Shared engine state where the deterministic flag is stored.
+
+Returns: void.
+
 ### drawFastRandom
 
 ```ts
@@ -744,37 +721,20 @@ Example:
 
 const sample = drawFastRandom(sharedState, rngParameters);
 
-### setDeterministicMode
-
-```ts
-setDeterministicMode(
-  state: EngineState,
-  seed: number | undefined,
-): void
-```
-
-Enable deterministic RNG mode and optionally reseed the shared RNG state.
-
-Parameters:
-- `state` - Shared engine state where the deterministic flag is stored.
-- `seed` - Optional deterministic seed. Finite numeric inputs are normalised to u32.
-
-Returns: void.
-
-### clearDeterministicMode
+### getProfilingAccumulators
 
 ```ts
-clearDeterministicMode(
+getProfilingAccumulators(
   state: EngineState,
-): void
+): Record<string, number>
 ```
 
-Disable deterministic RNG mode.
+Provide direct access to the profiling accumulator map.
 
 Parameters:
-- `state` - Shared engine state where the deterministic flag is stored.
+- `state` - Shared engine state containing the profiling accumulators.
 
-Returns: void.
+Returns: Mutable record of profiling accumulators keyed by category name.
 
 ### isDeterministicModeEnabled
 
@@ -806,72 +766,68 @@ Parameters:
 
 Returns: True when detail profiling is enabled.
 
-### getProfilingAccumulators
+### profilingStartTimestamp
 
 ```ts
-getProfilingAccumulators(
-  state: EngineState,
-): Record<string, number>
+profilingStartTimestamp(): number
 ```
 
-Provide direct access to the profiling accumulator map.
-
-Parameters:
-- `state` - Shared engine state containing the profiling accumulators.
-
-Returns: Mutable record of profiling accumulators keyed by category name.
+Return a profiling start timestamp that mirrors the historic `#PROFILE_T0` helper.
 
-## evolutionEngine/scratchPools.ts
+Returns: Millisecond timestamp representing the profiling start time.
 
-Scratch pool management helpers extracted from the maze evolution façade.
+### readHighResolutionTime
 
-These utilities centralise the logic that grows and shrinks pooled buffers attached to the
-shared {@link EngineState}. They keep the façade lean by encapsulating heuristics for logits
-ring sizing, telemetry scratch sizing, and connection flag pooling.
+```ts
+readHighResolutionTime(): number
+```
 
-### LogitsRingCapacityOptions
+Obtain a monotonic-ish timestamp suitable for profiling.
 
-Shape describing the parameters used when ensuring the logits ring capacity.
+Returns: Timestamp in milliseconds, preferring `performance.now` when available.
 
-### LogitsRingCapacityResult
+Example:
 
-Result returned after resizing the logits ring.
+const timestamp = readHighResolutionTime();
 
-### ensureLogitsRingCapacity
+### resolveRngParameters
 
 ```ts
-ensureLogitsRingCapacity(
-  capacityRequest: LogitsRingCapacityOptions,
-): LogitsRingCapacityResult
+resolveRngParameters(): RngCacheParameters
 ```
 
-Grow or shrink the logits ring to accomodate the requested recent-step budget.
-
-Parameters:
-- `capacityRequest` - Parameters describing the requested resize.
+Provide cached congruential parameters used by the shared fast RNG helper.
 
-Returns: The resulting capacity and whether shared-array mode stayed enabled.
+Returns: Immutable  {@link RngCacheParameters} reference reused across draws.
 
-### SharedLogitsConfig
+Example:
 
-Parameters passed when attempting to initialise the shared logits ring buffers.
+const parameters = resolveRngParameters();
 
-### initialiseSharedLogitsRing
+### setDeterministicMode
 
 ```ts
-initialiseSharedLogitsRing(
+setDeterministicMode(
   state: EngineState,
-  config: SharedLogitsConfig,
-): boolean
+  seed: number | undefined,
+): void
 ```
 
-Attempt to allocate SharedArrayBuffer-backed logits ring storage.
+Enable deterministic RNG mode and optionally reseed the shared RNG state.
 
 Parameters:
-- `state` - Shared engine state containing the logits buffers.
-- `config` - Shared ring configuration (capacity and action dimension).
+- `state` - Shared engine state where the deterministic flag is stored.
+- `seed` - Optional deterministic seed. Finite numeric inputs are normalised to u32.
 
-Returns: true when shared mode was activated successfully.
+Returns: void.
+
+## evolutionEngine/scratchPools.ts
+
+Scratch pool management helpers extracted from the maze evolution façade.
+
+These utilities centralise the logic that grows and shrinks pooled buffers attached to the
+shared {@link EngineState}. They keep the façade lean by encapsulating heuristics for logits
+ring sizing, telemetry scratch sizing, and connection flag pooling.
 
 ### allocateLogitsRing
 
@@ -890,9 +846,37 @@ Parameters:
 
 Returns: Array of typed rows representing the ring buffer.
 
-### ScratchCapacityRequest
+### ensureConnFlagsCapacity
 
-Parameters describing the scratch sizing requirements for ensureScratchCapacity.
+```ts
+ensureConnFlagsCapacity(
+  state: EngineState,
+  minimumCapacity: number,
+): Int8Array<ArrayBufferLike> | null
+```
+
+Ensure the recurrent/gated detection bitmap has sufficient capacity.
+
+Parameters:
+- `state` - Shared engine state containing the pooled bitmap.
+- `minimumCapacity` - Minimum number of entries required by the caller.
+
+Returns: Int8Array bitmap or null when allocation failed.
+
+### ensureLogitsRingCapacity
+
+```ts
+ensureLogitsRingCapacity(
+  capacityRequest: LogitsRingCapacityOptions,
+): LogitsRingCapacityResult
+```
+
+Grow or shrink the logits ring to accomodate the requested recent-step budget.
+
+Parameters:
+- `capacityRequest` - Parameters describing the requested resize.
+
+Returns: The resulting capacity and whether shared-array mode stayed enabled.
 
 ### ensureScratchCapacity
 
@@ -909,6 +893,31 @@ Parameters:
 - `state` - Shared engine state exposing scratch buffers.
 - `request` - Sizing request describing the evolution workload.
 
+### initialiseSharedLogitsRing
+
+```ts
+initialiseSharedLogitsRing(
+  state: EngineState,
+  config: SharedLogitsConfig,
+): boolean
+```
+
+Attempt to allocate SharedArrayBuffer-backed logits ring storage.
+
+Parameters:
+- `state` - Shared engine state containing the logits buffers.
+- `config` - Shared ring configuration (capacity and action dimension).
+
+Returns: true when shared mode was activated successfully.
+
+### LogitsRingCapacityOptions
+
+Shape describing the parameters used when ensuring the logits ring capacity.
+
+### LogitsRingCapacityResult
+
+Result returned after resizing the logits ring.
+
 ### maybeShrinkScratch
 
 ```ts
@@ -924,22 +933,13 @@ Parameters:
 - `state` - Shared engine state exposing scratch buffers.
 - `populationSize` - Current population size used to derive shrink heuristics.
 
-### ensureConnFlagsCapacity
-
-```ts
-ensureConnFlagsCapacity(
-  state: EngineState,
-  minimumCapacity: number,
-): Int8Array<ArrayBufferLike> | null
-```
+### ScratchCapacityRequest
 
-Ensure the recurrent/gated detection bitmap has sufficient capacity.
+Parameters describing the scratch sizing requirements for ensureScratchCapacity.
 
-Parameters:
-- `state` - Shared engine state containing the pooled bitmap.
-- `minimumCapacity` - Minimum number of entries required by the caller.
+### SharedLogitsConfig
 
-Returns: Int8Array bitmap or null when allocation failed.
+Parameters passed when attempting to initialise the shared logits ring buffers.
 
 ## evolutionEngine/setupHelpers.ts
 
@@ -950,50 +950,15 @@ Responsibilities:
 - Initialize Node.js persistence helpers when available.
 - Build resilient logging writers with dashboard and console fallbacks.
 
-### FilesystemModule
-
-Minimal filesystem module shape for type safety (Node.js fs module subset).
-
-### PathModule
-
-Minimal path module shape for type safety (Node.js path module subset).
-
 ### DashboardManagerLike
 
 Dashboard manager shape for logging (optional log function).
 
-### makeFlushToFrame
-
-```ts
-makeFlushToFrame(
-  hostAdapter: EvolutionHostAdapter | undefined,
-): () => Promise<void>
-```
-
-Create a cooperative frame-yielding function used by the evolution loop.
-
-Behaviour:
-- Prefers `requestAnimationFrame` when available (browser hosts)
-- Falls back to `setImmediate` when available (Node) or `setTimeout(...,0)` otherwise
-- 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 the host adapter reports pause, poll again after the tick
-3. Resolve once a tick passed while not paused
-
-Parameters:
-- `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
-
-### initPersistence
+### FilesystemModule
+
+Minimal filesystem module shape for type safety (Node.js fs module subset).
+
+### initPersistence
 
 ```ts
 initPersistence(
@@ -1027,6 +992,52 @@ if (fs && path) {
   fs.writeFileSync(path.join(dir, 'snapshot.json'), data);
 }
 
+### isPauseRequested
+
+```ts
+isPauseRequested(
+  hostAdapter: EvolutionHostAdapter | undefined,
+): boolean
+```
+
+Read host-controlled pause state without letting host errors break the engine.
+
+Parameters:
+- `hostAdapter` - - Optional host adapter implementing pause polling.
+
+Returns: True when the host asks the engine to remain paused.
+
+### makeFlushToFrame
+
+```ts
+makeFlushToFrame(
+  hostAdapter: EvolutionHostAdapter | undefined,
+): () => Promise<void>
+```
+
+Create a cooperative frame-yielding function used by the evolution loop.
+
+Behaviour:
+- Prefers `requestAnimationFrame` when available (browser hosts)
+- Falls back to `setImmediate` when available (Node) or `setTimeout(...,0)` otherwise
+- 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 the host adapter reports pause, poll again after the tick
+3. Resolve once a tick passed while not paused
+
+Parameters:
+- `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
+
 ### makeSafeWriter
 
 ```ts
@@ -1058,20 +1069,9 @@ Example:
 const safeWrite = makeSafeWriter(dashboardManager);
 safeWrite('[INFO] Generation 42 complete\n');
 
-### isPauseRequested
-
-```ts
-isPauseRequested(
-  hostAdapter: EvolutionHostAdapter | undefined,
-): boolean
-```
-
-Read host-controlled pause state without letting host errors break the engine.
-
-Parameters:
-- `hostAdapter` - - Optional host adapter implementing pause polling.
+### PathModule
 
-Returns: True when the host asks the engine to remain paused.
+Minimal path module shape for type safety (Node.js path module subset).
 
 ## evolutionEngine/evolutionLoop.ts
 
@@ -1141,53 +1141,6 @@ if (checkCancellation(opts)) {
   break;
 }
 
-### prepareLoopHelpers
-
-```ts
-prepareLoopHelpers(
-  opts: EvolutionOptions,
-  scratchBundle: ScratchBundle,
-): LoopHelpers
-```
-
-Build lightweight helpers used inside the evolution loop.
-
-This function assembles the helper utilities needed by the main evolution loop:
- - Frame flushing for cooperative yielding
- - Persistence handles for snapshot saving (Node.js only)
- - Safe logging writer with fallback chain
- - Scratch buffer warm-up (best-effort)
-
-Design Rationale:
- - All initialization is best-effort (failures swallowed)
- - Warms up common scratch buffers to reduce first-use allocation spikes
- - Returns simple POJO with utilities (no class coupling)
- - Side effects isolated to scratch bundle parameter
-
-Scratch Buffer Warm-Up:
- - samplePool: Array for population sampling
- - profilingScratch: Float64Array(4) for timing accumulation
- - exps: Float64Array(64) for exponential computations
-
-Parameters:
-
-Parameters:
-- `opts` - - Normalized run options (contains persistDir and dashboardManager)
-- `scratchBundle` - - Engine scratch state for optional buffer warm-up
-
-Returns: Object containing:
-- flushToFrame: Async function for cooperative yielding
-- fs: Node.js fs module (null in browsers)
-- path: Node.js path module (null in browsers)
-- safeWrite: Resilient logging function with fallback chain
-
-Example:
-
-// Prepare loop helpers with scratch buffer warm-up
-const { flushToFrame, fs, path, safeWrite } = prepareLoopHelpers(opts, engineState.scratch);
-safeWrite('Starting evolution...\n');
-await flushToFrame(); // Yield to host
-
 ### checkStopConditions
 
 ```ts
@@ -1261,6 +1214,73 @@ if (reason) {
   break;
 }
 
+### emitProfileSummary
+
+```ts
+emitProfileSummary(
+  engineState: EngineState,
+  safeWrite: (msg: string) => void,
+  completedGenerations: number,
+  totalEvolveMs: number,
+  totalLamarckMs: number,
+  totalSimMs: number,
+  isProfilingDetailsEnabledFn: (state: EngineState) => boolean,
+  getProfilingAccumulatorsFn: (state: EngineState) => ProfilingAccumulators,
+): void
+```
+
+Emit a formatted profiling summary showing average per-generation timings.
+
+This function prints a compact profiling summary with average millisecond timings
+for the main evolution phases (evolve, Lamarckian training, simulation). If detailed
+profiling is enabled, it also prints averages for telemetry, simplify, snapshot, and
+prune operations.
+
+Design Rationale:
+ - Allocation-free (reuses pooled Float64Array for intermediate calculations)
+ - Best-effort error handling (swallow all exceptions)
+ - Defensive numeric validation with divide-by-zero guards
+ - Conditional detailed profiling output
+
+Calculation Steps:
+ 1. Validate and normalize generation count (guard divide-by-zero)
+ 2. Store totals in pooled scratch buffer (4-slot Float64Array)
+ 3. Compute per-generation averages by dividing totals by generation count
+ 4. Format numbers with 2 decimal places and print compact summary
+ 5. If detailed profiling enabled, print averaged detail line
+
+Parameters:
+
+Parameters:
+- `engineState` - - Shared engine state with scratch buffers and profiling accumulators
+- `safeWrite` - - Safe logging function (best-effort, never throws)
+- `completedGenerations` - - Number of completed generations (must be > 0)
+- `totalEvolveMs` - - Total milliseconds spent in NEAT evolve() calls
+- `totalLamarckMs` - - Total milliseconds spent in Lamarckian training
+- `totalSimMs` - - Total milliseconds spent in simulation
+- `isProfilingDetailsEnabledFn` - - Function to check if detailed profiling is enabled
+- `getProfilingAccumulatorsFn` - - Function to get detailed profiling accumulators
+
+Example:
+
+// Print averages after a run that completed 100 generations
+emitProfileSummary(
+  state, console.log, 100, 12000, 3000, 4500,
+  isProfilingDetailsEnabled, getProfilingAccumulators
+);
+
+### EvolutionLoopResult
+
+Evolution loop result
+
+### GenerationOutcome
+
+Generation outcome with profiling timings
+
+### MutableMazeResult
+
+Mutable result object with exitReason field
+
 ### persistSnapshotIfNeeded
 
 ```ts
@@ -1342,170 +1362,109 @@ persistSnapshotIfNeeded(
   scratchObj, scratchTop, collectTail, getSorted, isProfilingEnabled, profileStart, profileAccum
 );
 
-### updateDashboardAndMaybeFlush
+### prepareLoopHelpers
 
 ```ts
-updateDashboardAndMaybeFlush(
-  maze: string[],
-  result: IMazeRunResult | undefined,
-  network: default | null,
-  completedGenerations: number,
-  neat: default,
-  dashboardManager: IDashboardManager | undefined,
-  flushToFrame: (() => Promise<void>) | undefined,
-): Promise<void>
+prepareLoopHelpers(
+  opts: EvolutionOptions,
+  scratchBundle: ScratchBundle,
+): LoopHelpers
 ```
 
-Safely update a UI dashboard with the latest run state and optionally yield to the
-host/frame via an awaited flush function.
+Build lightweight helpers used inside the evolution loop.
 
-Behaviour (best-effort):
- 1) If `dashboardManager.update` exists and is callable, call it with the stable
-    argument order (maze, result, network, completedGenerations, neat). Any exception
-    raised by the dashboard is swallowed to avoid interrupting the evolution loop.
- 2) If `flushToFrame` is supplied as an async function, await it to yield control to
-    the event loop or renderer (for example `() => new Promise(r => requestAnimationFrame(r))`).
- 3) The helper avoids heap allocations and relies on existing pooled scratch buffers in
-    the engine for heavy telemetry elsewhere; this method intentionally performs only
-    short-lived control flow and minimal work.
+This function assembles the helper utilities needed by the main evolution loop:
+ - Frame flushing for cooperative yielding
+ - Persistence handles for snapshot saving (Node.js only)
+ - Safe logging writer with fallback chain
+ - Scratch buffer warm-up (best-effort)
 
 Design Rationale:
- - Allocation-free (no ephemeral objects or arrays created)
- - Best-effort error handling (swallow all dashboard/flush errors)
- - Stable argument order for dashboard implementations
- - Async support for cooperative yielding to host scheduler
+ - All initialization is best-effort (failures swallowed)
+ - Warms up common scratch buffers to reduce first-use allocation spikes
+ - Returns simple POJO with utilities (no class coupling)
+ - Side effects isolated to scratch bundle parameter
+
+Scratch Buffer Warm-Up:
+ - samplePool: Array for population sampling
+ - profilingScratch: Float64Array(4) for timing accumulation
+ - exps: Float64Array(64) for exponential computations
 
 Parameters:
 
 Parameters:
-- `maze` - - Maze instance or descriptor used by dashboard rendering.
-- `result` - - Per-run result object (path, progress, telemetry, etc.).
-- `network` - - Network or genome object that should be visualised.
-- `completedGenerations` - - Integer index of the completed generation.
-- `neat` - - NEAT manager instance (context passed to the dashboard update).
-- `dashboardManager` - - Optional manager exposing `update(maze, result, network, gen, neat)`.
-- `flushToFrame` - - Optional async function used to yield to the host/frame scheduler; may be omitted.
-
-Example:
-
-// Yield to the browser's next repaint after dashboard update:
-await updateDashboardAndMaybeFlush(
-  maze, genResult, fittestNetwork, gen, neatInstance, dashboard, () => new Promise(r => requestAnimationFrame(r))
-);
-
-### updateDashboardPeriodic
-
-```ts
-updateDashboardPeriodic(
-  maze: string[],
-  bestResult: IMazeRunResult | undefined,
-  bestNetwork: default | null,
-  completedGenerations: number,
-  neat: default,
-  dashboardManager: IDashboardManager | undefined,
-  flushToFrame: (() => Promise<void>) | undefined,
-): Promise<void>
-```
-
-Periodic dashboard update used when the engine wants to refresh a non-primary
-dashboard view (for example background or periodic reporting). This helper is
-intentionally small, allocation-light and best-effort: dashboard errors are
-swallowed so the evolution loop cannot be interrupted by UI issues.
-
-Behavioural contract:
- 1) If `dashboardManager.update` is present and callable the method invokes it with
-    the stable argument order: (maze, bestResult, bestNetwork, completedGenerations, neat).
- 2) If `flushToFrame` is supplied the helper awaits it after the update to yield to
-    the host renderer (eg. requestAnimationFrame). Any exceptions raised by the
-    flush are swallowed.
- 3) The helper avoids creating ephemeral arrays/objects and therefore does not use
-    typed-array scratch buffers here — there is no hot numerical work to pool. Other
-    engine helpers already reuse class-level scratch buffers where appropriate.
-
-Design Rationale:
- - Fast-guard early when update cannot be performed
- - Best-effort error handling (swallow all exceptions)
- - Preserves dashboard `this` binding with `.call()`
- - Minimal allocations (no scratch buffers needed)
-
-Steps / inline intent:
- 1. Fast-guard when an update cannot be performed (missing manager, update method,
-    or missing content to visualise).
- 2. Call the dashboard update in a try/catch to preserve best-effort semantics.
- 3. Optionally await the provided `flushToFrame` function to yield to the host.
-
-Parameters:
+- `opts` - - Normalized run options (contains persistDir and dashboardManager)
+- `scratchBundle` - - Engine scratch state for optional buffer warm-up
 
-Parameters:
-- `maze` - - Maze descriptor passed to the dashboard renderer.
-- `bestResult` - - Best-run result object used for display (may be falsy when not present).
-- `bestNetwork` - - Network or genome object to visualise (may be falsy when not present).
-- `completedGenerations` - - Completed generation index (number).
-- `neat` - - NEAT manager instance (passed through to dashboard update).
-- `dashboardManager` - - Optional manager exposing `update(maze, result, network, gen, neat)`.
-- `flushToFrame` - - Optional async function used to yield to the host/frame scheduler
- (for example: `() => new Promise(r => requestAnimationFrame(r))`).
+Returns: Object containing:
+- flushToFrame: Async function for cooperative yielding
+- fs: Node.js fs module (null in browsers)
+- path: Node.js path module (null in browsers)
+- safeWrite: Resilient logging function with fallback chain
 
 Example:
 
-// Safe periodic update and yield to next frame
-await updateDashboardPeriodic(
-  maze, result, network, gen, neatInstance, dashboard, () => new Promise(r => requestAnimationFrame(r))
-);
+// Prepare loop helpers with scratch buffer warm-up
+const { flushToFrame, fs, path, safeWrite } = prepareLoopHelpers(opts, engineState.scratch);
+safeWrite('Starting evolution...\n');
+await flushToFrame(); // Yield to host
 
-### emitProfileSummary
+### runEvolutionLoop
 
 ```ts
-emitProfileSummary(
+runEvolutionLoop(
   engineState: EngineState,
-  safeWrite: (msg: string) => void,
-  completedGenerations: number,
-  totalEvolveMs: number,
-  totalLamarckMs: number,
-  totalSimMs: number,
-  isProfilingDetailsEnabledFn: (state: EngineState) => boolean,
-  getProfilingAccumulatorsFn: (state: EngineState) => ProfilingAccumulators,
-): void
+  neat: default,
+  opts: EvolutionOptions,
+  lamarckianTrainingSet: { input: number[]; output: number[]; }[],
+  encodedMaze: number[][],
+  startPosition: readonly [number, number],
+  exitPosition: readonly [number, number],
+  distanceMap: number[][],
+  helpers: LoopHelpers,
+  doProfile: boolean,
+  runtimeContext: EvolutionLoopRuntimeContext,
+  initialRingState: LogitsRingState,
+  telemetryContext: EvolutionLoopTelemetryContext,
+  supportContext: EvolutionLoopSupportContext,
+  constants: TrainingConstants & { DEFAULT_TRAIN_BATCH_LARGE: number; FITTEST_TRAIN_ITERATIONS: number; TELEMETRY_MINIMAL: boolean; SATURATION_PRUNE_THRESHOLD: number; RECENT_WINDOW: number; REDUCED_TELEMETRY: boolean; DISABLE_BALDWIN: boolean; },
+): Promise<EvolutionLoopResult>
 ```
 
-Emit a formatted profiling summary showing average per-generation timings.
-
-This function prints a compact profiling summary with average millisecond timings
-for the main evolution phases (evolve, Lamarckian training, simulation). If detailed
-profiling is enabled, it also prints averages for telemetry, simplify, snapshot, and
-prune operations.
-
-Design Rationale:
- - Allocation-free (reuses pooled Float64Array for intermediate calculations)
- - Best-effort error handling (swallow all exceptions)
- - Defensive numeric validation with divide-by-zero guards
- - Conditional detailed profiling output
+Internal evolution loop that executes generations until a stop condition or cancellation.
 
-Calculation Steps:
- 1. Validate and normalize generation count (guard divide-by-zero)
- 2. Store totals in pooled scratch buffer (4-slot Float64Array)
- 3. Compute per-generation averages by dividing totals by generation count
- 4. Format numbers with 2 decimal places and print compact summary
- 5. If detailed profiling enabled, print averaged detail line
+Behaviour & contract:
+ - Runs generations in a resilient, best-effort manner; internal errors are swallowed
+   so a single failure cannot abort the whole run.
+ - When `doProfile` is truthy the loop accumulates timing into a pooled Float64Array
+   to avoid per-iteration allocations. The pooled buffer is reused across calls.
+ - The helper performs side-effects (dashboard updates, persistence) in a non-fatal
+   fashion and yields to the host when requested via `helpers.flushToFrame`.
 
 Parameters:
+- `engineState` - - Shared engine state with scratch buffers and configuration
+- `neat` - - NEAT driver instance used to perform evolution and mutation operations
+- `opts` - - Normalised run options (produced by normalizeRunOptions)
+- `lamarckianTrainingSet` - - Optional supervised training cases used for Lamarckian warm-start
+- `encodedMaze` - - Encoded maze representation consumed by simulators
+- `startPosition` - - Start coordinates for the simulated agent
+- `exitPosition` - - Exit coordinates for the simulated agent
+- `distanceMap` - - Optional precomputed distance map to speed simulation
+- `helpers` - - Helper utilities: { flushToFrame, fs, path, safeWrite }
+- `doProfile` - - When truthy collect and return millisecond timings in the result
+- `runtimeContext` - - Shared pooled ring buffers and limits for the hot path.
+- `initialRingState` - - Current mutable ring state for this run.
+- `telemetryContext` - - Telemetry thresholds and verbosity switches used during simulation.
+- `supportContext` - - Shared scratch buffers and helper callbacks used by the loop.
+- `constants` - - Object containing all engine constants (DEFAULT_TRAIN_ERROR, etc.)
 
-Parameters:
-- `engineState` - - Shared engine state with scratch buffers and profiling accumulators
-- `safeWrite` - - Safe logging function (best-effort, never throws)
-- `completedGenerations` - - Number of completed generations (must be > 0)
-- `totalEvolveMs` - - Total milliseconds spent in NEAT evolve() calls
-- `totalLamarckMs` - - Total milliseconds spent in Lamarckian training
-- `totalSimMs` - - Total milliseconds spent in simulation
-- `isProfilingDetailsEnabledFn` - - Function to check if detailed profiling is enabled
-- `getProfilingAccumulatorsFn` - - Function to get detailed profiling accumulators
+Returns: Promise resolving to an object:
+{ bestNetwork, bestResult, neat, completedGenerations, totalEvolveMs, totalLamarckMs, totalSimMs, updatedRingState }
 
 Example:
 
-// Print averages after a run that completed 100 generations
-emitProfileSummary(
-  state, console.log, 100, 12000, 3000, 4500,
-  isProfilingDetailsEnabled, getProfilingAccumulators
+const runSummary = await runEvolutionLoop(
+  state, neat, opts, trainingSet, maze, start, exit, distMap, helpers, true, ...
 );
 
 ### runGeneration
@@ -1606,6 +1565,10 @@ const { fittest, tEvolve, tLamarck } = await runGeneration(
   { DEFAULT_TRAIN_ERROR: 0.01, ... }
 );
 
+### SimResultWithOutputs
+
+Simulation result with step outputs
+
 ### simulateAndPostprocess
 
 ```ts
@@ -1679,113 +1642,122 @@ const { generationResult, simTime, updatedRingState } = simulateAndPostprocess(
   state, bestGenome, maze, start, exit, distMap, 1000, true, console.log, 10, genIdx, neat, ...
 );
 
-### runEvolutionLoop
+### SimulationOutcome
+
+Simulation result with profiling and ring state
+
+### updateDashboardAndMaybeFlush
 
 ```ts
-runEvolutionLoop(
-  engineState: EngineState,
+updateDashboardAndMaybeFlush(
+  maze: string[],
+  result: IMazeRunResult | undefined,
+  network: default | null,
+  completedGenerations: number,
   neat: default,
-  opts: EvolutionOptions,
-  lamarckianTrainingSet: { input: number[]; output: number[]; }[],
-  encodedMaze: number[][],
-  startPosition: readonly [number, number],
-  exitPosition: readonly [number, number],
-  distanceMap: number[][],
-  helpers: LoopHelpers,
-  doProfile: boolean,
-  runtimeContext: EvolutionLoopRuntimeContext,
-  initialRingState: LogitsRingState,
-  telemetryContext: EvolutionLoopTelemetryContext,
-  supportContext: EvolutionLoopSupportContext,
-  constants: TrainingConstants & { DEFAULT_TRAIN_BATCH_LARGE: number; FITTEST_TRAIN_ITERATIONS: number; TELEMETRY_MINIMAL: boolean; SATURATION_PRUNE_THRESHOLD: number; RECENT_WINDOW: number; REDUCED_TELEMETRY: boolean; DISABLE_BALDWIN: boolean; },
-): Promise<EvolutionLoopResult>
+  dashboardManager: IDashboardManager | undefined,
+  flushToFrame: (() => Promise<void>) | undefined,
+): Promise<void>
 ```
 
-Internal evolution loop that executes generations until a stop condition or cancellation.
+Safely update a UI dashboard with the latest run state and optionally yield to the
+host/frame via an awaited flush function.
 
-Behaviour & contract:
- - Runs generations in a resilient, best-effort manner; internal errors are swallowed
-   so a single failure cannot abort the whole run.
- - When `doProfile` is truthy the loop accumulates timing into a pooled Float64Array
-   to avoid per-iteration allocations. The pooled buffer is reused across calls.
- - The helper performs side-effects (dashboard updates, persistence) in a non-fatal
-   fashion and yields to the host when requested via `helpers.flushToFrame`.
+Behaviour (best-effort):
+ 1) If `dashboardManager.update` exists and is callable, call it with the stable
+    argument order (maze, result, network, completedGenerations, neat). Any exception
+    raised by the dashboard is swallowed to avoid interrupting the evolution loop.
+ 2) If `flushToFrame` is supplied as an async function, await it to yield control to
+    the event loop or renderer (for example `() => new Promise(r => requestAnimationFrame(r))`).
+ 3) The helper avoids heap allocations and relies on existing pooled scratch buffers in
+    the engine for heavy telemetry elsewhere; this method intentionally performs only
+    short-lived control flow and minimal work.
+
+Design Rationale:
+ - Allocation-free (no ephemeral objects or arrays created)
+ - Best-effort error handling (swallow all dashboard/flush errors)
+ - Stable argument order for dashboard implementations
+ - Async support for cooperative yielding to host scheduler
 
 Parameters:
-- `engineState` - - Shared engine state with scratch buffers and configuration
-- `neat` - - NEAT driver instance used to perform evolution and mutation operations
-- `opts` - - Normalised run options (produced by normalizeRunOptions)
-- `lamarckianTrainingSet` - - Optional supervised training cases used for Lamarckian warm-start
-- `encodedMaze` - - Encoded maze representation consumed by simulators
-- `startPosition` - - Start coordinates for the simulated agent
-- `exitPosition` - - Exit coordinates for the simulated agent
-- `distanceMap` - - Optional precomputed distance map to speed simulation
-- `helpers` - - Helper utilities: { flushToFrame, fs, path, safeWrite }
-- `doProfile` - - When truthy collect and return millisecond timings in the result
-- `runtimeContext` - - Shared pooled ring buffers and limits for the hot path.
-- `initialRingState` - - Current mutable ring state for this run.
-- `telemetryContext` - - Telemetry thresholds and verbosity switches used during simulation.
-- `supportContext` - - Shared scratch buffers and helper callbacks used by the loop.
-- `constants` - - Object containing all engine constants (DEFAULT_TRAIN_ERROR, etc.)
 
-Returns: Promise resolving to an object:
-{ bestNetwork, bestResult, neat, completedGenerations, totalEvolveMs, totalLamarckMs, totalSimMs, updatedRingState }
+Parameters:
+- `maze` - - Maze instance or descriptor used by dashboard rendering.
+- `result` - - Per-run result object (path, progress, telemetry, etc.).
+- `network` - - Network or genome object that should be visualised.
+- `completedGenerations` - - Integer index of the completed generation.
+- `neat` - - NEAT manager instance (context passed to the dashboard update).
+- `dashboardManager` - - Optional manager exposing `update(maze, result, network, gen, neat)`.
+- `flushToFrame` - - Optional async function used to yield to the host/frame scheduler; may be omitted.
 
 Example:
 
-const runSummary = await runEvolutionLoop(
-  state, neat, opts, trainingSet, maze, start, exit, distMap, helpers, true, ...
+// Yield to the browser's next repaint after dashboard update:
+await updateDashboardAndMaybeFlush(
+  maze, genResult, fittestNetwork, gen, neatInstance, dashboard, () => new Promise(r => requestAnimationFrame(r))
 );
 
-### MutableMazeResult
-
-Mutable result object with exitReason field
-
-### GenerationOutcome
+### updateDashboardPeriodic
 
-Generation outcome with profiling timings
-
-### SimulationOutcome
-
-Simulation result with profiling and ring state
-
-### EvolutionLoopResult
-
-Evolution loop result
-
-### SimResultWithOutputs
-
-Simulation result with step outputs
+```ts
+updateDashboardPeriodic(
+  maze: string[],
+  bestResult: IMazeRunResult | undefined,
+  bestNetwork: default | null,
+  completedGenerations: number,
+  neat: default,
+  dashboardManager: IDashboardManager | undefined,
+  flushToFrame: (() => Promise<void>) | undefined,
+): Promise<void>
+```
 
-## evolutionEngine/curriculumPhase.ts
+Periodic dashboard update used when the engine wants to refresh a non-primary
+dashboard view (for example background or periodic reporting). This helper is
+intentionally small, allocation-light and best-effort: dashboard errors are
+swallowed so the evolution loop cannot be interrupted by UI issues.
 
-### resolveMazeEvolutionPhaseOutcome
+Behavioural contract:
+ 1) If `dashboardManager.update` is present and callable the method invokes it with
+    the stable argument order: (maze, bestResult, bestNetwork, completedGenerations, neat).
+ 2) If `flushToFrame` is supplied the helper awaits it after the update to yield to
+    the host renderer (eg. requestAnimationFrame). Any exceptions raised by the
+    flush are swallowed.
+ 3) The helper avoids creating ephemeral arrays/objects and therefore does not use
+    typed-array scratch buffers here — there is no hot numerical work to pool. Other
+    engine helpers already reuse class-level scratch buffers where appropriate.
 
-```ts
-resolveMazeEvolutionPhaseOutcome(
-  evolutionResult: MazeEvolutionRunResult,
-  previousBestNetwork: INetwork | undefined,
-  minProgressToPass: number,
-): MazeEvolutionCurriculumPhaseOutcome
-```
+Design Rationale:
+ - Fast-guard early when update cannot be performed
+ - Best-effort error handling (swallow all exceptions)
+ - Preserves dashboard `this` binding with `.call()`
+ - Minimal allocations (no scratch buffers needed)
 
-Resolve the stable curriculum-facing outcome of one maze evolution phase.
+Steps / inline intent:
+ 1. Fast-guard when an update cannot be performed (missing manager, update method,
+    or missing content to visualise).
+ 2. Call the dashboard update in a try/catch to preserve best-effort semantics.
+ 3. Optionally await the provided `flushToFrame` function to yield to the host.
 
 Parameters:
-- `evolutionResult` - - Stable engine result returned by `EvolutionEngine.runMazeEvolution()`.
-- `previousBestNetwork` - - Previously carried winner used when the latest phase has no replacement.
-- `minProgressToPass` - - Progress threshold required before curriculum should advance.
 
-Returns: Shared curriculum outcome describing progress, solve state, and next carry-over seed.
+Parameters:
+- `maze` - - Maze descriptor passed to the dashboard renderer.
+- `bestResult` - - Best-run result object used for display (may be falsy when not present).
+- `bestNetwork` - - Network or genome object to visualise (may be falsy when not present).
+- `completedGenerations` - - Completed generation index (number).
+- `neat` - - NEAT manager instance (passed through to dashboard update).
+- `dashboardManager` - - Optional manager exposing `update(maze, result, network, gen, neat)`.
+- `flushToFrame` - - Optional async function used to yield to the host/frame scheduler
+ (for example: `() => new Promise(r => requestAnimationFrame(r))`).
 
 Example:
 
-```ts
-const phaseOutcome = resolveMazeEvolutionPhaseOutcome(result, previousBest, 95);
-if (phaseOutcome.solved) {
-  previousBest = phaseOutcome.nextBestNetwork;
-}
-```
+// Safe periodic update and yield to next frame
+await updateDashboardPeriodic(
+  maze, result, network, gen, neatInstance, dashboard, () => new Promise(r => requestAnimationFrame(r))
+);
+
+## evolutionEngine/curriculumPhase.ts
 
 ### hasMazeEvolutionReachedCurriculumThreshold
 
@@ -1821,6 +1793,34 @@ Parameters:
 
 Returns: Refined winner or the best available carry-over network.
 
+### resolveMazeEvolutionPhaseOutcome
+
+```ts
+resolveMazeEvolutionPhaseOutcome(
+  evolutionResult: MazeEvolutionRunResult,
+  previousBestNetwork: INetwork | undefined,
+  minProgressToPass: number,
+): MazeEvolutionCurriculumPhaseOutcome
+```
+
+Resolve the stable curriculum-facing outcome of one maze evolution phase.
+
+Parameters:
+- `evolutionResult` - - Stable engine result returned by `EvolutionEngine.runMazeEvolution()`.
+- `previousBestNetwork` - - Previously carried winner used when the latest phase has no replacement.
+- `minProgressToPass` - - Progress threshold required before curriculum should advance.
+
+Returns: Shared curriculum outcome describing progress, solve state, and next carry-over seed.
+
+Example:
+
+```ts
+const phaseOutcome = resolveMazeEvolutionPhaseOutcome(result, previousBest, 95);
+if (phaseOutcome.solved) {
+  previousBest = phaseOutcome.nextBestNetwork;
+}
+```
+
 ## evolutionEngine/optionsAndSetup.ts
 
 Options and Setup Module
@@ -1842,6 +1842,65 @@ ES2023 Policy:
 - Optional chaining `?.` for safe property access
 - Spread operator for object composition
 
+### createAndSeedNeat
+
+```ts
+createAndSeedNeat(
+  opts: NormalizedRunOptions,
+  inputSize: number,
+  outputSize: number,
+  fitnessContext: IFitnessEvaluationContext,
+  scratchPopClone: default[],
+  scratchSample: unknown[],
+): CreateAndSeedNeatResult
+```
+
+Create and seed a NEAT driver with normalized configuration and optional initial population.
+
+This function orchestrates the complete NEAT setup workflow:
+ 1) Build a fitness callback bound to the fitness context
+ 2) Instantiate the NEAT driver with normalized options
+ 3) Seed the driver's population from optional initial networks
+ 4) Warm up pooled scratch buffers to reduce first-use allocation spikes
+
+Design Rationale:
+ - Single orchestration point for NEAT creation + seeding
+ - Delegates heavy lifting to createNeat and seedInitialPopulation
+ - Best-effort buffer warm-up (failures swallowed)
+ - Returns updated scratch buffers for caller to persist
+
+Buffer Management:
+ - Accepts and returns scratchPopClone buffer (grown if needed)
+ - Accepts and returns scratchSample buffer (grown if needed)
+ - Caller should persist returned buffers for reuse across runs
+
+Parameters:
+
+Parameters:
+- `opts` - - Normalized run options (produced by normalizeRunOptions)
+- `inputSize` - - Network input count
+- `outputSize` - - Network output count
+- `fitnessContext` - - Compact fitness evaluation context
+- `scratchPopClone` - - Pooled clone buffer (will be grown if needed)
+- `scratchSample` - - Pooled sample buffer (will be grown if needed)
+
+Returns: Object containing:
+- neat: Configured and seeded NEAT driver instance
+- scratchPopClone: Updated clone buffer (may be new array if grown)
+- scratchSample: Updated sample buffer (may be new array if grown)
+
+Example:
+
+// Create and seed NEAT with optional initial population
+const { neat, scratchPopClone, scratchSample } = createAndSeedNeat(
+  normalizedOpts,
+  6,
+  4,
+  fitnessContext,
+  scratchPopCloneBuffer,
+  scratchSampleBuffer
+);
+
 ### normalizeRunOptions
 
 ```ts
@@ -1964,72 +2023,41 @@ Example:
 const env = prepareEnvironmentForRun(normalizedOpts, engineState.scratch);
 const neat = createAndSeedNeat(normalizedOpts, env.inputSize, env.outputSize, env.fitnessContext);
 
-### createAndSeedNeat
-
-```ts
-createAndSeedNeat(
-  opts: NormalizedRunOptions,
-  inputSize: number,
-  outputSize: number,
-  fitnessContext: IFitnessEvaluationContext,
-  scratchPopClone: default[],
-  scratchSample: unknown[],
-): CreateAndSeedNeatResult
-```
-
-Create and seed a NEAT driver with normalized configuration and optional initial population.
+## evolutionEngine/telemetryMetrics.ts
 
-This function orchestrates the complete NEAT setup workflow:
- 1) Build a fitness callback bound to the fitness context
- 2) Instantiate the NEAT driver with normalized options
- 3) Seed the driver's population from optional initial networks
- 4) Warm up pooled scratch buffers to reduce first-use allocation spikes
+Telemetry logging and metric computation helpers extracted from the ASCII maze evolution engine.
 
-Design Rationale:
- - Single orchestration point for NEAT creation + seeding
- - Delegates heavy lifting to createNeat and seedInitialPopulation
- - Best-effort buffer warm-up (failures swallowed)
- - Returns updated scratch buffers for caller to persist
+The helpers in this module operate on the shared {@link EngineState} scratch buffers to avoid
+per-call allocations while keeping the main façade lighter. All telemetry is best-effort: any
+internal error is swallowed so that logging never impacts the evolution loop.
 
-Buffer Management:
- - Accepts and returns scratchPopClone buffer (grown if needed)
- - Accepts and returns scratchSample buffer (grown if needed)
- - Caller should persist returned buffers for reuse across runs
+### ActionEntropyStats
 
-Parameters:
+Structure describing the result of action-entropy computation.
 
-Parameters:
-- `opts` - - Normalized run options (produced by normalizeRunOptions)
-- `inputSize` - - Network input count
-- `outputSize` - - Network output count
-- `fitnessContext` - - Compact fitness evaluation context
-- `scratchPopClone` - - Pooled clone buffer (will be grown if needed)
-- `scratchSample` - - Pooled sample buffer (will be grown if needed)
+### collectTelemetryTail
 
-Returns: Object containing:
-- neat: Configured and seeded NEAT driver instance
-- scratchPopClone: Updated clone buffer (may be new array if grown)
-- scratchSample: Updated sample buffer (may be new array if grown)
+```ts
+collectTelemetryTail(
+  state: EngineState,
+  neat: unknown,
+  tailLength: number,
+): unknown
+```
 
-Example:
+Collect a short telemetry tail from a NEAT instance when available.
 
-// Create and seed NEAT with optional initial population
-const { neat, scratchPopClone, scratchSample } = createAndSeedNeat(
-  normalizedOpts,
-  6,
-  4,
-  fitnessContext,
-  scratchPopCloneBuffer,
-  scratchSampleBuffer
-);
+Parameters:
+- `state` - Shared engine state (provides pooled scratch buffers for `getTail`).
+- `neat` - NEAT instance that may expose a `getTelemetry` function.
+- `tailLength` - Desired tail length (floored to an integer >= 0). Defaults to 10.
 
-## evolutionEngine/telemetryMetrics.ts
+Returns: Tail array, raw telemetry value or `undefined` on missing API/errors.
 
-Telemetry logging and metric computation helpers extracted from the ASCII maze evolution engine.
+### GenerationResult
 
-The helpers in this module operate on the shared {@link EngineState} scratch buffers to avoid
-per-call allocations while keeping the main façade lighter. All telemetry is best-effort: any
-internal error is swallowed so that logging never impacts the evolution loop.
+Minimal structure representing a generation evolution result.
+Expected to have a path property containing the movement history.
 
 ### LOG_TAG_ACTION_ENTROPY
 
@@ -2039,14 +2067,6 @@ Example:
 
 safeWrite(`${LOG_TAG_ACTION_ENTROPY} gen=1 entropyNorm=0.500 uniqueMoves=4 pathLen=32\n`);
 
-### LOG_TAG_OUTPUT_BIAS
-
-Telemetry tag emitted when logging bias statistics for output nodes.
-
-Example:
-
-safeWrite(`${LOG_TAG_OUTPUT_BIAS} gen=2 mean=0.001 std=0.010 biases=0.01,-0.02,0.03,-0.01\n`);
-
 ### LOG_TAG_LOGITS
 
 Telemetry tag emitted when logging logits statistics and collapse diagnostics.
@@ -2055,9 +2075,13 @@ Example:
 
 safeWrite(`${LOG_TAG_LOGITS} gen=3 means=0.001,0.002,-0.001,-0.002 stds=0.01,0.02,0.03,0.04 kurt=0,0,0,0 entMean=0.500 stability=0.750 steps=32\n`);
 
-### LogActionEntropyParams
+### LOG_TAG_OUTPUT_BIAS
 
-Parameters required to emit action-entropy telemetry.
+Telemetry tag emitted when logging bias statistics for output nodes.
+
+Example:
+
+safeWrite(`${LOG_TAG_OUTPUT_BIAS} gen=2 mean=0.001 std=0.010 biases=0.01,-0.02,0.03,-0.01\n`);
 
 ### logActionEntropy
 
@@ -2074,47 +2098,28 @@ Parameters:
 
 Returns: void
 
-### LogOutputBiasParams
-
-Parameters required to emit output-bias telemetry.
-
-### logOutputBiasStats
-
-```ts
-logOutputBiasStats(
-  __0: LogOutputBiasParams,
-): void
-```
-
-Emit bias statistics for the fittest network's output nodes.
-
-Parameters:
-- `params` - Shared state, subject network and writer callback.
-
-Returns: void
-
-### LogLogitsParams
+### LogActionEntropyParams
 
-Parameters required to emit logits statistics, perform collapse detection and trigger recovery.
+Parameters required to emit action-entropy telemetry.
 
-### logLogitsAndCollapse
+### logDiversity
 
 ```ts
-logLogitsAndCollapse(
-  __0: LogLogitsParams,
+logDiversity(
+  __0: LogDiversityParams,
 ): void
 ```
 
-Emit logits-level telemetry, detect collapse streaks and trigger anti-collapse recovery when needed.
+Emit diversity telemetry including species count, Simpson index and weight standard deviation.
 
 Parameters:
-- `params` - Shared state, subject genomes and telemetry configuration.
+- `params` - Shared state, NEAT population reference and logger callback.
 
 Returns: void
 
-### LogExplorationParams
+### LogDiversityParams
 
-Parameters required to emit exploration telemetry.
+Parameters required to emit population diversity telemetry.
 
 ### logExploration
 
@@ -2131,43 +2136,9 @@ Parameters:
 
 Returns: void
 
-### LogDiversityParams
-
-Parameters required to emit population diversity telemetry.
-
-### logDiversity
-
-```ts
-logDiversity(
-  __0: LogDiversityParams,
-): void
-```
-
-Emit diversity telemetry including species count, Simpson index and weight standard deviation.
-
-Parameters:
-- `params` - Shared state, NEAT population reference and logger callback.
-
-Returns: void
-
-### collectTelemetryTail
-
-```ts
-collectTelemetryTail(
-  state: EngineState,
-  neat: unknown,
-  tailLength: number,
-): unknown
-```
-
-Collect a short telemetry tail from a NEAT instance when available.
-
-Parameters:
-- `state` - Shared engine state (provides pooled scratch buffers for `getTail`).
-- `neat` - NEAT instance that may expose a `getTelemetry` function.
-- `tailLength` - Desired tail length (floored to an integer >= 0). Defaults to 10.
+### LogExplorationParams
 
-Returns: Tail array, raw telemetry value or `undefined` on missing API/errors.
+Parameters required to emit exploration telemetry.
 
 ### logGenerationTelemetry
 
@@ -2238,36 +2209,65 @@ logGenerationTelemetry(
   isProfilingDetailsEnabled, profilingStartTimestamp, accumulateProfilingDuration
 );
 
-### TelemetryWriter
+### LogitStatsParams
+
+Input parameters for computing logit statistics.
+
+### LogitStatsResult
+
+Structure describing aggregated logit statistics.
+
+### logLogitsAndCollapse
 
 ```ts
-TelemetryWriter(
-  message: string,
+logLogitsAndCollapse(
+  __0: LogLogitsParams,
 ): void
 ```
 
-Writer signature reused across telemetry helpers.
+Emit logits-level telemetry, detect collapse streaks and trigger anti-collapse recovery when needed.
 
-### GenerationResult
+Parameters:
+- `params` - Shared state, subject genomes and telemetry configuration.
 
-Minimal structure representing a generation evolution result.
-Expected to have a path property containing the movement history.
+Returns: void
 
-### TelemetryBaseParams
+### LogLogitsParams
 
-Parameters shared by telemetry helpers that require access to the shared state and writer.
+Parameters required to emit logits statistics, perform collapse detection and trigger recovery.
 
-### ActionEntropyStats
+### LogOutputBiasParams
 
-Structure describing the result of action-entropy computation.
+Parameters required to emit output-bias telemetry.
 
-### LogitStatsParams
+### logOutputBiasStats
 
-Input parameters for computing logit statistics.
+```ts
+logOutputBiasStats(
+  __0: LogOutputBiasParams,
+): void
+```
 
-### LogitStatsResult
+Emit bias statistics for the fittest network's output nodes.
 
-Structure describing aggregated logit statistics.
+Parameters:
+- `params` - Shared state, subject network and writer callback.
+
+Returns: void
+
+### TelemetryBaseParams
+
+Parameters shared by telemetry helpers that require access to the shared state and writer.
+
+### TelemetryWriter
+
+```ts
+TelemetryWriter(
+  message: string,
+): void
+```
+
+Writer signature reused across telemetry helpers.
 
 ## evolutionEngine/neatConfiguration.ts
 
@@ -2290,10 +2290,6 @@ ES2023 Policy:
 - Optional chaining `?.` for safe property access
 - Spread operator for array/object operations
 
-### NeatConfig
-
-NEAT configuration object shape for type safety.
-
 ### createNeat
 
 ```ts
@@ -2356,6 +2352,10 @@ const neat = createNeat(10, 4, fitnessFn, { popSize: 200, lineageTracking: false
 // Create with default configuration
 const neat = createNeat(10, 4, fitnessFn);
 
+### NeatConfig
+
+NEAT configuration object shape for type safety.
+
 ### seedInitialPopulation
 
 ```ts
@@ -2433,36 +2433,6 @@ ES2023 Policy:
 - Pooled scratch buffers to avoid allocations
 - Best-effort error handling (swallow non-fatal errors)
 
-### swallowError
-
-```ts
-swallowError(
-  error: unknown,
-): void
-```
-
-Utility to explicitly mark swallowed errors for lint compliance.
-
-This function is used to explicitly void error objects in catch blocks
-to satisfy linters that flag unused catch binding variables. It has no
-runtime effect beyond the void operation.
-
-Design Rationale:
- - Explicit intent signaling for best-effort error handling
- - Lint-compliant alternative to catch binding suppression
- - Zero runtime overhead (optimized away by JIT)
-
-Parameters:
-- `error` - - The error object to void (can be any type)
-
-Example:
-
-try {
-  riskyOperation();
-} catch (error) {
-  swallowError(error); // Explicit void for lint compliance
-}
-
 ### printNetworkStructure
 
 ```ts
@@ -2493,6 +2463,36 @@ Example:
 
 printNetworkStructure(state, bestNetwork);
 
+### swallowError
+
+```ts
+swallowError(
+  error: unknown,
+): void
+```
+
+Utility to explicitly mark swallowed errors for lint compliance.
+
+This function is used to explicitly void error objects in catch blocks
+to satisfy linters that flag unused catch binding variables. It has no
+runtime effect beyond the void operation.
+
+Design Rationale:
+ - Explicit intent signaling for best-effort error handling
+ - Lint-compliant alternative to catch binding suppression
+ - Zero runtime overhead (optimized away by JIT)
+
+Parameters:
+- `error` - - The error object to void (can be any type)
+
+Example:
+
+try {
+  riskyOperation();
+} catch (error) {
+  swallowError(error); // Explicit void for lint compliance
+}
+
 ## evolutionEngine/populationPruning.ts
 
 Population pruning and network warm-start helpers for the ASCII maze evolution engine.
@@ -2510,6 +2510,35 @@ Responsibilities:
 
 All functions are best-effort: internal errors are swallowed to avoid destabilizing the evolution loop.
 
+### applyCompassWarmStart
+
+```ts
+applyCompassWarmStart(
+  __0: ApplyCompassWarmStartParams,
+): void
+```
+
+Warm-start wiring for compass and directional openness inputs.
+
+Steps:
+1. Validate network structure and extract node/connection arrays.
+2. Collect input and output node indices using the shared helper.
+3. For each of the 4 compass directions, ensure an input→output connection exists with light initialization.
+4. Connect the special 'compass' input (index 0) to all outputs with deterministic base weights.
+
+Parameters:
+- `params` - Shared state and network reference.
+
+Returns: void
+
+Example:
+
+applyCompassWarmStart({ state: sharedState, network: trainedNetwork });
+
+### ApplyCompassWarmStartParams
+
+Parameters for warm-starting compass wiring.
+
 ### ApplySimplifyPruningParams
 
 Parameters for applying simplify pruning to a population.
@@ -2542,48 +2571,15 @@ applySimplifyPruningToPopulation({
   simplifyPruneFraction: 0.15,
 });
 
-### ApplyCompassWarmStartParams
-
-Parameters for warm-starting compass wiring.
-
-### applyCompassWarmStart
+### centerOutputBiases
 
 ```ts
-applyCompassWarmStart(
-  __0: ApplyCompassWarmStartParams,
+centerOutputBiases(
+  __0: CenterOutputBiasesParams,
 ): void
 ```
 
-Warm-start wiring for compass and directional openness inputs.
-
-Steps:
-1. Validate network structure and extract node/connection arrays.
-2. Collect input and output node indices using the shared helper.
-3. For each of the 4 compass directions, ensure an input→output connection exists with light initialization.
-4. Connect the special 'compass' input (index 0) to all outputs with deterministic base weights.
-
-Parameters:
-- `params` - Shared state and network reference.
-
-Returns: void
-
-Example:
-
-applyCompassWarmStart({ state: sharedState, network: trainedNetwork });
-
-### CenterOutputBiasesParams
-
-Parameters for re-centering output biases.
-
-### centerOutputBiases
-
-```ts
-centerOutputBiases(
-  __0: CenterOutputBiasesParams,
-): void
-```
-
-Re-center and clamp output node biases to prevent drift.
+Re-center and clamp output node biases to prevent drift.
 
 Steps:
 1. Collect output node indices using the shared helper.
@@ -2600,6 +2596,10 @@ Example:
 
 centerOutputBiases({ state: sharedState, network: trainedNetwork });
 
+### CenterOutputBiasesParams
+
+Parameters for re-centering output biases.
+
 ## evolutionEngine/trainingWarmStart.ts
 
 trainingWarmStart.ts
@@ -2622,43 +2622,6 @@ 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.
 
-### buildLamarckianTrainingSet
-
-```ts
-buildLamarckianTrainingSet(
-  state: EngineState,
-  constants: { TRAIN_OUT_PROB_HIGH: number; TRAIN_OUT_PROB_LOW: number; PROGRESS_MEDIUM: number; PROGRESS_STRONG: number; PROGRESS_JUNCTION: number; PROGRESS_FOURWAY: number; PROGRESS_REGRESS: number; PROGRESS_MIN_SIGNAL: number; PROGRESS_MILD_REGRESS: number; DEFAULT_JITTER_PROB: number; AUGMENT_JITTER_BASE: number; AUGMENT_JITTER_RANGE: number; AUGMENT_PROGRESS_JITTER_PROB: number; AUGMENT_PROGRESS_DELTA_RANGE: number; AUGMENT_PROGRESS_DELTA_HALF: number; RNG_PARAMETERS: RngCacheParameters; },
-): { input: number[]; output: number[]; }[]
-```
-
-Build the supervised training set used for Lamarckian warm-start training.
-
-Generates a small curated dataset of canonical navigation scenarios combining:
-- Single-path corridors with varying progress signals
-- Two-way junctions with directional bias
-- Four-way intersections with full openness variety
-- Regression cases (backtracking or stalled progress)
-- Mild data augmentation via random jitter on openness and progress values
-
-Each training case maps a 6-dimensional input to a soft one-hot output:
-- Input: [compassScalar, openN, openE, openS, openW, progressDelta]
-- Output: [pN, pE, pS, pW] with probabilities (high for target, low for others)
-
-Parameters:
-- `state` - - Shared engine state (used for RNG when applying jitter augmentation).
-- `constants` - - Training hyperparameters and signal constants.
-
-Returns: Array of training cases `{ input: number[], output: number[] }`.
-
-Example:
-
-const trainingSet = buildLamarckianTrainingSet(engineState, {
-  TRAIN_OUT_PROB_HIGH: 0.9,
-  TRAIN_OUT_PROB_LOW: 0.033,
-  PROGRESS_MEDIUM: 0.5,
-  // ... other constants
-});
-
 ### adjustOutputBiasesAfterTraining
 
 ```ts
@@ -2702,52 +2665,6 @@ adjustOutputBiasesAfterTraining(
   getNodeIndicesByType
 );
 
-### pretrainPopulationWarmStart
-
-```ts
-pretrainPopulationWarmStart(
-  neat: default,
-  lamarckianTrainingSet: LamarckianTrainingCase[],
-  constants: { PRETRAIN_MAX_ITER: number; PRETRAIN_BASE_ITER: number; DEFAULT_TRAIN_ERROR: number; DEFAULT_PRETRAIN_RATE: number; DEFAULT_PRETRAIN_MOMENTUM: number; DEFAULT_TRAIN_BATCH_SMALL: number; },
-  applyCompassWarmStart: WarmStartNetworkCallback,
-  centerOutputBiases: WarmStartNetworkCallback,
-): void
-```
-
-Pretrain the population using a small supervised dataset and apply warm-start heuristics.
-
-Behaviour & contract:
-- 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)
-2. For each network: guard missing `train` method, compute conservative iteration budget, then call `train`
-3. Apply warm-start heuristics (compass wiring + bias centering). Swallow any per-network exceptions.
-
-Parameters:
-- `neat` - - NEAT instance exposing a `population` array of networks.
-- `lamarckianTrainingSet` - - Array of `{input:number[], output:number[]}` training cases.
-- `constants` - - Training hyperparameters (iteration limits, learning rates, etc.).
-- `applyCompassWarmStart` - - Helper function for compass wiring adjustment.
-- `centerOutputBiases` - - Helper function for output bias centering.
-
-Example:
-
-pretrainPopulationWarmStart(
-  neatInstance,
-  trainingDataset,
-  { PRETRAIN_MAX_ITER: 10, PRETRAIN_BASE_ITER: 3, ... },
-  applyCompassWarmStart,
-  centerOutputBiases
-);
-
 ### applyLamarckianTraining
 
 ```ts
@@ -2812,63 +2729,47 @@ const elapsed = applyLamarckianTraining(
   adjustOutputBiasesAfterTraining
 );
 
-### warmStartPopulationIfNeeded
+### buildLamarckianTrainingSet
 
 ```ts
-warmStartPopulationIfNeeded(
-  neat: default,
-  trainingSet: LamarckianTrainingCase[],
+buildLamarckianTrainingSet(
   state: EngineState,
-  pretrainPopulation: PretrainPopulationCallback,
-): void
+  constants: { TRAIN_OUT_PROB_HIGH: number; TRAIN_OUT_PROB_LOW: number; PROGRESS_MEDIUM: number; PROGRESS_STRONG: number; PROGRESS_JUNCTION: number; PROGRESS_FOURWAY: number; PROGRESS_REGRESS: number; PROGRESS_MIN_SIGNAL: number; PROGRESS_MILD_REGRESS: number; DEFAULT_JITTER_PROB: number; AUGMENT_JITTER_BASE: number; AUGMENT_JITTER_RANGE: number; AUGMENT_PROGRESS_JITTER_PROB: number; AUGMENT_PROGRESS_DELTA_RANGE: number; AUGMENT_PROGRESS_DELTA_HALF: number; RNG_PARAMETERS: RngCacheParameters; },
+): { input: number[]; output: number[]; }[]
 ```
 
-Conditionally warm-start / pretrain the population using a provided training set.
+Build the supervised training set used for Lamarckian warm-start training.
 
-Behaviour & contract:
-- If a non-empty `trainingSet` is provided this method will attempt a best-effort
-  invocation of `pretrainPopulationWarmStart(neat, trainingSet)`
-- To reduce first-use allocation spikes the helper will also attempt to ensure
-  engine-level pooled buffers exist and have a reasonable capacity before
-  pretraining begins (plain Array for sampling and Float64Array for numeric work)
-- All operations are non-throwing; any internal error is swallowed to keep the
-  evolution loop resilient
+Generates a small curated dataset of canonical navigation scenarios combining:
+- Single-path corridors with varying progress signals
+- Two-way junctions with directional bias
+- Four-way intersections with full openness variety
+- Regression cases (backtracking or stalled progress)
+- Mild data augmentation via random jitter on openness and progress values
 
-Steps:
-1. Fast-guard invalid inputs – nothing to do when no data or driver
-2. Best-effort ensure pooled buffers exist and have capacity
-3. Invoke the pretrain helper (best-effort). This may mutate the NEAT driver
+Each training case maps a 6-dimensional input to a soft one-hot output:
+- Input: [compassScalar, openN, openE, openS, openW, progressDelta]
+- Output: [pN, pE, pS, pW] with probabilities (high for target, low for others)
 
 Parameters:
-- `neat` - - NEAT driver instance which will be pre-trained (may be `null`/`undefined`).
-- `trainingSet` - - Array of supervised training cases used for warm-start; ignored when empty.
-- `state` - - Shared engine state (provides scratch buffer pools).
-- `pretrainPopulation` - - Helper function for population pretraining.
+- `state` - - Shared engine state (used for RNG when applying jitter augmentation).
+- `constants` - - Training hyperparameters and signal constants.
+
+Returns: Array of training cases `{ input: number[], output: number[] }`.
 
 Example:
 
-warmStartPopulationIfNeeded(
-  neatDriver,
-  trainingCasesArray,
-  engineState,
-  pretrainPopulationWarmStart
-);
+const trainingSet = buildLamarckianTrainingSet(engineState, {
+  TRAIN_OUT_PROB_HIGH: 0.9,
+  TRAIN_OUT_PROB_LOW: 0.033,
+  PROGRESS_MEDIUM: 0.5,
+  // ... other constants
+});
 
 ### LamarckianTrainingCase
 
 Small supervised case used during Lamarckian warm-start.
 
-### TrainableNetwork
-
-The warm-start path trains ordinary runtime networks; this alias keeps intent explicit.
-
-### WarmStartNeatLike
-
-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.
-
 ### NodeIndexCollector
 
 ```ts
@@ -2880,256 +2781,286 @@ NodeIndexCollector(
 
 Callback used when a helper needs to write node indices of a specific role into scratch.
 
-### WarmStartNetworkCallback
+### PretrainPopulationCallback
 
 ```ts
-WarmStartNetworkCallback(
-  network: default,
+PretrainPopulationCallback(
+  neat: default,
+  trainingSet: LamarckianTrainingCase[],
 ): void
 ```
 
-Best-effort post-training hook applied to one network at a time.
+Population-wide warm-start hook used by the public orchestration helper.
 
-### PretrainPopulationCallback
+### pretrainPopulationWarmStart
 
 ```ts
-PretrainPopulationCallback(
+pretrainPopulationWarmStart(
   neat: default,
-  trainingSet: LamarckianTrainingCase[],
+  lamarckianTrainingSet: LamarckianTrainingCase[],
+  constants: { PRETRAIN_MAX_ITER: number; PRETRAIN_BASE_ITER: number; DEFAULT_TRAIN_ERROR: number; DEFAULT_PRETRAIN_RATE: number; DEFAULT_PRETRAIN_MOMENTUM: number; DEFAULT_TRAIN_BATCH_SMALL: number; },
+  applyCompassWarmStart: WarmStartNetworkCallback,
+  centerOutputBiases: WarmStartNetworkCallback,
 ): void
 ```
 
-Population-wide warm-start hook used by the public orchestration helper.
+Pretrain the population using a small supervised dataset and apply warm-start heuristics.
 
-## evolutionEngine/populationDynamics.ts
+Behaviour & contract:
+- 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
 
-populationDynamics.ts
+Steps:
+1. Validate inputs and obtain `population` (fast-exit on empty populations)
+2. For each network: guard missing `train` method, compute conservative iteration budget, then call `train`
+3. Apply warm-start heuristics (compass wiring + bias centering). Swallow any per-network exceptions.
 
-Population-level dynamics for the ASCII Maze evolution loop.
+Parameters:
+- `neat` - - NEAT instance exposing a `population` array of networks.
+- `lamarckianTrainingSet` - - Array of `{input:number[], output:number[]}` training cases.
+- `constants` - - Training hyperparameters (iteration limits, learning rates, etc.).
+- `applyCompassWarmStart` - - Helper function for compass wiring adjustment.
+- `centerOutputBiases` - - Helper function for output bias centering.
 
-This module owns the parts of the run that only make sense once the engine
-stops thinking about one genome at a time and starts thinking about the
-population as a living search process: plateau detection, simplify phases,
-parent selection, child creation, collapse recovery, and bulk connection
-cleanup.
+Example:
 
-Responsibilities:
-- Decide when search appears stuck and whether to enter a simplify phase
-- Expand the population by sampling from the current top performers
-- Sort genomes by fitness without allocating fresh arrays every generation
-- Track species diversity so collapse is visible instead of silent
-- Recover from pathological convergence by perturbing outputs and weights
-- Compact disabled connections once pruning has made them dead weight
+pretrainPopulationWarmStart(
+  neatInstance,
+  trainingDataset,
+  { PRETRAIN_MAX_ITER: 10, PRETRAIN_BASE_ITER: 3, ... },
+  applyCompassWarmStart,
+  centerOutputBiases
+);
 
-The helpers here are intentionally allocation-light because they sit on the
-hot path of long runs. They lean on `EngineState` scratch buffers and accept
-slightly loose runtime surfaces so the public loop can stay orchestration-
-first while these internals adapt to the real Neat and Network instances.
+### TrainableNetwork
 
-### updatePlateauState
+The warm-start path trains ordinary runtime networks; this alias keeps intent explicit.
 
-```ts
-updatePlateauState(
-  fitness: number,
-  lastBestFitnessForPlateau: number,
-  plateauCounter: number,
-  plateauImprovementThreshold: number,
-): { plateauCounter: number; lastBestFitnessForPlateau: number; }
-```
+### WarmStartNeatLike
 
-Update plateau state based on current fitness vs baseline.
+Narrow NEAT view used by the warm-start helpers.
 
-Behaviour:
-- Compares `fitness` against `lastBestFitnessForPlateau + threshold`.
-- If improved, resets plateau counter to 0 and updates baseline.
-- Otherwise, increments plateau counter (capped at a safe maximum).
+These helpers only need population access and a couple of option fields, so
+they avoid depending on the entire engine-facing driver surface.
 
-Parameters:
-- `fitness` - - Current best fitness (must be finite).
-- `lastBestFitnessForPlateau` - - Previous baseline fitness.
-- `plateauCounter` - - Current consecutive plateau generations.
-- `plateauImprovementThreshold` - - Minimum improvement to reset plateau.
+### WarmStartNetworkCallback
 
-Returns: Updated `{ plateauCounter, lastBestFitnessForPlateau }`.
+```ts
+WarmStartNetworkCallback(
+  network: default,
+): void
+```
+
+Best-effort post-training hook applied to one network at a time.
+
+### warmStartPopulationIfNeeded
+
+```ts
+warmStartPopulationIfNeeded(
+  neat: default,
+  trainingSet: LamarckianTrainingCase[],
+  state: EngineState,
+  pretrainPopulation: PretrainPopulationCallback,
+): void
+```
+
+Conditionally warm-start / pretrain the population using a provided training set.
+
+Behaviour & contract:
+- If a non-empty `trainingSet` is provided this method will attempt a best-effort
+  invocation of `pretrainPopulationWarmStart(neat, trainingSet)`
+- To reduce first-use allocation spikes the helper will also attempt to ensure
+  engine-level pooled buffers exist and have a reasonable capacity before
+  pretraining begins (plain Array for sampling and Float64Array for numeric work)
+- All operations are non-throwing; any internal error is swallowed to keep the
+  evolution loop resilient
+
+Steps:
+1. Fast-guard invalid inputs – nothing to do when no data or driver
+2. Best-effort ensure pooled buffers exist and have capacity
+3. Invoke the pretrain helper (best-effort). This may mutate the NEAT driver
+
+Parameters:
+- `neat` - - NEAT driver instance which will be pre-trained (may be `null`/`undefined`).
+- `trainingSet` - - Array of supervised training cases used for warm-start; ignored when empty.
+- `state` - - Shared engine state (provides scratch buffer pools).
+- `pretrainPopulation` - - Helper function for population pretraining.
 
 Example:
 
-const state = updatePlateauState(1.23, 1.1, 3, 0.05);
-// state => { plateauCounter: 0, lastBestFitnessForPlateau: 1.23 }
+warmStartPopulationIfNeeded(
+  neatDriver,
+  trainingCasesArray,
+  engineState,
+  pretrainPopulationWarmStart
+);
 
-### maybeStartSimplify
+## evolutionEngine/populationDynamics.ts
+
+populationDynamics.ts
+
+Population-level dynamics for the ASCII Maze evolution loop.
+
+This module owns the parts of the run that only make sense once the engine
+stops thinking about one genome at a time and starts thinking about the
+population as a living search process: plateau detection, simplify phases,
+parent selection, child creation, collapse recovery, and bulk connection
+cleanup.
+
+Responsibilities:
+- Decide when search appears stuck and whether to enter a simplify phase
+- Expand the population by sampling from the current top performers
+- Sort genomes by fitness without allocating fresh arrays every generation
+- Track species diversity so collapse is visible instead of silent
+- Recover from pathological convergence by perturbing outputs and weights
+- Compact disabled connections once pruning has made them dead weight
+
+The helpers here are intentionally allocation-light because they sit on the
+hot path of long runs. They lean on `EngineState` scratch buffers and accept
+slightly loose runtime surfaces so the public loop can stay orchestration-
+first while these internals adapt to the real Neat and Network instances.
+
+### antiCollapseRecovery
 
 ```ts
-maybeStartSimplify(
-  plateauCounter: number,
-  plateauGenerations: number,
-  simplifyDuration: number,
-): number
+antiCollapseRecovery(
+  state: EngineState,
+  neat: PopulationDynamicsNeatLike,
+  completedGenerations: number,
+  safeWrite: (msg: string) => void,
+  sampleSegmentIntoScratchFn: (state: EngineState, array: PopulationDynamicsGenome[], startIdx: number, count: number) => number,
+): void
 ```
 
-Decide whether to start a simplify phase based on plateau duration.
+Reinitialize output biases and weights for anti-collapse recovery.
 
 Behaviour:
-- Returns requested simplify duration if plateau threshold is reached.
-- Skips simplify in browser environments (presence of `window` global).
+- Selects a fraction (up to 30%) of non-elite genomes.
+- Samples from non-elite segment using pooled sample buffer.
+- Reinitializes each sampled genome's outputs via `reinitializeGenomeOutputsAndWeights`.
+- Emits diagnostic summary.
 
 Parameters:
-- `plateauCounter` - - Observed consecutive plateau generations.
-- `plateauGenerations` - - Threshold to trigger simplify.
-- `simplifyDuration` - - Requested simplify phase length.
-
-Returns: Number of generations to run simplify (0 means "do not start").
+- `state` - - Shared engine state.
+- `neat` - - NEAT driver with `population` and `options.elitism`.
+- `completedGenerations` - - Current generation for logging.
+- `safeWrite` - - Logging callback.
+- `sampleSegmentIntoScratchFn` - - Sampling helper function.
 
 Example:
 
-const duration = maybeStartSimplify(plateauCount, 10, 5);
-if (duration > 0) {
-  // Begin simplify for `duration` generations
-}
+antiCollapseRecovery(state, neat, genIndex, console.log, sampleSegmentIntoScratch);
 
-### runSimplifyCycle
+### applyMutationsToClone
 
 ```ts
-runSimplifyCycle(
+applyMutationsToClone(
   state: EngineState,
+  clone: PopulationDynamicsGenome,
   neat: PopulationDynamicsNeatLike,
-  simplifyRemaining: number,
-  simplifyStrategy: string,
-  simplifyPruneFraction: number,
-): number
+  mutateCount: number,
+): void
 ```
 
-Run a single simplify/pruning generation if conditions permit.
-
-Conceptually, simplify mode is the engine saying: "stop growing for a moment
-and remove weak structure so the current population has to justify what it
-keeps." That is useful after a long plateau, but only in non-browser hosts
-where the extra pruning work is acceptable.
+Apply up to `mutateCount` distinct mutation operations to `clone`.
 
-Steps:
-1. Normalize inputs and perform fast exits for zero remaining or invalid population.
-2. Environment gate: skip pruning in browser-like hosts.
-3. Record profiling start time when enabled.
-4. Execute pruning across the population (best-effort per-genome).
-5. Record profiling delta and return remaining generations decremented.
+Behaviour:
+1. Uses cached mutation operation array from `getMutationOps`.
+2. Selects up to `mutateCount` unique operations via partial Fisher–Yates shuffle.
+3. For small `mutateCount` values, uses unrolled fast path.
 
 Parameters:
-- `state` - - Shared engine state for RNG and profiling.
-- `neat` - - NEAT instance with `population` array.
-- `simplifyRemaining` - - Remaining simplify generations.
-- `simplifyStrategy` - - Strategy identifier for pruning.
-- `simplifyPruneFraction` - - Fraction in [0,1] controlling pruning aggressiveness.
-
-Returns: Remaining simplify generations after executing one cycle (0 means done).
+- `state` - - Shared engine state for RNG and scratch buffers.
+- `clone` - - Genome-like object with `mutate(op)` method.
+- `neat` - - NEAT driver for resolving mutation ops.
+- `mutateCount` - - Desired number of distinct mutation ops.
 
 Example:
 
-const remaining = runSimplifyCycle(state, neat, 5, 'pruneWeak', 0.2);
+applyMutationsToClone(state, someClone, neat, 2);
 
-### handleSimplifyState
+### compactGenomeConnections
 
 ```ts
-handleSimplifyState(
-  state: EngineState,
-  neat: PopulationDynamicsNeatLike,
-  plateauCounter: number,
-  plateauGenerations: number,
-  simplifyDuration: number,
-  simplifyMode: boolean,
-  simplifyRemaining: number,
-  simplifyStrategy: string,
-  simplifyPruneFraction: number,
-): { simplifyMode: boolean; simplifyRemaining: number; plateauCounter: number; }
+compactGenomeConnections(
+  genome: PopulationDynamicsGenome,
+): number
 ```
 
-Handle simplify entry and per-generation advance.
+Compact a single genome's connection list by removing disabled connections.
 
 Behaviour:
-- Decides when to enter a simplification phase and runs one simplify cycle
-  per generation.
-- Resets the plateau counter when simplify starts so the engine does not
-  immediately re-enter simplify after leaving it.
-- Delegates the "should we start?" question to `maybeStartSimplify` and the
-  actual pruning work to `runSimplifyCycle`.
+- Performs in-place stable compaction of `genome.connections`.
+- Preserves relative order of enabled connections.
+- Two-pointer write/read technique.
 
 Parameters:
-- `state` - - Shared engine state.
-- `neat` - - NEAT driver instance.
-- `plateauCounter` - - Current plateau counter.
-- `plateauGenerations` - - Window size for plateau decision.
-- `simplifyDuration` - - Requested simplify duration.
-- `simplifyMode` - - Current simplify active flag.
-- `simplifyRemaining` - - Remaining simplify generations.
-- `simplifyStrategy` - - Strategy identifier.
-- `simplifyPruneFraction` - - Pruning fraction.
+- `genome` - - Mutable genome with `connections` array.
 
-Returns: Updated `{ simplifyMode, simplifyRemaining, plateauCounter }`.
+Returns: Number of removed (disabled) connections.
 
 Example:
 
-const state = handleSimplifyState(engineState, neat, 3, 10, 5, false, 0, 'aggressive', 0.2);
+const removed = compactGenomeConnections(genome);
 
-### expandPopulation
+### compactPopulation
 
 ```ts
-expandPopulation(
+compactPopulation(
   state: EngineState,
   neat: PopulationDynamicsNeatLike,
-  targetAdd: number,
-  safeWrite: (msg: string) => void,
-  completedGenerations: number,
-): void
+): number
 ```
 
-Expand the population by creating children from top-performing parents.
-
-This is the engine's controlled answer to stagnation before full collapse
-recovery becomes necessary: widen the search, but bias that widening toward
-the current best-performing slice of the population instead of sampling from
-everyone equally.
+Compact entire population by removing disabled connections from each genome.
 
-Steps:
-1. Prepare working sets (population reference, sorted parent indices, parent pool size).
-2. Sample parents uniformly from the top parent pool.
-3. Create children via `createChildFromParent` (per-child failures ignored).
-4. Update `neat.options.popsize` and emit status line.
+Behaviour:
+- Uses pooled sample buffer as scratch counts array.
+- Compacts each genome via `compactGenomeConnections`.
+- Returns total removed connections.
 
 Parameters:
-- `state` - - Shared engine state for RNG.
-- `neat` - - NEAT driver with `population` and `options`.
-- `targetAdd` - - Desired number of new genomes.
-- `safeWrite` - - Logging callback.
-- `completedGenerations` - - Generation counter for telemetry.
+- `state` - - Shared engine state.
+- `neat` - - NEAT driver with `population`.
+
+Returns: Total removed disabled connections.
 
 Example:
 
-expandPopulation(state, neat, 10, msg => process.stdout.write(msg), currentGen);
+const totalRemoved = compactPopulation(state, neat);
 
-### prepareExpansion
+### createChildFromParent
 
 ```ts
-prepareExpansion(
+createChildFromParent(
   state: EngineState,
   neat: PopulationDynamicsNeatLike,
-): { populationRef: PopulationDynamicsGenome[]; sortedIdx: number[]; parentPoolSize: number; }
+  parent: PopulationDynamicsGenome,
+): PopulationDynamicsGenome | undefined
 ```
 
-Prepare working sets for population expansion.
+Create a child genome from a parent via cloning and mutation.
 
-The key idea is to sort once, derive a parent pool from the best quarter of
-the population, and then let child creation sample uniformly from that pool.
-That gives expansion a clear bias toward current evidence without hard-coding
-elitist cloning only.
+Behaviour:
+1. Clone the parent genome (with or without ID tracking).
+2. Determine mutation count (1 or 2).
+3. Apply mutations to the clone.
+4. Register the clone with the NEAT driver.
 
 Parameters:
 - `state` - - Shared engine state.
-- `neat` - - NEAT driver with `population`.
-
-Returns: Object with `populationRef`, `sortedIdx`, `parentPoolSize`.
+- `neat` - - NEAT driver instance.
+- `parent` - - Parent genome object.
 
 Example:
 
-const { populationRef, sortedIdx, parentPoolSize } = prepareExpansion(state, neat);
+createChildFromParent(state, neat, someParentGenome);
 
 ### determineMutateCount
 
@@ -3146,81 +3077,63 @@ Parameters:
 
 Returns: 1 or 2 based on random sample.
 
-### applyMutationsToClone
+### ensureOutputIdentity
 
 ```ts
-applyMutationsToClone(
-  state: EngineState,
-  clone: PopulationDynamicsGenome,
+ensureOutputIdentity(
   neat: PopulationDynamicsNeatLike,
-  mutateCount: number,
 ): void
 ```
 
-Apply up to `mutateCount` distinct mutation operations to `clone`.
+Ensure all output nodes use identity activation.
 
 Behaviour:
-1. Uses cached mutation operation array from `getMutationOps`.
-2. Selects up to `mutateCount` unique operations via partial Fisher–Yates shuffle.
-3. For small `mutateCount` values, uses unrolled fast path.
+- Iterates population genomes.
+- Sets `node.squash = methods.Activation.identity` for output nodes.
+- Best-effort: swallows errors.
 
 Parameters:
-- `state` - - Shared engine state for RNG and scratch buffers.
-- `clone` - - Genome-like object with `mutate(op)` method.
-- `neat` - - NEAT driver for resolving mutation ops.
-- `mutateCount` - - Desired number of distinct mutation ops.
+- `neat` - - NEAT driver with `population` array.
 
 Example:
 
-applyMutationsToClone(state, someClone, neat, 2);
+ensureOutputIdentity(neat);
 
-### registerClone
+### expandPopulation
 
 ```ts
-registerClone(
+expandPopulation(
+  state: EngineState,
   neat: PopulationDynamicsNeatLike,
-  clone: PopulationDynamicsGenome,
-  parentId: PopulationDynamicsParentId | undefined,
+  targetAdd: number,
+  safeWrite: (msg: string) => void,
+  completedGenerations: number,
 ): void
 ```
 
-Register a cloned genome with the NEAT driver's bookkeeping.
-
-Parameters:
-- `neat` - - NEAT driver instance.
-- `clone` - - Cloned genome object.
-- `parentId` - - Optional parent ID for lineage tracking.
-
-Example:
-
-registerClone(neat, genomeClone, parentId);
-
-### createChildFromParent
-
-```ts
-createChildFromParent(
-  state: EngineState,
-  neat: PopulationDynamicsNeatLike,
-  parent: PopulationDynamicsGenome,
-): PopulationDynamicsGenome | undefined
-```
+Expand the population by creating children from top-performing parents.
 
-Create a child genome from a parent via cloning and mutation.
+This is the engine's controlled answer to stagnation before full collapse
+recovery becomes necessary: widen the search, but bias that widening toward
+the current best-performing slice of the population instead of sampling from
+everyone equally.
 
-Behaviour:
-1. Clone the parent genome (with or without ID tracking).
-2. Determine mutation count (1 or 2).
-3. Apply mutations to the clone.
-4. Register the clone with the NEAT driver.
+Steps:
+1. Prepare working sets (population reference, sorted parent indices, parent pool size).
+2. Sample parents uniformly from the top parent pool.
+3. Create children via `createChildFromParent` (per-child failures ignored).
+4. Update `neat.options.popsize` and emit status line.
 
 Parameters:
-- `state` - - Shared engine state.
-- `neat` - - NEAT driver instance.
-- `parent` - - Parent genome object.
+- `state` - - Shared engine state for RNG.
+- `neat` - - NEAT driver with `population` and `options`.
+- `targetAdd` - - Desired number of new genomes.
+- `safeWrite` - - Logging callback.
+- `completedGenerations` - - Generation counter for telemetry.
 
 Example:
 
-createChildFromParent(state, neat, someParentGenome);
+expandPopulation(state, neat, 10, msg => process.stdout.write(msg), currentGen);
 
 ### getSortedIndicesByScore
 
@@ -3249,27 +3162,48 @@ Example:
 
 const indices = getSortedIndicesByScore(state, population);
 
-### ensureOutputIdentity
+### handleSimplifyState
 
 ```ts
-ensureOutputIdentity(
+handleSimplifyState(
+  state: EngineState,
   neat: PopulationDynamicsNeatLike,
-): void
+  plateauCounter: number,
+  plateauGenerations: number,
+  simplifyDuration: number,
+  simplifyMode: boolean,
+  simplifyRemaining: number,
+  simplifyStrategy: string,
+  simplifyPruneFraction: number,
+): { simplifyMode: boolean; simplifyRemaining: number; plateauCounter: number; }
 ```
 
-Ensure all output nodes use identity activation.
+Handle simplify entry and per-generation advance.
 
 Behaviour:
-- Iterates population genomes.
-- Sets `node.squash = methods.Activation.identity` for output nodes.
-- Best-effort: swallows errors.
+- Decides when to enter a simplification phase and runs one simplify cycle
+  per generation.
+- Resets the plateau counter when simplify starts so the engine does not
+  immediately re-enter simplify after leaving it.
+- Delegates the "should we start?" question to `maybeStartSimplify` and the
+  actual pruning work to `runSimplifyCycle`.
 
 Parameters:
-- `neat` - - NEAT driver with `population` array.
+- `state` - - Shared engine state.
+- `neat` - - NEAT driver instance.
+- `plateauCounter` - - Current plateau counter.
+- `plateauGenerations` - - Window size for plateau decision.
+- `simplifyDuration` - - Requested simplify duration.
+- `simplifyMode` - - Current simplify active flag.
+- `simplifyRemaining` - - Remaining simplify generations.
+- `simplifyStrategy` - - Strategy identifier.
+- `simplifyPruneFraction` - - Pruning fraction.
+
+Returns: Updated `{ simplifyMode, simplifyRemaining, plateauCounter }`.
 
 Example:
 
-ensureOutputIdentity(neat);
+const state = handleSimplifyState(engineState, neat, 3, 10, 5, false, 0, 'aggressive', 0.2);
 
 ### handleSpeciesHistory
 
@@ -3289,58 +3223,155 @@ Behaviour:
 - Inspects recent window for collapse (consecutive single-species).
 - When collapsed, escalates mutation/novelty parameters.
 
-Parameters:
-- `state` - - Shared engine state.
-- `neat` - - NEAT driver with `population`.
-- `speciesHistory` - - Global species history array (mutated).
+Parameters:
+- `state` - - Shared engine state.
+- `neat` - - NEAT driver with `population`.
+- `speciesHistory` - - Global species history array (mutated).
+
+Returns: `true` when collapse detected; `false` otherwise.
+
+Example:
+
+const collapsed = handleSpeciesHistory(state, neat, historyArray);
+
+### IndexBuffer
+
+Typed or array-based index buffer for sorting
+
+### maybeExpandPopulation
+
+```ts
+maybeExpandPopulation(
+  state: EngineState,
+  neat: PopulationDynamicsNeatLike,
+  dynamicPopEnabled: boolean,
+  completedGenerations: number,
+  dynamicPopMax: number,
+  plateauGenerations: number,
+  plateauCounter: number,
+  dynamicPopExpandInterval: number,
+  dynamicPopExpandFactor: number,
+  dynamicPopPlateauSlack: number,
+  safeWrite: (msg: string) => void,
+): void
+```
+
+Attempt population expansion when conditions permit.
+
+Behaviour:
+- Checks if dynamic expansion is enabled and interval/plateau conditions met.
+- Computes target addition count based on current size and factor.
+- Delegates to `expandPopulation` when there is room to grow.
+
+Parameters:
+- `state` - - Shared engine state.
+- `neat` - - NEAT driver.
+- `dynamicPopEnabled` - - Flag to enable dynamic expansion.
+- `completedGenerations` - - Current generation index.
+- `dynamicPopMax` - - Maximum allowed population size.
+- `plateauGenerations` - - Plateau window size.
+- `plateauCounter` - - Current plateau counter.
+- `dynamicPopExpandInterval` - - Generations between expansion attempts.
+- `dynamicPopExpandFactor` - - Fraction of current size to add.
+- `dynamicPopPlateauSlack` - - Minimum plateau ratio to trigger.
+- `safeWrite` - - Logging callback.
+
+Example:
+
+maybeExpandPopulation(state, neat, true, 100, 500, 10, 8, 5, 0.1, 0.75, console.log);
+
+### maybeStartSimplify
+
+```ts
+maybeStartSimplify(
+  plateauCounter: number,
+  plateauGenerations: number,
+  simplifyDuration: number,
+): number
+```
+
+Decide whether to start a simplify phase based on plateau duration.
+
+Behaviour:
+- Returns requested simplify duration if plateau threshold is reached.
+- Skips simplify in browser environments (presence of `window` global).
+
+Parameters:
+- `plateauCounter` - - Observed consecutive plateau generations.
+- `plateauGenerations` - - Threshold to trigger simplify.
+- `simplifyDuration` - - Requested simplify phase length.
+
+Returns: Number of generations to run simplify (0 means "do not start").
+
+Example:
+
+const duration = maybeStartSimplify(plateauCount, 10, 5);
+if (duration > 0) {
+  // Begin simplify for `duration` generations
+}
+
+### PopulationDynamicsConnection
+
+Connection surface used when population helpers inspect network edges.
+
+### PopulationDynamicsGenome
+
+Narrow genome view used by this module.
+
+The real runtime objects are `Network` instances with a few extra evolution-
+time fields such as `score`, `species`, and lineage markers. Capturing that
+shape locally keeps the rest of the helper signatures readable without
+claiming that the entire engine only ever works with plain `Network` values.
+
+### PopulationDynamicsNeatLike
+
+Narrow NEAT driver view used by this module.
+
+The population-dynamics helpers care about population access, a handful of
+options, and mutation operator discovery. Everything else remains owned by
+the concrete `Neat` implementation.
+
+### PopulationDynamicsNode
+
+Node surface used when population helpers inspect network topology.
+
+### PopulationDynamicsNoveltyConfig
 
-Returns: `true` when collapse detected; `false` otherwise.
+Minimal novelty configuration surface used during anti-collapse escalation.
 
-Example:
+### PopulationDynamicsOptions
 
-const collapsed = handleSpeciesHistory(state, neat, historyArray);
+Minimal NEAT options surface used by population-dynamics helpers.
 
-### maybeExpandPopulation
+### PopulationDynamicsParentId
+
+Runtime parent identifier carried through clone lineage tracking.
+
+### prepareExpansion
 
 ```ts
-maybeExpandPopulation(
+prepareExpansion(
   state: EngineState,
   neat: PopulationDynamicsNeatLike,
-  dynamicPopEnabled: boolean,
-  completedGenerations: number,
-  dynamicPopMax: number,
-  plateauGenerations: number,
-  plateauCounter: number,
-  dynamicPopExpandInterval: number,
-  dynamicPopExpandFactor: number,
-  dynamicPopPlateauSlack: number,
-  safeWrite: (msg: string) => void,
-): void
+): { populationRef: PopulationDynamicsGenome[]; sortedIdx: number[]; parentPoolSize: number; }
 ```
 
-Attempt population expansion when conditions permit.
+Prepare working sets for population expansion.
 
-Behaviour:
-- Checks if dynamic expansion is enabled and interval/plateau conditions met.
-- Computes target addition count based on current size and factor.
-- Delegates to `expandPopulation` when there is room to grow.
+The key idea is to sort once, derive a parent pool from the best quarter of
+the population, and then let child creation sample uniformly from that pool.
+That gives expansion a clear bias toward current evidence without hard-coding
+elitist cloning only.
 
 Parameters:
 - `state` - - Shared engine state.
-- `neat` - - NEAT driver.
-- `dynamicPopEnabled` - - Flag to enable dynamic expansion.
-- `completedGenerations` - - Current generation index.
-- `dynamicPopMax` - - Maximum allowed population size.
-- `plateauGenerations` - - Plateau window size.
-- `plateauCounter` - - Current plateau counter.
-- `dynamicPopExpandInterval` - - Generations between expansion attempts.
-- `dynamicPopExpandFactor` - - Fraction of current size to add.
-- `dynamicPopPlateauSlack` - - Minimum plateau ratio to trigger.
-- `safeWrite` - - Logging callback.
+- `neat` - - NEAT driver with `population`.
+
+Returns: Object with `populationRef`, `sortedIdx`, `parentPoolSize`.
 
 Example:
 
-maybeExpandPopulation(state, neat, true, 100, 500, 10, 8, 5, 0.1, 0.75, console.log);
+const { populationRef, sortedIdx, parentPoolSize } = prepareExpansion(state, neat);
 
 ### pruneSaturatedHiddenOutputs
 
@@ -3370,36 +3401,26 @@ Example:
 
 pruneSaturatedHiddenOutputs(state, genome, getNodeIndicesByTypeFn, collectHiddenToOutputConnsFn);
 
-### antiCollapseRecovery
+### registerClone
 
 ```ts
-antiCollapseRecovery(
-  state: EngineState,
+registerClone(
   neat: PopulationDynamicsNeatLike,
-  completedGenerations: number,
-  safeWrite: (msg: string) => void,
-  sampleSegmentIntoScratchFn: (state: EngineState, array: PopulationDynamicsGenome[], startIdx: number, count: number) => number,
+  clone: PopulationDynamicsGenome,
+  parentId: PopulationDynamicsParentId | undefined,
 ): void
 ```
 
-Reinitialize output biases and weights for anti-collapse recovery.
-
-Behaviour:
-- Selects a fraction (up to 30%) of non-elite genomes.
-- Samples from non-elite segment using pooled sample buffer.
-- Reinitializes each sampled genome's outputs via `reinitializeGenomeOutputsAndWeights`.
-- Emits diagnostic summary.
+Register a cloned genome with the NEAT driver's bookkeeping.
 
 Parameters:
-- `state` - - Shared engine state.
-- `neat` - - NEAT driver with `population` and `options.elitism`.
-- `completedGenerations` - - Current generation for logging.
-- `safeWrite` - - Logging callback.
-- `sampleSegmentIntoScratchFn` - - Sampling helper function.
+- `neat` - - NEAT driver instance.
+- `clone` - - Cloned genome object.
+- `parentId` - - Optional parent ID for lineage tracking.
 
 Example:
 
-antiCollapseRecovery(state, neat, genIndex, console.log, sampleSegmentIntoScratch);
+registerClone(neat, genomeClone, parentId);
 
 ### reinitializeGenomeOutputsAndWeights
 
@@ -3427,129 +3448,84 @@ Example:
 
 const deltas = reinitializeGenomeOutputsAndWeights(state, genome);
 
-### compactGenomeConnections
+### runSimplifyCycle
 
 ```ts
-compactGenomeConnections(
-  genome: PopulationDynamicsGenome,
+runSimplifyCycle(
+  state: EngineState,
+  neat: PopulationDynamicsNeatLike,
+  simplifyRemaining: number,
+  simplifyStrategy: string,
+  simplifyPruneFraction: number,
 ): number
 ```
 
-Compact a single genome's connection list by removing disabled connections.
+Run a single simplify/pruning generation if conditions permit.
 
-Behaviour:
-- Performs in-place stable compaction of `genome.connections`.
-- Preserves relative order of enabled connections.
-- Two-pointer write/read technique.
+Conceptually, simplify mode is the engine saying: "stop growing for a moment
+and remove weak structure so the current population has to justify what it
+keeps." That is useful after a long plateau, but only in non-browser hosts
+where the extra pruning work is acceptable.
+
+Steps:
+1. Normalize inputs and perform fast exits for zero remaining or invalid population.
+2. Environment gate: skip pruning in browser-like hosts.
+3. Record profiling start time when enabled.
+4. Execute pruning across the population (best-effort per-genome).
+5. Record profiling delta and return remaining generations decremented.
 
 Parameters:
-- `genome` - - Mutable genome with `connections` array.
+- `state` - - Shared engine state for RNG and profiling.
+- `neat` - - NEAT instance with `population` array.
+- `simplifyRemaining` - - Remaining simplify generations.
+- `simplifyStrategy` - - Strategy identifier for pruning.
+- `simplifyPruneFraction` - - Fraction in [0,1] controlling pruning aggressiveness.
 
-Returns: Number of removed (disabled) connections.
+Returns: Remaining simplify generations after executing one cycle (0 means done).
 
 Example:
 
-const removed = compactGenomeConnections(genome);
+const remaining = runSimplifyCycle(state, neat, 5, 'pruneWeak', 0.2);
 
-### compactPopulation
+### updatePlateauState
 
 ```ts
-compactPopulation(
-  state: EngineState,
-  neat: PopulationDynamicsNeatLike,
-): number
+updatePlateauState(
+  fitness: number,
+  lastBestFitnessForPlateau: number,
+  plateauCounter: number,
+  plateauImprovementThreshold: number,
+): { plateauCounter: number; lastBestFitnessForPlateau: number; }
 ```
 
-Compact entire population by removing disabled connections from each genome.
+Update plateau state based on current fitness vs baseline.
 
 Behaviour:
-- Uses pooled sample buffer as scratch counts array.
-- Compacts each genome via `compactGenomeConnections`.
-- Returns total removed connections.
+- Compares `fitness` against `lastBestFitnessForPlateau + threshold`.
+- If improved, resets plateau counter to 0 and updates baseline.
+- Otherwise, increments plateau counter (capped at a safe maximum).
 
 Parameters:
-- `state` - - Shared engine state.
-- `neat` - - NEAT driver with `population`.
+- `fitness` - - Current best fitness (must be finite).
+- `lastBestFitnessForPlateau` - - Previous baseline fitness.
+- `plateauCounter` - - Current consecutive plateau generations.
+- `plateauImprovementThreshold` - - Minimum improvement to reset plateau.
 
-Returns: Total removed disabled connections.
+Returns: Updated `{ plateauCounter, lastBestFitnessForPlateau }`.
 
 Example:
 
-const totalRemoved = compactPopulation(state, neat);
-
-### IndexBuffer
-
-Typed or array-based index buffer for sorting
-
-### PopulationDynamicsParentId
-
-Runtime parent identifier carried through clone lineage tracking.
-
-### PopulationDynamicsGenome
-
-Narrow genome view used by this module.
-
-The real runtime objects are `Network` instances with a few extra evolution-
-time fields such as `score`, `species`, and lineage markers. Capturing that
-shape locally keeps the rest of the helper signatures readable without
-claiming that the entire engine only ever works with plain `Network` values.
-
-### PopulationDynamicsNode
-
-Node surface used when population helpers inspect network topology.
-
-### PopulationDynamicsConnection
-
-Connection surface used when population helpers inspect network edges.
-
-### PopulationDynamicsNoveltyConfig
-
-Minimal novelty configuration surface used during anti-collapse escalation.
-
-### PopulationDynamicsOptions
-
-Minimal NEAT options surface used by population-dynamics helpers.
-
-### PopulationDynamicsNeatLike
-
-Narrow NEAT driver view used by this module.
-
-The population-dynamics helpers care about population access, a handful of
-options, and mutation operator discovery. Everything else remains owned by
-the concrete `Neat` implementation.
+const state = updatePlateauState(1.23, 1.1, 3, 0.05);
+// state => { plateauCounter: 0, lastBestFitnessForPlateau: 1.23 }
 
 ## evolutionEngine/engineState.constants.ts
 
 Constant values shared by the ASCII maze engine-state facade and its helper utilities.
 
-### DEFAULT_LOGITS_RING_CAPACITY
-
-Default logits ring length used when allocating pooled softmax buffers.
-
 ### ACTION_OUTPUT_DIMENSION
 
 Number of action outputs (N, E, S, W) represented in each logits row.
 
-### DEFAULT_VISITED_HASH_LOAD_FACTOR
-
-Default load factor target for the visited coordinate hash table.
-
-### MIN_VISITED_HASH_LOAD_FACTOR
-
-Minimum safe load factor applied when normalising visited-hash configuration.
-
-### MAX_VISITED_HASH_LOAD_FACTOR
-
-Maximum safe load factor applied when normalising visited-hash configuration.
-
-### DEFAULT_RNG_CACHE_BATCH_SIZE
-
-Default RNG cache batch size mirroring the façade constant.
-
-### DEFAULT_SPECIES_SCRATCH_CAPACITY
-
-Default capacity reserved for species identifier scratch arrays.
-
 ### DEFAULT_CONNECTION_FLAG_CAPACITY
 
 Default capacity reserved for connection flag buffers.
@@ -3558,58 +3534,59 @@ Default capacity reserved for connection flag buffers.
 
 Default capacity reused by history and sampling scratch arrays.
 
-### DEFAULT_SORTED_INDEX_CAPACITY
+### DEFAULT_LOGITS_RING_CAPACITY
 
-Default capacity reserved for sorted index scratch arrays.
+Default logits ring length used when allocating pooled softmax buffers.
+
+### DEFAULT_NODE_INDEX_BUFFER_CAPACITY
+
+Default capacity for the node index buffer used during inspection.
 
 ### DEFAULT_QUICKSORT_STACK_CAPACITY
 
 Default stack depth reserved for quicksort range storage.
 
-### DEFAULT_SAMPLE_POOL_SIZE
+### DEFAULT_RNG_CACHE_BATCH_SIZE
 
-Default pool size for telemetry sampling helpers.
+Default RNG cache batch size mirroring the façade constant.
 
-### DEFAULT_STRING_BUFFER_CAPACITY
+### DEFAULT_SAMPLE_POOL_SIZE
 
-Default capacity for telemetry string assembly buffers.
+Default pool size for telemetry sampling helpers.
 
 ### DEFAULT_SMALL_EXPLORE_TABLE_CAPACITY
 
 Default capacity for the small exploration table scratch.
 
-### DEFAULT_NODE_INDEX_BUFFER_CAPACITY
+### DEFAULT_SORTED_INDEX_CAPACITY
 
-Default capacity for the node index buffer used during inspection.
+Default capacity reserved for sorted index scratch arrays.
 
-### RNG_GOLDEN_RATIO_SEED
+### DEFAULT_SPECIES_SCRATCH_CAPACITY
 
-Knuth-derived 32-bit constant used when seeding the RNG state.
+Default capacity reserved for species identifier scratch arrays.
 
-## evolutionEngine/evolutionEngine.services.ts
+### DEFAULT_STRING_BUFFER_CAPACITY
 
-### getEvolutionEngineSharedState
+Default capacity for telemetry string assembly buffers.
 
-```ts
-getEvolutionEngineSharedState(): EngineState
-```
+### DEFAULT_VISITED_HASH_LOAD_FACTOR
 
-Return the shared engine singleton used by extracted engine modules.
+Default load factor target for the visited coordinate hash table.
 
-The public facade now depends on the same owner as the rest of the engine
-boundary instead of creating a private duplicate singleton.
+### MAX_VISITED_HASH_LOAD_FACTOR
 
-Returns: Shared engine state singleton.
+Maximum safe load factor applied when normalising visited-hash configuration.
+
+### MIN_VISITED_HASH_LOAD_FACTOR
 
-### getEvolutionEngineFacadeRuntimeState
+Minimum safe load factor applied when normalising visited-hash configuration.
 
-```ts
-getEvolutionEngineFacadeRuntimeState(): LogitsRingState
-```
+### RNG_GOLDEN_RATIO_SEED
 
-Read the mutable facade-owned logits-ring runtime state.
+Knuth-derived 32-bit constant used when seeding the RNG state.
 
-Returns: Current ring-capacity, shared-mode, and write-cursor state.
+## evolutionEngine/evolutionEngine.services.ts
 
 ### applyEvolutionEngineRingState
 
@@ -3624,13 +3601,32 @@ Apply the latest logits-ring runtime values returned by the evolution loop.
 Parameters:
 - `updatedRingState` - - New ring-capacity, shared-mode, and write-cursor values.
 
-### resetEvolutionEngineRingState
+### configureEvolutionEngineToggles
 
 ```ts
-resetEvolutionEngineRingState(): void
+configureEvolutionEngineToggles(
+  reducedTelemetry: boolean,
+  telemetryMinimal: boolean,
+  disableBaldwinPhase: boolean,
+): void
 ```
 
-Reset the facade-owned logits-ring runtime state to its baseline defaults.
+Apply telemetry and Baldwin-phase toggles derived from one normalized run request.
+
+Parameters:
+- `reducedTelemetry` - - When true, keep only the essential telemetry metrics.
+- `telemetryMinimal` - - When true, disable verbose telemetry capture.
+- `disableBaldwinPhase` - - When true, skip the Baldwin refinement stage.
+
+### getEvolutionEngineFacadeRuntimeState
+
+```ts
+getEvolutionEngineFacadeRuntimeState(): LogitsRingState
+```
+
+Read the mutable facade-owned logits-ring runtime state.
+
+Returns: Current ring-capacity, shared-mode, and write-cursor state.
 
 ### getEvolutionEngineMaxLogitsRingCapacity
 
@@ -3642,22 +3638,26 @@ Read the hard maximum ring capacity used by the public facade.
 
 Returns: Maximum ring capacity allowed for logits telemetry.
 
-### configureEvolutionEngineToggles
+### getEvolutionEngineSharedState
 
 ```ts
-configureEvolutionEngineToggles(
-  reducedTelemetry: boolean,
-  telemetryMinimal: boolean,
-  disableBaldwinPhase: boolean,
-): void
+getEvolutionEngineSharedState(): EngineState
 ```
 
-Apply telemetry and Baldwin-phase toggles derived from one normalized run request.
+Return the shared engine singleton used by extracted engine modules.
 
-Parameters:
-- `reducedTelemetry` - - When true, keep only the essential telemetry metrics.
-- `telemetryMinimal` - - When true, disable verbose telemetry capture.
-- `disableBaldwinPhase` - - When true, skip the Baldwin refinement stage.
+The public facade now depends on the same owner as the rest of the engine
+boundary instead of creating a private duplicate singleton.
+
+Returns: Shared engine state singleton.
+
+### resetEvolutionEngineRingState
+
+```ts
+resetEvolutionEngineRingState(): void
+```
+
+Reset the facade-owned logits-ring runtime state to its baseline defaults.
 
 ## evolutionEngine/evolutionEngine.constants.ts
 
@@ -3667,21 +3667,21 @@ The public EvolutionEngine class should read as orchestration-first code.
 These constants live in a dedicated module so warm-start tuning, loop
 thresholds, and shared fallback arrays do not crowd the facade itself.
 
-### EVOLUTION_ENGINE_EMPTY_VECTOR
+### EVOLUTION_ENGINE_ACTION_DIMENSION
 
-Shared empty vector reused when engine helpers need a stable array fallback.
+Number of action outputs emitted by the ASCII maze policy network.
 
 Example:
 
-const outgoing = node.connections?.out ?? EVOLUTION_ENGINE_EMPTY_VECTOR;
+console.log(EVOLUTION_ENGINE_ACTION_DIMENSION); // 4
 
-### EVOLUTION_ENGINE_ACTION_DIMENSION
+### EVOLUTION_ENGINE_EMPTY_VECTOR
 
-Number of action outputs emitted by the ASCII maze policy network.
+Shared empty vector reused when engine helpers need a stable array fallback.
 
 Example:
 
-console.log(EVOLUTION_ENGINE_ACTION_DIMENSION); // 4
+const outgoing = node.connections?.out ?? EVOLUTION_ENGINE_EMPTY_VECTOR;
 
 ### EVOLUTION_ENGINE_INITIAL_LOGITS_RING_CAPACITY
 
@@ -3690,17 +3690,16 @@ Initial ring-buffer capacity used for logits telemetry.
 The ring may grow at runtime, but the facade starts from this size so the
 first generations stay allocation-light.
 
-### EVOLUTION_ENGINE_MAX_LOGITS_RING_CAPACITY
+### EVOLUTION_ENGINE_LOOP_CONSTANTS
 
-Hard safety limit for the logits telemetry ring-buffer capacity.
+Main-loop tuning values passed into the extracted evolution-loop helpers.
 
-### EVOLUTION_ENGINE_WARM_START_CONSTANTS
+This table keeps the public facade declarative while preserving the same
+runtime thresholds and training behaviour.
 
-Warm-start curriculum samples used to bias early supervised guidance.
+### EVOLUTION_ENGINE_MAX_LOGITS_RING_CAPACITY
 
-These values shape the synthetic targets used before the main NEAT loop
-takes over, so they are grouped here instead of being scattered across the
-facade method body.
+Hard safety limit for the logits telemetry ring-buffer capacity.
 
 ### EVOLUTION_ENGINE_PRETRAIN_CONSTANTS
 
@@ -3710,36 +3709,42 @@ Example:
 
 const iterations = EVOLUTION_ENGINE_PRETRAIN_CONSTANTS.PRETRAIN_MAX_ITER;
 
-### EVOLUTION_ENGINE_LOOP_CONSTANTS
+### EVOLUTION_ENGINE_WARM_START_CONSTANTS
 
-Main-loop tuning values passed into the extracted evolution-loop helpers.
+Warm-start curriculum samples used to bias early supervised guidance.
 
-This table keeps the public facade declarative while preserving the same
-runtime thresholds and training behaviour.
+These values shape the synthetic targets used before the main NEAT loop
+takes over, so they are grouped here instead of being scattered across the
+facade method body.
 
 ## evolutionEngine/engineState.utils.ts
 
 Pure utility helpers shared by the ASCII maze engine-state facade.
 
-### createLogitsRing
+### buildTelemetryHandles
 
 ```ts
-createLogitsRing(): Float32Array<ArrayBufferLike>[]
+buildTelemetryHandles(
+  scratch: EngineScratchState,
+): TelemetryScratchHandles
 ```
 
-Build a logits ring sized to the requested default capacity.
+Build typed handles referencing the ensured telemetry scratch buffers.
 
-Returns: Array of Float32Array rows sized to the action dimension.
+Parameters:
+- `scratch` - Scratch state containing the prepared buffers.
 
-### resolveProfilingEnabled
+Returns: Structured handles consumed by telemetry helpers.
+
+### createLogitsRing
 
 ```ts
-resolveProfilingEnabled(): boolean
+createLogitsRing(): Float32Array<ArrayBufferLike>[]
 ```
 
-Compute whether detailed profiling is enabled via the environment flag.
+Build a logits ring sized to the requested default capacity.
 
-Returns: True when the profiling environment flag is set.
+Returns: Array of Float32Array rows sized to the action dimension.
 
 ### createProfilingAccumulators
 
@@ -3761,21 +3766,6 @@ Build the reusable snapshot metadata payload consumed by persistence helpers.
 
 Returns: Snapshot placeholder populated with neutral defaults.
 
-### normaliseTelemetryCapacityHints
-
-```ts
-normaliseTelemetryCapacityHints(
-  request: TelemetryScratchRequest,
-): TelemetryCapacityHints
-```
-
-Derive normalised capacity hints from the raw telemetry scratch request.
-
-Parameters:
-- `request` - Raw capacity request supplied by callers.
-
-Returns: Sanitised capacity values used during buffer initialisation.
-
 ### ensureTelemetryFloatPools
 
 ```ts
@@ -3810,21 +3800,6 @@ Parameters:
 
 Returns: Original buffer when large enough, otherwise a grown copy.
 
-### buildTelemetryHandles
-
-```ts
-buildTelemetryHandles(
-  scratch: EngineScratchState,
-): TelemetryScratchHandles
-```
-
-Build typed handles referencing the ensured telemetry scratch buffers.
-
-Parameters:
-- `scratch` - Scratch state containing the prepared buffers.
-
-Returns: Structured handles consumed by telemetry helpers.
-
 ### nextPowerOfTwo
 
 ```ts
@@ -3840,93 +3815,92 @@ Parameters:
 
 Returns: Smallest power-of-two greater than or equal to the candidate.
 
-### normaliseVisitedHashEntries
+### normaliseRngBatchSize
 
 ```ts
-normaliseVisitedHashEntries(
-  requestedEntries: number,
+normaliseRngBatchSize(
+  requestedBatchSize: number,
 ): number
 ```
 
-Clamp the requested target entry count to a non-negative integer.
+Clamp the RNG cache batch size to a positive integer.
 
 Parameters:
-- `requestedEntries` - Raw target entry count supplied by callers.
+- `requestedBatchSize` - Raw batch size requested by callers.
 
-Returns: Sanitised entry count used for capacity planning.
+Returns: Valid batch size.
 
-### normaliseVisitedHashLoad
+### normaliseRngSeed
 
 ```ts
-normaliseVisitedHashLoad(
-  requestedLoadFactor: number,
+normaliseRngSeed(
+  rawSeed: number,
 ): number
 ```
 
-Ensure the visited hash load factor falls within a sensible range.
+Normalise a raw numeric seed into an unsigned 32-bit value.
 
 Parameters:
-- `requestedLoadFactor` - Proposed load factor from configuration or state.
+- `rawSeed` - Raw seed provided by the caller.
 
-Returns: Clamped load factor with a fallback to the project default.
+Returns: Unsigned 32-bit seed suitable for the congruential generator.
 
-### normaliseRngBatchSize
+### normaliseTelemetryCapacityHints
 
 ```ts
-normaliseRngBatchSize(
-  requestedBatchSize: number,
-): number
+normaliseTelemetryCapacityHints(
+  request: TelemetryScratchRequest,
+): TelemetryCapacityHints
 ```
 
-Clamp the RNG cache batch size to a positive integer.
+Derive normalised capacity hints from the raw telemetry scratch request.
 
 Parameters:
-- `requestedBatchSize` - Raw batch size requested by callers.
+- `request` - Raw capacity request supplied by callers.
 
-Returns: Valid batch size.
+Returns: Sanitised capacity values used during buffer initialisation.
 
-### normaliseRngSeed
+### normaliseVisitedHashEntries
 
 ```ts
-normaliseRngSeed(
-  rawSeed: number,
+normaliseVisitedHashEntries(
+  requestedEntries: number,
 ): number
 ```
 
-Normalise a raw numeric seed into an unsigned 32-bit value.
+Clamp the requested target entry count to a non-negative integer.
 
 Parameters:
-- `rawSeed` - Raw seed provided by the caller.
-
-Returns: Unsigned 32-bit seed suitable for the congruential generator.
+- `requestedEntries` - Raw target entry count supplied by callers.
 
-## evolutionEngine/evolutionEngine.utils.ts
+Returns: Sanitised entry count used for capacity planning.
 
-### collectEvolutionEngineNodeIndicesByType
+### normaliseVisitedHashLoad
 
 ```ts
-collectEvolutionEngineNodeIndicesByType(
-  state: EngineState,
-  nodes: NetworkNode[] | undefined,
-  type: string,
+normaliseVisitedHashLoad(
+  requestedLoadFactor: number,
 ): number
 ```
 
-Collect node indices of one requested type into the shared engine scratch buffer.
-
-This helper keeps the facade free of buffer-growth details while preserving
-the existing allocation-light behaviour used by the evolution loop.
+Ensure the visited hash load factor falls within a sensible range.
 
 Parameters:
-- `state` - - Shared engine state that owns the reusable node-index buffer.
-- `nodes` - - Candidate nodes to scan.
-- `type` - - Node type to collect, such as `input`, `hidden`, or `output`.
+- `requestedLoadFactor` - Proposed load factor from configuration or state.
 
-Returns: Number of matching indices written into the shared scratch buffer.
+Returns: Clamped load factor with a fallback to the project default.
 
-Example:
+### resolveProfilingEnabled
 
-const outputCount = collectEvolutionEngineNodeIndicesByType(state, nodes, 'output');
+```ts
+resolveProfilingEnabled(): boolean
+```
+
+Compute whether detailed profiling is enabled via the environment flag.
+
+Returns: True when the profiling environment flag is set.
+
+## evolutionEngine/evolutionEngine.utils.ts
 
 ### collectEvolutionEngineHiddenToOutputConnections
 
@@ -3960,3 +3934,29 @@ const connections = collectEvolutionEngineHiddenToOutputConnections(
   nodes,
   outputCount,
 );
+
+### collectEvolutionEngineNodeIndicesByType
+
+```ts
+collectEvolutionEngineNodeIndicesByType(
+  state: EngineState,
+  nodes: NetworkNode[] | undefined,
+  type: string,
+): number
+```
+
+Collect node indices of one requested type into the shared engine scratch buffer.
+
+This helper keeps the facade free of buffer-growth details while preserving
+the existing allocation-light behaviour used by the evolution loop.
+
+Parameters:
+- `state` - - Shared engine state that owns the reusable node-index buffer.
+- `nodes` - - Candidate nodes to scan.
+- `type` - - Node type to collect, such as `input`, `hidden`, or `output`.
+
+Returns: Number of matching indices written into the shared scratch buffer.
+
+Example:
+
+const outputCount = collectEvolutionEngineNodeIndicesByType(state, nodes, 'output');