@reicek/neataptic-ts 0.1.26 → 0.1.27

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

@@ -1,62 +1,89 @@
 # evolutionEngine
 
-Shared contracts for the ASCII Maze evolution engine subsystem.
-
-The `evolutionEngine/` folder is where the public `EvolutionEngine` facade
-fans out into the lower-level machinery that keeps long maze runs practical:
-pooled scratch state, deterministic RNG caches, telemetry workspaces,
-sampling helpers, warm-start support, and population-level recovery logic.
-
-This file is the common footing for that subsystem. It defines the shared
-state and scratch-buffer contracts that let the rest of the engine stay
-allocation-light and orchestration-first instead of passing dozens of loose
-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.
-
-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
-
-Collection of scratch buffers handed back after initialisation for convenience.
-
-### TelemetryScratchRequest
+Population-level runtime contracts for the ASCII Maze evolution engine.
+
+This folder is where one maze, one fitness story, and one NEAT controller
+turn into a repeatable training program. The public `EvolutionEngine` facade
+uses these contracts to normalize options, coordinate host callbacks, keep
+deterministic state reproducible, and decide when a curriculum phase has
+produced a winner worth carrying forward.
+
+The important distinction is scale. `mazeMovement/` explains one agent run.
+`fitness.ts` explains how that run is scored. `dashboardManager/` explains
+how progress is shown to a human. `evolutionEngine/` explains how many runs
+across many generations become one population-level search loop with stop
+reasons, telemetry, warm starts, and phase outcomes that the next maze can
+reuse.
+
+This file is the right chapter opening because it names the public nouns of
+that loop before the reader hits pooled scratch buffers or hot-path helpers.
+It answers four questions quickly: what a caller can configure, what a host
+may observe or interrupt, what result the engine returns, and which shared
+runtime contexts keep the hot path allocation-light.
+
+A useful mental model is to treat the engine as a control tower rather than
+the aircraft itself. The engine does not move the agent through one maze cell
+at a time. It schedules phases, batches generations, preserves deterministic
+state, and hands structured outcomes back to browser or terminal hosts.
+
+Read the chapter in three passes. Start here for the public contracts and the
+meaning of a run result. Continue to `engineState.types.ts` when you want the
+shared scratch and toggle state that keeps the loop cheap. Finish with
+`evolutionLoop.ts`, `evolutionEngine.services.ts`, and `sampling.ts` when you
+want the actual orchestration and telemetry mechanics.
+
+```mermaid
+flowchart LR
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  Caller["Caller or host"]:::base --> Options["IRunMazeEvolutionOptions\nrun inputs"]:::base
+  Options --> Engine["EvolutionEngine facade\npopulation-level control"]:::accent
+  Engine --> Loop["generation loop\nevaluate mutate telemetry"]:::base
+  Loop --> Result["MazeEvolutionRunResult\nbest network + exit reason"]:::base
+  Result --> Phase["MazeEvolutionCurriculumPhaseOutcome\ncarry winner forward"]:::base
+  Engine --> Host["EvolutionHostAdapter\npause and stop hooks"]:::base
+```
+
+```mermaid
+flowchart TD
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  EngineFolder["evolutionEngine/"]:::accent --> Contracts["evolutionEngine.types.ts\npublic run contracts"]:::base
+  EngineFolder --> Scratch["engineState.types.ts\nshared scratch and toggles"]:::base
+  EngineFolder --> Loop["evolutionLoop.ts\nmain generation orchestration"]:::base
+  EngineFolder --> Services["evolutionEngine.services.ts\nand helpers"]:::base
+  EngineFolder --> Sampling["sampling.ts\nand telemetry support"]:::base
+```
+
+For background reading on the staged difficulty idea behind the browser and
+curriculum-style runs, see Wikipedia contributors,
+[Curriculum learning](https://en.wikipedia.org/wiki/Curriculum_learning),
+which captures the broader teaching idea of solving easier tasks before
+harder ones.
+
+Example: describe the host adapter and reporting hooks the engine may call.
 
-Configuration describing which telemetry scratch buffers require capacity guarantees.
+```ts
+const hostAdapter: EvolutionHostAdapter = {
+  isPauseRequested: () => window.asciiMazePaused === true,
+  handleStop: ({ reason, completedGenerations }) => {
+    console.log(reason, completedGenerations);
+  },
+};
+```
 
-### VisitedHashScratchHandles
+Example: sketch one engine run configuration before execution begins.
 
-Handles exposed after ensuring the visited-coordinate hash table capacity.
+```ts
+const runOptions: IRunMazeEvolutionOptions = {
+  mazeConfig: { maze },
+  agentSimConfig: { maxSteps: 160 },
+  evolutionAlgorithmConfig: { popSize: 120, deterministic: true },
+  reportingConfig: { dashboardManager, logEvery: 5 },
+};
+```
 
 ## evolutionEngine/evolutionEngine.types.ts
 
@@ -255,1507 +282,1638 @@ Network instance annotated with telemetry fields during a generation.
 
 Training constants used by Lamarckian warm-start and refinement helpers.
 
-## evolutionEngine/sampling.ts
+## evolutionEngine/engineState.types.ts
 
-Sampling and history helpers extracted from the ASCII maze evolution façade.
+Shared contracts for the ASCII Maze evolution engine subsystem.
 
-Responsibilities:
-1. Provide allocation-light array sampling utilities that reuse the shared `EngineState` scratch pools.
-2. Expose history helpers that mirror the façade behaviour while keeping pooled buffers centralised.
-3. Centralise RNG parameter resolution for sampling paths to keep behaviour deterministic under shared state.
+The `evolutionEngine/` folder is where the public `EvolutionEngine` facade
+fans out into the lower-level machinery that keeps long maze runs practical:
+pooled scratch state, deterministic RNG caches, telemetry workspaces,
+sampling helpers, warm-start support, and population-level recovery logic.
 
-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.
+This file is the common footing for that subsystem. It defines the shared
+state and scratch-buffer contracts that let the rest of the engine stay
+allocation-light and orchestration-first instead of passing dozens of loose
+arrays and counters through every hot-path helper.
 
-### getTail
+### EngineProfilingState
 
-```ts
-getTail(
-  state: EngineState,
-  source: T[] | undefined,
-  count: number,
-): T[]
-```
+Aggregated profiling configuration and accumulators shared across the evolution run.
 
-Extract the last `count` items from `source` into the shared tail buffer.
+### EngineScratchState
 
-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.
+Centralised shared state for the ASCII maze evolution façade.
 
-Parameters:
-- `state` - Shared engine state providing the tail history buffer.
-- `source` - Source array reference.
-- `count` - Number of trailing items requested.
+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.
 
-Returns: Pooled array containing the requested tail slice.
+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.
 
-Example:
+### EngineState
 
-const recent = getTail(sharedState, telemetryLog, 40);
+Shared engine state instance combining pooled scratch buffers with toggle flags.
 
-### pushHistory
+### EngineToggleState
 
-```ts
-pushHistory(
-  buffer: T[] | undefined,
-  value: T,
-  maxLength: number,
-): T[]
-```
+Runtime switches that adjust telemetry verbosity and optional training phases.
 
-Proxy to {@link MazeUtils.pushHistory} for consistency with the façade API.
+### RngCacheHandles
 
-Parameters:
-- `buffer` - Existing history buffer (may be undefined).
-- `value` - Value to append to the buffer.
-- `maxLength` - Maximum allowed buffer length.
+Handles returned after ensuring the RNG cache is ready for consumption.
 
-Returns: Updated history buffer with `value` appended and trimmed to `maxLength`.
+### RngCacheParameters
 
-Example:
+Parameters controlling the RNG cache refill process.
 
-const history = pushHistory(existingHistory, snapshot, 20);
+### TelemetryScratchHandles
 
-### sampleArray
+Collection of scratch buffers handed back after initialisation for convenience.
 
-```ts
-sampleArray(
-  state: EngineState,
-  source: T[],
-  sampleCount: number,
-): T[]
-```
+### TelemetryScratchRequest
 
-Sample `sampleCount` items (with replacement) from `source` into the pooled scratch buffer.
+Configuration describing which telemetry scratch buffers require capacity guarantees.
 
-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.
+### VisitedHashScratchHandles
 
-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`.
+Handles exposed after ensuring the visited-coordinate hash table capacity.
 
-Parameters:
-- `state` - Shared engine state providing pooled scratch buffers.
-- `source` - Source array to sample from.
-- `sampleCount` - Number of samples to draw (with replacement).
+## evolutionEngine/evolutionLoop.ts
 
-Returns: Pooled ephemeral array containing the sampled elements.
+Evolution Loop Module
 
-Example:
+Purpose:
+-------
+Provides utilities for running the main NEAT evolution loop, including
+generation orchestration, cancellation checking, and loop helper preparation.
 
-const picks = sampleArray(sharedState, population, 16);
-const safeCopy = [...picks];
+This module encapsulates:
+ - Cancellation detection (AbortSignal and legacy cancellation API)
+ - Loop helper preparation (frame flushing, persistence, logging)
+ - Generation execution and orchestration
+ - Stop condition evaluation
 
-### sampleIntoScratch
+ES2023 Policy:
+-------------
+- Uses nullish coalescing `??` and optional chaining `?.`
+- Descriptive variable names (no short identifiers)
+- Async/await for generation loops
+- Best-effort error handling (swallow non-fatal errors)
+
+### checkCancellation
 
 ```ts
-sampleIntoScratch(
-  state: EngineState,
-  source: T[],
-  sampleCount: number,
-): number
+checkCancellation(
+  options: EvolutionOptions,
+  bestResult: IMazeRunResult | undefined,
+): string | undefined
 ```
 
-Sample up to `sampleCount` items (with replacement) into the shared `samplePool` buffer.
+Inspect cooperative cancellation sources and annotate the provided result when cancelled.
 
-Compared with `sampleArray`, this form is for callers that only need a count
-plus access to the pooled buffer on `state.scratch.samplePool`. That avoids
-one more logical array object on the hottest paths.
+This function checks for cancellation from two sources in priority order:
+ 1) Legacy cancellation object with `isCancelled()` method
+ 2) Standard AbortSignal with `aborted` property
 
-Steps:
-1. Validate inputs and ensure the pooled buffer exists.
-2. Grow the buffer by powers of two when more capacity is required.
-3. Fill the buffer with random selections and return the number of items written.
+Design Rationale:
+ - Allocation-free (uses only short-lived local references)
+ - Best-effort error handling (swallow exceptions to avoid disrupting loop)
+ - Sets `exitReason` on result object for caller inspection
+ - Safe to call on hot paths (no scratch buffers or pooling needed)
 
-Parameters:
-- `state` - Shared engine state providing the pooled buffer.
-- `source` - Source array to sample from.
-- `sampleCount` - Number of elements requested (floored to an integer).
+Cancellation Priority:
+ 1. Check `options.cancellation.isCancelled()` (legacy API)
+ 2. Check `options.signal.aborted` (standard AbortSignal)
+ 3. Return undefined if no cancellation detected
 
-Returns: Number of sampled elements written into the pooled buffer.
+Parameters:
 
-Example:
+Parameters:
+- `options` - - Optional run configuration which may contain `cancellation` and/or `signal`
+- `bestResult` - - Optional mutable result object that will be annotated with `exitReason`
 
-const sampled = sampleIntoScratch(sharedState, population, 24);
-for (let index = 0; index < sampled; index++) {
-  processGenome(sharedState.scratch.samplePool[index]);
-}
+Returns: A reason string ('cancelled' | 'aborted') when cancellation is detected, otherwise `undefined`
 
-### sampleSegmentIntoScratch
+Examples:
 
-```ts
-sampleSegmentIntoScratch(
-  state: EngineState,
-  source: T[],
-  segmentStart: number,
-  sampleCount: number,
-): number
-```
+// Check cancellation before starting next generation
+const cancelReason = checkCancellation(opts, runResult);
+if (cancelReason) return cancelReason;
 
-Sample from a suffix of `source` starting at `segmentStart` into the pooled buffer.
+// Check cancellation without result annotation
+if (checkCancellation(opts)) {
+  console.log('User requested cancellation');
+  break;
+}
 
-The common use case is "sample from the non-elite tail" or some later slice
-of a population without first allocating `source.slice(segmentStart)`.
+### checkStopConditions
 
-Steps:
-1. Clamp indices and ensure there is a non-empty segment.
-2. Ensure the pooled buffer can store the requested sample count.
-3. Fill the buffer via the shared RNG, returning the number of items written.
+```ts
+checkStopConditions(
+  bestResult: IMazeRunResult | undefined,
+  bestNetwork: default | null,
+  maze: string[],
+  completedGenerations: number,
+  neat: default,
+  dashboardManager: IDashboardManager | undefined,
+  flushToFrame: () => Promise<void>,
+  hostAdapter: EvolutionHostAdapter | undefined,
+  minProgressToPass: number,
+  autoPauseOnSolve: boolean,
+  stopOnlyOnSolve: boolean,
+  stagnantGenerations: number,
+  maxStagnantGenerations: number,
+  maxGenerations: number,
+): Promise<string | undefined>
+```
 
-Parameters:
-- `state` - Shared engine state providing pooled sampling buffers.
-- `source` - Source array to sample from.
-- `segmentStart` - Inclusive start index of the segment.
-- `sampleCount` - Number of items to sample (with replacement).
+Inspect common termination conditions and perform minimal, best-effort side-effects.
 
-Returns: Number of elements written into the pooled buffer.
+This function checks three canonical stop reasons in priority order:
+ 1) **Solved**: Best result achieves minimum progress threshold
+ 2) **Stagnation**: No improvement for maxStagnantGenerations
+ 3) **MaxGenerations**: Absolute generation cap reached
 
-Example:
+Design Rationale:
+ - Allocation-light (uses only local references)
+ - Best-effort error handling (all side effects swallowed)
+ - Safe to call frequently on hot paths
+ - Updates dashboard and yields to host when stopping
+ - Emits optional 'asciiMazeSolved' event on solve (browser only)
 
-const written = sampleSegmentIntoScratch(sharedState, population, elitismCount, 12);
-const genome = sharedState.scratch.samplePool[0];
+Side Effects (Best-Effort):
+ - Updates dashboard manager when stopping
+ - Awaits flushToFrame to yield to host
+ - Reports stop events through the optional host adapter
+ - Annotates `bestResult.exitReason` with canonical reason string
 
-## evolutionEngine/engineState.ts
+Parameters:
 
-Centralised shared state for the ASCII maze evolution façade.
+Parameters:
+- `bestResult` - - Mutable run summary object (may be mutated with `exitReason`)
+- `bestNetwork` - - Network object associated with the best result (for dashboard)
+- `maze` - - Maze descriptor passed to dashboard updates/events
+- `completedGenerations` - - Current generation index (integer)
+- `neat` - - NEAT driver instance (passed to dashboard update)
+- `dashboardManager` - - Optional manager exposing `update(maze, result, network, gen, neat)`
+- `flushToFrame` - - Async function to yield to host renderer (e.g. requestAnimationFrame)
+- `hostAdapter` - - Optional host adapter that owns host-side stop behavior
+- `minProgressToPass` - - Numeric threshold to consider a run 'solved'
+- `autoPauseOnSolve` - - When truthy request host-side pause handling on solve
+- `stopOnlyOnSolve` - - When true ignore stagnation/maxGenerations as stop reasons
+- `stagnantGenerations` - - Current count of stagnant generations observed
+- `maxStagnantGenerations` - - Max allowed stagnant generations before stopping
+- `maxGenerations` - - Absolute generation cap after which the run stops
 
-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.
+Returns: A canonical reason string ('solved'|'stagnation'|'maxGenerations') when stopping, otherwise `undefined`
 
-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.
+Example:
 
-### createEngineState
+// Check stop conditions after each generation
+const reason = await checkStopConditions(
+  bestResult, bestNet, maze, gen, neat, dashboard, flush,
+  95, true, false, stagnant, 500, 10000
+);
+if (reason) {
+  console.log('Stopping due to', reason);
+  break;
+}
+
+### emitProfileSummary
 
 ```ts
-createEngineState(): EngineState
+emitProfileSummary(
+  engineState: EngineState,
+  safeWrite: (msg: string) => void,
+  completedGenerations: number,
+  totalEvolveMs: number,
+  totalLamarckMs: number,
+  totalSimMs: number,
+  isProfilingDetailsEnabledFn: (state: EngineState) => boolean,
+  getProfilingAccumulatorsFn: (state: EngineState) => ProfilingAccumulators,
+): void
 ```
 
-Fabricates a new {@link EngineState} with pre-sized scratch buffers and default toggle values.
+Emit a formatted profiling summary showing average per-generation timings.
 
-Returns: Initialized engine state used by the maze evolution façade.
+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.
 
-### createProfilingState
+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
 
-```ts
-createProfilingState(): EngineProfilingState
-```
+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
 
-Fabricates the profiling state bundle consumed by timing helpers.
+Parameters:
 
-Returns: Profiling configuration and accumulator state.
+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:
 
-const profiling = createProfilingState();
-console.log(profiling.detailsEnabled); // false unless env flag set
+// Print averages after a run that completed 100 generations
+emitProfileSummary(
+  state, console.log, 100, 12000, 3000, 4500,
+  isProfilingDetailsEnabled, getProfilingAccumulators
+);
 
-### createScratchState
+### EvolutionLoopResult
 
-```ts
-createScratchState(): EngineScratchState
-```
+Evolution loop result
 
-Fabricates the default pooled scratch buffers shared by the evolution façade.
+### GenerationOutcome
 
-Returns: Scratch bundle sized for the baseline maze curriculum workload.
+Generation outcome with profiling timings
 
-Example:
+### MutableMazeResult
 
-const scratch = createScratchState();
-console.log(scratch.exps.length); // 4
+Mutable result object with exitReason field
 
-### createToggleState
+### persistSnapshotIfNeeded
 
 ```ts
-createToggleState(): EngineToggleState
+persistSnapshotIfNeeded(
+  engineState: EngineState,
+  fs: { writeFileSync?: ((path: string, data: string) => void) | undefined; } | null,
+  pathModule: { join?: ((...paths: string[]) => string) | undefined; } | null,
+  persistDir: string | undefined,
+  persistTopK: number,
+  completedGenerations: number,
+  persistEvery: number,
+  neat: default,
+  bestFitness: number,
+  simplifyMode: boolean,
+  plateauCounter: number,
+  scratchSnapshotObj: Record<string, unknown>,
+  scratchSnapshotTop: SnapshotEntry[],
+  collectTelemetryTailFn: (state: EngineState, neat: default, count: number) => unknown,
+  getSortedIndicesByScoreFn: (state: EngineState, population: default[]) => number[],
+  isProfilingDetailsEnabledFn: (state: EngineState) => boolean,
+  profilingStartTimestampFn: (state: EngineState) => number,
+  accumulateProfilingDurationFn: (state: EngineState, label: string, duration: number) => void,
+): void
 ```
 
-Fabricates the default runtime toggle bundle for the evolution façade.
+Persist a population snapshot to disk at the configured interval.
 
-Returns: Toggle state with all optional phases enabled.
+This function writes a JSON snapshot of the current generation state when the
+generation cadence aligns with the configured persistence interval. It captures
+top-K genomes, telemetry tail, and metadata for later analysis or resume.
 
-Example:
+Design Rationale:
+ - Best-effort semantics: swallows all errors to avoid disrupting evolution loop
+ - Reuses pooled scratch objects (SCRATCH_SNAPSHOT_OBJ, SCRATCH_SNAPSHOT_TOP) to minimize allocations
+ - Optional profiling when enabled (measures snapshot serialization time)
+ - Defensive validation to ensure FS/path modules are available
 
-const toggles = createToggleState();
-console.log(toggles.reducedTelemetry); // false
+Scheduling Logic:
+ - Only persists when `completedGenerations % persistEvery === 0`
+ - Requires valid fs.writeFileSync and pathModule.join functions
+ - Requires non-empty population
 
-### DEFAULT_RNG_CACHE_BATCH_SIZE
+Snapshot Structure:
+ - generation: completed generation index
+ - bestFitness: best fitness score this generation
+ - simplifyMode: whether simplification was active
+ - plateauCounter: current plateau detection counter
+ - timestamp: Date.now() when snapshot was created
+ - telemetryTail: last N telemetry entries
+ - top: top-K genomes with minimal metadata (idx, score, nodes, connections, json)
 
-Default RNG cache batch size mirroring the façade constant.
+Parameters:
 
-### DEFAULT_VISITED_HASH_LOAD_FACTOR
+Parameters:
+- `engineState` - - Shared engine state with scratch buffers and profiling
+- `fs` - - Node.js fs module or compatible FS API
+- `pathModule` - - Node.js path module or compatible path API
+- `persistDir` - - Directory path where snapshots should be written
+- `persistTopK` - - Number of top genomes to include in snapshot
+- `completedGenerations` - - Current generation index
+- `persistEvery` - - Generation interval for persistence (e.g., 25 = every 25th generation)
+- `neat` - - NEAT instance with population
+- `bestFitness` - - Best fitness score this generation
+- `simplifyMode` - - Whether simplification mode is active
+- `plateauCounter` - - Current plateau counter value
+- `scratchSnapshotObj` - - Pooled snapshot object (reused across calls)
+- `scratchSnapshotTop` - - Pooled top-K buffer (reused across calls)
+- `collectTelemetryTailFn` - - Function to collect telemetry tail from state
+- `getSortedIndicesByScoreFn` - - Function to get sorted genome indices
+- `isProfilingDetailsEnabledFn` - - Function to check profiling state
+- `profilingStartTimestampFn` - - Function to get profiling start time
+- `accumulateProfilingDurationFn` - - Function to accumulate profiling duration
 
-Default load factor target for the visited coordinate hash table.
+Example:
 
-### EngineProfilingState
+// Persist snapshot every 25 generations
+persistSnapshotIfNeeded(
+  state, fs, path, './snapshots', 10, 50, 25, neat, 0.95, false, 3,
+  scratchObj, scratchTop, collectTail, getSorted, isProfilingEnabled, profileStart, profileAccum
+);
 
-Aggregated profiling configuration and accumulators shared across the evolution run.
+### prepareLoopHelpers
 
-### EngineScratchState
+```ts
+prepareLoopHelpers(
+  opts: EvolutionOptions,
+  scratchBundle: ScratchBundle,
+): LoopHelpers
+```
 
-Centralised shared state for the ASCII maze evolution façade.
+Build lightweight helpers used inside the evolution loop.
 
-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.
+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)
 
-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.
+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
 
-### EngineState
-
-Shared engine state instance combining pooled scratch buffers with toggle flags.
-
-### EngineToggleState
-
-Runtime switches that adjust telemetry verbosity and optional training phases.
+Scratch Buffer Warm-Up:
+ - samplePool: Array for population sampling
+ - profilingScratch: Float64Array(4) for timing accumulation
+ - exps: Float64Array(64) for exponential computations
 
-### ensureRngCacheBatch
+Parameters:
 
-```ts
-ensureRngCacheBatch(
-  parameters: RngCacheParameters,
-  state: EngineState,
-): RngCacheHandles
-```
+Parameters:
+- `opts` - - Normalized run options (contains persistDir and dashboardManager)
+- `scratchBundle` - - Engine scratch state for optional buffer warm-up
 
-Ensure the RNG cache contains fresh samples before consumption.
+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
 
-Parameters:
-- `parameters` - Congruential generator parameters and cache batch size.
-- `state` - Optional engine state container (defaults to the shared singleton).
+Example:
 
-Returns: Handles exposing the cache and its batch size.
+// 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
 
-### ensureVisitedHashCapacity
+### runEvolutionLoop
 
 ```ts
-ensureVisitedHashCapacity(
-  targetEntryCount: number,
-  state: EngineState,
-): VisitedHashScratchHandles
+runEvolutionLoop(
+  engineState: EngineState,
+  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>
 ```
 
-Ensure the visited-coordinate hash table can store the requested entry count.
+Internal evolution loop that executes generations until a stop condition or cancellation.
 
-Growth policy:
-1. Tables expand geometrically (powers of two) while respecting the configured load factor.
-2. When the existing table is large enough, it is cleared in place to preserve the allocation.
-3. Load factors outside the (0,1) range fall back to {@link DEFAULT_VISITED_HASH_LOAD_FACTOR}.
+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:
-- `targetEntryCount` - Expected number of unique coordinates to store.
-- `state` - Optional engine state container (defaults to the shared singleton).
+- `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: Cleared table reference plus the slot mask for probing loops.
+Returns: Promise resolving to an object:
+{ bestNetwork, bestResult, neat, completedGenerations, totalEvolveMs, totalLamarckMs, totalSimMs, updatedRingState }
 
 Example:
 
-const { table, slotMask } = ensureVisitedHashCapacity(256);
+const runSummary = await runEvolutionLoop(
+  state, neat, opts, trainingSet, maze, start, exit, distMap, helpers, true, ...
+);
 
-### initialiseTelemetryScratch
+### runGeneration
 
 ```ts
-initialiseTelemetryScratch(
-  request: TelemetryScratchRequest,
-  state: EngineState,
-): TelemetryScratchHandles
+runGeneration(
+  engineState: EngineState,
+  neat: default,
+  doProfile: boolean,
+  lamarckianIterations: number,
+  lamarckianTrainingSet: { input: number[]; output: number[]; }[],
+  lamarckianSampleSize: number | undefined,
+  safeWrite: (msg: string) => void,
+  completedGenerations: number,
+  dynamicPopEnabled: boolean,
+  dynamicPopMax: number,
+  plateauGenerations: number,
+  plateauCounter: number,
+  dynamicPopExpandInterval: number,
+  dynamicPopExpandFactor: number,
+  dynamicPopPlateauSlack: number,
+  speciesHistoryRef: number[],
+  emptyVec: default[],
+  scratchNodeIdx: Int32Array<ArrayBufferLike>,
+  getNodeIndicesByType: (nodes: NetworkNode[], type: string) => number,
+  constants: TrainingConstants,
+): Promise<GenerationOutcome>
 ```
 
-Ensure telemetry-related scratch buffers allocate enough capacity for upcoming work.
-
-Growth strategy:
-- Float64Array pools grow geometrically (powers of two) and preserve previously written prefixes.
-- String buffers are replaced with larger arrays (also geometric) to avoid repeated reallocations.
-- Optional higher-moment buffers (M3/M4/kurtosis) are only created when {@link TelemetryScratchRequest.includeHigherMoments}
-  is truthy to keep reduced telemetry lightweight.
-
-Parameters:
-- `request` - Capacity hints for upcoming telemetry computations.
-- `state` - Optional engine state target (defaults to the singleton  {@link engineState} ).
-
-Returns: Handles referencing the ensured scratch buffers for immediate use.
-
-### reseedRngState
-
-```ts
-reseedRngState(
-  seed: number,
-  state: EngineState,
-): number
-```
+Run one generation: evolve, ensure output identity, update species history, maybe expand population,
+and run Lamarckian training if configured.
 
-Persist a new RNG seed and schedule a cache refill on the next draw.
+Behaviour & contract:
+ - Performs a single NEAT generation step in a best-effort, non-throwing manner.
+ - Measures profiling durations when `doProfile` is truthy. Profiling is optional and
+   kept allocation-free (uses local numeric temporaries only).
+ - Invokes the following steps in order (each step is wrapped in a try/catch so
+   the evolution loop remains resilient to per-stage failures):
+     1) `neat.evolve()` to produce the fittest network for this generation.
+     2) `ensureOutputIdentity` to normalise output activations for consumers.
+     3) `handleSpeciesHistory` to update species statistics and history.
+     4) `maybeExpandPopulation` to grow the population when configured and warranted.
+     5) Optional Lamarckian warm-start training via `applyLamarckianTraining`.
+ - The method is allocation-light and reuses engine helpers / pooled buffers where
+   appropriate. It never throws; internal errors are swallowed and optionally logged
+   via the provided `safeWrite` function.
 
 Parameters:
