@reicek/neataptic-ts 0.1.21 → 0.1.23

package/test/examples/flappy_bird/trainer/evaluation/trainer.evaluation.service.utils.ts

@@ -0,0 +1,182 @@
+import type { FlappySeedBatchEvaluation } from '../../flappyEvaluation';
+import {
+  FLAPPY_TRAINER_FRAME_PRIMARY_BASE_SCORE,
+  FLAPPY_TRAINER_FRAME_PRIMARY_PIPE_WEIGHT,
+  FLAPPY_TRAINER_FRAME_PRIMARY_SURVIVAL_WEIGHT,
+  FLAPPY_TRAINER_FRAME_STABILITY_STDDEV_WEIGHT,
+  FLAPPY_TRAINER_PIPE_FALLBACK_PIPE_WEIGHT,
+  FLAPPY_TRAINER_PIPE_FILTER_TOLERANCE,
+} from '../trainer.constants';
+import type { FlappyTrainerNetwork } from '../trainer.types';
+import {
+  FLAPPY_TRAINER_MIN_PIPE_PROGRESS,
+  FLAPPY_TRAINER_NEGATIVE_INFINITY_SCORE,
+} from './trainer.evaluation.service.constants';
+import type { PopulationAggregateScoringContext } from './trainer.evaluation.service.types';
+
+/**
+ * Assigns refreshed frame-primary scores to the current population.
+ *
+ * Educational note:
+ * The trainer does not rank genomes purely by one raw metric. It combines pipe
+ * progress, survival, and stability into a provisional score so early-stage
+ * selection remains robust when several genomes are close in quality.
+ *
+ * @param population - Current population.
+ * @param aggregateByGenome - Aggregate cache keyed by genome.
+ * @param provisionalScoresByGenome - Mutable provisional score map.
+ * @returns Nothing.
+ */
+export function assignFramePrimaryScores(
+  population: readonly FlappyTrainerNetwork[],
+  aggregateByGenome: ReadonlyMap<
+    FlappyTrainerNetwork,
+    FlappySeedBatchEvaluation
+  >,
+  provisionalScoresByGenome: Map<FlappyTrainerNetwork, number>,
+): void {
+  // Step 1: Resolve the aggregate scoring context shared by all genomes.
+  const populationAggregateScoringContext =
+    resolvePopulationAggregateScoringContext(population, aggregateByGenome);
+
+  // Step 2: Score each genome using the refreshed aggregate context.
+  for (const genome of population) {
+    const aggregate = aggregateByGenome.get(genome);
+    if (!aggregate) {
+      provisionalScoresByGenome.set(
+        genome,
+        FLAPPY_TRAINER_NEGATIVE_INFINITY_SCORE,
+      );
+      continue;
+    }
+
+    provisionalScoresByGenome.set(
+      genome,
+      scoreAggregateFramePrimary(
+        aggregate,
+        populationAggregateScoringContext.maximumMeanPipesPassed,
+      ),
+    );
+  }
+}
+
+/**
+ * Collects all currently available aggregate values.
+ *
+ * Only genomes with completed aggregate results are included. That lets the
+ * scoring helpers distinguish between genuinely weak genomes and genomes that
+ * simply have not yet reached a later stage.
+ *
+ * @param population - Current population.
+ * @param aggregateByGenome - Aggregate cache keyed by genome.
+ * @returns Collected aggregate values.
+ */
+export function collectAggregateValues(
+  population: readonly FlappyTrainerNetwork[],
+  aggregateByGenome: ReadonlyMap<
+    FlappyTrainerNetwork,
+    FlappySeedBatchEvaluation
+  >,
+): FlappySeedBatchEvaluation[] {
+  const aggregateValues: FlappySeedBatchEvaluation[] = [];
+
+  // Step 1: Include only genomes that already have an aggregate in the cache.
+  for (const genome of population) {
+    const aggregate = aggregateByGenome.get(genome);
+    if (aggregate) {
+      aggregateValues.push(aggregate);
+    }
+  }
+
+  return aggregateValues;
+}
+
+/**
+ * Resolves the leading mean pipe-progress value across available aggregates.
+ *
+ * Mean pipe progress acts as the leading indicator for the frame-primary score:
+ * if a genome is far behind the current pipe leader, it falls back to a simpler
+ * progress-first score.
+ *
+ * @param aggregateValues - Aggregate values currently available.
+ * @returns Highest mean pipe-progress value.
+ */
+export function resolveMaximumMeanPipesPassed(
+  aggregateValues: readonly FlappySeedBatchEvaluation[],
+): number {
+  // Step 1: Resolve the leading mean pipe-progress value across all aggregates.
+  return aggregateValues.reduce(
+    (bestPipeProgress, aggregate) =>
+      Math.max(bestPipeProgress, aggregate.meanPipesPassed),
+    FLAPPY_TRAINER_MIN_PIPE_PROGRESS,
+  );
+}
+
+/**
+ * Scores one aggregate using the frame-primary heuristic.
+ *
+ * Educational note:
+ * The heuristic intentionally mixes progress and stability. A genome that passes
+ * many pipes but has wildly inconsistent fitness across seeds is treated more
+ * cautiously than a similarly strong but steadier genome.
+ *
+ * @param aggregate - Aggregate evaluation result.
+ * @param maximumMeanPipesPassed - Best mean pipe progress in the population.
+ * @returns Provisional score.
+ */
+export function scoreAggregateFramePrimary(
+  aggregate: FlappySeedBatchEvaluation,
+  maximumMeanPipesPassed: number,
+): number {
+  // Step 1: Resolve the stability penalty and pipe-progress eligibility filter.
+  const frameStabilityPenalty =
+    aggregate.fitnessStdDev * FLAPPY_TRAINER_FRAME_STABILITY_STDDEV_WEIGHT;
+  const passesPipeFilter =
+    aggregate.meanPipesPassed >=
+    maximumMeanPipesPassed - FLAPPY_TRAINER_PIPE_FILTER_TOLERANCE;
+
+  // Step 2: Use the full frame-primary score when the genome remains near the pipe leader.
+  if (passesPipeFilter) {
+    return (
+      FLAPPY_TRAINER_FRAME_PRIMARY_BASE_SCORE +
+      aggregate.meanFramesSurvived *
+        FLAPPY_TRAINER_FRAME_PRIMARY_SURVIVAL_WEIGHT +
+      aggregate.meanPipesPassed * FLAPPY_TRAINER_FRAME_PRIMARY_PIPE_WEIGHT -
+      frameStabilityPenalty
+    );
+  }
+
+  // Step 3: Fall back to the pipe-progress-first score for trailing genomes.
+  return (
+    aggregate.meanPipesPassed * FLAPPY_TRAINER_PIPE_FALLBACK_PIPE_WEIGHT +
+    aggregate.meanFramesSurvived -
+    frameStabilityPenalty
+  );
+}
+
+/**
+ * Resolves the aggregate scoring context used by frame-primary scoring.
+ *
+ * This precomputation step keeps the per-genome scoring loop lean and avoids
+ * recomputing population-wide maxima for every genome.
+ *
+ * @param population - Current population.
+ * @param aggregateByGenome - Aggregate cache keyed by genome.
+ * @returns Aggregate scoring context.
+ */
+function resolvePopulationAggregateScoringContext(
+  population: readonly FlappyTrainerNetwork[],
+  aggregateByGenome: ReadonlyMap<
+    FlappyTrainerNetwork,
+    FlappySeedBatchEvaluation
+  >,
+): PopulationAggregateScoringContext {
+  // Step 1: Collect the currently available aggregate values.
+  const aggregateValues = collectAggregateValues(population, aggregateByGenome);
+
+  // Step 2: Resolve the highest mean pipe-progress value in the population.
+  return {
+    aggregateValues,
+    maximumMeanPipesPassed: resolveMaximumMeanPipesPassed(aggregateValues),
+  };
+}

