@reicek/neataptic-ts 0.1.25 → 0.1.26

package/test/examples/flappy_bird/trainer/README.md

@@ -78,13 +78,23 @@ flowchart TB
     ScoreEntry["ScoredGenomeEntry\nranking helper"] --> Network
 ```
 
-### FlappyTrainerNetwork
+### FlappyGenerationEvaluationPlan
 
-Network shape expected by the Flappy trainer.
+Generation-level rollout plans for staged evaluation.
 
-The trainer only needs the evaluation-facing subset of a full network plus an
-optional score field used by staged ranking helpers. That narrow shape keeps
-the trainer decoupled from most of the broader network implementation.
+Each generation resolves one plan that answers three questions: how strong is
+the current mutation schedule, which shared seeds belong to each stage, and
+what rollout budget each stage is allowed to spend. This is the contract that
+makes quick screening, full passes, and reevaluation feel like one coherent
+policy instead of three unrelated helper calls.
+
+### FlappyGenerationReport
+
+Compact generation report used for training logs.
+
+The report is shaped for longitudinal monitoring rather than raw storage. It
+collects the distribution and best-run details needed to judge whether a
+generation improved robustly instead of producing one lucky outlier.
 
 ### FlappyTrainerNeatController
 
@@ -95,13 +105,13 @@ documents only the methods and mutable options it actually depends on, which
 makes the orchestration code read more like policy and less like framework
 plumbing.
 
-### FlappyGenerationReport
+### FlappyTrainerNetwork
 
-Compact generation report used for training logs.
+Network shape expected by the Flappy trainer.
 
-The report is shaped for longitudinal monitoring rather than raw storage. It
-collects the distribution and best-run details needed to judge whether a
-generation improved robustly instead of producing one lucky outlier.
+The trainer only needs the evaluation-facing subset of a full network plus an
+optional score field used by staged ranking helpers. That narrow shape keeps
+the trainer decoupled from most of the broader network implementation.
 
 ### FlappyTrainerRuntimeState
 
@@ -119,16 +129,6 @@ These values define the static training shape before runtime state and staged
 evaluation are attached. Once created, the rest of the trainer can treat this
 as a stable configuration shelf rather than scattered ad hoc constants.
 
-### FlappyGenerationEvaluationPlan
-
-Generation-level rollout plans for staged evaluation.
-
-Each generation resolves one plan that answers three questions: how strong is
-the current mutation schedule, which shared seeds belong to each stage, and
-what rollout budget each stage is allowed to spend. This is the contract that
-makes quick screening, full passes, and reevaluation feel like one coherent
-policy instead of three unrelated helper calls.
-
 ### ScoredGenomeEntry
 
 Score carrier used for deterministic ordering helpers.
@@ -139,6 +139,39 @@ leak across multiple helpers.
 
 ## trainer/trainer.ts
 
+### handleTrainerMainError
+
+```ts
+handleTrainerMainError(
+  error: unknown,
+): void
+```
+
+Handles fatal `main` rejection path.
+
+The trainer keeps this boundary small so unexpected failures are formatted in
+one consistent place before reaching the CLI. That keeps shutdown behavior
+and terminal messaging consistent whether the failure came from setup,
+evaluation, or the loop itself.
+
+Parameters:
+- `error` - - Unknown rejection reason from trainer execution.
+
+Returns: Nothing.
+
+### isDirectTrainerExecution
+
+```ts
+isDirectTrainerExecution(): boolean
+```
+
+Resolves whether this module is the direct Node entrypoint.
+
+This lets the file behave as both a reusable module and a runnable script
+without duplicating the startup boundary in a second wrapper file.
+
+Returns: `true` when Node launched this file directly.
+
 ### runTrainer
 
 ```ts
@@ -176,39 +209,6 @@ Example:
 await runTrainer();
 ```
 
-### handleTrainerMainError
-
-```ts
-handleTrainerMainError(
-  error: unknown,
-): void
-```
-
-Handles fatal `main` rejection path.
-
-The trainer keeps this boundary small so unexpected failures are formatted in
-one consistent place before reaching the CLI. That keeps shutdown behavior
-and terminal messaging consistent whether the failure came from setup,
-evaluation, or the loop itself.
-
-Parameters:
-- `error` - - Unknown rejection reason from trainer execution.
-
-Returns: Nothing.
-
-### isDirectTrainerExecution
-
-```ts
-isDirectTrainerExecution(): boolean
-```
-
-Resolves whether this module is the direct Node entrypoint.
-
-This lets the file behave as both a reusable module and a runnable script
-without duplicating the startup boundary in a second wrapper file.
-
-Returns: `true` when Node launched this file directly.
-
 ## trainer/trainer.errors.ts
 
 Small CLI-facing error-rendering boundary for the trainer.
@@ -218,6 +218,10 @@ shutdown paths from inventing slightly different terminal messages. That is a
 small detail, but it makes long-running scripts and quick debugging sessions
 easier to scan.
 
+### FLAPPY_TRAINER_UNEXPECTED_ERROR_PREFIX
+
+Prefix used when rendering unexpected trainer failures to stderr.
+
 ### formatTrainerErrorMessage
 
 ```ts