-- `seed` - Raw numeric seed requested by deterministic mode.
-- `state` - Optional engine state container (defaults to the shared singleton).
+- `engineState` - - Shared engine state with scratch buffers and RNG
+- `neat` - - NEAT driver instance used for evolving the generation
+- `doProfile` - - When truthy measure timing for the evolve step (ms) using engine clock
+- `lamarckianIterations` - - Number of supervised training iterations to run per genome (0 to skip)
+- `lamarckianTrainingSet` - - Array of supervised training cases used for warm-start (may be empty)
+- `lamarckianSampleSize` - - Optional per-network sample size used by the warm-start routine
+- `safeWrite` - - Safe logging function; used only for best-effort diagnostic messages
+- `completedGenerations` - - Current generation index (used by expansion heuristics)
+- `dynamicPopEnabled` - - Whether dynamic population expansion is enabled
+- `dynamicPopMax` - - Upper bound on population size for expansion
+- `plateauGenerations` - - Window size used by plateau detection
+- `plateauCounter` - - Current plateau counter used by expansion heuristics
+- `dynamicPopExpandInterval` - - Generation interval to attempt expansion
+- `dynamicPopExpandFactor` - - Fractional growth factor used to compute new members
+- `dynamicPopPlateauSlack` - - Minimum plateau ratio required to trigger expansion
+- `speciesHistoryRef` - - Mutable array holding species history (maintained externally)
+- `emptyVec` - - Empty array fallback to avoid ephemeral allocations
+- `scratchNodeIdx` - - Pooled node index buffer (passed through to helpers)
+- `getNodeIndicesByType` - - Helper function to collect node indices by type
+- `constants` - - Object containing DEFAULT_TRAIN_ERROR, DEFAULT_TRAIN_RATE, DEFAULT_TRAIN_MOMENTUM, DEFAULT_TRAIN_BATCH_SMALL, DEFAULT_STD_SMALL, DEFAULT_STD_ADJUST_MULT
 
