@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/selection/core/README.md

@@ -33,19 +33,6 @@ Keep the contract loose when you add new genome-side fields elsewhere in the
 controller. If a selection helper can still do its job from score plus opaque
 metadata, the extra fields belong outside this boundary.
 
-### SelectionOptions
-
-Selection strategy settings used by the NEAT controller.
-
-These options are intentionally small because the public selection story is
-already taught at the root selection chapter and exposed through the stable
-`Neat` wrappers. The core layer only needs the knobs that alter actual parent
-choice mechanics: which strategy runs, how strongly POWER biases toward the
-front, and how TOURNAMENT sizes and probabilistic winner walks behave.
-
-Keeping this contract narrow prevents the core chapter from turning into a
-second facade for broader controller policy.
-
 ### NeatLikeWithSelection
 
 NEAT-like instance extended with selection-specific state and helpers.
@@ -76,6 +63,19 @@ data off the host.
 Read this as the per-selection call frame: one host, one population view,
 one resolved selection-options object, and one RNG source.
 
+### SelectionOptions
+
+Selection strategy settings used by the NEAT controller.
+
+These options are intentionally small because the public selection story is
+already taught at the root selection chapter and exposed through the stable
+`Neat` wrappers. The core layer only needs the knobs that alter actual parent
+choice mechanics: which strategy runs, how strongly POWER biases toward the
+front, and how TOURNAMENT sizes and probabilistic winner walks behave.
+
+Keeping this contract narrow prevents the core chapter from turning into a
+second facade for broader controller policy.
+
 ## neat/selection/core/selection.core.ts
 
 Selection mechanics used by the NEAT controller.
@@ -128,77 +128,27 @@ flowchart TD
   Tournament --> Parent
 ```
 
-### selectParentByStrategy
-
-```ts
-selectParentByStrategy(
-  internal: NeatLikeWithSelection,
-): GenomeWithScore
-```
-
-Select a parent genome according to the configured selection strategy.
-
-This is the single dispatch point shared by the controller-facing selection
-helpers. It resolves the active strategy once, builds a compact
-{@link SelectionContext}, and then hands off to the concrete algorithm.
-
-The fallback to the first population entry is deliberate. When callers have
-configured an unknown strategy name, selection still returns a deterministic
-candidate instead of failing unexpectedly deep inside crossover or mutation
-flow.
-
-Parameters:
-- `internal` - - NEAT host containing population, options, and RNG access.
-
-Returns: A genome chosen according to the active selection strategy.
-
-Example:
-
-```ts
-const parent = selectParentByStrategy(neat);
-const strategyName = neat.options.selection?.name;
-```
-
-### ensurePopulationEvaluated
-
-```ts
-ensurePopulationEvaluated(
-  internal: NeatLikeWithSelection,
-): void
-```
-
-Ensure population scores exist by running evaluation if needed.
-
-Selection treats score production as an upstream responsibility, but the
-controller still needs a safe guard at the point where score-dependent reads
-actually happen. This helper preserves that assumption: callers can ask for
-fittest genomes, averages, or parents without manually remembering whether
-evaluation already ran this generation.
-
-Parameters:
-- `internal` - - NEAT host containing population and evaluation support.
-
-Returns: Nothing. Evaluation is triggered only when the population is unevaluated.
-
-### ensurePopulationSortedDescending
+### calculateFitnessTotals
 
 ```ts