@@ -237,10 +241,6 @@ Parameters:
 
 Returns: Formatted error string for CLI logging.
 
-### FLAPPY_TRAINER_UNEXPECTED_ERROR_PREFIX
-
-Prefix used when rendering unexpected trainer failures to stderr.
-
 ## trainer/trainer.constants.ts
 
 Named knobs for trainer cadence, fairness, fallback behavior, and terminal
@@ -322,13 +322,6 @@ Reporting and terminal output:
 | `FLAPPY_TRAINER_LOG_PARTS_DELIMITER` | Keeps compact generation logs consistently tokenized. |
 | `FLAPPY_TRAINER_STOPPED_MESSAGE` | Gives graceful shutdown a stable terminal message. |
 
-### FLAPPY_TRAINER_DEFAULT_POPULATION_SIZE
-
-Default population size used by the Flappy trainer NEAT run.
-
-The demo keeps this large enough for staged selection to matter while still
-remaining practical for local experimentation.
-
 ### FLAPPY_TRAINER_DEFAULT_ELITISM_COUNT
 
 Number of elite genomes preserved unchanged each generation.
@@ -336,6 +329,13 @@ Number of elite genomes preserved unchanged each generation.
 Preserving a small elite keeps the trainer from discarding clearly strong
 genomes while the rest of the population continues exploring.
 
+### FLAPPY_TRAINER_DEFAULT_POPULATION_SIZE
+
+Default population size used by the Flappy trainer NEAT run.
+
+The demo keeps this large enough for staged selection to matter while still
+remaining practical for local experimentation.
+
 ### FLAPPY_TRAINER_DEFAULT_RNG_SEED
 
 Deterministic trainer RNG seed used for reproducible training runs.
@@ -343,215 +343,215 @@ Deterministic trainer RNG seed used for reproducible training runs.
 Reusing the shared Flappy example seed makes trainer behavior easier to
 compare across doc examples, tests, and manual tuning sessions.
 
-### FLAPPY_TRAINER_STOPPED_MESSAGE
+### FLAPPY_TRAINER_DUMMY_FLAP_OUTPUT
 
-Log message emitted when trainer loop exits cleanly.
+Dummy output channel value for the "flap" action score.
 
-A dedicated constant keeps the shutdown path stable for humans and for any
-scripts that watch trainer output.
+Keeping the flap score lower than the no-flap score produces a predictable
+never-flap dummy network for defensive report code paths.
 
-### FLAPPY_TRAINER_REEVALUATION_MIN_CANDIDATE_COUNT
+### FLAPPY_TRAINER_DUMMY_NETWORK_ID
 
-Minimum candidate count for reevaluation stage, regardless of elitism.
+ID used by dummy fallback network for defensive reporting paths.
 
-This prevents small elite settings from starving the anti-luck pass of enough
-genomes to produce a meaningful final comparison.
+The report helpers occasionally need a safe stand-in network so logging can
+stay total even when no real population data is available.
 
-### FLAPPY_TRAINER_SCORE_MEDIAN_PERCENTILE
+### FLAPPY_TRAINER_DUMMY_NO_FLAP_OUTPUT
 
-Percentile used when reporting median population score.
+Dummy output channel value for the "no flap" action score.
 
-Keeping the percentile explicit makes the report math self-documenting even
-for readers who skim the log formatter before the statistics helpers.
+The dummy network intentionally prefers the passive action so fallback report
+generation remains deterministic and simple.
 
-### FLAPPY_TRAINER_SCORE_P90_PERCENTILE
+### FLAPPY_TRAINER_FRAME_PRIMARY_BASE_SCORE
 
-Percentile used when reporting high-end population score (P90).
+Base offset awarded to genomes that satisfy the mean-pipe progress filter.
 
-The trainer uses `p90` as a quick "is the upper tail getting healthier?"
-signal without over-focusing on only the single best genome.
+The large offset makes it obvious that surviving the gate is more important
+than tiny differences in the secondary frame-oriented terms.
 
-### FLAPPY_TRAINER_MUTATION_ANNEAL_GENERATIONS
+### FLAPPY_TRAINER_FRAME_PRIMARY_PIPE_WEIGHT
 
-Generation count used to fully anneal mutation schedule from start to end values.
+Pipe-progress contribution weight for frame-primary scoring.
 
-Within this window the trainer gradually cools from more exploratory updates
-toward smaller, steadier changes.
+This keeps pipe progress visible even inside the gated scoring branch so the
+ranking still prefers genuinely advancing policies.
 
-### FLAPPY_TRAINER_MUTATION_RATE_START
+### FLAPPY_TRAINER_FRAME_PRIMARY_SURVIVAL_WEIGHT
 
