@reicek/neataptic-ts 0.1.21 → 0.1.22

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

@@ -0,0 +1,199 @@
+# trainer/evaluation
+
+## trainer/evaluation/trainer.evaluation.service.types.ts
+
+### PopulationAggregateScoringContext
+
+Aggregate scoring context shared while computing frame-primary scores.
+
+### PopulationStageEvaluationRequest
+
+Candidate-stage request used by the staged population evaluator.
+
+Keeping this internal contract narrow lets the orchestration service choose
+a candidate budget without coupling the execution helpers to generation-plan
+details.
+
+## trainer/evaluation/trainer.evaluation.service.ts
+
+### commitPopulationScores
+
+`(population: readonly import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork[], provisionalScoresByGenome: ReadonlyMap<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, number>) => void`
+
+Commits provisional scores to genome score fields.
+
+Parameters:
+
+- `population` - - Current population.
+- `provisionalScoresByGenome` - - Final provisional score map.
+
+Returns: Nothing.
+
+### evaluatePopulationFullStage
+
+`(population: readonly import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork[], generationEvaluationPlan: import("test/examples/flappy_bird/trainer/trainer.types").FlappyGenerationEvaluationPlan, aggregateByGenome: Map<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation>, provisionalScoresByGenome: Map<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, number>, elitismCount: number) => void`
+
+Executes the full evaluation stage over the top provisional candidates.
+
+Parameters:
+
+- `population` - - Current population.
+- `generationEvaluationPlan` - - Per-generation staged evaluation plan.
+- `aggregateByGenome` - - Mutable aggregate cache keyed by genome.
+- `provisionalScoresByGenome` - - Mutable provisional score map.
+- `elitismCount` - - Configured elitism count.
+
+Returns: Nothing.
+
+### evaluatePopulationQuickStage
+
+`(population: readonly import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork[], generationEvaluationPlan: import("test/examples/flappy_bird/trainer/trainer.types").FlappyGenerationEvaluationPlan, aggregateByGenome: Map<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation>, provisionalScoresByGenome: Map<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, number>) => void`
+
+Executes the quick evaluation stage over the full population.
+
+Parameters:
+
+- `population` - - Current population.
+- `generationEvaluationPlan` - - Per-generation staged evaluation plan.
+- `aggregateByGenome` - - Mutable aggregate cache keyed by genome.
+- `provisionalScoresByGenome` - - Mutable provisional score map.
+
+Returns: Nothing.
+
+### evaluatePopulationReevaluationStage
+
+`(population: readonly import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork[], generationEvaluationPlan: import("test/examples/flappy_bird/trainer/trainer.types").FlappyGenerationEvaluationPlan, aggregateByGenome: Map<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation>, provisionalScoresByGenome: Map<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, number>, elitismCount: number) => void`
+
+Executes the large-seed reevaluation stage over top candidates.
+
+Parameters:
+
+- `population` - - Current population.
+- `generationEvaluationPlan` - - Per-generation staged evaluation plan.
+- `aggregateByGenome` - - Mutable aggregate cache keyed by genome.
+- `provisionalScoresByGenome` - - Mutable provisional score map.
+- `elitismCount` - - Configured elitism count.
+
+Returns: Nothing.
+
+### resolveFullPassCandidateCount
+
+`(populationSize: number, elitismCount: number) => number`
+
+Resolves how many genomes should advance to the full-pass stage.
+
+Parameters:
+
+- `populationSize` - - Population size.
+- `elitismCount` - - Configured elitism count.
+
+Returns: Full-pass candidate count.
+
+## trainer/evaluation/trainer.evaluation.service.services.ts
+
+### evaluatePopulationSelectedCandidateStage
+
+`(population: readonly import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork[], populationStageEvaluationRequest: import("test/examples/flappy_bird/trainer/evaluation/trainer.evaluation.service.types").PopulationStageEvaluationRequest, aggregateByGenome: Map<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation>, provisionalScoresByGenome: Map<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, number>) => void`
+
+Evaluates a selected candidate subset for a population stage.
+
+Parameters:
+
+- `population` - - Current population.
+- `populationStageEvaluationRequest` - - Candidate-stage evaluation request.
+- `aggregateByGenome` - - Mutable aggregate cache keyed by genome.
+- `provisionalScoresByGenome` - - Mutable provisional score map.
+
+Returns: Nothing.
+
+### evaluateSpecificGenomesAcrossSeeds
+
+`(genomes: readonly import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork[], sharedSeeds: readonly number[], rolloutOptions: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyRolloutOptions, aggregateByGenome: Map<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation>) => void`
+
+Evaluates a specific genome subset across shared seeds.
+
+Parameters:
+
+- `genomes` - - Genomes selected for evaluation.
+- `sharedSeeds` - - Shared deterministic seeds.
+- `rolloutOptions` - - Rollout options for this stage.
+- `aggregateByGenome` - - Mutable aggregate cache keyed by genome.
+
+Returns: Nothing.
+
+## trainer/evaluation/trainer.evaluation.service.constants.ts
+
+### trainer.evaluation.service.constants
+
+Fallback score assigned to genomes that have not yet been evaluated.
+
+### FLAPPY_TRAINER_MIN_PIPE_PROGRESS
+
+### FLAPPY_TRAINER_NEGATIVE_INFINITY_SCORE
+
+## trainer/evaluation/trainer.evaluation.service.utils.ts
+
+### assignFramePrimaryScores
+
+`(population: readonly import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork[], aggregateByGenome: ReadonlyMap<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation>, provisionalScoresByGenome: Map<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, number>) => void`
+
+Assigns refreshed frame-primary scores to the current population.
+
+Parameters:
+
+- `population` - - Current population.
+- `aggregateByGenome` - - Aggregate cache keyed by genome.
+- `provisionalScoresByGenome` - - Mutable provisional score map.
+
+Returns: Nothing.
+
+### collectAggregateValues
+
+`(population: readonly import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork[], aggregateByGenome: ReadonlyMap<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation>) => import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation[]`
+
+Collects all currently available aggregate values.
+
+Parameters:
+
+- `population` - - Current population.
+- `aggregateByGenome` - - Aggregate cache keyed by genome.
+
+Returns: Collected aggregate values.
+
+### resolveMaximumMeanPipesPassed
+
+`(aggregateValues: readonly import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation[]) => number`
+
+Resolves the leading mean pipe-progress value across available aggregates.
+
+Parameters:
+
+- `aggregateValues` - - Aggregate values currently available.
+
+Returns: Highest mean pipe-progress value.
+
+### resolvePopulationAggregateScoringContext
+
+`(population: readonly import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork[], aggregateByGenome: ReadonlyMap<import("test/examples/flappy_bird/trainer/trainer.types").FlappyTrainerNetwork, import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation>) => import("test/examples/flappy_bird/trainer/evaluation/trainer.evaluation.service.types").PopulationAggregateScoringContext`
+
+Resolves the aggregate scoring context used by frame-primary scoring.
+
+Parameters:
+
+- `population` - - Current population.
+- `aggregateByGenome` - - Aggregate cache keyed by genome.
+
+Returns: Aggregate scoring context.
+
+### scoreAggregateFramePrimary
+
+`(aggregate: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappySeedBatchEvaluation, maximumMeanPipesPassed: number) => number`
+
+Scores one aggregate using the frame-primary heuristic.
+
+Parameters:
+
+- `aggregate` - - Aggregate evaluation result.
+- `maximumMeanPipesPassed` - - Best mean pipe progress in the population.
+
+Returns: Provisional score.

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

