@reicek/neataptic-ts 0.1.21 → 0.1.22

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

@@ -1,378 +1,8 @@
-import {
-  FLAPPY_CONTROL_SUBSTEPS_PER_FRAME,
-  FLAPPY_FITNESS_ALIGNMENT_WEIGHT_PER_FRAME,
-  FLAPPY_FITNESS_APPROACH_PROGRESS_WEIGHT,
-  FLAPPY_FITNESS_BONUS_PER_PIPE,
-  FLAPPY_FITNESS_CENTERING_PROGRESS_WEIGHT,
-  FLAPPY_FITNESS_CLEARANCE_WEIGHT_PER_FRAME,
-  FLAPPY_FITNESS_SECOND_GAP_ALIGNMENT_WEIGHT_PER_FRAME,
-  FLAPPY_FITNESS_STABLE_VELOCITY_WEIGHT_PER_FRAME,
-  FLAPPY_FITNESS_SURVIVAL_WEIGHT,
-  FLAPPY_FITNESS_TERMINAL_ALIGNMENT_BONUS_WEIGHT,
-  FLAPPY_FITNESS_TERMINAL_PROGRESS_BONUS_WEIGHT,
-  FLAPPY_MAX_FRAMES_PER_EPISODE,
-} from '../constants/constants';
-import {
-  FLAPPY_EVALUATION_DEFAULT_DIFFICULTY_SCALE,
-  FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_CONSECUTIVE_FRAMES,
-  FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_GRACE_FRAMES,
-  FLAPPY_EVALUATION_DEFAULT_PIPE_PROGRESS_TARGET,
-  FLAPPY_EVALUATION_DENSE_SHAPING_FRAMES_NORMALIZER,
-  FLAPPY_EVALUATION_NORMALIZED_DENSE_WEIGHT,
-  FLAPPY_EVALUATION_NORMALIZED_PROGRESS_WEIGHT,
-  FLAPPY_EVALUATION_NORMALIZED_SURVIVAL_WEIGHT,
-  FLAPPY_EVALUATION_NORMALIZED_TERMINAL_WEIGHT,
-  FLAPPY_EVALUATION_UNRECOVERABLE_ABOVE_GAP_DELTA,
-  FLAPPY_EVALUATION_UNRECOVERABLE_BELOW_GAP_DELTA,
-  FLAPPY_EVALUATION_UNRECOVERABLE_CLEARANCE_THRESHOLD,
-  FLAPPY_EVALUATION_UNRECOVERABLE_FALLING_VELOCITY,
-  FLAPPY_EVALUATION_UNRECOVERABLE_RISING_VELOCITY,
-} from './evaluation.constants';
-import {
-  createInitialFlappyState,
-  getFlappyObservationFeatures,
-  stepFlappyStateWithControlSubsteps,
-  type FlappyGameState,
-  type FlappyObservationFeatures,
-} from '../flappyEnvironment.ts';
-import {
-  clampValue,
-  commitSharedObservationMemoryStep,
-  createSharedObservationMemoryState,
-  resolveFlapDecision,
-  resolveTemporalObservationVector,
-} from '../flappy.simulation.shared.utils';
-import { createXorshift32 } from '../rng';
-import { mixGenomeEvaluationSeed } from './evaluation.seed.utils';
-import type {
-  FlappyEpisodeResult,
-  FlappyNetworkLike,
-  FlappyRolloutOptions,
-} from './evaluation.types';
-
 /**
- * Roll out an episode and return details.
+ * Public rollout compatibility facade.
  *
- * @param network - Genome/network to evaluate.
- * @param rolloutOptions - Optional rollout controls.
- * @returns Episode result details.
+ * Keeping this file at the evaluation layer preserves the established import
+ * path while the actual rollout orchestration lives behind the dedicated
+ * rollout-owned module boundary.
  */