-Initial mutation rate at generation `0` before annealing.
+Survival contribution weight for frame-primary scoring.
 
-The starting rate is intentionally aggressive so the early population can
-discover useful topologies quickly.
+Once a genome passes the pipe-progress gate, extra survival time still matters
+because it often signals more stable control.
 
-### FLAPPY_TRAINER_MUTATION_RATE_END
+### FLAPPY_TRAINER_FRAME_STABILITY_STDDEV_WEIGHT
 
-Final mutation rate reached after annealing window completes.
+Penalty multiplier applied to fitness standard deviation in frame-primary scoring.
 
-Lower late-stage mutation pressure helps good policies stabilize instead of
-being reshuffled as aggressively as the opening generations.
+Higher instability lowers the provisional score so a lucky but erratic genome
+is less likely to outrank a steadier competitor.
 
-### FLAPPY_TRAINER_MUTATION_AMOUNT_START
+### FLAPPY_TRAINER_FULL_PASS_ELITISM_MULTIPLIER
 
-Initial mutation amount at generation `0` before annealing.
+Multiplier over elitism used to size full-pass candidate pool.
 
-This controls how many mutation operations can be applied while the trainer
-is still in its exploratory phase.
+This ties the full-pass budget to a familiar population concept so the deeper
+stage scales alongside the preserved elite.
 
-### FLAPPY_TRAINER_MUTATION_AMOUNT_END
+### FLAPPY_TRAINER_FULL_PASS_POPULATION_FRACTION
 
-Final mutation amount reached after annealing window completes.
+Population fraction used to size full-pass candidate pool.
 
-Cooling the mutation amount along with the rate reduces late-generation noise
-without fully freezing structural search.
+The full stage uses the larger of this fraction and the elitism-based floor so
+promising mid-pack genomes are not excluded too aggressively.
 
-### FLAPPY_TRAINER_NEAT_INITIAL_MUTATION_RATE
+### FLAPPY_TRAINER_FULL_ROLLOUT_EARLY_TERMINATION_CONSECUTIVE_FRAMES
 
-Initial NEAT mutation rate before generation schedule annealing is applied.
+Consecutive unrecoverable frames needed to stop full rollout early.
 
-This seeds the controller with a sensible baseline before the per-generation
-planner starts taking over.
+This longer streak makes the full stage less trigger-happy than the quick
+screen while still avoiding wasted rollout budget.
 
-### FLAPPY_TRAINER_NEAT_INITIAL_MUTATION_AMOUNT
+### FLAPPY_TRAINER_FULL_ROLLOUT_EARLY_TERMINATION_GRACE_FRAMES
 
-Initial NEAT mutation amount before generation schedule annealing is applied.
+Early-termination grace frames used during full rollout stage.
 
-Matching the controller bootstrap to the trainer policy avoids a confusing
-mismatch between generation `0` and later loop behavior.
+The deeper stage allows more time before judging a trajectory unrecoverable
+because the trainer is now evaluating stronger candidates more carefully.
 
-### FLAPPY_TRAINER_QUICK_ROLLOUT_MAX_FRAMES
+### FLAPPY_TRAINER_FULL_ROLLOUT_PIPE_PROGRESS_TARGET
 
-Frame cap used during quick screening rollout stage.
+Pipe-progress target used to normalize full and reevaluation rollout fitness.
 
-The quick stage is supposed to eliminate obviously weak genomes cheaply, so
-its horizon is intentionally shorter than the full evaluation horizon.
+The deeper stages share a tougher target because they are used for robust
+ranking rather than first-pass elimination.
 
-### FLAPPY_TRAINER_QUICK_ROLLOUT_EARLY_TERMINATION_GRACE_FRAMES
+### FLAPPY_TRAINER_LOG_PARTS_DELIMITER
 
-Early-termination grace frames used during quick screening rollout stage.
+Delimiter used when composing compact generation log lines.
 
-This short grace period gives a policy a brief chance to stabilize before the
-unrecoverable-flight heuristic is allowed to stop the rollout.
+A single-space delimiter keeps the log dense, stable, and easy to parse by eye
+during long-running terminal sessions.
 
-### FLAPPY_TRAINER_QUICK_ROLLOUT_EARLY_TERMINATION_CONSECUTIVE_FRAMES
+### FLAPPY_TRAINER_MUTATION_AMOUNT_END
 
-Consecutive unrecoverable frames needed to stop quick screening rollout early.
+Final mutation amount reached after annealing window completes.
 
-Requiring a streak prevents one noisy frame from ending the screen too early
-while still saving time on clearly doomed trajectories.
+Cooling the mutation amount along with the rate reduces late-generation noise
+without fully freezing structural search.
 
-### FLAPPY_TRAINER_QUICK_ROLLOUT_PIPE_PROGRESS_TARGET
+### FLAPPY_TRAINER_MUTATION_AMOUNT_START
 