@@ -0,0 +1,9 @@
+/**
+ * Fallback score assigned to genomes that have not yet been evaluated.
+ */
+export const FLAPPY_TRAINER_NEGATIVE_INFINITY_SCORE = Number.NEGATIVE_INFINITY;
+
+/**
+ * Minimum pipe-progress baseline used when no aggregates are available.
+ */
+export const FLAPPY_TRAINER_MIN_PIPE_PROGRESS = 0;

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

@@ -0,0 +1,73 @@
+import {
+  evaluateFlappyFitnessAcrossSeeds,
+  type FlappyRolloutOptions,
+  type FlappySeedBatchEvaluation,
+} from '../../flappyEvaluation';
+import { selectTopGenomesByScore } from '../trainer.selection.utils';
+import type { FlappyTrainerNetwork } from '../trainer.types';
+import { assignFramePrimaryScores } from './trainer.evaluation.service.utils';
+import type { PopulationStageEvaluationRequest } from './trainer.evaluation.service.types';
+
+/**
+ * Evaluates a selected candidate subset for a population stage.
+ *
+ * @param population - Current population.
+ * @param populationStageEvaluationRequest - Candidate-stage evaluation request.
+ * @param aggregateByGenome - Mutable aggregate cache keyed by genome.
+ * @param provisionalScoresByGenome - Mutable provisional score map.
+ * @returns Nothing.
+ */
+export function evaluatePopulationSelectedCandidateStage(
+  population: readonly FlappyTrainerNetwork[],
+  populationStageEvaluationRequest: PopulationStageEvaluationRequest,
+  aggregateByGenome: Map<FlappyTrainerNetwork, FlappySeedBatchEvaluation>,
+  provisionalScoresByGenome: Map<FlappyTrainerNetwork, number>,
+): void {
+  // Step 1: Select the top-scoring candidates for the requested stage.
+  const selectedCandidates = selectTopGenomesByScore(
+    population,
+    provisionalScoresByGenome,
+    populationStageEvaluationRequest.candidateCount,
+  );
+
+  // Step 2: Evaluate the selected candidates across the stage's shared seeds.
+  evaluateSpecificGenomesAcrossSeeds(
+    selectedCandidates,
+    populationStageEvaluationRequest.sharedSeeds,
+    populationStageEvaluationRequest.rolloutOptions,
+    aggregateByGenome,
+  );
+
+  // Step 3: Refresh frame-primary scores for the full population.
+  assignFramePrimaryScores(
+    population,
+    aggregateByGenome,
+    provisionalScoresByGenome,
+  );
+}
+
+/**
+ * Evaluates a specific genome subset across shared seeds.
+ *
+ * @param genomes - Genomes selected for evaluation.
+ * @param sharedSeeds - Shared deterministic seeds.
+ * @param rolloutOptions - Rollout options for this stage.
+ * @param aggregateByGenome - Mutable aggregate cache keyed by genome.
+ * @returns Nothing.
+ */
+export function evaluateSpecificGenomesAcrossSeeds(
+  genomes: readonly FlappyTrainerNetwork[],
+  sharedSeeds: readonly number[],
+  rolloutOptions: FlappyRolloutOptions,
+  aggregateByGenome: Map<FlappyTrainerNetwork, FlappySeedBatchEvaluation>,
+): void {
+  // Step 1: Evaluate each selected genome independently across the shared batch.
+  for (const genome of genomes) {
+    const aggregate = evaluateFlappyFitnessAcrossSeeds(
+      genome,
+      sharedSeeds,
+      rolloutOptions,
+    );
+    aggregateByGenome.set(genome, aggregate);
+  }
+}

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