-ensurePopulationSortedDescending(
-  internal: NeatLikeWithSelection,
-): void
+calculateFitnessTotals(
+  population: GenomeWithScore[],
+): { totalFitness: number; minFitnessShift: number; }
 ```
 
-Ensure the population is sorted descending by score when out of order.
+Compute the total fitness and minimal shift used by roulette selection.
 
-Several selection reads assume best-first order but should not pay the cost
-of sorting when the population is already in the expected shape. This helper
-preserves that cheap guard by checking only the leading edge before calling
-the shared in-place sort hook.
+Fitness-proportionate selection must work even when a population contains
+negative scores. This helper records the most-negative value, converts that
+into a uniform upward shift, and returns the adjusted total that the later
+threshold scan uses.
+In other words, it prepares the roulette space so every genome still gets a
+measurable slice even when raw scores dip below zero.
 
 Parameters:
-- `internal` - - NEAT host containing the current population.
+- `population` - - Genomes in the current population.
 
-Returns: Nothing. Sorting only runs when the first two scores are out of order.
+Returns: Aggregate fitness totals with the negative-score shift.
 
 ### calculateTotalScore
 
@@ -232,26 +182,6 @@ That makes this the mildest built-in pressure setting: strong enough to
 prefer the front of the sorted population, but not so aggressive that the
 champion becomes nearly inevitable on every draw.
 
-### DEFAULT_TOURNAMENT_SIZE
-
-Default tournament size when none is configured.
-
-The built-in bracket stays intentionally small so tournament selection keeps
-some competitive pressure without collapsing into near-deterministic champion
-picks. In practice this means the default strategy samples just enough local
-competition to reward strong genomes while still letting non-champion genomes
-remain reachable.
-
-### DEFAULT_TOURNAMENT_PROBABILITY
-
-Default tournament win probability when none is configured.
-
-This keeps the top sampled participant favored while still allowing weaker
-entrants to remain reachable later in the tournament walk. Read it as the
-tournament counterpart to selection pressure: a balanced default that keeps
-the bracket competitive instead of turning every mini-tournament into a
-guaranteed top-seed march.
-
 ### DEFAULT_SCORE
 
 Default score when a genome has no explicit score.
@@ -262,175 +192,159 @@ chapter coherence as much as runtime behavior: every inspection helper and
 parent-selection guard speaks the same "missing score" language instead of
 inventing its own local default.
 
-### FIRST_INDEX
-
-First element index used by guards, fallbacks, and best-first reads.
-
-Selection logic names this index explicitly because the front of the
-population has semantic meaning: it is where champion reads and sorted-bias
-strategies begin.
-
-### SECOND_INDEX
-
-Second element index used by the cheap leading-edge ordering guard.
-
-Comparing the first two genomes is enough for the root helpers' fast
-"probably already sorted" check, so this constant marks the smallest useful
-comparison boundary.
-
-### LAST_INDEX_OFFSET
+### DEFAULT_TOURNAMENT_PROBABILITY
 
-Offset for retrieving the last element via length arithmetic.
+Default tournament win probability when none is configured.
 
-This keeps tail access readable in places where explicit length math is more
-portable than `at()` for the surrounding helper shape.
+This keeps the top sampled participant favored while still allowing weaker
+entrants to remain reachable later in the tournament walk. Read it as the
+tournament counterpart to selection pressure: a balanced default that keeps
+the bracket competitive instead of turning every mini-tournament into a
+guaranteed top-seed march.
 
-### LOOP_INDEX_INCREMENT
+### DEFAULT_TOURNAMENT_SIZE
 
-Loop step used by explicit tournament and threshold walks.
+Default tournament size when none is configured.
 
-Naming the increment makes the small index-based scans read like deliberate
-traversal code instead of scattered magic numbers.
+The built-in bracket stays intentionally small so tournament selection keeps
+some competitive pressure without collapsing into near-deterministic champion
+picks. In practice this means the default strategy samples just enough local
+competition to reward strong genomes while still letting non-champion genomes
+remain reachable.
 
-### LAST_ELEMENT_INDEX
+### ensurePopulationEvaluated
 
-Index used with `at()` when checking the tail of the population.
+```ts
+ensurePopulationEvaluated(
+  internal: NeatLikeWithSelection,
+): void
+```
 
-The evaluation guard only needs the final genome to answer one practical
-question: has this generation already been scored all the way through?
+Ensure population scores exist by running evaluation if needed.
 
-### INITIAL_TOTAL_FITNESS
+Selection treats score production as an upstream responsibility, but the
+controller still needs a safe guard at the point where score-dependent reads
+actually happen. This helper preserves that assumption: callers can ask for
+fittest genomes, averages, or parents without manually remembering whether
+evaluation already ran this generation.
 
-Initial accumulator value for generation-wide score folds.
+Parameters:
+- `internal` - - NEAT host containing population and evaluation support.
 
-Summary helpers begin from this neutral total so whole-population averages
-and other folds remain explicit about their starting score semantics.
+Returns: Nothing. Evaluation is triggered only when the population is unevaluated.
 
-### INITIAL_MOST_NEGATIVE_SCORE
+### ensurePopulationSortedDescending
 
-Initial most-negative score sentinel for shifted-fitness scans.
+```ts
+ensurePopulationSortedDescending(
+  internal: NeatLikeWithSelection,
+): void
+```
 
-FITNESS_PROPORTIONATE selection may need to lift negative scores into a
-usable roulette space, and this sentinel marks the baseline from which that
-most-negative search starts.
+Ensure the population is sorted descending by score when out of order.
 
-### INITIAL_CUMULATIVE_FITNESS
+Several selection reads assume best-first order but should not pay the cost
+of sorting when the population is already in the expected shape. This helper
+preserves that cheap guard by checking only the leading edge before calling
+the shared in-place sort hook.
 
-Initial cumulative fitness value for roulette threshold scans.
+Parameters:
+- `internal` - - NEAT host containing the current population.
 
-Roulette-style selection accumulates shifted fitness as it walks the
-population. This zero point keeps that running threshold explicit and aligned
-with the rest of the selection fallback semantics.
+Returns: Nothing. Sorting only runs when the first two scores are out of order.
 
-### selectParentByPower
+### ensurePopulationSortedDescendingForPower
 
 ```ts