-Pipe-progress target used to normalize quick screening rollout fitness.
+Initial mutation amount at generation `0` before annealing.
 
-The lower quick-stage target reflects the fact that this pass is a screen, not
-the trainer's final statement of policy quality.
+This controls how many mutation operations can be applied while the trainer
+is still in its exploratory phase.
 
-### FLAPPY_TRAINER_FULL_ROLLOUT_EARLY_TERMINATION_GRACE_FRAMES
+### FLAPPY_TRAINER_MUTATION_ANNEAL_GENERATIONS
 
-Early-termination grace frames used during full rollout stage.
+Generation count used to fully anneal mutation schedule from start to end values.
 
-The deeper stage allows more time before judging a trajectory unrecoverable
-because the trainer is now evaluating stronger candidates more carefully.
+Within this window the trainer gradually cools from more exploratory updates
+toward smaller, steadier changes.
 
-### FLAPPY_TRAINER_FULL_ROLLOUT_EARLY_TERMINATION_CONSECUTIVE_FRAMES
+### FLAPPY_TRAINER_MUTATION_RATE_END
 
-Consecutive unrecoverable frames needed to stop full rollout early.
+Final mutation rate reached after annealing window completes.
 
-This longer streak makes the full stage less trigger-happy than the quick
-screen while still avoiding wasted rollout budget.
+Lower late-stage mutation pressure helps good policies stabilize instead of
+being reshuffled as aggressively as the opening generations.
 
-### FLAPPY_TRAINER_FULL_ROLLOUT_PIPE_PROGRESS_TARGET
+### FLAPPY_TRAINER_MUTATION_RATE_START
 
-Pipe-progress target used to normalize full and reevaluation rollout fitness.
+Initial mutation rate at generation `0` before annealing.
 
-The deeper stages share a tougher target because they are used for robust
-ranking rather than first-pass elimination.
+The starting rate is intentionally aggressive so the early population can
+discover useful topologies quickly.
 
-### FLAPPY_TRAINER_FRAME_STABILITY_STDDEV_WEIGHT
+### FLAPPY_TRAINER_NEAT_INITIAL_MUTATION_AMOUNT
 
-Penalty multiplier applied to fitness standard deviation in frame-primary scoring.
+Initial NEAT mutation amount before generation schedule annealing is applied.
 
-Higher instability lowers the provisional score so a lucky but erratic genome
-is less likely to outrank a steadier competitor.
+Matching the controller bootstrap to the trainer policy avoids a confusing
+mismatch between generation `0` and later loop behavior.
 
-### FLAPPY_TRAINER_PIPE_FILTER_TOLERANCE
+### FLAPPY_TRAINER_NEAT_INITIAL_MUTATION_RATE
 
-Allowed mean-pipes delta from the current best before frame-primary scoring applies.
+Initial NEAT mutation rate before generation schedule annealing is applied.
 
-This acts like a gating tolerance: only genomes close enough in pipe progress
-get the more generous frame-primary score treatment.
+This seeds the controller with a sensible baseline before the per-generation
+planner starts taking over.
 
-### FLAPPY_TRAINER_FRAME_PRIMARY_BASE_SCORE
+### FLAPPY_TRAINER_PIPE_FALLBACK_PIPE_WEIGHT
 
-Base offset awarded to genomes that satisfy the mean-pipe progress filter.
+Pipe-progress contribution weight for fallback scoring path.
 
-The large offset makes it obvious that surviving the gate is more important
-than tiny differences in the secondary frame-oriented terms.
+The fallback path leans heavily on pipe progress because it is the clearest
+robust signal available before the primary gate is satisfied.
 
-### FLAPPY_TRAINER_FRAME_PRIMARY_SURVIVAL_WEIGHT
+### FLAPPY_TRAINER_PIPE_FILTER_TOLERANCE
 
-Survival contribution weight for frame-primary scoring.
+Allowed mean-pipes delta from the current best before frame-primary scoring applies.
 
-Once a genome passes the pipe-progress gate, extra survival time still matters
-because it often signals more stable control.
+This acts like a gating tolerance: only genomes close enough in pipe progress
+get the more generous frame-primary score treatment.
 
-### FLAPPY_TRAINER_FRAME_PRIMARY_PIPE_WEIGHT
+### FLAPPY_TRAINER_QUICK_ROLLOUT_EARLY_TERMINATION_CONSECUTIVE_FRAMES
 
-Pipe-progress contribution weight for frame-primary scoring.
+Consecutive unrecoverable frames needed to stop quick screening rollout early.
 
-This keeps pipe progress visible even inside the gated scoring branch so the
-ranking still prefers genuinely advancing policies.
+Requiring a streak prevents one noisy frame from ending the screen too early
+while still saving time on clearly doomed trajectories.
 