@@ -0,0 +1,165 @@
+import type { FlappySeedBatchEvaluation } from '../../flappyEvaluation';
+import {
+  FLAPPY_TRAINER_FULL_PASS_ELITISM_MULTIPLIER,
+  FLAPPY_TRAINER_FULL_PASS_POPULATION_FRACTION,
+  FLAPPY_TRAINER_REEVALUATION_MIN_CANDIDATE_COUNT,
+} from '../trainer.constants';
+import type {
+  FlappyGenerationEvaluationPlan,
+  FlappyTrainerNetwork,
+} from '../trainer.types';
+import { FLAPPY_TRAINER_NEGATIVE_INFINITY_SCORE } from './trainer.evaluation.service.constants';
+import {
+  evaluatePopulationSelectedCandidateStage,
+  evaluateSpecificGenomesAcrossSeeds,
+} from './trainer.evaluation.service.services';
+import { assignFramePrimaryScores } from './trainer.evaluation.service.utils';
+import type { PopulationStageEvaluationRequest } from './trainer.evaluation.service.types';
+
+/**
+ * Executes the quick evaluation stage over the full population.
+ *
+ * @param population - Current population.
+ * @param generationEvaluationPlan - Per-generation staged evaluation plan.
+ * @param aggregateByGenome - Mutable aggregate cache keyed by genome.
+ * @param provisionalScoresByGenome - Mutable provisional score map.
+ * @returns Nothing.
+ *
+ * @example
+ * ```ts
+ * evaluatePopulationQuickStage(
+ *   population,
+ *   generationEvaluationPlan,
+ *   aggregateByGenome,
+ *   provisionalScoresByGenome,
+ * );
+ * ```
+ */
+export function evaluatePopulationQuickStage(
+  population: readonly FlappyTrainerNetwork[],
+  generationEvaluationPlan: FlappyGenerationEvaluationPlan,
+  aggregateByGenome: Map<FlappyTrainerNetwork, FlappySeedBatchEvaluation>,
+  provisionalScoresByGenome: Map<FlappyTrainerNetwork, number>,
+): void {
+  evaluateSpecificGenomesAcrossSeeds(
+    population,
+    generationEvaluationPlan.quickSeeds,
+    generationEvaluationPlan.quickRolloutOptions,
+    aggregateByGenome,
+  );
+
+  assignFramePrimaryScores(
+    population,
+    aggregateByGenome,
+    provisionalScoresByGenome,
+  );
+}
+
+/**
+ * Executes the full evaluation stage over the top provisional candidates.
+ *
+ * @param population - Current population.
+ * @param generationEvaluationPlan - Per-generation staged evaluation plan.
+ * @param aggregateByGenome - Mutable aggregate cache keyed by genome.
+ * @param provisionalScoresByGenome - Mutable provisional score map.
+ * @param elitismCount - Configured elitism count.
+ * @returns Nothing.
+ */
+export function evaluatePopulationFullStage(
+  population: readonly FlappyTrainerNetwork[],
+  generationEvaluationPlan: FlappyGenerationEvaluationPlan,
+  aggregateByGenome: Map<FlappyTrainerNetwork, FlappySeedBatchEvaluation>,
+  provisionalScoresByGenome: Map<FlappyTrainerNetwork, number>,
+  elitismCount: number,
+): void {
+  // Step 1: Resolve the candidate-stage request for the full evaluation pass.
+  const populationStageEvaluationRequest = {
+    candidateCount: resolveFullPassCandidateCount(
+      population.length,
+      elitismCount,
+    ),
+    sharedSeeds: generationEvaluationPlan.fullSeeds,
+    rolloutOptions: generationEvaluationPlan.fullRolloutOptions,
+  } satisfies PopulationStageEvaluationRequest;
+
+  // Step 2: Evaluate the selected candidates and refresh provisional scores.
+  evaluatePopulationSelectedCandidateStage(
+    population,
+    populationStageEvaluationRequest,
+    aggregateByGenome,
+    provisionalScoresByGenome,
+  );
+}
+
+/**
+ * Executes the large-seed reevaluation stage over top candidates.
+ *
+ * @param population - Current population.
+ * @param generationEvaluationPlan - Per-generation staged evaluation plan.
+ * @param aggregateByGenome - Mutable aggregate cache keyed by genome.
+ * @param provisionalScoresByGenome - Mutable provisional score map.
+ * @param elitismCount - Configured elitism count.
+ * @returns Nothing.
+ */
+export function evaluatePopulationReevaluationStage(
+  population: readonly FlappyTrainerNetwork[],
+  generationEvaluationPlan: FlappyGenerationEvaluationPlan,
+  aggregateByGenome: Map<FlappyTrainerNetwork, FlappySeedBatchEvaluation>,
+  provisionalScoresByGenome: Map<FlappyTrainerNetwork, number>,
+  elitismCount: number,
+): void {
+  // Step 1: Resolve the candidate-stage request for reevaluation.
+  const populationStageEvaluationRequest = {
+    candidateCount: Math.max(
+      elitismCount,
+      FLAPPY_TRAINER_REEVALUATION_MIN_CANDIDATE_COUNT,
+    ),
+    sharedSeeds: generationEvaluationPlan.reevaluationSeeds,
+    rolloutOptions: generationEvaluationPlan.reevaluationRolloutOptions,
+  } satisfies PopulationStageEvaluationRequest;
+
+  // Step 2: Evaluate the selected candidates and refresh provisional scores.
+  evaluatePopulationSelectedCandidateStage(
+    population,
+    populationStageEvaluationRequest,
+    aggregateByGenome,
+    provisionalScoresByGenome,
+  );
+}
+
+/**
+ * Commits provisional scores to genome score fields.
+ *
+ * @param population - Current population.
+ * @param provisionalScoresByGenome - Final provisional score map.
+ * @returns Nothing.
+ */
+export function commitPopulationScores(
+  population: readonly FlappyTrainerNetwork[],
+  provisionalScoresByGenome: ReadonlyMap<FlappyTrainerNetwork, number>,
+): void {
+  // Step 1: Copy provisional scores into the mutable genome score fields.
+  for (const genome of population) {
+    genome.score =
+      provisionalScoresByGenome.get(genome) ??
+      FLAPPY_TRAINER_NEGATIVE_INFINITY_SCORE;
+  }
+}
+
+/**
+ * Resolves how many genomes should advance to the full-pass stage.
+ *
+ * @param populationSize - Population size.
+ * @param elitismCount - Configured elitism count.
+ * @returns Full-pass candidate count.
+ */
+function resolveFullPassCandidateCount(
+  populationSize: number,
+  elitismCount: number,
+): number {
+  // Step 1: Use the larger of the elitism-based and population-fraction candidate budgets.
+  return Math.max(
+    elitismCount * FLAPPY_TRAINER_FULL_PASS_ELITISM_MULTIPLIER,
+    Math.floor(populationSize * FLAPPY_TRAINER_FULL_PASS_POPULATION_FRACTION),
+  );
+}

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

@@ -0,0 +1,25 @@
+import type {
+  FlappyRolloutOptions,
+  FlappySeedBatchEvaluation,
+} from '../../flappyEvaluation';
+
+/**
+ * Candidate-stage request used by the staged population evaluator.
+ *
+ * Keeping this internal contract narrow lets the orchestration service choose
+ * a candidate budget without coupling the execution helpers to generation-plan
+ * details.
+ */
+export type PopulationStageEvaluationRequest = {
+  candidateCount: number;
+  sharedSeeds: readonly number[];
+  rolloutOptions: FlappyRolloutOptions;
+};
+
+/**
+ * Aggregate scoring context shared while computing frame-primary scores.
+ */
+export type PopulationAggregateScoringContext = {
+  aggregateValues: FlappySeedBatchEvaluation[];
+  maximumMeanPipesPassed: number;
+};

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

@@ -0,0 +1,161 @@
+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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @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';