-Returns: Unsigned seed stored in scratch state for diagnostics.
+Returns: An object shaped { fittest, tEvolve, tLamarck } where:
+- `fittest` is the network returned by `neat.evolve()` (may be null on error),
+- `tEvolve` is the measured evolve duration in milliseconds when `doProfile` is true (0 otherwise),
+- `tLamarck` is the total time spent in Lamarckian training (0 when skipped)
 
-### RngCacheHandles
+Example:
 
-Handles returned after ensuring the RNG cache is ready for consumption.
+// Run a single generation with profiling and optional Lamarckian warm-start
+const { fittest, tEvolve, tLamarck } = await runGeneration(
+  engineState,
+  neatInstance,
+  true,   // doProfile
+  5,      // lamarckianIterations
+  trainingSet,
+  16,     // lamarckianSampleSize
+  console.log,
+  genIndex,
+  true,
+  500,
+  10,
+  plateauCounter,
+  5,
+  0.1,
+  0.75,
+  speciesHistory,
+  [],
+  nodeIndexBuffer,
+  getNodeIndicesByTypeFn,
+  { DEFAULT_TRAIN_ERROR: 0.01, ... }
+);
 
-### RngCacheParameters
+### SimResultWithOutputs
 
-Parameters controlling the RNG cache refill process.
+Simulation result with step outputs
 
-### setBaldwinPhaseDisabledFlag
+### simulateAndPostprocess
 
 ```ts
-setBaldwinPhaseDisabledFlag(
-  isDisabled: boolean,
-): void
+simulateAndPostprocess(
+  engineState: EngineState,
+  fittest: default,
+  encodedMaze: number[][],
+  startPosition: readonly [number, number],
+  exitPosition: readonly [number, number],
+  distanceMap: number[][],
+  maxSteps: number | undefined,
+  doProfile: boolean,
+  safeWrite: (msg: string) => void,
+  logEvery: number,
+  completedGenerations: number,
+  neat: default,
+  runtimeContext: EvolutionLoopRuntimeContext,
+  ringState: LogitsRingState,
+  telemetryContext: EvolutionLoopTelemetryContext,
+  loopSupportContext: Pick<EvolutionLoopSupportContext, "loopHelpers">,
+): SimulationResult
 ```
 
-Enable or disable the Baldwin-phase warm-start pipeline.
+Simulate the supplied `fittest` genome/network and perform allocation-light postprocessing.
 
-Parameters:
-- `isDisabled` - When true, skips the Lamarckian training stage.
+Behaviour & contract:
+ - Runs the simulation via `MazeMovement.simulateAgent` and attaches compact telemetry
+   (saturation fraction, action entropy) directly onto the `fittest` object (in-place).
+ - When per-step logits are returned the helper attempts to copy them into the engine's pooled
+   ring buffers to avoid per-run allocations. Two copy modes are supported:
+     1) Shared SAB-backed flat Float32Array with an atomic Int32 write index (cross-worker safe).
+     2) Local in-process per-row Float32Array ring (`scratchLogitsRing`).
+ - Best-effort: all mutation and buffer-copy steps are guarded; failures are swallowed so the
+   evolution loop is not interrupted. Use `safeWrite` for optional diagnostic messages.
 
-### setReducedTelemetryFlag
-
-```ts
-setReducedTelemetryFlag(
-  isEnabled: boolean,
-): void
-```
-
-Toggle the reduced telemetry mode.
-
-Parameters:
-- `isEnabled` - When true, trims telemetry to the essential metrics only.
-
-### setTelemetryMinimalFlag
-
-```ts
-setTelemetryMinimalFlag(
-  isMinimal: boolean,
-): void
-```
+Steps (high level):
+ 1) Run the simulator and capture wall-time when `doProfile` is truthy.
+ 2) Attach compact telemetry fields to `fittest` and ensure legacy `_lastStepOutputs` exists.
+ 3) If per-step logits are available, ensure ring capacity and copy them into the selected ring.
+ 4) Optionally prune saturated hidden->output connections and emit telemetry via logGenerationTelemetry.
+ 5) Return the raw simulation result and elapsed simulation time (ms when profiling enabled).
 