-selectParentByPower(
+ensurePopulationSortedDescendingForPower(
   selectionContext: SelectionContext,
-): GenomeWithScore
+): void
 ```
 
-Select a parent by power-law distribution on the sorted population.
+Ensure the population is sorted descending by score for POWER selection.
 
-POWER selection assumes best-first ordering and then biases random choice
-toward the front of that ranking. Lower random samples stay near the leading
-genomes, while the configured exponent controls how quickly the chance falls
-away from the champion.
-Read this as the lightest built-in strategy: it does not inspect absolute
-score gaps, only the current descending order.
+POWER selection is the only built-in strategy that depends on the population
+already being rank-ordered before index sampling. The narrower guard lives
+here instead of in the root chapter so the strategy can preserve that rule
+without forcing unrelated selection paths to sort first.
 
 Parameters:
 - `selectionContext` - - Shared selection state.
 
-Returns: The chosen parent genome.
+Returns: Nothing. Sorting only runs when the first two entries are out of order.
 
-### selectParentByFitnessProportionate
+### FIRST_INDEX
+
+First element index used by guards, fallbacks, and best-first reads.
+
+Selection logic names this index explicitly because the front of the
+population has semantic meaning: it is where champion reads and sorted-bias
+strategies begin.
+
+### getRandomPopulationMember
 
 ```ts