-### FLAPPY_TRAINER_PIPE_FALLBACK_PIPE_WEIGHT
+### FLAPPY_TRAINER_QUICK_ROLLOUT_EARLY_TERMINATION_GRACE_FRAMES
 
-Pipe-progress contribution weight for fallback scoring path.
+Early-termination grace frames used during quick screening rollout stage.
 
-The fallback path leans heavily on pipe progress because it is the clearest
-robust signal available before the primary gate is satisfied.
+This short grace period gives a policy a brief chance to stabilize before the
+unrecoverable-flight heuristic is allowed to stop the rollout.
 
-### FLAPPY_TRAINER_FULL_PASS_ELITISM_MULTIPLIER
+### FLAPPY_TRAINER_QUICK_ROLLOUT_MAX_FRAMES
 
-Multiplier over elitism used to size full-pass candidate pool.
+Frame cap used during quick screening rollout stage.
 
-This ties the full-pass budget to a familiar population concept so the deeper
-stage scales alongside the preserved elite.
+The quick stage is supposed to eliminate obviously weak genomes cheaply, so
+its horizon is intentionally shorter than the full evaluation horizon.
 
-### FLAPPY_TRAINER_FULL_PASS_POPULATION_FRACTION
+### FLAPPY_TRAINER_QUICK_ROLLOUT_PIPE_PROGRESS_TARGET
 
-Population fraction used to size full-pass candidate pool.
+Pipe-progress target used to normalize quick screening rollout fitness.
 
-The full stage uses the larger of this fraction and the elitism-based floor so
-promising mid-pack genomes are not excluded too aggressively.
+The lower quick-stage target reflects the fact that this pass is a screen, not
+the trainer's final statement of policy quality.
 
-### FLAPPY_TRAINER_DUMMY_NETWORK_ID
+### FLAPPY_TRAINER_REEVALUATION_MIN_CANDIDATE_COUNT
 
-ID used by dummy fallback network for defensive reporting paths.
+Minimum candidate count for reevaluation stage, regardless of elitism.
 
-The report helpers occasionally need a safe stand-in network so logging can
-stay total even when no real population data is available.
+This prevents small elite settings from starving the anti-luck pass of enough
+genomes to produce a meaningful final comparison.
 
-### FLAPPY_TRAINER_DUMMY_NO_FLAP_OUTPUT
+### FLAPPY_TRAINER_SCORE_MEDIAN_PERCENTILE
 
-Dummy output channel value for the "no flap" action score.
+Percentile used when reporting median population score.
 
-The dummy network intentionally prefers the passive action so fallback report
-generation remains deterministic and simple.
+Keeping the percentile explicit makes the report math self-documenting even
+for readers who skim the log formatter before the statistics helpers.
 
-### FLAPPY_TRAINER_DUMMY_FLAP_OUTPUT
+### FLAPPY_TRAINER_SCORE_P90_PERCENTILE
 
-Dummy output channel value for the "flap" action score.
+Percentile used when reporting high-end population score (P90).
 
-Keeping the flap score lower than the no-flap score produces a predictable
-never-flap dummy network for defensive report code paths.
+The trainer uses `p90` as a quick "is the upper tail getting healthier?"
+signal without over-focusing on only the single best genome.
 
-### FLAPPY_TRAINER_LOG_PARTS_DELIMITER
+### FLAPPY_TRAINER_STOPPED_MESSAGE
 
-Delimiter used when composing compact generation log lines.
+Log message emitted when trainer loop exits cleanly.
 
-A single-space delimiter keeps the log dense, stable, and easy to parse by eye
-during long-running terminal sessions.
+A dedicated constant keeps the shutdown path stable for humans and for any
+scripts that watch trainer output.
 
 ## trainer/trainer.loop.service.ts
 
@@ -572,29 +572,26 @@ flowchart LR
     Log --> Resolve
 ```
 
-### runTrainerEvolutionLoop
+### applyMutationSchedule
 
 ```ts
-runTrainerEvolutionLoop(
+applyMutationSchedule(
   neatController: FlappyTrainerNeatController,
-  trainerRuntimeState: FlappyTrainerRuntimeState,
-  logGenerationSummary: LogGenerationSummaryCallback,
-): Promise<void>
+  mutationSchedule: FlappyMutationSchedule,
+): void
 ```
 
-Runs the outer evolution loop until runtime stop is requested.
+Applies mutation schedule values to the NEAT controller options.
 
-Educational note:
-This is the trainer's main heartbeat: resolve the current mutation schedule,
-evolve one generation, run a representative fallback rollout for logging, and
-emit a compact summary.
+The schedule is resolved outside this helper so the loop can read as a clean
+"resolve -> apply -> evolve -> report" flow. That separation also makes it
+easier to inspect the active schedule in logs or tests.
 
 Parameters:
 - `neatController` - - Trainer NEAT controller.
-- `trainerRuntimeState` - - Mutable trainer runtime state.
-- `logGenerationSummary` - - Callback that emits compact generation logs.
+- `mutationSchedule` - - Mutation schedule for current generation.
 
-Returns: Promise resolved when the trainer has been stopped.
+Returns: Nothing.
 
 ### LogGenerationSummaryCallback
 
@@ -614,26 +611,29 @@ The loop owns evolution cadence, while the callback owns presentation.
 Keeping those concerns separate makes it easy to reuse the loop with richer
 reporting later.
 
-### applyMutationSchedule
+### runTrainerEvolutionLoop
 
 ```ts