-export function rolloutEpisode(
-  network: FlappyNetworkLike,
-  rolloutOptions: FlappyRolloutOptions = {},
-): FlappyEpisodeResult {
-  const genomeId = network._id ?? 0;
-  const seed = rolloutOptions.seed ?? mixGenomeEvaluationSeed(genomeId);
-  const difficultyScale = clampValue(
-    rolloutOptions.difficultyScale ??
-      FLAPPY_EVALUATION_DEFAULT_DIFFICULTY_SCALE,
-    0,
-    1,
-  );
-  const maxFramesPerEpisode = Math.max(
-    1,
-    Math.min(
-      FLAPPY_MAX_FRAMES_PER_EPISODE,
-      Math.trunc(rolloutOptions.maxFrames ?? FLAPPY_MAX_FRAMES_PER_EPISODE),
-    ),
-  );
-  const earlyTerminationGraceFrames = Math.max(
-    0,
-    Math.trunc(
-      rolloutOptions.earlyTerminationGraceFrames ??
-        FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_GRACE_FRAMES,
-    ),
-  );
-  const earlyTerminationConsecutiveFrames = Math.max(
-    1,
-    Math.trunc(
-      rolloutOptions.earlyTerminationConsecutiveFrames ??
-        FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_CONSECUTIVE_FRAMES,
-    ),
-  );
-  const rng = createXorshift32(seed);
-
-  const state = createInitialFlappyState(rng);
-  const observationMemoryState = createSharedObservationMemoryState();
-  let denseShapingFitness = 0;
-  let unrecoverableFrameCount = 0;
-
-  while (!state.done && state.frameIndex < maxFramesPerEpisode) {
-    const previousObservationFeatures = getFlappyObservationFeatures(
-      state,
-      difficultyScale,
-    );
-    stepFlappyStateWithControlSubsteps(
-      state,
-      rng,
-      () => {
-        const observationFeatures = getFlappyObservationFeatures(
-          state,
-          difficultyScale,
-        );
-        const observation = resolveTemporalObservationVector(
-          observationFeatures,
-          observationMemoryState,
-        );
-        const outputs = network.activate(observation);
-        const shouldFlap = resolveFlapDecision(outputs);
-        commitSharedObservationMemoryStep(
-          observationMemoryState,
-          observationFeatures,
-          shouldFlap,
-        );
-        return shouldFlap;
-      },
-      difficultyScale,
-      FLAPPY_CONTROL_SUBSTEPS_PER_FRAME,
-    );
-
-    const currentObservationFeatures = getFlappyObservationFeatures(
-      state,
-      difficultyScale,
-    );
-    denseShapingFitness += computeDenseShapingReward(
-      previousObservationFeatures,
-      currentObservationFeatures,
-    );
-
-    if (rolloutOptions.enableEarlyTermination === true) {
-      const birdLikelyUnrecoverable = isBirdLikelyUnrecoverable(
-        currentObservationFeatures,
-      );
-      const earlyTerminationEligible =
-        state.pipesPassed === 0 &&
-        state.frameIndex >= earlyTerminationGraceFrames;
-
-      unrecoverableFrameCount =
-        earlyTerminationEligible && birdLikelyUnrecoverable
-          ? unrecoverableFrameCount + 1
-          : 0;
-
-      if (unrecoverableFrameCount >= earlyTerminationConsecutiveFrames) {
-        state.done = true;
-        state.doneReason = 'collision';
-      }
-    }
-  }
-
-  if (!state.done && state.frameIndex >= maxFramesPerEpisode) {
-    state.done = true;
-    state.doneReason = 'timeout';
-  }
-
-  const framesSurvived = state.frameIndex;
-  const pipesPassed = state.pipesPassed;
-  const survivalFitness = framesSurvived * FLAPPY_FITNESS_SURVIVAL_WEIGHT;
-  const pipePassFitness = pipesPassed * FLAPPY_FITNESS_BONUS_PER_PIPE;
-  const terminalShapingFitness = computeTerminalShapingFitness(
-    state,
-    difficultyScale,
-  );
-  const fitness =
-    rolloutOptions.normalizeFitness === true
-      ? composeNormalizedFitness(
-          framesSurvived,
-          pipesPassed,
-          denseShapingFitness,
-          terminalShapingFitness,
-          maxFramesPerEpisode,
-          rolloutOptions.pipeProgressTarget,
-        )
-      : survivalFitness +
-        pipePassFitness +
-        denseShapingFitness +
-        terminalShapingFitness;
-
-  return {
-    framesSurvived,
-    pipesPassed,
-    done: state.done,
-    doneReason: state.doneReason,
-    fitness,
-    fitnessBreakdown: {
-      survival: survivalFitness,
-      pipeProgress: pipePassFitness,
-      denseShaping: denseShapingFitness,
-      terminalShaping: terminalShapingFitness,
-    },
-  };
-}
-
-/**
- * Computes dense reward shaping from consecutive observations.
- *
- * @param previousFeatures - Observation before stepping the environment.
- * @param currentFeatures - Observation after stepping the environment.
- * @returns Per-step shaped reward.
- */
-function computeDenseShapingReward(
-  previousFeatures: FlappyObservationFeatures,
-  currentFeatures: FlappyObservationFeatures,
-): number {
-  const nextGapAlignment =
-    1 - Math.abs(currentFeatures.normalizedDeltaToNextGap);
-  const nextGapAlignmentReward =
-    Math.max(0, nextGapAlignment) * FLAPPY_FITNESS_ALIGNMENT_WEIGHT_PER_FRAME;
-
-  const distanceImprovement = Math.max(
-    0,
-    previousFeatures.normalizedDistanceToNextPipe -
-      currentFeatures.normalizedDistanceToNextPipe,
-  );
-  const approachProgressReward =
-    distanceImprovement * FLAPPY_FITNESS_APPROACH_PROGRESS_WEIGHT;
-
-  const previousAbsoluteGapError = Math.abs(
-    previousFeatures.normalizedDeltaToNextGap,
-  );
-  const currentAbsoluteGapError = Math.abs(
-    currentFeatures.normalizedDeltaToNextGap,
-  );
-  const centeringImprovement = Math.max(
-    0,
-    previousAbsoluteGapError - currentAbsoluteGapError,
-  );
-  const centeringProgressReward =
-    centeringImprovement * FLAPPY_FITNESS_CENTERING_PROGRESS_WEIGHT;
-
-  const positiveClearance = Math.max(
-    0,
-    currentFeatures.normalizedNextGapClearance,
-  );
-  const clearanceReward =
-    positiveClearance * FLAPPY_FITNESS_CLEARANCE_WEIGHT_PER_FRAME;
-
-  const secondGapAlignment =
-    1 - Math.abs(currentFeatures.normalizedDeltaToSecondGap);
-  const secondGapAlignmentReward =
-    Math.max(0, secondGapAlignment) *
-    FLAPPY_FITNESS_SECOND_GAP_ALIGNMENT_WEIGHT_PER_FRAME;
-
-  const velocityStability = 1 - Math.abs(currentFeatures.normalizedVelocity);
-  const velocityStabilityReward =
-    Math.max(0, velocityStability) *
-    FLAPPY_FITNESS_STABLE_VELOCITY_WEIGHT_PER_FRAME;
-
-  return (
-    nextGapAlignmentReward +
-    approachProgressReward +
-    centeringProgressReward +
-    clearanceReward +
-    secondGapAlignmentReward +
-    velocityStabilityReward
-  );
-}
-
-/**
- * Adds small terminal bonuses from final progress/alignment signals.
- *
- * @param episodeState - Final rollout state.
- * @param difficultyScale - Active rollout difficulty scale.
- * @returns Terminal shaping reward.
- */
-function computeTerminalShapingFitness(
-  episodeState: FlappyGameState,
-  difficultyScale: number,
-): number {
-  const finalObservationFeatures = getFlappyObservationFeatures(
-    episodeState,
-    difficultyScale,
-  );
-  const finalAlignment =
-    1 - Math.abs(finalObservationFeatures.normalizedDeltaToNextGap);
-  const finalProgress =
-    1 -
-    Math.max(
-      0,
-      Math.min(1, finalObservationFeatures.normalizedDistanceToNextPipe),
-    );
-
-  const terminalAlignmentBonus =
-    Math.max(0, finalAlignment) *
-    FLAPPY_FITNESS_TERMINAL_ALIGNMENT_BONUS_WEIGHT;
-  const terminalProgressBonus =
-    Math.max(0, finalProgress) * FLAPPY_FITNESS_TERMINAL_PROGRESS_BONUS_WEIGHT;
-
-  return terminalAlignmentBonus + terminalProgressBonus;
-}
-
-/**
- * Normalize and cap fitness channels so no single reward term dominates.
- */
-function composeNormalizedFitness(
-  framesValue: number,
-  pipesPassedValue: number,
-  denseShapingValue: number,
-  terminalShapingValue: number,
-  maxFramesValue: number,
-  pipeProgressTarget: number | undefined,
-): number {
-  const effectivePipeProgressTarget = Math.max(
-    1,
-    Math.trunc(
-      pipeProgressTarget ?? FLAPPY_EVALUATION_DEFAULT_PIPE_PROGRESS_TARGET,
-    ),
-  );
-  const normalizedSurvival = clampValue(
-    framesValue / Math.max(1, maxFramesValue),
-    0,
-    1,
-  );
-  const normalizedPipeProgress = clampValue(
-    pipesPassedValue / effectivePipeProgressTarget,
-    0,
-    1,
-  );
-  const normalizedDenseShaping = clampValue(
-    denseShapingValue /
-      Math.max(
-        1,
-        framesValue * FLAPPY_EVALUATION_DENSE_SHAPING_FRAMES_NORMALIZER,
-      ),
-    0,
-    1,
-  );
-  const normalizedTerminalShaping = clampValue(
-    terminalShapingValue /
-      Math.max(
-        1,
-        FLAPPY_FITNESS_TERMINAL_ALIGNMENT_BONUS_WEIGHT +
-          FLAPPY_FITNESS_TERMINAL_PROGRESS_BONUS_WEIGHT,
-      ),
-    0,
-    1,
-  );
-
-  return (
-    normalizedSurvival *
-      FLAPPY_EVALUATION_NORMALIZED_SURVIVAL_WEIGHT *
-      FLAPPY_FITNESS_SURVIVAL_WEIGHT +
-    normalizedPipeProgress * FLAPPY_EVALUATION_NORMALIZED_PROGRESS_WEIGHT +
-    normalizedDenseShaping * FLAPPY_EVALUATION_NORMALIZED_DENSE_WEIGHT +
-    normalizedTerminalShaping * FLAPPY_EVALUATION_NORMALIZED_TERMINAL_WEIGHT
-  );
-}
-
-/**
- * Detects trajectories that are usually irrecoverable in early warmup.
- */
-function isBirdLikelyUnrecoverable(
-  observationFeatures: FlappyObservationFeatures,
-): boolean {
-  const farOutsideGap =
-    observationFeatures.normalizedNextGapClearance <
-    FLAPPY_EVALUATION_UNRECOVERABLE_CLEARANCE_THRESHOLD;
-  const belowGapAndStillFalling =
-    observationFeatures.normalizedDeltaToNextGap >
-      FLAPPY_EVALUATION_UNRECOVERABLE_BELOW_GAP_DELTA &&
-    observationFeatures.normalizedVelocity >
-      FLAPPY_EVALUATION_UNRECOVERABLE_FALLING_VELOCITY;
-  const aboveGapAndStillRising =
-    observationFeatures.normalizedDeltaToNextGap <
-      FLAPPY_EVALUATION_UNRECOVERABLE_ABOVE_GAP_DELTA &&
-    observationFeatures.normalizedVelocity <
-      FLAPPY_EVALUATION_UNRECOVERABLE_RISING_VELOCITY;
-
-  return farOutsideGap && (belowGapAndStillFalling || aboveGapAndStillRising);
-}
+export { rolloutEpisode } from './rollout/evaluation.rollout.service';

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