-Toggle the minimal telemetry mode for JSON output.
+Notes on pooling / reentrancy:
+ - The local ring is not re-entrant; callers must avoid concurrent writes.
+ - When shared mode is true we prefer the SAB-backed path which uses Atomics and is safe
+   for cross-thread producers.
 
 Parameters:
-- `isMinimal` - When true, disables verbose telemetry capture.
+- `engineState` - - Shared engine state with scratch buffers and ring configuration
+- `fittest` - - Genome/network considered the generation's best; may be mutated with metadata
+- `encodedMaze` - - Maze descriptor used by the simulator
+- `startPosition` - - Start co-ordinates passed as-is to the simulator
+- `exitPosition` - - Exit co-ordinates passed as-is to the simulator
+- `distanceMap` - - Optional precomputed distance map consumed by the simulator
+- `maxSteps` - - Optional maximum simulation steps; may be undefined to allow default
+- `doProfile` - - When truthy measure and return the simulation time in milliseconds
+- `safeWrite` - - Optional logger used for non-fatal diagnostic messages
+- `logEvery` - - Emit telemetry every `logEvery` generations (0 disables periodic telemetry)
+- `completedGenerations` - - Current generation index used for conditional telemetry
+- `neat` - - NEAT driver instance passed to telemetry hooks
+- `runtimeContext` - - Shared pooled ring buffers and limits for logits telemetry.
+- `ringState` - - Current mutable ring state (capacity, shared-mode flag, write cursor).
+- `telemetryContext` - - Telemetry thresholds and verbosity switches used after simulation.
+- `loopSupportContext` - - Shared scratch buffers and helper callbacks used by the loop.
 
-### TelemetryScratchHandles
+Returns: An object { generationResult, simTime, updatedRingState } where simTime is ms when profiling is enabled
 
-Collection of scratch buffers handed back after initialisation for convenience.
+Example:
 
-### TelemetryScratchRequest
+const { generationResult, simTime, updatedRingState } = simulateAndPostprocess(
+  state, bestGenome, maze, start, exit, distMap, 1000, true, console.log, 10, genIdx, neat, ...
+);
 
-Configuration describing which telemetry scratch buffers require capacity guarantees.
+### SimulationOutcome
 
-### VisitedHashScratchHandles
+Simulation result with profiling and ring state
 
-Handles exposed after ensuring the visited-coordinate hash table capacity.
+### updateDashboardAndMaybeFlush
 
-## evolutionEngine/rngAndTiming.ts
+```ts
+updateDashboardAndMaybeFlush(
+  maze: string[],
+  result: IMazeRunResult | undefined,
+  network: default | null,
+  completedGenerations: number,
+  neat: default,
+  dashboardManager: IDashboardManager | undefined,
+  flushToFrame: (() => Promise<void>) | undefined,
+): Promise<void>
+```
 
-RNG and timing helpers extracted from the evolution façade.
+Safely update a UI dashboard with the latest run state and optionally yield to the
+host/frame via an awaited flush function.
 
-### accumulateProfilingDuration
+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.
 
-```ts
-accumulateProfilingDuration(
-  state: EngineState,
-  category: string,
-  deltaMs: number,
-): void
-```
+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
 
-Accumulate a profiling duration under the supplied key when detail profiling is enabled.
+Parameters:
 
 Parameters:
-- `state` - Shared engine state containing profiling configuration.
-- `category` - Profiling segment key (for example `telemetry`).
-- `deltaMs` - Millisecond duration to add to the accumulator.
+- `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.
 
-Returns: void.
+Example:
 
-### clearDeterministicMode
+// 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
-clearDeterministicMode(
-  state: EngineState,
-): void
+updateDashboardPeriodic(
+  maze: string[],
+  bestResult: IMazeRunResult | undefined,
+  bestNetwork: default | null,
+  completedGenerations: number,
+  neat: default,
+  dashboardManager: IDashboardManager | undefined,
+  flushToFrame: (() => Promise<void>) | undefined,
+): Promise<void>
 ```
 
-Disable deterministic RNG mode.
-
-Parameters:
-- `state` - Shared engine state where the deterministic flag is stored.
-
-Returns: 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.
 
-### drawFastRandom
+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
-drawFastRandom(
-  state: EngineState,
-  parameters: RngCacheParameters,
-): number
-```
+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)
 
-Generate a fast uniform random sample using the shared RNG cache.
+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:
-- `state` - Shared engine state providing the RNG cache and seed.
-- `parameters` - Congruential parameters forwarded to  {@link ensureRngCacheBatch} .
 
-Returns: Uniform sample in the range [0, 1).
+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:
 
-const sample = drawFastRandom(sharedState, rngParameters);
+// Safe periodic update and yield to next frame
+await updateDashboardPeriodic(
+  maze, result, network, gen, neatInstance, dashboard, () => new Promise(r => requestAnimationFrame(r))
+);
 
-### getProfilingAccumulators
+## evolutionEngine/evolutionEngine.services.ts
+
+### applyEvolutionEngineRingState
 
 ```ts
-getProfilingAccumulators(
-  state: EngineState,
-): Record<string, number>
+applyEvolutionEngineRingState(
+  updatedRingState: LogitsRingState,
+): void
 ```
 
-Provide direct access to the profiling accumulator map.
+Apply the latest logits-ring runtime values returned by the evolution loop.
 
 Parameters:
-- `state` - Shared engine state containing the profiling accumulators.
-
-Returns: Mutable record of profiling accumulators keyed by category name.
+- `updatedRingState` - - New ring-capacity, shared-mode, and write-cursor values.
 
-### isDeterministicModeEnabled
+### configureEvolutionEngineToggles
 
 ```ts
-isDeterministicModeEnabled(
-  state: EngineState,
-): boolean
+configureEvolutionEngineToggles(
+  reducedTelemetry: boolean,
+  telemetryMinimal: boolean,
+  disableBaldwinPhase: boolean,
+): void
 ```
 
-Retrieve the deterministic RNG flag stored on the shared engine state.
+Apply telemetry and Baldwin-phase toggles derived from one normalized run request.
 
 Parameters:
-- `state` - Shared engine state where the deterministic flag is stored.
-
-Returns: True when deterministic mode is active.
+- `reducedTelemetry` - - When true, keep only the essential telemetry metrics.
+- `telemetryMinimal` - - When true, disable verbose telemetry capture.
+- `disableBaldwinPhase` - - When true, skip the Baldwin refinement stage.
 
-### isProfilingDetailsEnabled
+### getEvolutionEngineFacadeRuntimeState
 
 ```ts
-isProfilingDetailsEnabled(
-  state: EngineState,
-): boolean
+getEvolutionEngineFacadeRuntimeState(): LogitsRingState
 ```
 
-Determine whether detailed profiling accumulation is active.
-
-Parameters:
-- `state` - Shared engine state providing profiling configuration.
+Read the mutable facade-owned logits-ring runtime state.
 
-Returns: True when detail profiling is enabled.
+Returns: Current ring-capacity, shared-mode, and write-cursor state.
 
-### profilingStartTimestamp
+### getEvolutionEngineMaxLogitsRingCapacity
 
 ```ts
-profilingStartTimestamp(): number
+getEvolutionEngineMaxLogitsRingCapacity(): number
 ```
 
-Return a profiling start timestamp that mirrors the historic `#PROFILE_T0` helper.
+Read the hard maximum ring capacity used by the public facade.
 
-Returns: Millisecond timestamp representing the profiling start time.
+Returns: Maximum ring capacity allowed for logits telemetry.
 
-### readHighResolutionTime
+### getEvolutionEngineSharedState
 
 ```ts
-readHighResolutionTime(): number
+getEvolutionEngineSharedState(): EngineState
 ```
 
-Obtain a monotonic-ish timestamp suitable for profiling.
-
-Returns: Timestamp in milliseconds, preferring `performance.now` when available.
+Return the shared engine singleton used by extracted engine modules.
 
-Example:
+The public facade now depends on the same owner as the rest of the engine
+boundary instead of creating a private duplicate singleton.
 
-const timestamp = readHighResolutionTime();
+Returns: Shared engine state singleton.
 
-### resolveRngParameters
+### resetEvolutionEngineRingState
 
 ```ts
-resolveRngParameters(): RngCacheParameters
+resetEvolutionEngineRingState(): void
 ```
 
-Provide cached congruential parameters used by the shared fast RNG helper.
+Reset the facade-owned logits-ring runtime state to its baseline defaults.
 
-Returns: Immutable  {@link RngCacheParameters} reference reused across draws.
+## evolutionEngine/sampling.ts
 
-Example:
+Sampling and history helpers extracted from the ASCII maze evolution façade.
 
-const parameters = resolveRngParameters();
+Responsibilities:
+1. Provide allocation-light array sampling utilities that reuse the shared `EngineState` scratch pools.
+2. Expose history helpers that mirror the façade behaviour while keeping pooled buffers centralised.
+3. Centralise RNG parameter resolution for sampling paths to keep behaviour deterministic under shared state.
 
-### setDeterministicMode
+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.
+
+### getTail
 
 ```ts
-setDeterministicMode(
+getTail(
   state: EngineState,
-  seed: number | undefined,
-): void
+  source: T[] | undefined,
+  count: number,
+): T[]
 ```
 
-Enable deterministic RNG mode and optionally reseed the shared RNG state.
+Extract the last `count` items from `source` into the shared tail buffer.
 
-Parameters:
-- `state` - Shared engine state where the deterministic flag is stored.
-- `seed` - Optional deterministic seed. Finite numeric inputs are normalised to u32.
+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.
 
-Returns: void.
+Parameters:
+- `state` - Shared engine state providing the tail history buffer.
+- `source` - Source array reference.
+- `count` - Number of trailing items requested.
 
-## evolutionEngine/scratchPools.ts
+Returns: Pooled array containing the requested tail slice.
 
-Scratch pool management helpers extracted from the maze evolution façade.
+Example:
 
-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.
+const recent = getTail(sharedState, telemetryLog, 40);
 
-### allocateLogitsRing
+### pushHistory
 
 ```ts
-allocateLogitsRing(
-  capacity: number,
-  actionDimension: number,
-): Float32Array<ArrayBufferLike>[]
+pushHistory(
+  buffer: T[] | undefined,
+  value: T,
+  maxLength: number,
+): T[]
 ```
 
-Build a non-shared logits ring sized to the requested capacity.
+Proxy to {@link MazeUtils.pushHistory} for consistency with the façade API.
 
 Parameters:
-- `capacity` - Number of rows to create.
-- `actionDimension` - Number of logits stored per row.
+- `buffer` - Existing history buffer (may be undefined).
+- `value` - Value to append to the buffer.
+- `maxLength` - Maximum allowed buffer length.
 
-Returns: Array of typed rows representing the ring buffer.
+Returns: Updated history buffer with `value` appended and trimmed to `maxLength`.
 
-### ensureConnFlagsCapacity
+Example:
+
+const history = pushHistory(existingHistory, snapshot, 20);
+
+### sampleArray
 
 ```ts
-ensureConnFlagsCapacity(
+sampleArray(
   state: EngineState,
-  minimumCapacity: number,
-): Int8Array<ArrayBufferLike> | null
+  source: T[],
+  sampleCount: number,
+): T[]
 ```
 