-applyMutationSchedule(
+runTrainerEvolutionLoop(
   neatController: FlappyTrainerNeatController,
-  mutationSchedule: FlappyMutationSchedule,
-): void
+  trainerRuntimeState: FlappyTrainerRuntimeState,
+  logGenerationSummary: LogGenerationSummaryCallback,
+): Promise<void>
 ```
 
-Applies mutation schedule values to the NEAT controller options.
+Runs the outer evolution loop until runtime stop is requested.
 
-The schedule is resolved outside this helper so the loop can read as a clean
-"resolve -> apply -> evolve -> report" flow. That separation also makes it
-easier to inspect the active schedule in logs or tests.
+Educational note:
+This is the trainer's main heartbeat: resolve the current mutation schedule,
+evolve one generation, run a representative fallback rollout for logging, and
+emit a compact summary.
 
 Parameters:
 - `neatController` - - Trainer NEAT controller.
-- `mutationSchedule` - - Mutation schedule for current generation.
+- `trainerRuntimeState` - - Mutable trainer runtime state.
+- `logGenerationSummary` - - Callback that emits compact generation logs.
 
-Returns: Nothing.
+Returns: Promise resolved when the trainer has been stopped.
 
 ## trainer/trainer.setup.service.ts
 
@@ -644,20 +644,32 @@ controller construction can be read, tested, and tuned without also reading
 the outer loop. This boundary answers a simple question: what does the demo
 need before the first generation can run?
 
-### createTrainerSetup
+### createNeatController
 
 ```ts
-createTrainerSetup(): FlappyTrainerSetup
+createNeatController(
+  trainerSetup: FlappyTrainerSetup,
+): FlappyTrainerNeatController
 ```
 
-Creates immutable setup values for the trainer.
+Builds the NEAT controller with baseline options.
 
 Educational note:
-The setup object freezes the core training shape up front: input width,
-output width, population size, and elitism count. Centralizing those values
-makes the rest of the trainer read as policy rather than configuration noise.
+The trainer enables population-level fitness mode because the quality of a
+Flappy policy depends on fair comparison across shared seed batches, not on a
+one-network-at-a-time scoring callback.
 
-Returns: Default trainer setup values used for NEAT configuration.
+Parameters:
+- `trainerSetup` - - Immutable trainer setup values.
+
+Returns: Typed NEAT controller used by the trainer loop.
+
+Example:
+
+```ts
+const trainerSetup = createTrainerSetup();
+const neatController = createNeatController(trainerSetup);
+```
 
 ### createTrainerRuntimeState
 
@@ -672,32 +684,20 @@ latest report so the outer loop can remain easy to reason about.
 
 Returns: Fresh runtime state used by loop orchestration.
 
-### createNeatController
+### createTrainerSetup
 
 ```ts
-createNeatController(
-  trainerSetup: FlappyTrainerSetup,
-): FlappyTrainerNeatController
+createTrainerSetup(): FlappyTrainerSetup
 ```
 
-Builds the NEAT controller with baseline options.
+Creates immutable setup values for the trainer.
 
 Educational note:
-The trainer enables population-level fitness mode because the quality of a
-Flappy policy depends on fair comparison across shared seed batches, not on a
-one-network-at-a-time scoring callback.
-
-Parameters:
-- `trainerSetup` - - Immutable trainer setup values.
-
-Returns: Typed NEAT controller used by the trainer loop.
-
-Example:
+The setup object freezes the core training shape up front: input width,
+output width, population size, and elitism count. Centralizing those values
+makes the rest of the trainer read as policy rather than configuration noise.
 
-```ts
-const trainerSetup = createTrainerSetup();
-const neatController = createNeatController(trainerSetup);
-```
+Returns: Default trainer setup values used for NEAT configuration.
 
 ### resolveNoopFitness
 
@@ -868,38 +868,38 @@ The trainer should stop between generations, not by tearing the process down
 in the middle of evaluation. This file converts OS-level stop signals into one
 shared runtime intent flag that the main loop can observe safely.
 
-### registerTrainerStopSignals
+### handleTrainerStopSignal
 
 ```ts