@@ -0,0 +1,291 @@
+# evaluation/rollout
+
+## evaluation/rollout/evaluation.rollout.types.ts
+
+### evaluation.rollout.types
+
+Rollout-internal type contracts.
+
+This file will host runtime-only rollout types that should not widen the
+public evaluation-level API surface.
+
+### DenseShapingRewardComponents
+
+Per-frame dense shaping channels resolved from consecutive observations.
+
+### RolloutEpisodeContext
+
+Immutable rollout options normalized into execution-safe ranges.
+
+### RolloutEpisodeRuntimeState
+
+Mutable runtime state accumulated while one rollout episode executes.
+
+### RolloutFitnessBreakdown
+
+Fitness-channel breakdown used to compose the public episode result.
+
+## evaluation/rollout/evaluation.rollout.service.ts
+
+### evaluation.rollout.service
+
+Rollout orchestration module.
+
+This file will host the internal rollout orchestration entry while the
+public evaluation-level service remains a stable compatibility facade.
+
+### rolloutEpisode
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, rolloutOptions: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyRolloutOptions) => import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyEpisodeResult`
+
+Roll out an episode and return details.
+
+Parameters:
+
+- `network` - - Genome/network to evaluate.
+- `rolloutOptions` - - Optional rollout controls.
+
+Returns: Episode result details.
+
+## evaluation/rollout/evaluation.rollout.services.ts
+
+### evaluation.rollout.services
+
+Rollout runtime services.
+
+This file will host context resolution, runtime initialization, frame loop,
+and early-termination behavior for rollout execution.
+
+### applyRolloutEarlyTerminationIfNeeded
+
+`(rolloutEpisodeContext: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeContext, rolloutEpisodeRuntimeState: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeRuntimeState, currentObservationFeatures: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures) => void`
+
+Applies the optional early-termination heuristic for unrecoverable starts.
+
+Parameters:
+
+- `rolloutEpisodeContext` - - Normalized rollout configuration.
+- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
+- `currentObservationFeatures` - - Post-step observation features.
+
+Returns: Nothing.
+
+### createRolloutEpisodeRuntimeState
+
+`(rolloutEpisodeContext: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeContext) => import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeRuntimeState`
+
+Creates mutable runtime state for one rollout episode.
+
+Parameters:
+
+- `rolloutEpisodeContext` - - Normalized rollout configuration.
+
+Returns: Mutable runtime state.
+
+### finalizeRolloutEpisodeState
+
+`(rolloutEpisodeContext: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeContext, rolloutEpisodeRuntimeState: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeRuntimeState) => void`
+
+Finalizes episode state after the main rollout loop exits.
+
+Parameters:
+
+- `rolloutEpisodeContext` - - Normalized rollout configuration.
+- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
+
+Returns: Nothing.
+
+### resolveRolloutEpisodeContext
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, rolloutOptions: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyRolloutOptions) => import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeContext`
+
+Resolves normalized rollout configuration from user options.
+
+Parameters:
+
+- `network` - - Genome/network to evaluate.
+- `rolloutOptions` - - Optional rollout controls.
+
+Returns: Normalized rollout configuration.
+
+### resolveRolloutFrameFlapDecision
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, rolloutEpisodeContext: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeContext, rolloutEpisodeRuntimeState: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeRuntimeState) => boolean`
+
+Resolves the flap decision for one control substep and commits memory state.
+
+Parameters:
+
+- `network` - - Genome/network to evaluate.
+- `rolloutEpisodeContext` - - Normalized rollout configuration.
+- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
+
+Returns: Whether the bird should flap.
+
+### runRolloutEpisodeFrame
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, rolloutEpisodeContext: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeContext, rolloutEpisodeRuntimeState: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeRuntimeState) => void`
+
+Runs one rollout frame including control, shaping, and early termination.
+
+Parameters:
+
+- `network` - - Genome/network to evaluate.
+- `rolloutEpisodeContext` - - Normalized rollout configuration.
+- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
+
+Returns: Nothing.
+
+### runRolloutEpisodeLoop
+
+`(network: import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyNetworkLike, rolloutEpisodeContext: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeContext, rolloutEpisodeRuntimeState: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeRuntimeState) => void`
+
+Runs the main rollout loop until termination or frame-budget exhaustion.
+
+Parameters:
+
+- `network` - - Genome/network to evaluate.
+- `rolloutEpisodeContext` - - Normalized rollout configuration.
+- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
+
+Returns: Nothing.
+
+## evaluation/rollout/evaluation.rollout.constants.ts
+
+### evaluation.rollout.constants
+
+Rollout-local constants.
+
+This file will host rollout-only constants and sentinels that belong to the
+rollout subsystem rather than the wider evaluation surface.
+
+### FLAPPY_ROLLOUT_DEFAULT_GENOME_ID
+
+### FLAPPY_ROLLOUT_DONE_REASON_COLLISION
+
+### FLAPPY_ROLLOUT_DONE_REASON_TIMEOUT
+
+### FLAPPY_ROLLOUT_MIN_EARLY_TERMINATION_CONSECUTIVE_FRAMES
+
+### FLAPPY_ROLLOUT_MIN_EARLY_TERMINATION_GRACE_FRAMES
+
+### FLAPPY_ROLLOUT_MIN_MAX_FRAMES
+
+### FLAPPY_ROLLOUT_ZERO_FITNESS
+
+## evaluation/rollout/evaluation.rollout.utils.ts
+
+### evaluation.rollout.utils
+
+Rollout shaping and result helpers.
+
+This file will host rollout-local fitness composition, shaping utilities,
+and terminal result assembly helpers.
+
+### composeNormalizedFitness
+
+`(framesValue: number, pipesPassedValue: number, denseShapingValue: number, terminalShapingValue: number, maxFramesValue: number, pipeProgressTarget: number | undefined) => number`
+
+Normalize and cap fitness channels so no single reward term dominates.
+
+Parameters:
+
+- `framesValue` - - Frames survived for the episode.
+- `pipesPassedValue` - - Pipes passed during the episode.
+- `denseShapingValue` - - Accumulated dense shaping reward.
+- `terminalShapingValue` - - Terminal shaping reward.
+- `maxFramesValue` - - Frame budget used for the episode.
+- `pipeProgressTarget` - - Optional target used to normalize pipe progress.
+
+Returns: Normalized composite fitness.
+
+### composeRolloutEpisodeResult
+
+`(rolloutEpisodeContext: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeContext, rolloutEpisodeRuntimeState: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeRuntimeState) => import("test/examples/flappy_bird/evaluation/evaluation.types").FlappyEpisodeResult`
+
+Composes the final rollout result from the terminal game state.
+
+Parameters:
+
+- `rolloutEpisodeContext` - - Normalized rollout configuration.
+- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
+
+Returns: Episode result details.
+
+### computeDenseShapingReward
+
+`(previousFeatures: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures, currentFeatures: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures) => number`
+
+Computes dense reward shaping from consecutive observations.
+
+Parameters:
+
+- `previousFeatures` - - Observation before stepping the environment.
+- `currentFeatures` - - Observation after stepping the environment.
+
+Returns: Per-step shaped reward.
+
+### computeTerminalShapingFitness
+
+`(episodeState: import("test/examples/flappy_bird/environment/environment.types").FlappyGameState, difficultyScale: number) => number`
+
+Adds small terminal bonuses from final progress/alignment signals.
+
+Parameters:
+
+- `episodeState` - - Final rollout state.
+- `difficultyScale` - - Active rollout difficulty scale.
+
+Returns: Terminal shaping reward.
+
+### isBirdLikelyUnrecoverable
+
+`(observationFeatures: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures) => boolean`
+
+Detects trajectories that are usually irrecoverable in early warmup.
+
+Parameters:
+
+- `observationFeatures` - - Post-step observation features.
+
+Returns: Whether the current trajectory appears unrecoverable.
+
+### resolveDenseShapingRewardComponents
+
+`(previousFeatures: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures, currentFeatures: import("test/examples/flappy_bird/simulation-shared/simulation-shared.types").SharedObservationFeatures) => import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").DenseShapingRewardComponents`
+
+Resolves every dense-shaping reward component from consecutive observations.
+
+Parameters:
+
+- `previousFeatures` - - Observation before stepping the environment.
+- `currentFeatures` - - Observation after stepping the environment.
+
+Returns: Dense-shaping reward components.
+
+### resolveRolloutFitnessBreakdown
+
+`(rolloutEpisodeContext: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeContext, rolloutEpisodeRuntimeState: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutEpisodeRuntimeState, framesSurvived: number, pipesPassed: number) => import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutFitnessBreakdown`
+
+Resolves the raw fitness channels from the final episode state.
+
+Parameters:
+
+- `rolloutEpisodeContext` - - Normalized rollout configuration.
+- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
+- `framesSurvived` - - Final frame count.
+- `pipesPassed` - - Final pipe-pass count.
+
+Returns: Fitness-channel breakdown.
+
+### resolveUnnormalizedRolloutFitness
+
+`(rolloutFitnessBreakdown: import("test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.types").RolloutFitnessBreakdown) => number`
+
+Resolves raw fitness by summing every fitness channel.
+
+Parameters:
+
+- `rolloutFitnessBreakdown` - - Fitness-channel breakdown.
+
+Returns: Raw unnormalized fitness.

