@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/rng/facade/README.md

@@ -26,52 +26,26 @@ The wrapper surface naturally falls into three pairs:
 
 ## neat/rng/facade/rng.facade.ts
 
-### snapshotRNGState
+### exportRNGState
 
 ```ts
-snapshotRNGState(
+exportRNGState(
   host: RngHost,
 ): number | undefined
 ```
 
-Return the current opaque RNG numeric state used by the instance.
-
-This is mainly useful for deterministic replay, test fixtures, and bug
-reports that need to resume the same random subsequence.
+Export the current RNG state for persistence or debugging.
 
-Prefer this wrapper when the state is staying inside the current debugging or
-test session. It captures the current numeric position without implying that
-the token is about to cross a persistence boundary.
+Use this wrapper when the replay token is likely to leave the immediate call
+site, such as checkpoint serialization, fixture capture, or bug-report
+handoff. Compared with `snapshotRNGState()`, the emphasis here is portability
+rather than momentary inspection.
 
 Parameters:
 - `host` - - `Neat` instance exposing RNG state.
 
 Returns: Numeric RNG state or `undefined` when the RNG has not been initialized.
 
-### restoreRNGState
-
-```ts
-restoreRNGState(
-  host: RngHost,
-  state: string | number | undefined,
-): void
-```
-
-Restore a previously captured RNG state.
-
-The next RNG access will continue from the restored subsequence, which makes
-it useful for replaying evolution bugs or comparing deterministic traces.
-
-Pair this with `snapshotRNGState()` or `exportRNGState()` when you want to
-prove that two runs consume the same future subsequence. The wrapper does not
-draw a random number itself; it only repositions the next draw.
-
-Parameters:
-- `host` - - `Neat` instance exposing RNG state.
-- `state` - - Numeric or string seed snapshot to restore.
-
-Returns: Nothing. The helper mutates the host RNG state in place.
-
 ### importRNGState
 
 ```ts
@@ -95,25 +69,41 @@ Parameters:
 
 Returns: Nothing. The helper mutates the host RNG state in place.
 
-### exportRNGState
+### NeatRngFacadeHost
+
+Narrow `Neat` host surface required by the public RNG facade.
+
+This stays intentionally small because the facade only forwards state
+snapshot, restore, export, and sampling calls into the existing RNG helpers.
+
+Keeping the host contract tiny protects the public wrapper boundary from the
+rest of the controller. Replay helpers need RNG state, optional configuration,
+and lightweight population context, but they do not need mutation, selection,
+or telemetry internals.
+
+### restoreRNGState
 
 ```ts
-exportRNGState(
+restoreRNGState(
   host: RngHost,
-): number | undefined
+  state: string | number | undefined,
+): void
 ```
 
-Export the current RNG state for persistence or debugging.
+Restore a previously captured RNG state.
 
-Use this wrapper when the replay token is likely to leave the immediate call
-site, such as checkpoint serialization, fixture capture, or bug-report
-handoff. Compared with `snapshotRNGState()`, the emphasis here is portability
-rather than momentary inspection.
+The next RNG access will continue from the restored subsequence, which makes
+it useful for replaying evolution bugs or comparing deterministic traces.
+
+Pair this with `snapshotRNGState()` or `exportRNGState()` when you want to
+prove that two runs consume the same future subsequence. The wrapper does not
+draw a random number itself; it only repositions the next draw.
 
 Parameters:
 - `host` - - `Neat` instance exposing RNG state.
+- `state` - - Numeric or string seed snapshot to restore.
 
-Returns: Numeric RNG state or `undefined` when the RNG has not been initialized.
+Returns: Nothing. The helper mutates the host RNG state in place.
 
 ### sampleRandom
 
@@ -149,14 +139,24 @@ const repeatedSequence = neat.sampleRandom(3);
 console.log(firstSequence, repeatedSequence);
 ```
 
-### NeatRngFacadeHost
+### snapshotRNGState
 
-Narrow `Neat` host surface required by the public RNG facade.
+```ts
+snapshotRNGState(
+  host: RngHost,
+): number | undefined
+```
 
-This stays intentionally small because the facade only forwards state
-snapshot, restore, export, and sampling calls into the existing RNG helpers.
+Return the current opaque RNG numeric state used by the instance.
 