-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.
+Sample `sampleCount` items (with replacement) from `source` into the pooled scratch buffer.
 
-Returns: Int8Array bitmap or null when allocation failed.
+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.
 
-### ensureLogitsRingCapacity
+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`.
 
-```ts
-ensureLogitsRingCapacity(
-  capacityRequest: LogitsRingCapacityOptions,
-): LogitsRingCapacityResult
-```
+Parameters:
+- `state` - Shared engine state providing pooled scratch buffers.
+- `source` - Source array to sample from.
+- `sampleCount` - Number of samples to draw (with replacement).
 
-Grow or shrink the logits ring to accomodate the requested recent-step budget.
+Returns: Pooled ephemeral array containing the sampled elements.
 
-Parameters:
-- `capacityRequest` - Parameters describing the requested resize.
+Example:
 
-Returns: The resulting capacity and whether shared-array mode stayed enabled.
+const picks = sampleArray(sharedState, population, 16);
+const safeCopy = [...picks];
 
-### ensureScratchCapacity
+### sampleIntoScratch
 
 ```ts
-ensureScratchCapacity(
+sampleIntoScratch(
   state: EngineState,
-  request: ScratchCapacityRequest,
-): void
+  source: T[],
+  sampleCount: number,
+): number
 ```
 
-Grow pooled scratch buffers to conservative sizes for the upcoming run.
+Sample up to `sampleCount` items (with replacement) into the shared `samplePool` buffer.
+
+Compared with `sampleArray`, this form is for callers that only need a count
+plus access to the pooled buffer on `state.scratch.samplePool`. That avoids
+one more logical array object on the hottest paths.
+
+Steps:
+1. Validate inputs and ensure the pooled buffer exists.
+2. Grow the buffer by powers of two when more capacity is required.
+3. Fill the buffer with random selections and return the number of items written.
 
 Parameters:
-- `state` - Shared engine state exposing scratch buffers.
-- `request` - Sizing request describing the evolution workload.
+- `state` - Shared engine state providing the pooled buffer.
+- `source` - Source array to sample from.
+- `sampleCount` - Number of elements requested (floored to an integer).
 
-### initialiseSharedLogitsRing
+Returns: Number of sampled elements written into the pooled buffer.
+
+Example:
+
+const sampled = sampleIntoScratch(sharedState, population, 24);
+for (let index = 0; index < sampled; index++) {
+  processGenome(sharedState.scratch.samplePool[index]);
+}
+
+### sampleSegmentIntoScratch
 
 ```ts
-initialiseSharedLogitsRing(
+sampleSegmentIntoScratch(
   state: EngineState,
-  config: SharedLogitsConfig,
-): boolean
+  source: T[],
+  segmentStart: number,
+  sampleCount: number,
+): number
 ```
 
-Attempt to allocate SharedArrayBuffer-backed logits ring storage.
+Sample from a suffix of `source` starting at `segmentStart` into the pooled buffer.
+
+The common use case is "sample from the non-elite tail" or some later slice
+of a population without first allocating `source.slice(segmentStart)`.
+
+Steps:
+1. Clamp indices and ensure there is a non-empty segment.
+2. Ensure the pooled buffer can store the requested sample count.
+3. Fill the buffer via the shared RNG, returning the number of items written.
 
 Parameters:
-- `state` - Shared engine state containing the logits buffers.
-- `config` - Shared ring configuration (capacity and action dimension).
+- `state` - Shared engine state providing pooled sampling buffers.
+- `source` - Source array to sample from.
+- `segmentStart` - Inclusive start index of the segment.
+- `sampleCount` - Number of items to sample (with replacement).
 
-Returns: true when shared mode was activated successfully.
+Returns: Number of elements written into the pooled buffer.
 
-### LogitsRingCapacityOptions
+Example:
 
-Shape describing the parameters used when ensuring the logits ring capacity.
+const written = sampleSegmentIntoScratch(sharedState, population, elitismCount, 12);
+const genome = sharedState.scratch.samplePool[0];
 
-### LogitsRingCapacityResult
+## evolutionEngine/engineState.ts
 
-Result returned after resizing the logits ring.
+Centralised shared state for the ASCII maze evolution façade.
 
-### maybeShrinkScratch
+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.
+
+### createEngineState
 
 ```ts
-maybeShrinkScratch(
-  state: EngineState,
-  populationSize: number,
-): void
+createEngineState(): EngineState
 ```
 
-Shrink oversized scratch buffers once the population size drops significantly.
+Fabricates a new {@link EngineState} with pre-sized scratch buffers and default toggle values.
 
-Parameters:
-- `state` - Shared engine state exposing scratch buffers.
-- `populationSize` - Current population size used to derive shrink heuristics.
+Returns: Initialized engine state used by the maze evolution façade.
 
-### ScratchCapacityRequest
+### createProfilingState
 
-Parameters describing the scratch sizing requirements for ensureScratchCapacity.
+```ts
+createProfilingState(): EngineProfilingState
+```
 
-### SharedLogitsConfig
+Fabricates the profiling state bundle consumed by timing helpers.
 
-Parameters passed when attempting to initialise the shared logits ring buffers.
+Returns: Profiling configuration and accumulator state.
 
-## evolutionEngine/setupHelpers.ts
+Example:
 
-Setup helpers for the ASCII maze evolution engine.
+const profiling = createProfilingState();
+console.log(profiling.detailsEnabled); // false unless env flag set
 
-Responsibilities:
-- Create cooperative frame-yielding helpers for async evolution loops.
-- Initialize Node.js persistence helpers when available.
-- Build resilient logging writers with dashboard and console fallbacks.
+### createScratchState
 
-### DashboardManagerLike
+```ts
+createScratchState(): EngineScratchState
+```
 
-Dashboard manager shape for logging (optional log function).
+Fabricates the default pooled scratch buffers shared by the evolution façade.
 
-### FilesystemModule
+Returns: Scratch bundle sized for the baseline maze curriculum workload.
 
-Minimal filesystem module shape for type safety (Node.js fs module subset).
+Example:
 
-### initPersistence
+const scratch = createScratchState();
+console.log(scratch.exps.length); // 4
+
+### createToggleState
 
 ```ts
-initPersistence(
-  persistDir: string | undefined,
-): { fs: FilesystemModule | null; path: PathModule | null; }
+createToggleState(): EngineToggleState
 ```
 
-Initialize persistence helpers (Node `fs` & `path`) when available and ensure the target
-directory exists. This helper intentionally does nothing in browser-like hosts.
+Fabricates the default runtime toggle bundle for the evolution façade.
 
-Steps:
-1. Detect whether a Node-like `require` is available and attempt to load `fs` and `path`
-2. If both modules are available and `persistDir` is provided, ensure the directory exists
-   by creating it recursively when necessary
-3. Return an object containing the (possibly null) `{ fs, path }` references for callers to use
+Returns: Toggle state with all optional phases enabled.
 
-Notes:
-- This helper deliberately performs defensive checks and swallows synchronous errors because
-  persistence is optional in many host environments (tests, browser demos)
-- No large allocations are performed here; the function returns lightweight references
+Example:
 
-Parameters:
-- `persistDir` - - Optional directory to ensure exists. If falsy, no filesystem mutations are attempted.
+const toggles = createToggleState();
+console.log(toggles.reducedTelemetry); // false
 
-Returns: Object with `{ fs, path }` where each value may be `null` when unavailable.
+### DEFAULT_RNG_CACHE_BATCH_SIZE
 
-Example:
+Default RNG cache batch size mirroring the façade constant.
 
-const { fs, path } = initPersistence('./snapshots');
-if (fs && path) {
-  fs.writeFileSync(path.join(dir, 'snapshot.json'), data);
-}
+### DEFAULT_VISITED_HASH_LOAD_FACTOR
 
-### isPauseRequested
+Default load factor target for the visited coordinate hash table.
+
+### 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.
+
+### ensureRngCacheBatch
 
 ```ts
-isPauseRequested(
-  hostAdapter: EvolutionHostAdapter | undefined,
-): boolean
+ensureRngCacheBatch(
+  parameters: RngCacheParameters,
+  state: EngineState,
+): RngCacheHandles
 ```
 
-Read host-controlled pause state without letting host errors break the engine.
+Ensure the RNG cache contains fresh samples before consumption.
 
 Parameters:
-- `hostAdapter` - - Optional host adapter implementing pause polling.
+- `parameters` - Congruential generator parameters and cache batch size.
+- `state` - Optional engine state container (defaults to the shared singleton).
 
-Returns: True when the host asks the engine to remain paused.
+Returns: Handles exposing the cache and its batch size.
 
-### makeFlushToFrame
+### ensureVisitedHashCapacity
 
 ```ts
-makeFlushToFrame(
-  hostAdapter: EvolutionHostAdapter | undefined,
-): () => Promise<void>
+ensureVisitedHashCapacity(
+  targetEntryCount: number,
+  state: EngineState,
+): VisitedHashScratchHandles
 ```
 
-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
+Ensure the visited-coordinate hash table can store the requested entry count.
 
-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
+Growth policy:
+1. Tables expand geometrically (powers of two) while respecting the configured load factor.
+2. When the existing table is large enough, it is cleared in place to preserve the allocation.
+3. Load factors outside the (0,1) range fall back to {@link DEFAULT_VISITED_HASH_LOAD_FACTOR}.
 
 Parameters:
-- `hostAdapter` - - Optional host adapter that owns cooperative pause state.
+- `targetEntryCount` - Expected number of unique coordinates to store.
+- `state` - Optional engine state container (defaults to the shared singleton).
 
-Returns: A function that yields cooperatively to the next animation frame / tick.
+Returns: Cleared table reference plus the slot mask for probing loops.
 
 Example:
 
-const flushToFrame = makeFlushToFrame();
-await flushToFrame(); // yields to next frame/tick
+const { table, slotMask } = ensureVisitedHashCapacity(256);
 
-### makeSafeWriter
+### initialiseTelemetryScratch
 
 ```ts