package/test/examples/flappy_bird/evaluation/rollout/evaluation.rollout.constants.ts

@@ -0,0 +1,30 @@
+/**
+ * Rollout-local constants.
+ *
+ * This file will host rollout-only constants and sentinels that belong to the
+ * rollout subsystem rather than the wider evaluation surface.
+ */
+import type { FlappyGameState } from '../../flappyEnvironment.ts';
+
+/** Default genome id used when a network does not expose one. */
+export const FLAPPY_ROLLOUT_DEFAULT_GENOME_ID = 0;
+
+/** Minimum positive frame-like scalar used by rollout normalization. */
+export const FLAPPY_ROLLOUT_MIN_MAX_FRAMES = 1;
+
+/** Minimum grace period allowed before early termination can activate. */
+export const FLAPPY_ROLLOUT_MIN_EARLY_TERMINATION_GRACE_FRAMES = 0;
+
+/** Minimum unrecoverable-frame streak required for early termination. */
+export const FLAPPY_ROLLOUT_MIN_EARLY_TERMINATION_CONSECUTIVE_FRAMES = 1;
+
+/** Shared zero baseline used across rollout fitness and counters. */
+export const FLAPPY_ROLLOUT_ZERO_FITNESS = 0;
+
+/** Rollout done reason used by heuristic early termination. */
+export const FLAPPY_ROLLOUT_DONE_REASON_COLLISION: FlappyGameState['doneReason'] =
+  'collision';
+
+/** Rollout done reason used when the episode exhausts its frame budget. */
+export const FLAPPY_ROLLOUT_DONE_REASON_TIMEOUT: FlappyGameState['doneReason'] =
+  'timeout';