-Keeping the host contract tiny protects the public wrapper boundary from the
-rest of the controller. Replay helpers need RNG state, optional configuration,
-and lightweight population context, but they do not need mutation, selection,
-or telemetry internals.
+This is mainly useful for deterministic replay, test fixtures, and bug
+reports that need to resume the same random subsequence.
+
+Prefer this wrapper when the state is staying inside the current debugging or
+test session. It captures the current numeric position without implying that
+the token is about to cross a persistence boundary.
+
+Parameters:
+- `host` - - `Neat` instance exposing RNG state.
+
+Returns: Numeric RNG state or `undefined` when the RNG has not been initialized.

package/src/neat/selection/README.md

@@ -98,59 +98,79 @@ const parent = neat.getParent();
 
 ## neat/selection/selection.ts
 
-### sort
+### DEFAULT_POWER
 
-```ts
-sort(): void
-```
+Default power exponent for POWER selection when none is configured.
 
-Sort the internal population in place by descending fitness.
+A value of `1` keeps POWER selection as a direct index-bias curve without
+adding extra front-loading beyond the strategy's normal rank preference.
+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.
 
-Use this when later controller steps should read the population in explicit
-best-first order. The helper applies the same fallback-score semantics used
-elsewhere in selection, so genomes without a score are treated as if they had
-{@link DEFAULT_SCORE} until evaluation supplies a real value.
+### DEFAULT_SCORE
 
-This helper is intentionally narrow: it only reorders the current population.
-It does not evaluate genomes, mutate them, or change the active parent
-selection strategy.
+Default score when a genome has no explicit score.
 
-Returns: Nothing. The population array is reordered in place.
+Selection uses one shared fallback so summaries, sorting, and threshold scans
+all interpret unevaluated or missing scores consistently. That matters for
+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.
 
-Example:
+### DEFAULT_TOURNAMENT_PROBABILITY
 
-```ts
-neat.sort();
-const bestScore = neat.population[0]?.score;
-```
+Default tournament win probability when none is configured.
 
-### getParent
+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_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.
+
+### 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.
+
+### getAverage
 
 ```ts
-getParent(): GenomeWithScore
+getAverage(): number
 ```
 
-Select a parent genome according to the configured selection strategy.
-
-This is the controller-facing gateway into the three built-in strategies:
+Compute the average fitness across the population.
 
-- `POWER` biases selection toward the front of the sorted population,
-- `FITNESS_PROPORTIONATE` performs roulette-style sampling and shifts
-  negative scores into a usable threshold space,
-- `TOURNAMENT` samples a temporary bracket and walks it with the configured
-  win probability.
+Use this when you want a coarse health signal for the whole generation rather
+than the single best genome. The helper ensures evaluation has happened,
+folds the total score across the full population, and returns the arithmetic
+mean that telemetry, progress logging, and quick sanity checks usually need.
 
-If the selection mode is unrecognized, the helper falls back to the first
-genome in the current population so the controller still has a deterministic
-parent candidate instead of failing deep inside crossover logic.
+Unlike parent selection, this helper does not care about order. It reports on
+the population as a group, which makes it a convenient companion to
+{@link getFittest} when you want both "best genome" and "overall generation"
+signals side by side.
 
-Returns: Genome chosen according to the active selection strategy.
+Returns: Mean fitness across the current population.
 
 Example:
 
 ```ts
-const parent = neat.getParent();
-const strategyName = neat.options.selection?.name;
+const meanScore = neat.getAverage();
+console.log(`Average score: ${meanScore}`);
 ```
 
 ### getFittest
@@ -179,88 +199,64 @@ const champion = neat.getFittest();
 console.log(champion.score);
 ```
 
-### getAverage
+### getParent
 
 ```ts