-makeSafeWriter(
-  dashboardManager: DashboardManagerLike | undefined,
-): (msg: string) => void
+initialiseTelemetryScratch(
+  request: TelemetryScratchRequest,
+  state: EngineState,
+): TelemetryScratchHandles
 ```
 
-Build a resilient writer that attempts to write to Node stdout, then a provided
-dashboard logger, and finally `console.log` as a last resort.
-
-Steps:
-1. If Node `process.stdout.write` is available, use it (no trailing newline forced)
-2. Else if `dashboardManager.logFunction` exists, call it
-3. Else fall back to `console.log` and trim the message
+Ensure telemetry-related scratch buffers allocate enough capacity for upcoming work.
 
-Notes:
-- Errors are swallowed; logging must never throw and disrupt the evolution loop
-- This factory is allocation-light; the returned function only creates a trimmed string
-  when falling back to `console.log`
+Growth strategy:
+- Float64Array pools grow geometrically (powers of two) and preserve previously written prefixes.
+- String buffers are replaced with larger arrays (also geometric) to avoid repeated reallocations.
+- Optional higher-moment buffers (M3/M4/kurtosis) are only created when {@link TelemetryScratchRequest.includeHigherMoments}
+  is truthy to keep reduced telemetry lightweight.
 
 Parameters:
-- `dashboardManager` - - Optional manager exposing `logFunction(msg:string)` used in some UIs.
+- `request` - Capacity hints for upcoming telemetry computations.
+- `state` - Optional engine state target (defaults to the singleton  {@link engineState} ).
 
-Returns: A function accepting a single string message to write.
+Returns: Handles referencing the ensured scratch buffers for immediate use.
 
-Example:
+### reseedRngState
 
-const safeWrite = makeSafeWriter(dashboardManager);
-safeWrite('[INFO] Generation 42 complete\n');
+```ts
+reseedRngState(
+  seed: number,
+  state: EngineState,
+): number
+```
 
-### PathModule
+Persist a new RNG seed and schedule a cache refill on the next draw.
 
-Minimal path module shape for type safety (Node.js path module subset).
+Parameters:
+- `seed` - Raw numeric seed requested by deterministic mode.
+- `state` - Optional engine state container (defaults to the shared singleton).
 
-## evolutionEngine/evolutionLoop.ts
+Returns: Unsigned seed stored in scratch state for diagnostics.
 
-Evolution Loop Module
+### RngCacheHandles
 
-Purpose:
--------
-Provides utilities for running the main NEAT evolution loop, including
-generation orchestration, cancellation checking, and loop helper preparation.
+Handles returned after ensuring the RNG cache is ready for consumption.
 
-This module encapsulates:
- - Cancellation detection (AbortSignal and legacy cancellation API)
- - Loop helper preparation (frame flushing, persistence, logging)
- - Generation execution and orchestration
- - Stop condition evaluation
+### RngCacheParameters
 
-ES2023 Policy:
--------------
-- Uses nullish coalescing `??` and optional chaining `?.`
-- Descriptive variable names (no short identifiers)
-- Async/await for generation loops
-- Best-effort error handling (swallow non-fatal errors)
+Parameters controlling the RNG cache refill process.
 
-### checkCancellation
+### setBaldwinPhaseDisabledFlag
 
 ```ts
-checkCancellation(
-  options: EvolutionOptions,
-  bestResult: IMazeRunResult | undefined,
-): string | undefined
+setBaldwinPhaseDisabledFlag(
+  isDisabled: boolean,
+): void
 ```
 
-Inspect cooperative cancellation sources and annotate the provided result when cancelled.
+Enable or disable the Baldwin-phase warm-start pipeline.
 
-This function checks for cancellation from two sources in priority order:
- 1) Legacy cancellation object with `isCancelled()` method
- 2) Standard AbortSignal with `aborted` property
+Parameters:
+- `isDisabled` - When true, skips the Lamarckian training stage.
 
-Design Rationale:
- - Allocation-free (uses only short-lived local references)
- - Best-effort error handling (swallow exceptions to avoid disrupting loop)
- - Sets `exitReason` on result object for caller inspection
- - Safe to call on hot paths (no scratch buffers or pooling needed)
+### setReducedTelemetryFlag
 
-Cancellation Priority:
- 1. Check `options.cancellation.isCancelled()` (legacy API)
- 2. Check `options.signal.aborted` (standard AbortSignal)
- 3. Return undefined if no cancellation detected
+```ts
+setReducedTelemetryFlag(
+  isEnabled: boolean,
+): void
+```
 
-Parameters:
+Toggle the reduced telemetry mode.
 
 Parameters:
-- `options` - - Optional run configuration which may contain `cancellation` and/or `signal`
-- `bestResult` - - Optional mutable result object that will be annotated with `exitReason`
+- `isEnabled` - When true, trims telemetry to the essential metrics only.
 
-Returns: A reason string ('cancelled' | 'aborted') when cancellation is detected, otherwise `undefined`
+### setTelemetryMinimalFlag
 
-Examples:
+```ts
+setTelemetryMinimalFlag(
+  isMinimal: boolean,
+): void
+```
 
-// Check cancellation before starting next generation
-const cancelReason = checkCancellation(opts, runResult);
-if (cancelReason) return cancelReason;
+Toggle the minimal telemetry mode for JSON output.
 
-// Check cancellation without result annotation
-if (checkCancellation(opts)) {
-  console.log('User requested cancellation');
-  break;
-}
+Parameters:
+- `isMinimal` - When true, disables verbose telemetry capture.
 
-### checkStopConditions
+### TelemetryScratchHandles
 
-```ts
-checkStopConditions(
-  bestResult: IMazeRunResult | undefined,
-  bestNetwork: default | null,
-  maze: string[],
-  completedGenerations: number,
-  neat: default,
-  dashboardManager: IDashboardManager | undefined,
-  flushToFrame: () => Promise<void>,
-  hostAdapter: EvolutionHostAdapter | undefined,
-  minProgressToPass: number,
-  autoPauseOnSolve: boolean,
-  stopOnlyOnSolve: boolean,
-  stagnantGenerations: number,
-  maxStagnantGenerations: number,
-  maxGenerations: number,
-): Promise<string | undefined>
-```
+Collection of scratch buffers handed back after initialisation for convenience.
 
-Inspect common termination conditions and perform minimal, best-effort side-effects.
+### TelemetryScratchRequest
 
-This function checks three canonical stop reasons in priority order:
- 1) **Solved**: Best result achieves minimum progress threshold
- 2) **Stagnation**: No improvement for maxStagnantGenerations
- 3) **MaxGenerations**: Absolute generation cap reached
+Configuration describing which telemetry scratch buffers require capacity guarantees.
 
-Design Rationale:
- - Allocation-light (uses only local references)
- - Best-effort error handling (all side effects swallowed)
- - Safe to call frequently on hot paths
- - Updates dashboard and yields to host when stopping
- - Emits optional 'asciiMazeSolved' event on solve (browser only)
+### VisitedHashScratchHandles
 
-Side Effects (Best-Effort):
- - Updates dashboard manager when stopping
- - Awaits flushToFrame to yield to host
- - Reports stop events through the optional host adapter
- - Annotates `bestResult.exitReason` with canonical reason string
+Handles exposed after ensuring the visited-coordinate hash table capacity.
 
-Parameters:
+## evolutionEngine/rngAndTiming.ts
 
-Parameters:
-- `bestResult` - - Mutable run summary object (may be mutated with `exitReason`)
-- `bestNetwork` - - Network object associated with the best result (for dashboard)
-- `maze` - - Maze descriptor passed to dashboard updates/events
-- `completedGenerations` - - Current generation index (integer)
-- `neat` - - NEAT driver instance (passed to dashboard update)
-- `dashboardManager` - - Optional manager exposing `update(maze, result, network, gen, neat)`
-- `flushToFrame` - - Async function to yield to host renderer (e.g. requestAnimationFrame)
-- `hostAdapter` - - Optional host adapter that owns host-side stop behavior
-- `minProgressToPass` - - Numeric threshold to consider a run 'solved'
-- `autoPauseOnSolve` - - When truthy request host-side pause handling on solve
-- `stopOnlyOnSolve` - - When true ignore stagnation/maxGenerations as stop reasons
-- `stagnantGenerations` - - Current count of stagnant generations observed
-- `maxStagnantGenerations` - - Max allowed stagnant generations before stopping
-- `maxGenerations` - - Absolute generation cap after which the run stops
+RNG and timing helpers extracted from the evolution façade.
 
-Returns: A canonical reason string ('solved'|'stagnation'|'maxGenerations') when stopping, otherwise `undefined`
+### accumulateProfilingDuration
 
-Example:
+```ts
+accumulateProfilingDuration(
+  state: EngineState,
+  category: string,
+  deltaMs: number,
+): void
+```
 
-// Check stop conditions after each generation
-const reason = await checkStopConditions(
-  bestResult, bestNet, maze, gen, neat, dashboard, flush,
-  95, true, false, stagnant, 500, 10000
-);
-if (reason) {
-  console.log('Stopping due to', reason);
-  break;
-}
+Accumulate a profiling duration under the supplied key when detail profiling is enabled.
 
-### emitProfileSummary
+Parameters:
+- `state` - Shared engine state containing profiling configuration.
+- `category` - Profiling segment key (for example `telemetry`).
+- `deltaMs` - Millisecond duration to add to the accumulator.
+
+Returns: void.
+
+### clearDeterministicMode
 
 ```ts
