@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -17,16 +17,6 @@ contract is what makes deterministic stepping and reward debugging practical.
 
 ## environment/environment.types.ts
 
-### FlappyPipe
-
-Pipe obstacle definition.
-
-Pipes move from right to left. The bird scores once per pipe when the pipe
-completely crosses the bird x-position.
-
-This is the environment-owned pipe state, distinct from the packed snapshot
-transport shapes used by the browser worker.
-
 ### FlappyBird
 
 Bird kinematic state for one simulation frame.
@@ -34,6 +24,16 @@ Bird kinematic state for one simulation frame.
 The environment keeps only the minimum physics state needed to advance the
 episode: vertical position and vertical velocity.
 
+### FlappyDifficultyScale
+
+Difficulty scale used by the curriculum scheduler.
+
+- `0` means easiest profile (wide gaps, slower pipes).
+- `1` means fully adaptive profile based on passed pipes.
+
+Values between `0` and `1` interpolate between those extremes, which lets the
+trainer or environment caller dial curriculum strength continuously.
+
 ### FlappyGameState
 
 Full simulation state for one Flappy episode.
@@ -50,24 +50,18 @@ Structured observation features used to build the neural-network input vector.
 Re-exported from shared simulation utilities so trainer and browser paths
 stay synchronized as the observation schema evolves.
 
-### FlappyDifficultyScale
+### FlappyPipe
 
-Difficulty scale used by the curriculum scheduler.
+Pipe obstacle definition.
 
-- `0` means easiest profile (wide gaps, slower pipes).
-- `1` means fully adaptive profile based on passed pipes.
+Pipes move from right to left. The bird scores once per pipe when the pipe
+completely crosses the bird x-position.
 
-Values between `0` and `1` interpolate between those extremes, which lets the
-trainer or environment caller dial curriculum strength continuously.
+This is the environment-owned pipe state, distinct from the packed snapshot
+transport shapes used by the browser worker.
 
 ## environment/environment.constants.ts
 
-### FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE
-
-Default curriculum difficulty scale used by environment stepping.
-
-A value of `1` means the environment uses the full adaptive difficulty ramp.
-
 ### FLAPPY_ENVIRONMENT_DEFAULT_CONTROL_SUBSTEPS_PER_FRAME
 
 Default number of control/physics substeps executed per simulation frame.
@@ -75,6 +69,12 @@ Default number of control/physics substeps executed per simulation frame.
 Reusing the shared control-substep count keeps the environment and browser
 playback aligned on the same stepping granularity.
 
+### FLAPPY_ENVIRONMENT_DEFAULT_DIFFICULTY_SCALE
+
+Default curriculum difficulty scale used by environment stepping.
+
+A value of `1` means the environment uses the full adaptive difficulty ramp.
+
 ### FLAPPY_ENVIRONMENT_MAX_FRAMES_PER_EPISODE
 
 Maximum frame budget before the environment forces timeout termination.

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

@@ -20,6 +20,13 @@ Read the exports in that order:
 
 ## evaluation/evaluation.types.ts
 
+### FlappyEpisodeResult
+
+Summary metrics for a single Flappy episode rollout.
+
+The result intentionally keeps both a single scalar `fitness` and the channel
+breakdown that produced it, which makes reward debugging much easier.
+
 ### FlappyNetworkLike
 
 Minimal network contract required by Flappy evaluation.
@@ -34,13 +41,6 @@ Runtime controls for one rollout evaluation.
 This is the public control surface for evaluation callers. The rollout layer
 later normalizes these options into execution-safe context values.
 
-### FlappyEpisodeResult
-
-Summary metrics for a single Flappy episode rollout.
-
-The result intentionally keeps both a single scalar `fitness` and the channel
-breakdown that produced it, which makes reward debugging much easier.
-
 ### FlappySeedBatchEvaluation
 
 Aggregate statistics from evaluating one network across shared seeds.
@@ -60,14 +60,14 @@ Default difficulty scale for rollouts when caller does not provide one.
 
 A value of `1` means full adaptive difficulty is enabled during evaluation.
 
-### FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_GRACE_FRAMES
-
-Default grace period (frames) before early termination checks begin.
-
 ### FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_CONSECUTIVE_FRAMES
 
 Default consecutive unrecoverable frames required for early termination.
 
+### FLAPPY_EVALUATION_DEFAULT_EARLY_TERMINATION_GRACE_FRAMES
+
+Default grace period (frames) before early termination checks begin.
+
 ### FLAPPY_EVALUATION_DEFAULT_PIPE_PROGRESS_TARGET
 
 Default pipe-progress target used when normalizing rollout fitness.
@@ -79,17 +79,17 @@ even when individual episodes vary widely in difficulty and duration.
 
 Dense shaping normalization factor per survived frame.
 
-### FLAPPY_EVALUATION_NORMALIZED_SURVIVAL_WEIGHT
+### FLAPPY_EVALUATION_NORMALIZED_DENSE_WEIGHT
 
-Survival channel weight in normalized fitness composition.
+Dense-shaping channel weight in normalized fitness composition.
 
 ### FLAPPY_EVALUATION_NORMALIZED_PROGRESS_WEIGHT
 
 Pipe-progress channel weight in normalized fitness composition.
 
-### FLAPPY_EVALUATION_NORMALIZED_DENSE_WEIGHT
+### FLAPPY_EVALUATION_NORMALIZED_SURVIVAL_WEIGHT
 
-Dense-shaping channel weight in normalized fitness composition.
+Survival channel weight in normalized fitness composition.
 
 ### FLAPPY_EVALUATION_NORMALIZED_TERMINAL_WEIGHT
 
@@ -102,40 +102,40 @@ Robust fitness penalty multiplier applied to standard deviation.
 A higher value penalizes instability more strongly when computing robust
 fitness from a shared-seed batch.
 
-### FLAPPY_EVALUATION_UNRECOVERABLE_CLEARANCE_THRESHOLD
+### FLAPPY_EVALUATION_SEED_MIX_MULTIPLIER_A
 
-Unrecoverable clearance threshold used by early termination heuristic.
+Seed-mix first multiplicative avalanche constant.
 
-### FLAPPY_EVALUATION_UNRECOVERABLE_BELOW_GAP_DELTA
+### FLAPPY_EVALUATION_SEED_MIX_MULTIPLIER_B
 
-Lower-gap delta threshold used by early termination heuristic.
+Seed-mix second multiplicative avalanche constant.
 
-### FLAPPY_EVALUATION_UNRECOVERABLE_FALLING_VELOCITY
+### FLAPPY_EVALUATION_SEED_MIX_XOR_SALT
 
-Falling-speed threshold used by early termination heuristic.
+Seed-mix additive constant used to decorrelate nearby genome ids.
+
+Together with the multiplicative constants below, this creates a small
+avalanche-style mixing pipeline for deterministic seed derivation.
 
 ### FLAPPY_EVALUATION_UNRECOVERABLE_ABOVE_GAP_DELTA
 
 Upper-gap delta threshold used by early termination heuristic.
 
-### FLAPPY_EVALUATION_UNRECOVERABLE_RISING_VELOCITY
-
-Rising-speed threshold used by early termination heuristic.
+### FLAPPY_EVALUATION_UNRECOVERABLE_BELOW_GAP_DELTA
 
-### FLAPPY_EVALUATION_SEED_MIX_XOR_SALT
+Lower-gap delta threshold used by early termination heuristic.
 
-Seed-mix additive constant used to decorrelate nearby genome ids.
+### FLAPPY_EVALUATION_UNRECOVERABLE_CLEARANCE_THRESHOLD
 
-Together with the multiplicative constants below, this creates a small
-avalanche-style mixing pipeline for deterministic seed derivation.
+Unrecoverable clearance threshold used by early termination heuristic.
 
-### FLAPPY_EVALUATION_SEED_MIX_MULTIPLIER_A
+### FLAPPY_EVALUATION_UNRECOVERABLE_FALLING_VELOCITY
 
-Seed-mix first multiplicative avalanche constant.
+Falling-speed threshold used by early termination heuristic.
 
-### FLAPPY_EVALUATION_SEED_MIX_MULTIPLIER_B
+### FLAPPY_EVALUATION_UNRECOVERABLE_RISING_VELOCITY
 