-getAverage(): number
+getParent(): GenomeWithScore
 ```
 
-Compute the average fitness across the population.
+Select a parent genome according to the configured selection strategy.
 
-Use this when you want a coarse health signal for the whole generation rather
-than the single best genome. The helper ensures evaluation has happened,
-folds the total score across the full population, and returns the arithmetic
-mean that telemetry, progress logging, and quick sanity checks usually need.
+This is the controller-facing gateway into the three built-in strategies:
 
-Unlike parent selection, this helper does not care about order. It reports on
-the population as a group, which makes it a convenient companion to
-{@link getFittest} when you want both "best genome" and "overall generation"
-signals side by side.
+- `POWER` biases selection toward the front of the sorted population,
+- `FITNESS_PROPORTIONATE` performs roulette-style sampling and shifts
+  negative scores into a usable threshold space,
+- `TOURNAMENT` samples a temporary bracket and walks it with the configured
+  win probability.
 
-Returns: Mean fitness across the current population.
+If the selection mode is unrecognized, the helper falls back to the first
+genome in the current population so the controller still has a deterministic
+parent candidate instead of failing deep inside crossover logic.
+
+Returns: Genome chosen according to the active selection strategy.
 
 Example:
 
 ```ts
-const meanScore = neat.getAverage();
-console.log(`Average score: ${meanScore}`);
+const parent = neat.getParent();
+const strategyName = neat.options.selection?.name;
 ```
 
-### DEFAULT_POWER
-
-Default power exponent for POWER selection when none is configured.
-
-A value of `1` keeps POWER selection as a direct index-bias curve without
-adding extra front-loading beyond the strategy's normal rank preference.
-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
+### INITIAL_CUMULATIVE_FITNESS
 
-Default tournament win probability when none is configured.
+Initial cumulative fitness value for roulette threshold scans.
 
-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.
+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.
 
-### DEFAULT_SCORE
+### INITIAL_MOST_NEGATIVE_SCORE
 
-Default score when a genome has no explicit score.
+Initial most-negative score sentinel for shifted-fitness scans.
 
-Selection uses one shared fallback so summaries, sorting, and threshold scans
-all interpret unevaluated or missing scores consistently. That matters for
-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.
+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.
 
-### FIRST_INDEX
+### INITIAL_TOTAL_FITNESS
 
-First element index used by guards, fallbacks, and best-first reads.
+Initial accumulator value for generation-wide score folds.
 
-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.
+Summary helpers begin from this neutral total so whole-population averages
+and other folds remain explicit about their starting score semantics.
 
-### SECOND_INDEX
+### LAST_ELEMENT_INDEX
 
-Second element index used by the cheap leading-edge ordering guard.
+Index used with `at()` when checking the tail of the population.
 
-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.
+The evaluation guard only needs the final genome to answer one practical
+question: has this generation already been scored all the way through?
 
 ### LAST_INDEX_OFFSET
 
@@ -276,32 +272,36 @@ Loop step used by explicit tournament and threshold walks.
 Naming the increment makes the small index-based scans read like deliberate
 traversal code instead of scattered magic numbers.
 
-### LAST_ELEMENT_INDEX
-
-Index used with `at()` when checking the tail of the population.
+### SECOND_INDEX
 
-The evaluation guard only needs the final genome to answer one practical
-question: has this generation already been scored all the way through?
+Second element index used by the cheap leading-edge ordering guard.
 
-### INITIAL_TOTAL_FITNESS
+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.
 
-Initial accumulator value for generation-wide score folds.
+### sort
 
-Summary helpers begin from this neutral total so whole-population averages
-and other folds remain explicit about their starting score semantics.
+```ts
+sort(): void
+```
 
-### INITIAL_MOST_NEGATIVE_SCORE
+Sort the internal population in place by descending fitness.
 
-Initial most-negative score sentinel for shifted-fitness scans.
+Use this when later controller steps should read the population in explicit
+best-first order. The helper applies the same fallback-score semantics used
+elsewhere in selection, so genomes without a score are treated as if they had
+{@link DEFAULT_SCORE} until evaluation supplies a real value.
 
-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.
+This helper is intentionally narrow: it only reorders the current population.
+It does not evaluate genomes, mutate them, or change the active parent
+selection strategy.
 
-### INITIAL_CUMULATIVE_FITNESS
+Returns: Nothing. The population array is reordered in place.
 
-Initial cumulative fitness value for roulette threshold scans.
+Example:
 
-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.
+```ts
+neat.sort();
+const bestScore = neat.population[0]?.score;
+```