-registerTrainerStopSignals(
+handleTrainerStopSignal(
   trainerRuntimeState: FlappyTrainerRuntimeState,
 ): void
 ```
 
-Registers graceful stop signal handlers.
+Handles one stop signal update.
 
-Educational note:
-Long-running evolutionary runs should stop cleanly when the user presses
-`Ctrl+C`. This service flips runtime intent instead of abruptly tearing down
-the process mid-generation.
+The handler does the minimum possible work because signal paths should stay
+predictable and side-effect light.
 
 Parameters:
 - `trainerRuntimeState` - - Mutable trainer runtime state.
 
 Returns: Nothing.
 
-### handleTrainerStopSignal
+### registerTrainerStopSignals
 
 ```ts
-handleTrainerStopSignal(
+registerTrainerStopSignals(
   trainerRuntimeState: FlappyTrainerRuntimeState,
 ): void
 ```
 
-Handles one stop signal update.
+Registers graceful stop signal handlers.
 
-The handler does the minimum possible work because signal paths should stay
-predictable and side-effect light.
+Educational note:
+Long-running evolutionary runs should stop cleanly when the user presses
+`Ctrl+C`. This service flips runtime intent instead of abruptly tearing down
+the process mid-generation.
 
 Parameters:
 - `trainerRuntimeState` - - Mutable trainer runtime state.
@@ -1164,43 +1164,43 @@ These utilities keep score extraction and descending-order selection in one
 place so the staged evaluation services do not each reinvent the same sorting
 logic with slightly different fallback rules.
 
-### selectTopGenomesByScore
+### resolveBestGenomeByScore
 
 ```ts
-selectTopGenomesByScore(
+resolveBestGenomeByScore(
   population: readonly FlappyTrainerNetwork[],
-  provisionalScoresByGenome: ReadonlyMap<FlappyTrainerNetwork, number>,
-  targetCount: number,
-): FlappyTrainerNetwork[]
+): FlappyTrainerNetwork | undefined
 ```
 
-Returns top genomes ordered by current provisional score.
+Resolves the best genome by current score.
+
+This helper is intentionally tiny, but it gives the rest of the trainer a
+single vocabulary term for "the current best genome under whatever score shelf
+is currently populated."
 
 Parameters:
 - `population` - - Current trainer population.
-- `provisionalScoresByGenome` - - Optional map of staged provisional scores.
-- `targetCount` - - Maximum number of genomes to return.
 
-Returns: Highest-scoring genomes in descending score order.
+Returns: Highest-scoring genome or `undefined` when population is empty.
 
-### resolveBestGenomeByScore
+### selectTopGenomesByScore
 
 ```ts
-resolveBestGenomeByScore(
+selectTopGenomesByScore(
   population: readonly FlappyTrainerNetwork[],
-): FlappyTrainerNetwork | undefined
+  provisionalScoresByGenome: ReadonlyMap<FlappyTrainerNetwork, number>,
+  targetCount: number,
+): FlappyTrainerNetwork[]
 ```
 
-Resolves the best genome by current score.
-
-This helper is intentionally tiny, but it gives the rest of the trainer a
-single vocabulary term for "the current best genome under whatever score shelf
-is currently populated."
+Returns top genomes ordered by current provisional score.
 
 Parameters:
 - `population` - - Current trainer population.
+- `provisionalScoresByGenome` - - Optional map of staged provisional scores.
+- `targetCount` - - Maximum number of genomes to return.
 
-Returns: Highest-scoring genome or `undefined` when population is empty.
+Returns: Highest-scoring genomes in descending score order.
 
 ## trainer/trainer.evaluation-plan.utils.ts
 
@@ -1232,50 +1232,46 @@ flowchart TB
     ReevalOptions --> Plan
 ```
 
-### resolveGenerationEvaluationPlan
+### buildSharedSeedBatch
 
 ```ts
-resolveGenerationEvaluationPlan(
+buildSharedSeedBatch(
   generationIndex: number,
-): FlappyGenerationEvaluationPlan
+  stageSalt: number,
+  seedCount: number,
+): number[]
 ```
 
-Resolves all per-generation evaluation controls.
+Build deterministic shared seeds for one generation stage.
 
-Think of this as the trainer's "generation contract": the rest of the system
-can ask for one object and receive a fully prepared set of seeds, rollout
-options, and annealed mutation values.
+Shared seeds are what make same-generation comparisons fair: genomes face the
+same sampled worlds instead of winning because they happened to get a kinder
+random rollout.
 
 Parameters:
 - `generationIndex` - - Zero-based generation index.
+- `stageSalt` - - Constant stage-specific salt.
+- `seedCount` - - Number of seeds to produce.
 
-Returns: Full staged evaluation plan for the generation.
+Returns: Deterministic shared seed list.
 
-### resolveMutationSchedule
+### createFullRolloutOptions
 
 ```ts
-resolveMutationSchedule(
-  generationIndex: number,
-): FlappyMutationSchedule
+createFullRolloutOptions(
+  difficultyScale: number,
+): FlappyRolloutOptions
 ```
 
-Resolve a smooth mutation annealing schedule.
+Builds full-stage rollout options.
 
-Early generations mutate more aggressively so the population can search the
-space broadly. Later generations cool down so the trainer can refine useful
-structures rather than constantly replacing them.
+This stage gives stronger candidates a longer, stricter test so the trainer
+can refine the leaderboard before committing to expensive reevaluation.
 
 Parameters:
-- `generationIndex` - - Zero-based generation index.
-
-Returns: Mutation rate and mutation amount for this generation.
-
-### FlappyMutationSchedule
-
-Mutation schedule used by generation planning and outer loop logging.
+- `difficultyScale` - - Difficulty scale for this generation.
 
-These two numbers are treated as a single policy decision because the trainer
-cools both the frequency and the size of mutations together.
+Returns: Full stage rollout options.
 
 ### createQuickRolloutOptions
 
@@ -1296,41 +1292,50 @@ Parameters:
 
 Returns: Quick stage rollout options.
 
-### createFullRolloutOptions
+### createReevaluationRolloutOptions
 
 ```ts
-createFullRolloutOptions(
+createReevaluationRolloutOptions(
   difficultyScale: number,
 ): FlappyRolloutOptions
 ```
 
-Builds full-stage rollout options.
+Builds high-confidence reevaluation rollout options.
 
-This stage gives stronger candidates a longer, stricter test so the trainer
-can refine the leaderboard before committing to expensive reevaluation.
+Reevaluation deliberately disables early termination so the strongest
+candidates are judged on a more faithful, less shortcut-heavy comparison.
 
 Parameters:
 - `difficultyScale` - - Difficulty scale for this generation.
 
-Returns: Full stage rollout options.
+Returns: Reevaluation stage rollout options.
 
-### createReevaluationRolloutOptions
+### FlappyMutationSchedule
+
+Mutation schedule used by generation planning and outer loop logging.
+
+These two numbers are treated as a single policy decision because the trainer
+cools both the frequency and the size of mutations together.
+
+### mixSeed
 
 ```ts
-createReevaluationRolloutOptions(
-  difficultyScale: number,
-): FlappyRolloutOptions
+mixSeed(
+  generationIndex: number,
+  stageSalt: number,
+): number
 ```
 
-Builds high-confidence reevaluation rollout options.
+Mixes generation and stage salts into a deterministic uint32 RNG seed.
 
-Reevaluation deliberately disables early termination so the strongest
-candidates are judged on a more faithful, less shortcut-heavy comparison.
+The small mixing pipeline spreads nearby generation numbers apart so adjacent
+stages and generations do not accidentally reuse overly correlated seed sets.
 
 Parameters:
-- `difficultyScale` - - Difficulty scale for this generation.
+- `generationIndex` - - Current generation index.
+- `stageSalt` - - Stage-specific salt.
 
-Returns: Reevaluation stage rollout options.
+Returns: Mixed uint32 seed.
 
 ### resolveCurriculumDifficultyScale
 
@@ -1350,45 +1355,40 @@ Parameters:
 
 Returns: Difficulty scale in [0, 1].
 
-### buildSharedSeedBatch
+### resolveGenerationEvaluationPlan
 
 ```ts
-buildSharedSeedBatch(
+resolveGenerationEvaluationPlan(
   generationIndex: number,
-  stageSalt: number,
-  seedCount: number,
-): number[]
+): FlappyGenerationEvaluationPlan
 ```
 
-Build deterministic shared seeds for one generation stage.
+Resolves all per-generation evaluation controls.
 
-Shared seeds are what make same-generation comparisons fair: genomes face the
-same sampled worlds instead of winning because they happened to get a kinder
-random rollout.
+Think of this as the trainer's "generation contract": the rest of the system
+can ask for one object and receive a fully prepared set of seeds, rollout
+options, and annealed mutation values.
 
 Parameters:
 - `generationIndex` - - Zero-based generation index.
-- `stageSalt` - - Constant stage-specific salt.
-- `seedCount` - - Number of seeds to produce.
 
-Returns: Deterministic shared seed list.
+Returns: Full staged evaluation plan for the generation.
 
-### mixSeed
+### resolveMutationSchedule
 
 ```ts
-mixSeed(
+resolveMutationSchedule(
   generationIndex: number,
-  stageSalt: number,
-): number
+): FlappyMutationSchedule
 ```
 
-Mixes generation and stage salts into a deterministic uint32 RNG seed.
+Resolve a smooth mutation annealing schedule.
 
-The small mixing pipeline spreads nearby generation numbers apart so adjacent
-stages and generations do not accidentally reuse overly correlated seed sets.
+Early generations mutate more aggressively so the population can search the
+space broadly. Later generations cool down so the trainer can refine useful
+structures rather than constantly replacing them.
 
 Parameters:
-- `generationIndex` - - Current generation index.
-- `stageSalt` - - Stage-specific salt.
+- `generationIndex` - - Zero-based generation index.
 
-Returns: Mixed uint32 seed.
+Returns: Mutation rate and mutation amount for this generation.