-emitProfileSummary(
-  engineState: EngineState,
-  safeWrite: (msg: string) => void,
-  completedGenerations: number,
-  totalEvolveMs: number,
-  totalLamarckMs: number,
-  totalSimMs: number,
-  isProfilingDetailsEnabledFn: (state: EngineState) => boolean,
-  getProfilingAccumulatorsFn: (state: EngineState) => ProfilingAccumulators,
+clearDeterministicMode(
+  state: EngineState,
 ): void
 ```
 
-Emit a formatted profiling summary showing average per-generation timings.
+Disable deterministic RNG mode.
 
-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.
+Parameters:
+- `state` - Shared engine state where the deterministic flag is stored.
 
-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
+Returns: void.
 
-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
+### drawFastRandom
 
-Parameters:
+```ts
+drawFastRandom(
+  state: EngineState,
+  parameters: RngCacheParameters,
+): number
+```
+
+Generate a fast uniform random sample using the shared RNG cache.
 
 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
+- `state` - Shared engine state providing the RNG cache and seed.
+- `parameters` - Congruential parameters forwarded to  {@link ensureRngCacheBatch} .
 
-Example:
+Returns: Uniform sample in the range [0, 1).
 
-// Print averages after a run that completed 100 generations
-emitProfileSummary(
-  state, console.log, 100, 12000, 3000, 4500,
-  isProfilingDetailsEnabled, getProfilingAccumulators
-);
+Example:
 
-### EvolutionLoopResult
+const sample = drawFastRandom(sharedState, rngParameters);
 
-Evolution loop result
+### getProfilingAccumulators
 
-### GenerationOutcome
+```ts
+getProfilingAccumulators(
+  state: EngineState,
+): Record<string, number>
+```
 
-Generation outcome with profiling timings
+Provide direct access to the profiling accumulator map.
 
-### MutableMazeResult
+Parameters:
+- `state` - Shared engine state containing the profiling accumulators.
 
-Mutable result object with exitReason field
+Returns: Mutable record of profiling accumulators keyed by category name.
 
-### persistSnapshotIfNeeded
+### isDeterministicModeEnabled
 
 ```ts
-persistSnapshotIfNeeded(
-  engineState: EngineState,
-  fs: { writeFileSync?: ((path: string, data: string) => void) | undefined; } | null,
-  pathModule: { join?: ((...paths: string[]) => string) | undefined; } | null,
-  persistDir: string | undefined,
-  persistTopK: number,
-  completedGenerations: number,
-  persistEvery: number,
-  neat: default,
-  bestFitness: number,
-  simplifyMode: boolean,
-  plateauCounter: number,
-  scratchSnapshotObj: Record<string, unknown>,
-  scratchSnapshotTop: SnapshotEntry[],
-  collectTelemetryTailFn: (state: EngineState, neat: default, count: number) => unknown,
-  getSortedIndicesByScoreFn: (state: EngineState, population: default[]) => number[],
-  isProfilingDetailsEnabledFn: (state: EngineState) => boolean,
-  profilingStartTimestampFn: (state: EngineState) => number,
-  accumulateProfilingDurationFn: (state: EngineState, label: string, duration: number) => void,
-): void
+isDeterministicModeEnabled(
+  state: EngineState,
+): boolean
 ```
 
-Persist a population snapshot to disk at the configured interval.
+Retrieve the deterministic RNG flag stored on the shared engine state.
 
-This function writes a JSON snapshot of the current generation state when the
-generation cadence aligns with the configured persistence interval. It captures
-top-K genomes, telemetry tail, and metadata for later analysis or resume.
+Parameters:
+- `state` - Shared engine state where the deterministic flag is stored.
 
-Design Rationale:
- - Best-effort semantics: swallows all errors to avoid disrupting evolution loop
- - Reuses pooled scratch objects (SCRATCH_SNAPSHOT_OBJ, SCRATCH_SNAPSHOT_TOP) to minimize allocations
- - Optional profiling when enabled (measures snapshot serialization time)
- - Defensive validation to ensure FS/path modules are available
+Returns: True when deterministic mode is active.
 
-Scheduling Logic:
- - Only persists when `completedGenerations % persistEvery === 0`
- - Requires valid fs.writeFileSync and pathModule.join functions
- - Requires non-empty population
+### isProfilingDetailsEnabled
 
-Snapshot Structure:
- - generation: completed generation index
- - bestFitness: best fitness score this generation
- - simplifyMode: whether simplification was active
- - plateauCounter: current plateau detection counter
- - timestamp: Date.now() when snapshot was created
- - telemetryTail: last N telemetry entries
- - top: top-K genomes with minimal metadata (idx, score, nodes, connections, json)
+```ts
+isProfilingDetailsEnabled(
+  state: EngineState,
+): boolean
+```
 
-Parameters:
+Determine whether detailed profiling accumulation is active.
 
 Parameters:
-- `engineState` - - Shared engine state with scratch buffers and profiling
-- `fs` - - Node.js fs module or compatible FS API
-- `pathModule` - - Node.js path module or compatible path API
-- `persistDir` - - Directory path where snapshots should be written
-- `persistTopK` - - Number of top genomes to include in snapshot
-- `completedGenerations` - - Current generation index
-- `persistEvery` - - Generation interval for persistence (e.g., 25 = every 25th generation)
-- `neat` - - NEAT instance with population
-- `bestFitness` - - Best fitness score this generation
-- `simplifyMode` - - Whether simplification mode is active
-- `plateauCounter` - - Current plateau counter value
-- `scratchSnapshotObj` - - Pooled snapshot object (reused across calls)
-- `scratchSnapshotTop` - - Pooled top-K buffer (reused across calls)
-- `collectTelemetryTailFn` - - Function to collect telemetry tail from state
-- `getSortedIndicesByScoreFn` - - Function to get sorted genome indices
-- `isProfilingDetailsEnabledFn` - - Function to check profiling state
-- `profilingStartTimestampFn` - - Function to get profiling start time
-- `accumulateProfilingDurationFn` - - Function to accumulate profiling duration
-
-Example:
+- `state` - Shared engine state providing profiling configuration.
 
-// Persist snapshot every 25 generations
-persistSnapshotIfNeeded(
-  state, fs, path, './snapshots', 10, 50, 25, neat, 0.95, false, 3,
-  scratchObj, scratchTop, collectTail, getSorted, isProfilingEnabled, profileStart, profileAccum
-);
+Returns: True when detail profiling is enabled.
 
-### prepareLoopHelpers
+### profilingStartTimestamp
 
 ```ts
-prepareLoopHelpers(
-  opts: EvolutionOptions,
-  scratchBundle: ScratchBundle,
-): LoopHelpers
+profilingStartTimestamp(): number
 ```
 
-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)
+Return a profiling start timestamp that mirrors the historic `#PROFILE_T0` helper.
 
-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
+Returns: Millisecond timestamp representing the profiling start time.
 
-Scratch Buffer Warm-Up:
- - samplePool: Array for population sampling
- - profilingScratch: Float64Array(4) for timing accumulation
- - exps: Float64Array(64) for exponential computations
+### readHighResolutionTime
 
-Parameters:
+```ts
+readHighResolutionTime(): number
+```
 
-Parameters:
-- `opts` - - Normalized run options (contains persistDir and dashboardManager)
-- `scratchBundle` - - Engine scratch state for optional buffer warm-up
+Obtain a monotonic-ish timestamp suitable for profiling.
 
-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
+Returns: Timestamp in milliseconds, preferring `performance.now` when available.
 
 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
+const timestamp = readHighResolutionTime();
 
-### runEvolutionLoop
+### resolveRngParameters
 
 ```ts
-runEvolutionLoop(
-  engineState: EngineState,
-  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>
+resolveRngParameters(): RngCacheParameters
 ```
 
-Internal evolution loop that executes generations until a stop condition or cancellation.
+Provide cached congruential parameters used by the shared fast RNG helper.
 
-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`.
+Returns: Immutable  {@link RngCacheParameters} reference reused across draws.
+
+Example:
+
+const parameters = resolveRngParameters();
+
+### setDeterministicMode
+
+```ts
+setDeterministicMode(
+  state: EngineState,
+  seed: number | undefined,
+): void
+```
+
+Enable deterministic RNG mode and optionally reseed the shared RNG state.
 
 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.)
+- `state` - Shared engine state where the deterministic flag is stored.
+- `seed` - Optional deterministic seed. Finite numeric inputs are normalised to u32.
 
-Returns: Promise resolving to an object:
-{ bestNetwork, bestResult, neat, completedGenerations, totalEvolveMs, totalLamarckMs, totalSimMs, updatedRingState }
+Returns: void.
 
-Example:
+## evolutionEngine/scratchPools.ts
 
-const runSummary = await runEvolutionLoop(
-  state, neat, opts, trainingSet, maze, start, exit, distMap, helpers, true, ...
-);
+Scratch pool management helpers extracted from the maze evolution façade.
 
-### runGeneration
+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
 
 ```ts
-runGeneration(
-  engineState: EngineState,
-  neat: default,
-  doProfile: boolean,
-  lamarckianIterations: number,
-  lamarckianTrainingSet: { input: number[]; output: number[]; }[],
-  lamarckianSampleSize: number | undefined,
-  safeWrite: (msg: string) => void,
-  completedGenerations: number,
-  dynamicPopEnabled: boolean,
-  dynamicPopMax: number,
-  plateauGenerations: number,
-  plateauCounter: number,
-  dynamicPopExpandInterval: number,
-  dynamicPopExpandFactor: number,
-  dynamicPopPlateauSlack: number,
-  speciesHistoryRef: number[],
-  emptyVec: default[],
-  scratchNodeIdx: Int32Array<ArrayBufferLike>,
-  getNodeIndicesByType: (nodes: NetworkNode[], type: string) => number,
-  constants: TrainingConstants,
-): Promise<GenerationOutcome>
+allocateLogitsRing(
+  capacity: number,
+  actionDimension: number,
+): Float32Array<ArrayBufferLike>[]
 ```
 
-Run one generation: evolve, ensure output identity, update species history, maybe expand population,
-and run Lamarckian training if configured.
+Build a non-shared logits ring sized to the requested capacity.
 
-Behaviour & contract:
- - Performs a single NEAT generation step in a best-effort, non-throwing manner.
- - Measures profiling durations when `doProfile` is truthy. Profiling is optional and
-   kept allocation-free (uses local numeric temporaries only).
- - Invokes the following steps in order (each step is wrapped in a try/catch so
-   the evolution loop remains resilient to per-stage failures):
-     1) `neat.evolve()` to produce the fittest network for this generation.
-     2) `ensureOutputIdentity` to normalise output activations for consumers.
-     3) `handleSpeciesHistory` to update species statistics and history.
-     4) `maybeExpandPopulation` to grow the population when configured and warranted.
-     5) Optional Lamarckian warm-start training via `applyLamarckianTraining`.
- - The method is allocation-light and reuses engine helpers / pooled buffers where
-   appropriate. It never throws; internal errors are swallowed and optionally logged
-   via the provided `safeWrite` function.
+Parameters:
+- `capacity` - Number of rows to create.
+- `actionDimension` - Number of logits stored per row.
+
+Returns: Array of typed rows representing the ring buffer.
+
+### ensureConnFlagsCapacity
+
+```ts
+ensureConnFlagsCapacity(
+  state: EngineState,
+  minimumCapacity: number,
+): Int8Array<ArrayBufferLike> | null
+```
+
+Ensure the recurrent/gated detection bitmap has sufficient capacity.
 
 Parameters:
-- `engineState` - - Shared engine state with scratch buffers and RNG
-- `neat` - - NEAT driver instance used for evolving the generation
-- `doProfile` - - When truthy measure timing for the evolve step (ms) using engine clock
-- `lamarckianIterations` - - Number of supervised training iterations to run per genome (0 to skip)
-- `lamarckianTrainingSet` - - Array of supervised training cases used for warm-start (may be empty)
-- `lamarckianSampleSize` - - Optional per-network sample size used by the warm-start routine
-- `safeWrite` - - Safe logging function; used only for best-effort diagnostic messages
-- `completedGenerations` - - Current generation index (used by expansion heuristics)
-- `dynamicPopEnabled` - - Whether dynamic population expansion is enabled
-- `dynamicPopMax` - - Upper bound on population size for expansion
-- `plateauGenerations` - - Window size used by plateau detection
-- `plateauCounter` - - Current plateau counter used by expansion heuristics
-- `dynamicPopExpandInterval` - - Generation interval to attempt expansion
-- `dynamicPopExpandFactor` - - Fractional growth factor used to compute new members
-- `dynamicPopPlateauSlack` - - Minimum plateau ratio required to trigger expansion
-- `speciesHistoryRef` - - Mutable array holding species history (maintained externally)
-- `emptyVec` - - Empty array fallback to avoid ephemeral allocations
-- `scratchNodeIdx` - - Pooled node index buffer (passed through to helpers)
-- `getNodeIndicesByType` - - Helper function to collect node indices by type
-- `constants` - - Object containing DEFAULT_TRAIN_ERROR, DEFAULT_TRAIN_RATE, DEFAULT_TRAIN_MOMENTUM, DEFAULT_TRAIN_BATCH_SMALL, DEFAULT_STD_SMALL, DEFAULT_STD_ADJUST_MULT
+- `state` - Shared engine state containing the pooled bitmap.
+- `minimumCapacity` - Minimum number of entries required by the caller.
 
-Returns: An object shaped { fittest, tEvolve, tLamarck } where:
-- `fittest` is the network returned by `neat.evolve()` (may be null on error),
-- `tEvolve` is the measured evolve duration in milliseconds when `doProfile` is true (0 otherwise),
-- `tLamarck` is the total time spent in Lamarckian training (0 when skipped)
+Returns: Int8Array bitmap or null when allocation failed.
 
-Example:
+### ensureLogitsRingCapacity
 
-// Run a single generation with profiling and optional Lamarckian warm-start
-const { fittest, tEvolve, tLamarck } = await runGeneration(
-  engineState,
-  neatInstance,
-  true,   // doProfile
-  5,      // lamarckianIterations
-  trainingSet,
-  16,     // lamarckianSampleSize
-  console.log,
-  genIndex,
-  true,
-  500,
-  10,
-  plateauCounter,
-  5,
-  0.1,
-  0.75,
-  speciesHistory,
-  [],
-  nodeIndexBuffer,
-  getNodeIndicesByTypeFn,
-  { DEFAULT_TRAIN_ERROR: 0.01, ... }
-);
+```ts
+ensureLogitsRingCapacity(
+  capacityRequest: LogitsRingCapacityOptions,
+): LogitsRingCapacityResult
+```
 
-### SimResultWithOutputs
+Grow or shrink the logits ring to accomodate the requested recent-step budget.
 
-Simulation result with step outputs
+Parameters:
+- `capacityRequest` - Parameters describing the requested resize.
 
-### simulateAndPostprocess
+Returns: The resulting capacity and whether shared-array mode stayed enabled.
+
+### ensureScratchCapacity
 
 ```ts
-simulateAndPostprocess(
-  engineState: EngineState,
-  fittest: default,
-  encodedMaze: number[][],
-  startPosition: readonly [number, number],
-  exitPosition: readonly [number, number],
-  distanceMap: number[][],
-  maxSteps: number | undefined,
-  doProfile: boolean,
-  safeWrite: (msg: string) => void,
-  logEvery: number,
-  completedGenerations: number,
-  neat: default,
-  runtimeContext: EvolutionLoopRuntimeContext,
-  ringState: LogitsRingState,
-  telemetryContext: EvolutionLoopTelemetryContext,
-  loopSupportContext: Pick<EvolutionLoopSupportContext, "loopHelpers">,
-): SimulationResult
+ensureScratchCapacity(
+  state: EngineState,
+  request: ScratchCapacityRequest,
+): void
 ```
 
-Simulate the supplied `fittest` genome/network and perform allocation-light postprocessing.
+Grow pooled scratch buffers to conservative sizes for the upcoming run.
 
-Behaviour & contract:
- - Runs the simulation via `MazeMovement.simulateAgent` and attaches compact telemetry
-   (saturation fraction, action entropy) directly onto the `fittest` object (in-place).
- - When per-step logits are returned the helper attempts to copy them into the engine's pooled
-   ring buffers to avoid per-run allocations. Two copy modes are supported:
-     1) Shared SAB-backed flat Float32Array with an atomic Int32 write index (cross-worker safe).
-     2) Local in-process per-row Float32Array ring (`scratchLogitsRing`).
- - Best-effort: all mutation and buffer-copy steps are guarded; failures are swallowed so the
-   evolution loop is not interrupted. Use `safeWrite` for optional diagnostic messages.
+Parameters:
+- `state` - Shared engine state exposing scratch buffers.
+- `request` - Sizing request describing the evolution workload.
 
-Steps (high level):
- 1) Run the simulator and capture wall-time when `doProfile` is truthy.
- 2) Attach compact telemetry fields to `fittest` and ensure legacy `_lastStepOutputs` exists.
- 3) If per-step logits are available, ensure ring capacity and copy them into the selected ring.
- 4) Optionally prune saturated hidden->output connections and emit telemetry via logGenerationTelemetry.
- 5) Return the raw simulation result and elapsed simulation time (ms when profiling enabled).
+### 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
+maybeShrinkScratch(
+  state: EngineState,
+  populationSize: number,
+): void
+```
+
+Shrink oversized scratch buffers once the population size drops significantly.
+
+Parameters:
+- `state` - Shared engine state exposing scratch buffers.
+- `populationSize` - Current population size used to derive shrink heuristics.
+
+### ScratchCapacityRequest
+
+Parameters describing the scratch sizing requirements for ensureScratchCapacity.
+
+### SharedLogitsConfig
+
+Parameters passed when attempting to initialise the shared logits ring buffers.
+
+## evolutionEngine/setupHelpers.ts
+
+Setup helpers for the ASCII maze evolution engine.
+
+Responsibilities:
+- Create cooperative frame-yielding helpers for async evolution loops.
+- Initialize Node.js persistence helpers when available.
+- Build resilient logging writers with dashboard and console fallbacks.
+
+### DashboardManagerLike
+
+Dashboard manager shape for logging (optional log function).
+
+### FilesystemModule
+
+Minimal filesystem module shape for type safety (Node.js fs module subset).
+
+### initPersistence
+
+```ts
+initPersistence(
+  persistDir: string | undefined,
+): { fs: FilesystemModule | null; path: PathModule | null; }
+```
 
-Notes on pooling / reentrancy:
- - The local ring is not re-entrant; callers must avoid concurrent writes.
- - When shared mode is true we prefer the SAB-backed path which uses Atomics and is safe
-   for cross-thread producers.
+Initialize persistence helpers (Node `fs` & `path`) when available and ensure the target
+directory exists. This helper intentionally does nothing in browser-like hosts.
+
+Steps:
+1. Detect whether a Node-like `require` is available and attempt to load `fs` and `path`
+2. If both modules are available and `persistDir` is provided, ensure the directory exists
+   by creating it recursively when necessary
+3. Return an object containing the (possibly null) `{ fs, path }` references for callers to use
+
+Notes:
+- This helper deliberately performs defensive checks and swallows synchronous errors because
+  persistence is optional in many host environments (tests, browser demos)
+- No large allocations are performed here; the function returns lightweight references
 
 Parameters:
-- `engineState` - - Shared engine state with scratch buffers and ring configuration
-- `fittest` - - Genome/network considered the generation's best; may be mutated with metadata
-- `encodedMaze` - - Maze descriptor used by the simulator
-- `startPosition` - - Start co-ordinates passed as-is to the simulator
-- `exitPosition` - - Exit co-ordinates passed as-is to the simulator
-- `distanceMap` - - Optional precomputed distance map consumed by the simulator
-- `maxSteps` - - Optional maximum simulation steps; may be undefined to allow default
-- `doProfile` - - When truthy measure and return the simulation time in milliseconds
-- `safeWrite` - - Optional logger used for non-fatal diagnostic messages
-- `logEvery` - - Emit telemetry every `logEvery` generations (0 disables periodic telemetry)
-- `completedGenerations` - - Current generation index used for conditional telemetry
-- `neat` - - NEAT driver instance passed to telemetry hooks
-- `runtimeContext` - - Shared pooled ring buffers and limits for logits telemetry.
-- `ringState` - - Current mutable ring state (capacity, shared-mode flag, write cursor).
-- `telemetryContext` - - Telemetry thresholds and verbosity switches used after simulation.
-- `loopSupportContext` - - Shared scratch buffers and helper callbacks used by the loop.
+- `persistDir` - - Optional directory to ensure exists. If falsy, no filesystem mutations are attempted.
 
-Returns: An object { generationResult, simTime, updatedRingState } where simTime is ms when profiling is enabled
+Returns: Object with `{ fs, path }` where each value may be `null` when unavailable.
 
 Example:
 
-const { generationResult, simTime, updatedRingState } = simulateAndPostprocess(
-  state, bestGenome, maze, start, exit, distMap, 1000, true, console.log, 10, genIdx, neat, ...
-);
+const { fs, path } = initPersistence('./snapshots');
+if (fs && path) {
+  fs.writeFileSync(path.join(dir, 'snapshot.json'), data);
+}
 
-### SimulationOutcome
+### isPauseRequested
 
-Simulation result with profiling and ring state
+```ts
+isPauseRequested(
+  hostAdapter: EvolutionHostAdapter | undefined,
+): boolean
+```
 
-### updateDashboardAndMaybeFlush
+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
-updateDashboardAndMaybeFlush(
-  maze: string[],
-  result: IMazeRunResult | undefined,
-  network: default | null,
-  completedGenerations: number,
-  neat: default,
-  dashboardManager: IDashboardManager | undefined,
-  flushToFrame: (() => Promise<void>) | undefined,
-): Promise<void>
+makeFlushToFrame(
+  hostAdapter: EvolutionHostAdapter | undefined,
+): () => Promise<void>
 ```
 
-Safely update a UI dashboard with the latest run state and optionally yield to the
-host/frame via an awaited flush function.
+Create a cooperative frame-yielding function used by 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.
+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
 
-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
+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.
 
-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.
+Returns: A function that yields cooperatively to the next animation frame / tick.
 
 Example:
 
-// Yield to the browser's next repaint after dashboard update:
-await updateDashboardAndMaybeFlush(
-  maze, genResult, fittestNetwork, gen, neatInstance, dashboard, () => new Promise(r => requestAnimationFrame(r))
-);
+const flushToFrame = makeFlushToFrame();
+await flushToFrame(); // yields to next frame/tick
 
-### updateDashboardPeriodic
+### makeSafeWriter
 
 ```ts
-updateDashboardPeriodic(
-  maze: string[],
-  bestResult: IMazeRunResult | undefined,
-  bestNetwork: default | null,
-  completedGenerations: number,
-  neat: default,
-  dashboardManager: IDashboardManager | undefined,
-  flushToFrame: (() => Promise<void>) | undefined,
-): Promise<void>
+makeSafeWriter(
+  dashboardManager: DashboardManagerLike | undefined,
+): (msg: string) => 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.
+Build a resilient writer that attempts to write to Node stdout, then a provided
+dashboard logger, and finally `console.log` as a last resort.
 
-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:
+1. If Node `process.stdout.write` is available, use it (no trailing newline forced)
+2. Else if `dashboardManager.logFunction` exists, call it
+3. Else fall back to `console.log` and trim the message
 
-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.
+Notes:
+- Errors are swallowed; logging must never throw and disrupt the evolution loop
+- This factory is allocation-light; the returned function only creates a trimmed string
+  when falling back to `console.log`
 
 Parameters:
+- `dashboardManager` - - Optional manager exposing `logFunction(msg:string)` used in some UIs.
 
-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: A function accepting a single string message to write.
 
 Example:
 
-// Safe periodic update and yield to next frame
-await updateDashboardPeriodic(
-  maze, result, network, gen, neatInstance, dashboard, () => new Promise(r => requestAnimationFrame(r))
-);
+const safeWrite = makeSafeWriter(dashboardManager);
+safeWrite('[INFO] Generation 42 complete\n');
+
+### PathModule
+
+Minimal path module shape for type safety (Node.js path module subset).
 
 ## evolutionEngine/curriculumPhase.ts
 
@@ -3586,79 +3744,6 @@ Minimum safe load factor applied when normalising visited-hash configuration.
 
 Knuth-derived 32-bit constant used when seeding the RNG state.
 
-## evolutionEngine/evolutionEngine.services.ts
-
-### applyEvolutionEngineRingState
-
-```ts
-applyEvolutionEngineRingState(
-  updatedRingState: LogitsRingState,
-): void
-```
-
-Apply the latest logits-ring runtime values returned by the evolution loop.
-
-Parameters:
-- `updatedRingState` - - New ring-capacity, shared-mode, and write-cursor values.
-
-### configureEvolutionEngineToggles
-
-```ts
-configureEvolutionEngineToggles(
-  reducedTelemetry: boolean,
-  telemetryMinimal: boolean,
-  disableBaldwinPhase: boolean,
-): void
-```
-
-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
-
-```ts
-getEvolutionEngineMaxLogitsRingCapacity(): number
-```
-
-Read the hard maximum ring capacity used by the public facade.
-
-Returns: Maximum ring capacity allowed for logits telemetry.
-
-### getEvolutionEngineSharedState
-
-```ts
-getEvolutionEngineSharedState(): EngineState
-```
-
-Return the shared engine singleton used by extracted engine modules.
-
-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
 
 Stable tuning values consumed by the ASCII maze evolution facade.