-Seed-mix second multiplicative avalanche constant.
+Rising-speed threshold used by early termination heuristic.
 
 ## evaluation/evaluation.fitness.utils.ts
 

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

@@ -89,25 +89,29 @@ finalizeRolloutEpisodeState(
 );
 ```
 
-### resolveRolloutEpisodeContext
+### applyRolloutEarlyTerminationIfNeeded
 
 ```ts
-resolveRolloutEpisodeContext(
-  network: FlappyNetworkLike,
-  rolloutOptions: FlappyRolloutOptions,
-): RolloutEpisodeContext
+applyRolloutEarlyTerminationIfNeeded(
+  rolloutEpisodeContext: RolloutEpisodeContext,
+  rolloutEpisodeRuntimeState: RolloutEpisodeRuntimeState,
+  currentObservationFeatures: SharedObservationFeatures,
+): void
 ```
 
-Resolves normalized rollout configuration from user options.
+Applies the optional early-termination heuristic for unrecoverable starts.
 
-This is the rollout safety boundary: caller-provided values are clamped into
-deterministic, execution-safe ranges before the main loop touches them.
+Educational note:
+Early termination is an evaluation-speed heuristic, not a gameplay rule. It
+exists to stop obviously doomed warmup trajectories from consuming excessive
+rollout budget.
 
 Parameters:
-- `network` - - Genome/network to evaluate.
-- `rolloutOptions` - - Optional rollout controls.
+- `rolloutEpisodeContext` - - Normalized rollout configuration.
+- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
+- `currentObservationFeatures` - - Post-step observation features.
 
-Returns: Normalized rollout configuration.
+Returns: Nothing.
 
 ### createRolloutEpisodeRuntimeState
 
@@ -128,28 +132,6 @@ Parameters:
 
 Returns: Mutable runtime state.
 
-### runRolloutEpisodeLoop
-
-```ts
-runRolloutEpisodeLoop(
-  network: FlappyNetworkLike,
-  rolloutEpisodeContext: RolloutEpisodeContext,
-  rolloutEpisodeRuntimeState: RolloutEpisodeRuntimeState,
-): void
-```
-
-Runs the main rollout loop until termination or frame-budget exhaustion.
-
-This is the episode heartbeat: keep stepping while the bird is alive and the
-rollout still has budget left.
-
-Parameters:
-- `network` - - Genome/network to evaluate.
-- `rolloutEpisodeContext` - - Normalized rollout configuration.
-- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
-
-Returns: Nothing.
-
 ### finalizeRolloutEpisodeState
 
 ```ts
@@ -170,28 +152,25 @@ Parameters:
 
 Returns: Nothing.
 
-### runRolloutEpisodeFrame
+### resolveRolloutEpisodeContext
 
 ```ts
-runRolloutEpisodeFrame(
+resolveRolloutEpisodeContext(
   network: FlappyNetworkLike,
-  rolloutEpisodeContext: RolloutEpisodeContext,
-  rolloutEpisodeRuntimeState: RolloutEpisodeRuntimeState,
-): void
+  rolloutOptions: FlappyRolloutOptions,
+): RolloutEpisodeContext
 ```
 
-Runs one rollout frame including control, shaping, and early termination.
+Resolves normalized rollout configuration from user options.
 
-Educational note:
-Each frame follows a compact pipeline: observe, act, step the environment,
-accumulate shaping reward, then optionally prune the trajectory.
+This is the rollout safety boundary: caller-provided values are clamped into
+deterministic, execution-safe ranges before the main loop touches them.
 
 Parameters:
 - `network` - - Genome/network to evaluate.
-- `rolloutEpisodeContext` - - Normalized rollout configuration.
-- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
+- `rolloutOptions` - - Optional rollout controls.
 
-Returns: Nothing.
+Returns: Normalized rollout configuration.
 
 ### resolveRolloutFrameFlapDecision
 
@@ -215,27 +194,48 @@ Parameters:
 
 Returns: Whether the bird should flap.
 