package/test/examples/flappy_bird/trainer/trainer.evaluation.service.ts

@@ -0,0 +1,13 @@
+/**
+ * Trainer evaluation compatibility facade.
+ *
+ * The staged population-evaluation implementation now lives in the dedicated
+ * `trainer/evaluation/` submodule so orchestration, scoring helpers, internal
+ * contracts, and sub-services can evolve behind a focused boundary.
+ */
+export {
+  commitPopulationScores,
+  evaluatePopulationFullStage,
+  evaluatePopulationQuickStage,
+  evaluatePopulationReevaluationStage,
+} from './evaluation/trainer.evaluation.service';

package/test/examples/flappy_bird/trainer/trainer.fitness.service.ts

@@ -7,7 +7,14 @@ import type {
   FlappyTrainerRuntimeState,
 } from './trainer.types';
 
-/** Callback dependencies required by the trainer fitness orchestration service. */
+/**
+ * Callback dependencies required by the trainer fitness orchestration service.
+ *
+ * Educational note:
+ * The trainer evaluates whole populations in staged passes. This dependency bag
+ * keeps the top-level service declarative and makes each stage independently
+ * replaceable without rewriting the orchestration logic.
+ */
 export interface TrainerFitnessServiceDependencies {
   resolveGenerationEvaluationPlan: (
     generationIndex: number,
@@ -49,10 +56,16 @@ export interface TrainerFitnessServiceDependencies {
 /**
  * Attaches population-level staged evaluator to the NEAT controller.
  *
+ * This is the moment where the generic NEAT controller becomes a
+ * Flappy-specific trainer: a plain controller receives the staged population
+ * evaluator that understands shared-seed screening, full-pass scoring, and
+ * reevaluation.
+ *
  * @param neatController - Trainer NEAT controller.
  * @param trainerRuntimeState - Mutable trainer runtime state.
  * @param elitismCount - Number of elite genomes preserved each generation.
  * @param dependencies - Pure/impure helper callbacks used by the evaluator.
+ * @returns Nothing.
  */
 export function attachPopulationFitnessEvaluator(
   neatController: FlappyTrainerNeatController,
@@ -71,6 +84,15 @@ export function attachPopulationFitnessEvaluator(
 /**
  * Creates the asynchronous population fitness evaluator.
  *
+ * Educational note:
+ * The trainer uses staged evaluation to reduce luck. Genomes are first screened
+ * quickly, then the most promising ones receive more expensive evaluation, and
+ * the best candidates are reevaluated again for robustness.
+ *
+ * That strategy is closer to tournament design than to naive one-shot scoring:
+ * the same generation budget is spent unevenly so weak genomes are filtered out
+ * early and strong genomes are compared more carefully.
+ *
  * @param neatController - Trainer NEAT controller.
  * @param trainerRuntimeState - Mutable trainer runtime state.
  * @param elitismCount - Number of elite genomes preserved each generation.

package/test/examples/flappy_bird/trainer/trainer.loop.service.ts

@@ -11,7 +11,13 @@ import type {
   FlappyTrainerRuntimeState,
 } from './trainer.types';
 
-/** Callback signature for one-line generation logging. */
+/**
+ * Callback signature for one-line generation logging.
+ *
+ * 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.
+ */
 export type LogGenerationSummaryCallback = (
   generationLabel: number,
   mutationSchedule: FlappyMutationSchedule,
@@ -23,9 +29,15 @@ export type LogGenerationSummaryCallback = (
 /**
  * Runs the outer evolution loop until runtime stop is requested.
  *
+ * 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.
+ *
  * @param neatController - Trainer NEAT controller.
  * @param trainerRuntimeState - Mutable trainer runtime state.
  * @param logGenerationSummary - Callback that emits compact generation logs.
+ * @returns Promise resolved when the trainer has been stopped.
  */
 export async function runTrainerEvolutionLoop(
   neatController: FlappyTrainerNeatController,
@@ -55,8 +67,12 @@ export async function runTrainerEvolutionLoop(
 /**
  * Applies mutation schedule values to the NEAT controller options.
  *
+ * The schedule is resolved outside this helper so the loop can read as a clean
+ * "resolve -> apply -> evolve -> report" flow.
+ *
  * @param neatController - Trainer NEAT controller.
  * @param mutationSchedule - Mutation schedule for current generation.
+ * @returns Nothing.
  */
 function applyMutationSchedule(
   neatController: FlappyTrainerNeatController,

package/test/examples/flappy_bird/trainer/trainer.report.service.services.ts

@@ -0,0 +1,181 @@
+import {
+  evaluateFlappyFitnessAcrossSeeds,
+  rolloutEpisode,
+  type FlappyRolloutOptions,
+  type FlappySeedBatchEvaluation,
+} from '../flappyEvaluation';
+import {
+  FLAPPY_TRAINER_DUMMY_FLAP_OUTPUT,
+  FLAPPY_TRAINER_DUMMY_NETWORK_ID,
+  FLAPPY_TRAINER_DUMMY_NO_FLAP_OUTPUT,
+} from './trainer.constants';
+import type { FlappyTrainerNetwork } from './trainer.types';
+
+/**
+ * Aggregate and representative rollout resolved for the best genome.
+ *
+ * Keeping these values together lets the report facade stay focused on
+ * orchestration while this helper module owns cache fallback behavior.
+ */
+export interface ResolvedBestGenerationDetails {
+  bestAggregate: FlappySeedBatchEvaluation;
+  bestEpisode: ReturnType<typeof rolloutEpisode>;
+}
+
+/**
+ * Collects only finite scores from the current population.
+ *
+ * Unevaluated or invalid scores are intentionally skipped so percentile and
+ * standard deviation calculations operate on stable numeric inputs only.
+ *
+ * @param population - Current population.
+ * @returns Finite scores in population order.
+ * @example
+ * ```ts
+ * const scores = collectFiniteGenomeScores(population);
+ * ```
+ */
+export function collectFiniteGenomeScores(
+  population: readonly FlappyTrainerNetwork[],
+): number[] {
+  const finiteScores: number[] = [];
+
+  for (const genome of population) {
+    const genomeScore = genome.score ?? Number.NEGATIVE_INFINITY;
+    if (Number.isFinite(genomeScore)) {
+      finiteScores.push(genomeScore);
+    }
+  }
+
+  return finiteScores;
+}
+
+/**
+ * Resolves cached or fallback best-of-generation details for reporting.
+ *
+ * The report layer needs both aggregate seed statistics and one representative
+ * episode. This helper centralizes the fallback rules so the service facade can
+ * remain a thin orchestration layer.
+ *
+ * @param population - Current population.
+ * @param bestGenome - Genome selected as generation best.
+ * @param aggregateByGenome - Cached aggregate evaluations keyed by genome.
+ * @param fallbackSeeds - Seeds used when the aggregate must be recomputed.
+ * @param fallbackRolloutOptions - Rollout options for fallback evaluation.
+ * @returns Aggregate metrics and a representative best-genome episode.
+ * @example
+ * ```ts
+ * const { bestAggregate, bestEpisode } = resolveBestGenerationDetails(
+ *   population,
+ *   bestGenome,
+ *   aggregateByGenome,
+ *   reevaluationSeeds,
+ *   reevaluationRolloutOptions,
+ * );
+ * ```
+ */
+export function resolveBestGenerationDetails(
+  population: readonly FlappyTrainerNetwork[],
+  bestGenome: FlappyTrainerNetwork | undefined,
+  aggregateByGenome: ReadonlyMap<
+    FlappyTrainerNetwork,
+    FlappySeedBatchEvaluation
+  >,
+  fallbackSeeds: readonly number[],
+  fallbackRolloutOptions: FlappyRolloutOptions,
+): ResolvedBestGenerationDetails {
+  return {
+    bestAggregate: resolveBestAggregate(
+      population,
+      bestGenome,
+      aggregateByGenome,
+      fallbackSeeds,
+      fallbackRolloutOptions,
+    ),
+    bestEpisode: resolveBestEpisode(
+      population,
+      bestGenome,
+      fallbackSeeds,
+      fallbackRolloutOptions,
+    ),
+  };
+}
+
+function resolveBestAggregate(
+  population: readonly FlappyTrainerNetwork[],
+  bestGenome: FlappyTrainerNetwork | undefined,
+  aggregateByGenome: ReadonlyMap<
+    FlappyTrainerNetwork,
+    FlappySeedBatchEvaluation
+  >,
+  fallbackSeeds: readonly number[],
+  fallbackRolloutOptions: FlappyRolloutOptions,
+): FlappySeedBatchEvaluation {
+  const fallbackGenome = resolveFallbackGenome(population, bestGenome);
+  if (!fallbackGenome) {
+    return buildEmptySeedBatchEvaluation();
+  }
+
+  const cachedAggregate = aggregateByGenome.get(fallbackGenome);
+  if (cachedAggregate) {
+    return cachedAggregate;
+  }
+
+  return evaluateFlappyFitnessAcrossSeeds(
+    fallbackGenome,
+    fallbackSeeds,
+    fallbackRolloutOptions,
+  );
+}
+
+function resolveBestEpisode(
+  population: readonly FlappyTrainerNetwork[],
+  bestGenome: FlappyTrainerNetwork | undefined,
+  fallbackSeeds: readonly number[],
+  fallbackRolloutOptions: FlappyRolloutOptions,
+): ReturnType<typeof rolloutEpisode> {
+  const fallbackGenome = resolveFallbackGenome(population, bestGenome);
+  if (!fallbackGenome) {
+    return rolloutEpisode(resolveDummyNetwork(), fallbackRolloutOptions);
+  }
+
+  const episodeSeed = fallbackSeeds[0];
+  return rolloutEpisode(fallbackGenome, {
+    ...fallbackRolloutOptions,
+    seed: episodeSeed,
+  });
+}
+
+function resolveFallbackGenome(
+  population: readonly FlappyTrainerNetwork[],
+  bestGenome: FlappyTrainerNetwork | undefined,
+): FlappyTrainerNetwork | undefined {
+  return bestGenome ?? population[0];
+}
+
+function buildEmptySeedBatchEvaluation(): FlappySeedBatchEvaluation {
+  return {
+    seedCount: 0,
+    meanFitness: 0,
+    medianFitness: 0,
+    p90Fitness: 0,
+    fitnessStdDev: 0,
+    robustFitness: 0,
+    meanPipesPassed: 0,
+    meanFramesSurvived: 0,
+  };
+}
+
+function resolveDummyNetwork(): FlappyTrainerNetwork {
+  return {
+    activate: activateWithoutFlap,
+    _id: FLAPPY_TRAINER_DUMMY_NETWORK_ID,
+  };
+}
+
+function activateWithoutFlap(): number[] {
+  return [
+    FLAPPY_TRAINER_DUMMY_NO_FLAP_OUTPUT,
+    FLAPPY_TRAINER_DUMMY_FLAP_OUTPUT,
+  ];
+}

package/test/examples/flappy_bird/trainer/trainer.report.service.ts

@@ -0,0 +1,136 @@
+import {
+  rolloutEpisode,
+  type FlappySeedBatchEvaluation,
+} from '../flappyEvaluation';
+import {
+  FLAPPY_TRAINER_LOG_PARTS_DELIMITER,
+  FLAPPY_TRAINER_SCORE_MEDIAN_PERCENTILE,
+  FLAPPY_TRAINER_SCORE_P90_PERCENTILE,
+} from './trainer.constants';
+import type { FlappyMutationSchedule } from './trainer.evaluation-plan.utils';
+import {
+  collectFiniteGenomeScores,
+  resolveBestGenerationDetails,
+} from './trainer.report.service.services';
+import { buildGenerationLogParts } from './trainer.reporting.utils';
+import { resolveBestGenomeByScore } from './trainer.selection.utils';
+import {
+  computeMean,
+  computePercentile,
+  computePopulationStandardDeviation,
+} from '../flappy.simulation.shared.utils';
+import type {
+  FlappyGenerationEvaluationPlan,
+  FlappyGenerationReport,
+  FlappyTrainerNetwork,
+} from './trainer.types';
+
+/**
+ * Builds a compact report for the current generation.
+ *
+ * Educational note:
+ * The trainer logs more than a single best score because single-number progress
+ * can hide instability. Mean, median, $p90$, and standard deviation reveal
+ * whether a generation is broadly improving or whether one lucky genome is
+ * masking a weak population.
+ *
+ * @param population - Current population.
+ * @param aggregateByGenome - Aggregate evaluation results keyed by genome.
+ * @param generationEvaluationPlan - Per-generation staged evaluation plan.
+ * @returns Aggregated generation report.
+ */
+export function buildGenerationReport(
+  population: readonly FlappyTrainerNetwork[],
+  aggregateByGenome: ReadonlyMap<
+    FlappyTrainerNetwork,
+    FlappySeedBatchEvaluation
+  >,
+  generationEvaluationPlan: FlappyGenerationEvaluationPlan,
+): FlappyGenerationReport {
+  // Step 1: Collect stable numeric inputs for distribution statistics.
+  const finalScores = collectFiniteGenomeScores(population);
+  const scoreMean = computeMean(finalScores);
+  const scoreStdDev = computePopulationStandardDeviation(
+    finalScores,
+    scoreMean,
+  );
+
+  // Step 2: Resolve best-genome derived metrics through the report helper boundary.
+  const bestGenome = resolveBestGenomeByScore(population);
+  const { bestAggregate, bestEpisode } = resolveBestGenerationDetails(
+    population,
+    bestGenome,
+    aggregateByGenome,
+    generationEvaluationPlan.reevaluationSeeds,
+    generationEvaluationPlan.reevaluationRolloutOptions,
+  );
+
+  // Step 3: Fold the resolved metrics into the compact generation report.
+  return {
+    generationIndex: generationEvaluationPlan.generationIndex,
+    difficultyScale: generationEvaluationPlan.difficultyScale,
+    mutationRate: generationEvaluationPlan.mutationRate,
+    mutationAmount: generationEvaluationPlan.mutationAmount,
+    quickSeedCount: generationEvaluationPlan.quickSeeds.length,
+    fullSeedCount: generationEvaluationPlan.fullSeeds.length,
+    reevaluationSeedCount: generationEvaluationPlan.reevaluationSeeds.length,
+    evaluatedPopulationSize: population.length,
+    scoreMean,
+    scoreMedian: computePercentile(
+      finalScores,
+      FLAPPY_TRAINER_SCORE_MEDIAN_PERCENTILE,
+    ),
+    scoreP90: computePercentile(
+      finalScores,
+      FLAPPY_TRAINER_SCORE_P90_PERCENTILE,
+    ),
+    scoreStdDev,
+    bestRobustFitness: bestGenome?.score ?? Number.NaN,
+    bestMeanFitness: bestAggregate.meanFitness,
+    bestPipesPassed: bestEpisode.pipesPassed,
+    bestFramesSurvived: bestEpisode.framesSurvived,
+  };
+}
+
+/**
+ * Emits one compact generation log line.
+ *
+ * The emitted line is designed for long-running terminal sessions: dense enough
+ * to be useful, but stable enough that humans can visually scan progress over
+ * hundreds of generations.
+ *
+ * @param generationLabel - Current generation label.
+ * @param mutationSchedule - Active mutation schedule.
+ * @param report - Optional aggregated generation report.
+ * @param fittestGenome - Fittest genome returned by the NEAT controller.
+ * @param fallbackEpisode - Fallback representative rollout episode.
+ * @returns Nothing.
+ */
+export function logGenerationSummary(
+  generationLabel: number,
+  mutationSchedule: FlappyMutationSchedule,
+  report: FlappyGenerationReport | undefined,
+  fittestGenome: FlappyTrainerNetwork,
+  fallbackEpisode: ReturnType<typeof rolloutEpisode>,
+): void {
+  const bestFitness =
+    report?.bestRobustFitness ??
+    (fittestGenome.score as number) ??
+    fallbackEpisode.fitness;
+  const bestPipesPassed =
+    report?.bestPipesPassed ?? fallbackEpisode.pipesPassed;
+  const bestFramesSurvived =
+    report?.bestFramesSurvived ?? fallbackEpisode.framesSurvived;
+
+  const logParts = buildGenerationLogParts(
+    generationLabel,
+    bestFitness,
+    bestPipesPassed,
+    bestFramesSurvived,
+    report,
+    mutationSchedule,
+  );
+
+  // eslint-disable-next-line no-console
+  console.log(logParts.join(FLAPPY_TRAINER_LOG_PARTS_DELIMITER));
+}

package/test/examples/flappy_bird/trainer/trainer.selection.utils.ts

@@ -0,0 +1,89 @@
+import type { FlappyTrainerNetwork, ScoredGenomeEntry } from './trainer.types';
+
+/**
+ * Returns top genomes ordered by current provisional score.
+ *
+ * @param population - Current trainer population.
+ * @param provisionalScoresByGenome - Optional map of staged provisional scores.
+ * @param targetCount - Maximum number of genomes to return.
+ * @returns Highest-scoring genomes in descending score order.
+ */
+export function selectTopGenomesByScore(
+  population: readonly FlappyTrainerNetwork[],
+  provisionalScoresByGenome: ReadonlyMap<FlappyTrainerNetwork, number>,
+  targetCount: number,
+): FlappyTrainerNetwork[] {
+  const scoredEntries = buildScoredGenomeEntries(
+    population,
+    provisionalScoresByGenome,
+  );
+
+  scoredEntries.sort(compareScoredGenomeEntriesDescending);
+
+  const selectedGenomes: FlappyTrainerNetwork[] = [];
+  const maximumSelectionCount = Math.max(
+    0,
+    Math.min(targetCount, scoredEntries.length),
+  );
+
+  let selectedIndex = 0;
+  while (selectedIndex < maximumSelectionCount) {
+    const scoredEntry = scoredEntries[selectedIndex];
+    if (scoredEntry) {
+      selectedGenomes.push(scoredEntry.genome);
+    }
+    selectedIndex += 1;
+  }
+
+  return selectedGenomes;
+}
+
+/**
+ * Resolves the best genome by current score.
+ *
+ * @param population - Current trainer population.
+ * @returns Highest-scoring genome or `undefined` when population is empty.
+ */
+export function resolveBestGenomeByScore(
+  population: readonly FlappyTrainerNetwork[],
+): FlappyTrainerNetwork | undefined {
+  const scoredGenomes = buildScoredGenomeEntries(population, undefined);
+  scoredGenomes.sort(compareScoredGenomeEntriesDescending);
+  return scoredGenomes[0]?.genome;
+}
+
+function buildScoredGenomeEntries(
+  population: readonly FlappyTrainerNetwork[],
+  provisionalScoresByGenome:
+    | ReadonlyMap<FlappyTrainerNetwork, number>
+    | undefined,
+): ScoredGenomeEntry[] {
+  const scoredEntries: ScoredGenomeEntry[] = [];
+
+  for (const genome of population) {
+    const score = resolveGenomeScore(genome, provisionalScoresByGenome);
+    scoredEntries.push({ genome, score });
+  }
+
+  return scoredEntries;
+}
+
+function resolveGenomeScore(
+  genome: FlappyTrainerNetwork,
+  provisionalScoresByGenome:
+    | ReadonlyMap<FlappyTrainerNetwork, number>
+    | undefined,
+): number {
+  if (provisionalScoresByGenome) {
+    return provisionalScoresByGenome.get(genome) ?? Number.NEGATIVE_INFINITY;
+  }
+
+  return genome.score ?? Number.NEGATIVE_INFINITY;
+}
+
+function compareScoredGenomeEntriesDescending(
+  leftEntry: ScoredGenomeEntry,
+  rightEntry: ScoredGenomeEntry,
+): number {
+  return rightEntry.score - leftEntry.score;
+}