-selectParentByFitnessProportionate(
+getRandomPopulationMember(
   selectionContext: SelectionContext,
 ): GenomeWithScore
 ```
 
-Select a parent using roulette-wheel fitness proportionate selection.
+Select a random population member using the configured RNG.
 
-This path turns the current population into a weighted threshold scan. When
-some genomes have negative scores, the helper first shifts the whole fitness
-space upward so every participant still occupies a non-negative span on the
-roulette wheel.
-That makes this strategy the most score-sensitive branch in the chapter: it
-reacts to relative score magnitude rather than only rank or sampled bracket
-ordering.
+This is the small shared fallback used by roulette misses and suppressed
+tournament overflow. Centralizing it here keeps every selection path tied to
+the same controller RNG stream.
+It also makes the fallback semantics explicit instead of hiding ad hoc random
+picks inside individual strategies.
 
 Parameters:
 - `selectionContext` - - Shared selection state.
 
-Returns: The chosen parent genome.
+Returns: Randomly chosen genome from the current population.
 
-### selectParentByTournament
+### INITIAL_CUMULATIVE_FITNESS
 
-```ts
-selectParentByTournament(
-  selectionContext: SelectionContext,
-): GenomeWithScore
-```
+Initial cumulative fitness value for roulette threshold scans.
 
-Select a parent by tournament selection.
+Roulette-style selection accumulates shifted fitness as it walks the
+population. This zero point keeps that running threshold explicit and aligned
+with the rest of the selection fallback semantics.
 
-Tournament selection samples a temporary bracket, orders it by descending
-score, then walks from strongest to weakest using the configured win
-probability. This gives the controller a middle ground between pure
-best-first bias and fully score-proportional roulette.
-The sampled bracket is intentionally local: the strategy asks "who wins this
-small contest?" rather than "how does the whole population distribute
-weight?"
+### INITIAL_MOST_NEGATIVE_SCORE
 
-Parameters:
-- `selectionContext` - - Shared selection state.
+Initial most-negative score sentinel for shifted-fitness scans.
 
-Returns: The chosen parent genome.
+FITNESS_PROPORTIONATE selection may need to lift negative scores into a
+usable roulette space, and this sentinel marks the baseline from which that
+most-negative search starts.
 
-### ensurePopulationSortedDescendingForPower
+### INITIAL_TOTAL_FITNESS
 
-```ts
-ensurePopulationSortedDescendingForPower(
-  selectionContext: SelectionContext,
-): void
-```
+Initial accumulator value for generation-wide score folds.
 
-Ensure the population is sorted descending by score for POWER selection.
+Summary helpers begin from this neutral total so whole-population averages
+and other folds remain explicit about their starting score semantics.
 
-POWER selection is the only built-in strategy that depends on the population
-already being rank-ordered before index sampling. The narrower guard lives
-here instead of in the root chapter so the strategy can preserve that rule
-without forcing unrelated selection paths to sort first.
+### LAST_ELEMENT_INDEX
 
-Parameters:
-- `selectionContext` - - Shared selection state.
+Index used with `at()` when checking the tail of the population.
 
-Returns: Nothing. Sorting only runs when the first two entries are out of order.
+The evaluation guard only needs the final genome to answer one practical
+question: has this generation already been scored all the way through?
 
-### calculateFitnessTotals
+### LAST_INDEX_OFFSET
 
-```ts
-calculateFitnessTotals(
-  population: GenomeWithScore[],
-): { totalFitness: number; minFitnessShift: number; }
-```
+Offset for retrieving the last element via length arithmetic.
 
-Compute the total fitness and minimal shift used by roulette selection.
+This keeps tail access readable in places where explicit length math is more
+portable than `at()` for the surrounding helper shape.
 
-Fitness-proportionate selection must work even when a population contains
-negative scores. This helper records the most-negative value, converts that
-into a uniform upward shift, and returns the adjusted total that the later
-threshold scan uses.
-In other words, it prepares the roulette space so every genome still gets a
-measurable slice even when raw scores dip below zero.
+### LOOP_INDEX_INCREMENT
 
-Parameters:
-- `population` - - Genomes in the current population.
+Loop step used by explicit tournament and threshold walks.
 
-Returns: Aggregate fitness totals with the negative-score shift.
+Naming the increment makes the small index-based scans read like deliberate
+traversal code instead of scattered magic numbers.
 
 ### pickByShiftedThreshold
 
@@ -456,6 +370,29 @@ Parameters:
 
 Returns: The chosen genome when a threshold crossing occurs.
 
+### pickTournamentWinner
+
+```ts
+pickTournamentWinner(
+  selectionContext: SelectionContext,
+  sortedParticipants: GenomeWithScore[],
+): GenomeWithScore
+```
+
+Select a winner from sorted tournament participants.
+
+After participants are sorted best-first, this helper walks the list from the
+front and gives each participant a chance to win immediately. The configured
+probability therefore controls how often the top entrant wins outright versus
+how often weaker entrants remain reachable later in the walk.
+This is what makes tournament selection tunable instead of purely greedy.
+
+Parameters:
+- `selectionContext` - - Shared selection state.
+- `sortedParticipants` - - Participants sorted by descending score.
+
+Returns: The chosen tournament winner.
+
 ### resolveTournamentOverflow
 
 ```ts
@@ -501,46 +438,109 @@ Parameters:
 
 Returns: Sampled participants.
 
-### pickTournamentWinner
+### SECOND_INDEX
+
+Second element index used by the cheap leading-edge ordering guard.
+
+Comparing the first two genomes is enough for the root helpers' fast
+"probably already sorted" check, so this constant marks the smallest useful
+comparison boundary.
+
+### selectParentByFitnessProportionate
 
 ```ts
-pickTournamentWinner(
+selectParentByFitnessProportionate(
   selectionContext: SelectionContext,
-  sortedParticipants: GenomeWithScore[],
 ): GenomeWithScore
 ```
 
-Select a winner from sorted tournament participants.
+Select a parent using roulette-wheel fitness proportionate selection.
 
-After participants are sorted best-first, this helper walks the list from the
-front and gives each participant a chance to win immediately. The configured
-probability therefore controls how often the top entrant wins outright versus
-how often weaker entrants remain reachable later in the walk.
-This is what makes tournament selection tunable instead of purely greedy.
+This path turns the current population into a weighted threshold scan. When
+some genomes have negative scores, the helper first shifts the whole fitness
+space upward so every participant still occupies a non-negative span on the
+roulette wheel.
+That makes this strategy the most score-sensitive branch in the chapter: it
+reacts to relative score magnitude rather than only rank or sampled bracket
+ordering.
 
 Parameters:
 - `selectionContext` - - Shared selection state.
-- `sortedParticipants` - - Participants sorted by descending score.
 
-Returns: The chosen tournament winner.
+Returns: The chosen parent genome.
 
-### getRandomPopulationMember
+### selectParentByPower
 
 ```ts
-getRandomPopulationMember(
+selectParentByPower(
   selectionContext: SelectionContext,
 ): GenomeWithScore
 ```
 
-Select a random population member using the configured RNG.
+Select a parent by power-law distribution on the sorted population.
 
-This is the small shared fallback used by roulette misses and suppressed
-tournament overflow. Centralizing it here keeps every selection path tied to
-the same controller RNG stream.
-It also makes the fallback semantics explicit instead of hiding ad hoc random
-picks inside individual strategies.
+POWER selection assumes best-first ordering and then biases random choice
+toward the front of that ranking. Lower random samples stay near the leading
+genomes, while the configured exponent controls how quickly the chance falls
+away from the champion.
+Read this as the lightest built-in strategy: it does not inspect absolute
+score gaps, only the current descending order.
 
 Parameters:
 - `selectionContext` - - Shared selection state.
 
-Returns: Randomly chosen genome from the current population.
+Returns: The chosen parent genome.
+
+### selectParentByStrategy
+
+```ts
+selectParentByStrategy(
+  internal: NeatLikeWithSelection,
+): GenomeWithScore
+```
+
+Select a parent genome according to the configured selection strategy.
+
+This is the single dispatch point shared by the controller-facing selection
+helpers. It resolves the active strategy once, builds a compact
+{@link SelectionContext}, and then hands off to the concrete algorithm.
+
+The fallback to the first population entry is deliberate. When callers have
+configured an unknown strategy name, selection still returns a deterministic
+candidate instead of failing unexpectedly deep inside crossover or mutation
+flow.
+
+Parameters:
+- `internal` - - NEAT host containing population, options, and RNG access.
+
+Returns: A genome chosen according to the active selection strategy.
+
+Example:
+
+```ts
+const parent = selectParentByStrategy(neat);
+const strategyName = neat.options.selection?.name;
+```
+
+### selectParentByTournament
+
+```ts
+selectParentByTournament(
+  selectionContext: SelectionContext,
+): GenomeWithScore
+```
+
+Select a parent by tournament selection.
+
+Tournament selection samples a temporary bracket, orders it by descending
+score, then walks from strongest to weakest using the configured win
+probability. This gives the controller a middle ground between pure
+best-first bias and fully score-proportional roulette.
+The sampled bracket is intentionally local: the strategy asks "who wins this
+small contest?" rather than "how does the whole population distribute
+weight?"
+
+Parameters:
+- `selectionContext` - - Shared selection state.
+
+Returns: The chosen parent genome.