-### applyRolloutEarlyTerminationIfNeeded
+### runRolloutEpisodeFrame
 
 ```ts
-applyRolloutEarlyTerminationIfNeeded(
+runRolloutEpisodeFrame(
+  network: FlappyNetworkLike,
   rolloutEpisodeContext: RolloutEpisodeContext,
   rolloutEpisodeRuntimeState: RolloutEpisodeRuntimeState,
-  currentObservationFeatures: SharedObservationFeatures,
 ): void
 ```
 
-Applies the optional early-termination heuristic for unrecoverable starts.
+Runs one rollout frame including control, shaping, and early termination.
 
 Educational note:
-Early termination is an evaluation-speed heuristic, not a gameplay rule. It
-exists to stop obviously doomed warmup trajectories from consuming excessive
-rollout budget.
+Each frame follows a compact pipeline: observe, act, step the environment,
+accumulate shaping reward, then optionally prune the trajectory.
 
 Parameters:
+- `network` - - Genome/network to evaluate.
+- `rolloutEpisodeContext` - - Normalized rollout configuration.
+- `rolloutEpisodeRuntimeState` - - Mutable runtime state.
+
+Returns: Nothing.
+
+### runRolloutEpisodeLoop
+
+```ts
+runRolloutEpisodeLoop(
+  network: FlappyNetworkLike,
+  rolloutEpisodeContext: RolloutEpisodeContext,
+  rolloutEpisodeRuntimeState: RolloutEpisodeRuntimeState,
+): void
+```
+
+Runs the main rollout loop until termination or frame-budget exhaustion.
+
+This is the episode heartbeat: keep stepping while the bird is alive and the
+rollout still has budget left.
+
+Parameters:
+- `network` - - Genome/network to evaluate.
 - `rolloutEpisodeContext` - - Normalized rollout configuration.
 - `rolloutEpisodeRuntimeState` - - Mutable runtime state.
-- `currentObservationFeatures` - - Post-step observation features.
 
 Returns: Nothing.
 
@@ -252,6 +252,35 @@ The rollout subsystem separates simulation from scoring on purpose. The
 services file determines what happened; this file determines how that episode
 should be interpreted as fitness.
 
+### composeNormalizedFitness
+
+```ts
+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.
+
+Educational note:
+Channel normalization is a pragmatic way to keep the objective balanced across
+episodes of different lengths and levels of progress.
+
+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
 
 ```ts
@@ -293,6 +322,26 @@ Parameters:
 
 Returns: Per-step shaped reward.
 
+### computeTerminalShapingFitness
+
+```ts
+computeTerminalShapingFitness(
+  episodeState: FlappyGameState,
+  difficultyScale: number,
+): number
+```
+
+Adds small terminal bonuses from final progress/alignment signals.
+
+Terminal bonuses refine the final ranking, but they are intentionally smaller
+than the main survival and pipe-progress channels.
+
+Parameters:
+- `episodeState` - - Final rollout state.
+- `difficultyScale` - - Active rollout difficulty scale.
+
+Returns: Terminal shaping reward.
+
 ### isBirdLikelyUnrecoverable
 
 ```ts
@@ -311,6 +360,26 @@ Parameters:
 
 Returns: Whether the current trajectory appears unrecoverable.
 
+### resolveDenseShapingRewardComponents
+
+```ts
+resolveDenseShapingRewardComponents(
+  previousFeatures: SharedObservationFeatures,
+  currentFeatures: SharedObservationFeatures,
+): DenseShapingRewardComponents
+```
+
+Resolves every dense-shaping reward component from consecutive observations.
+
+If you want background reading, the Wikipedia article on "reward shaping" is
+a good high-level companion concept for why these components exist.
+
+Parameters:
+- `previousFeatures` - - Observation before stepping the environment.
+- `currentFeatures` - - Observation after stepping the environment.
+
+Returns: Dense-shaping reward components.
+
 ### resolveRolloutFitnessBreakdown
 
 ```ts
@@ -353,75 +422,6 @@ Parameters:
 
 Returns: Raw unnormalized fitness.
 
-### resolveDenseShapingRewardComponents
-
-```ts
-resolveDenseShapingRewardComponents(
-  previousFeatures: SharedObservationFeatures,
-  currentFeatures: SharedObservationFeatures,
-): DenseShapingRewardComponents
-```
-
-Resolves every dense-shaping reward component from consecutive observations.
-
-If you want background reading, the Wikipedia article on "reward shaping" is
-a good high-level companion concept for why these components exist.
-
-Parameters:
-- `previousFeatures` - - Observation before stepping the environment.
-- `currentFeatures` - - Observation after stepping the environment.
-
-Returns: Dense-shaping reward components.
-
-### computeTerminalShapingFitness
-
-```ts
-computeTerminalShapingFitness(
-  episodeState: FlappyGameState,
-  difficultyScale: number,
-): number
-```
-
-Adds small terminal bonuses from final progress/alignment signals.
-
-Terminal bonuses refine the final ranking, but they are intentionally smaller
-than the main survival and pipe-progress channels.
-
-Parameters:
-- `episodeState` - - Final rollout state.
-- `difficultyScale` - - Active rollout difficulty scale.
-
-Returns: Terminal shaping reward.
-
-### composeNormalizedFitness
-
-```ts
-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.
-
-Educational note:
-Channel normalization is a pragmatic way to keep the objective balanced across
-episodes of different lengths and levels of progress.
-
-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.
-
 ## evaluation/rollout/evaluation.rollout.types.ts
 
 Rollout-internal type contracts.
@@ -436,6 +436,13 @@ Read them as three layers:
 - `RolloutEpisodeRuntimeState`: mutable execution state.
 - fitness and shaping types: named reward channels used during folding.
 
+### DenseShapingRewardComponents
+
+Per-frame dense shaping channels resolved from consecutive observations.
+
+The shaping system rewards more than survival: it also tracks approach,
+centering, clearance, and stable motion.
+
 ### RolloutEpisodeContext
 
 Immutable rollout options normalized into execution-safe ranges.
@@ -455,13 +462,6 @@ Fitness-channel breakdown used to compose the public episode result.
 
 Named channels make reward design easier to audit than a single opaque number.
 
-### DenseShapingRewardComponents
-
-Per-frame dense shaping channels resolved from consecutive observations.
-
-The shaping system rewards more than survival: it also tracks approach,
-centering, clearance, and stable motion.
-
 ## evaluation/rollout/evaluation.rollout.constants.ts
 
 Rollout-local constants.
@@ -477,29 +477,29 @@ sea of raw `0`, `1`, and string literals.
 
 Default genome id used when a network does not expose one.
 
-### FLAPPY_ROLLOUT_MIN_MAX_FRAMES
+### FLAPPY_ROLLOUT_DONE_REASON_COLLISION
 
-Minimum positive frame-like scalar used by rollout normalization.
+Rollout done reason used by heuristic early termination.
 
-### FLAPPY_ROLLOUT_MIN_EARLY_TERMINATION_GRACE_FRAMES
+### FLAPPY_ROLLOUT_DONE_REASON_TIMEOUT
 
-Minimum grace period allowed before early termination can activate.
+Rollout done reason used when the episode exhausts its frame budget.
 
 ### FLAPPY_ROLLOUT_MIN_EARLY_TERMINATION_CONSECUTIVE_FRAMES
 
 Minimum unrecoverable-frame streak required for early termination.
 
-### FLAPPY_ROLLOUT_ZERO_FITNESS
+### FLAPPY_ROLLOUT_MIN_EARLY_TERMINATION_GRACE_FRAMES
 
-Shared zero baseline used across rollout fitness and counters.
+Minimum grace period allowed before early termination can activate.
 
-This acts as the semantic baseline for both shaping accumulation and several
-rollout guard conditions.
+### FLAPPY_ROLLOUT_MIN_MAX_FRAMES
 
-### FLAPPY_ROLLOUT_DONE_REASON_COLLISION
+Minimum positive frame-like scalar used by rollout normalization.
 
-Rollout done reason used by heuristic early termination.
+### FLAPPY_ROLLOUT_ZERO_FITNESS
 
-### FLAPPY_ROLLOUT_DONE_REASON_TIMEOUT
+Shared zero baseline used across rollout fitness and counters.
 
-Rollout done reason used when the episode exhausts its frame budget.
+This acts as the semantic baseline for both shaping accumulation and several
+rollout guard conditions.