@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/evolve/population/README.md

@@ -70,77 +70,100 @@ flowchart LR
 
 ## neat/evolve/population/evolve.population.utils.ts
 
-### buildNextPopulation
+### addOffspring
 
 ```ts
-buildNextPopulation(
+addOffspring(
   internal: NeatControllerForEvolution,
-  helpers: { applyElitism: (nextPopulation: default[]) => void; applyProvenance: (nextPopulation: default[]) => void; addOffspring: (nextPopulation: default[]) => Promise<void>; },
-): Promise<default[]>
+  nextPopulation: default[],
+  helpers: { addSpeciatedOffspring: (nextPopulation: default[], remainingSlots: number) => Promise<void>; addUnspeciatedOffspring: (nextPopulation: default[], remainingSlots: number) => Promise<void>; },
+): Promise<void>
 ```
 
-Build the next population (elitism, provenance, offspring).
+Add offspring to fill remaining population slots.
 
-This helper is the orchestration entrypoint for next-generation assembly.
-It deliberately reads like a short collect-and-fill pipeline: start with an
-empty container, reserve the slots that should bypass parent selection, then
-spend the remaining capacity on offspring generation. The mutation and prune
-phases happen later; this boundary only answers how the raw next population is
-assembled before those later transforms run.
+This helper spends whatever population budget remains after elitism and
+provenance have claimed their slots. Its main job is not to create children
+itself, but to choose the correct filling strategy: species-aware allocation
+when the controller currently maintains a species registry, or global parent
+selection when it does not.
 
-Pedagogically, this is the chapter's "packing list" helper. It does not yet
-ask whether the chosen genomes are structurally clean enough for the next
-loop. It only decides which genomes enter the first draft of the next
-population, and in which order those admission rules are applied.
+That branch is the main conceptual seam in the chapter. Everything before
+this point is deterministic packing. This helper is where the controller asks
+whether the remaining search budget should respect live species boundaries or
+whether it should fall back to one global parent pool.
 
-Example:
+Parameters:
+- `internal` - - NEAT controller instance.
+- `nextPopulation` - - Target population array.
+- `helpers` - - Helper callbacks for offspring selection.
+- `helpers` - - Speciated offspring helper.
+- `helpers` - - Unspeciated offspring helper.
+
+Returns: A promise that resolves after the remaining population budget is filled.
+
+### addSpeciatedOffspring
 
 ```ts
-const nextPopulation = await buildNextPopulation(internal, {
-  applyElitism: (population) => applyElitism(internal, population),
-  applyProvenance: (population) => applyProvenance(internal, population),
-  addOffspring: (population) => addOffspring(internal, population, helpers),
-});
+addSpeciatedOffspring(
+  internal: NeatControllerForEvolution,
+  nextPopulation: default[],
+  remainingSlots: number,
+  config: { minOffspringDefault: number; survivalThresholdDefault: number; youngThresholdDefault: number; youngMultiplierDefault: number; oldThresholdDefault: number; oldMultiplierDefault: number; crossSpeciesGuardLimit: number; },
+): Promise<void>
 ```
 
+Add offspring when speciation is enabled.
+
+This is the species-aware branch of population filling. It converts the
+remaining population budget into per-species child counts, records those
+counts for later telemetry or diagnostics reads, then breeds within each
+species using the narrower offspring mechanics described in `offspring/`.
+
+The helper stays intentionally focused on allocation and local survivor
+pools. It does not re-run speciation or mutate the produced children.
+
+The important teaching split is that this helper does two different jobs in
+sequence:
+
+1. decide how much reproductive budget each species deserves,
+2. spend each species-local budget through survivor-based crossover.
+
+Keeping those jobs together makes the generated chapter longer, but it also
+keeps the species-aware branch readable in one place instead of scattering the
+allocation rationale across several tiny helpers.
+
 Parameters:
 - `internal` - - NEAT controller instance.
-- `helpers` - - Helper callbacks for population construction.
-- `helpers` - - Elitism helper.
-- `helpers` - - Provenance helper.
-- `helpers` - - Offspring helper.
+- `nextPopulation` - - Target population array.
+- `remainingSlots` - - Slots remaining to fill.
+- `config` - - Offspring allocation constants.
 
-Returns: Next population array before later mutation and pruning phases.
+Returns: A promise that resolves after species-aware offspring have been added.
 
-### enforcePopulationConstraints
+### addUnspeciatedOffspring
 
 ```ts
-enforcePopulationConstraints(
+addUnspeciatedOffspring(
   internal: NeatControllerForEvolution,
   nextPopulation: default[],
+  remainingSlots: number,
 ): Promise<void>
 ```
 
-Ensure new population meets structural constraints.
-
-Population assembly intentionally separates slot-filling from structural
-cleanup. Elites may already be valid, provenance genomes may come from a
-seed network or a fresh constructor path, and offspring may arrive from
-crossover with small topology issues that the controller routinely repairs.
-Running those repairs here keeps later evolve code free to assume the new
-population already satisfies the controller's minimum hidden-node and
-dead-end expectations.
+Add offspring when speciation is disabled.
 
-Keeping this repair pass at the end is a deliberate architecture choice. If
-every earlier helper tried to repair genomes inline, the chapter would blur
-slot-allocation policy together with structural-safety policy. Centralizing
-cleanup here keeps the earlier helpers focused on population composition.
+When no species registry is active, the population builder falls back to the
+controller's global offspring-selection path. This keeps the no-speciation
+branch small and makes the contrast with the species-aware allocator easy to
+read in the generated chapter.
 
 Parameters:
 - `internal` - - NEAT controller instance.
-- `nextPopulation` - - Population to validate.
+- `nextPopulation` - - Target population array.
+- `remainingSlots` - - Slots remaining to fill.
 
-Returns: A promise that resolves after best-effort structural cleanup.
+Returns: A promise that resolves after all remaining slots have been filled.
 
 ### applyElitism
 
@@ -194,100 +217,82 @@ Parameters:
 
 Returns: Nothing.
 
-### addOffspring
+### buildNextPopulation
 
 ```ts
-addOffspring(
+buildNextPopulation(
   internal: NeatControllerForEvolution,
-  nextPopulation: default[],
-  helpers: { addSpeciatedOffspring: (nextPopulation: default[], remainingSlots: number) => Promise<void>; addUnspeciatedOffspring: (nextPopulation: default[], remainingSlots: number) => Promise<void>; },
-): Promise<void>
+  helpers: { applyElitism: (nextPopulation: default[]) => void; applyProvenance: (nextPopulation: default[]) => void; addOffspring: (nextPopulation: default[]) => Promise<void>; },
+): Promise<default[]>
 ```
 
-Add offspring to fill remaining population slots.
-
-This helper spends whatever population budget remains after elitism and
-provenance have claimed their slots. Its main job is not to create children
-itself, but to choose the correct filling strategy: species-aware allocation
-when the controller currently maintains a species registry, or global parent
-selection when it does not.
-
-That branch is the main conceptual seam in the chapter. Everything before
-this point is deterministic packing. This helper is where the controller asks
-whether the remaining search budget should respect live species boundaries or
-whether it should fall back to one global parent pool.
+Build the next population (elitism, provenance, offspring).
 
-Parameters:
-- `internal` - - NEAT controller instance.
-- `nextPopulation` - - Target population array.
-- `helpers` - - Helper callbacks for offspring selection.
-- `helpers` - - Speciated offspring helper.
-- `helpers` - - Unspeciated offspring helper.
+This helper is the orchestration entrypoint for next-generation assembly.
+It deliberately reads like a short collect-and-fill pipeline: start with an
+empty container, reserve the slots that should bypass parent selection, then
+spend the remaining capacity on offspring generation. The mutation and prune
+phases happen later; this boundary only answers how the raw next population is
+assembled before those later transforms run.
 
-Returns: A promise that resolves after the remaining population budget is filled.
+Pedagogically, this is the chapter's "packing list" helper. It does not yet
+ask whether the chosen genomes are structurally clean enough for the next
+loop. It only decides which genomes enter the first draft of the next
+population, and in which order those admission rules are applied.
 
-### addSpeciatedOffspring
+Example:
 
 ```ts
-addSpeciatedOffspring(
-  internal: NeatControllerForEvolution,
-  nextPopulation: default[],
-  remainingSlots: number,
-  config: { minOffspringDefault: number; survivalThresholdDefault: number; youngThresholdDefault: number; youngMultiplierDefault: number; oldThresholdDefault: number; oldMultiplierDefault: number; crossSpeciesGuardLimit: number; },
-): Promise<void>
+const nextPopulation = await buildNextPopulation(internal, {
+  applyElitism: (population) => applyElitism(internal, population),
+  applyProvenance: (population) => applyProvenance(internal, population),
+  addOffspring: (population) => addOffspring(internal, population, helpers),
+});
 ```
 
-Add offspring when speciation is enabled.
-
-This is the species-aware branch of population filling. It converts the
-remaining population budget into per-species child counts, records those
-counts for later telemetry or diagnostics reads, then breeds within each
-species using the narrower offspring mechanics described in `offspring/`.
-
-The helper stays intentionally focused on allocation and local survivor
-pools. It does not re-run speciation or mutate the produced children.
-
-The important teaching split is that this helper does two different jobs in
-sequence:
-
-1. decide how much reproductive budget each species deserves,
-2. spend each species-local budget through survivor-based crossover.
-
-Keeping those jobs together makes the generated chapter longer, but it also
-keeps the species-aware branch readable in one place instead of scattering the
-allocation rationale across several tiny helpers.
-
 Parameters:
 - `internal` - - NEAT controller instance.
-- `nextPopulation` - - Target population array.
-- `remainingSlots` - - Slots remaining to fill.
-- `config` - - Offspring allocation constants.
+- `helpers` - - Helper callbacks for population construction.
+- `helpers` - - Elitism helper.
+- `helpers` - - Provenance helper.
+- `helpers` - - Offspring helper.
 
-Returns: A promise that resolves after species-aware offspring have been added.
+Returns: Next population array before later mutation and pruning phases.
 
-### addUnspeciatedOffspring
+### buildSpeciesOffspring
 
 ```ts
-addUnspeciatedOffspring(
+buildSpeciesOffspring(
   internal: NeatControllerForEvolution,
-  nextPopulation: default[],
-  remainingSlots: number,
-): Promise<void>
+  survivors: GenomeWithMetadata[],
+  speciesIndex: number,
+  crossSpeciesProbability: number,
+  crossSpeciesGuardLimit: number,
+  survivalThresholdDefault: number,
+): GenomeWithMetadata
 ```
 
-Add offspring when speciation is disabled.
+Build a single offspring within a species.
 
-When no species registry is active, the population builder falls back to the
-controller's global offspring-selection path. This keeps the no-speciation
-branch small and makes the contrast with the species-aware allocator easy to
-read in the generated chapter.
+This helper is the point where species-local survivor selection turns into
+one actual child. It chooses both parents, performs crossover, and annotates
+runtime lineage metadata so the resulting genome is ready for later telemetry,
+lineage, and inbreeding reads.
+
+Conceptually, this is where the abstract allocation budget becomes one real
+experiment. Everything above this helper is still about counts and survivor
+pools; this helper is where the controller finally spends one unit of that
+budget on one concrete child genome.
 
 Parameters:
 - `internal` - - NEAT controller instance.
-- `nextPopulation` - - Target population array.
-- `remainingSlots` - - Slots remaining to fill.
+- `survivors` - - Survivors pool for selection.
+- `speciesIndex` - - Species index.
+- `crossSpeciesProbability` - - Cross-species mating probability.
+- `crossSpeciesGuardLimit` - - Retry guard for cross-species selection.
+- `survivalThresholdDefault` - - Default survivor-window policy used when cross-species selection samples another species.
 
-Returns: A promise that resolves after all remaining slots have been filled.
+Returns: Offspring genome carrying runtime metadata.
 
 ### computeOffspringAllocation
 
@@ -322,34 +327,6 @@ Parameters:
 
 Returns: Offspring allocation per species index.
 
-### enforceMinimumOffspring
-
-```ts
-enforceMinimumOffspring(
-  internal: NeatControllerForEvolution,
-  allocation: number[],
-  remainingSlots: number,
-  minOffspringDefault: number,
-): void
-```
-
-Enforce minimum offspring per species when possible.
-
-This rule prevents species allocation from collapsing entirely onto a few
-dominant lineages when the remaining slot budget is large enough to preserve
-a broader search frontier.
-
-In other words, this is the chapter's anti-monoculture guard. It only runs
-when the slot budget is big enough to afford that diversity protection.
-
-Parameters:
-- `internal` - - NEAT controller instance.
-- `allocation` - - Allocation array to adjust.
-- `remainingSlots` - - Total slots available.
-- `minOffspringDefault` - - Default minimum offspring.
-
-Returns: Nothing.
-
 ### distributeRemainingSlots
 
 ```ts
@@ -377,10 +354,10 @@ Parameters:
 
 Returns: Nothing.
 
-### trimOversubscription
+### enforceMinimumOffspring
 
 ```ts
-trimOversubscription(
+enforceMinimumOffspring(
   internal: NeatControllerForEvolution,
   allocation: number[],
   remainingSlots: number,
@@ -388,15 +365,14 @@ trimOversubscription(
 ): void
 ```
 
-Trim allocations when oversubscribed.
+Enforce minimum offspring per species when possible.
 
-Minimum-offspring guarantees can occasionally oversubscribe the remaining
-budget. This helper trims from the largest allocations first while still
-respecting the minimum line preserved for each surviving species.
+This rule prevents species allocation from collapsing entirely onto a few
+dominant lineages when the remaining slot budget is large enough to preserve
+a broader search frontier.
 
-Read it as the final safety rail after the diversity protections have done
-their work. The helper is not changing the policy goal; it is only forcing
-the final integer allocation back inside the available slot budget.
+In other words, this is the chapter's anti-monoculture guard. It only runs
+when the slot budget is big enough to afford that diversity protection.
 
 Parameters:
 - `internal` - - NEAT controller instance.
@@ -406,40 +382,35 @@ Parameters:
 
 Returns: Nothing.
 
-### buildSpeciesOffspring
+### enforcePopulationConstraints
 
 ```ts
-buildSpeciesOffspring(
+enforcePopulationConstraints(
   internal: NeatControllerForEvolution,
-  survivors: GenomeWithMetadata[],
-  speciesIndex: number,
-  crossSpeciesProbability: number,
-  crossSpeciesGuardLimit: number,
-  survivalThresholdDefault: number,
-): GenomeWithMetadata
+  nextPopulation: default[],
+): Promise<void>
 ```
 
-Build a single offspring within a species.
+Ensure new population meets structural constraints.
 
-This helper is the point where species-local survivor selection turns into
-one actual child. It chooses both parents, performs crossover, and annotates
-runtime lineage metadata so the resulting genome is ready for later telemetry,
-lineage, and inbreeding reads.
+Population assembly intentionally separates slot-filling from structural
+cleanup. Elites may already be valid, provenance genomes may come from a
+seed network or a fresh constructor path, and offspring may arrive from
+crossover with small topology issues that the controller routinely repairs.
+Running those repairs here keeps later evolve code free to assume the new
+population already satisfies the controller's minimum hidden-node and
+dead-end expectations.
 
-Conceptually, this is where the abstract allocation budget becomes one real
-experiment. Everything above this helper is still about counts and survivor
-pools; this helper is where the controller finally spends one unit of that
-budget on one concrete child genome.
+Keeping this repair pass at the end is a deliberate architecture choice. If
+every earlier helper tried to repair genomes inline, the chapter would blur
+slot-allocation policy together with structural-safety policy. Centralizing
+cleanup here keeps the earlier helpers focused on population composition.
 
 Parameters:
 - `internal` - - NEAT controller instance.
-- `survivors` - - Survivors pool for selection.
-- `speciesIndex` - - Species index.
-- `crossSpeciesProbability` - - Cross-species mating probability.
-- `crossSpeciesGuardLimit` - - Retry guard for cross-species selection.
-- `survivalThresholdDefault` - - Default survivor-window policy used when cross-species selection samples another species.
+- `nextPopulation` - - Population to validate.
 
-Returns: Offspring genome carrying runtime metadata.
+Returns: A promise that resolves after best-effort structural cleanup.
 
 ### selectSecondParent
 
@@ -475,3 +446,32 @@ Parameters:
 - `survivalThresholdDefault` - - Default survivor-window policy used when sampling another species.
 
 Returns: Chosen parent genome from the current or another species.
+
+### trimOversubscription
+
+```ts
+trimOversubscription(
+  internal: NeatControllerForEvolution,
+  allocation: number[],
+  remainingSlots: number,
+  minOffspringDefault: number,
+): void
+```
+
+Trim allocations when oversubscribed.
+
+Minimum-offspring guarantees can occasionally oversubscribe the remaining
+budget. This helper trims from the largest allocations first while still
+respecting the minimum line preserved for each surviving species.
+
+Read it as the final safety rail after the diversity protections have done
+their work. The helper is not changing the policy goal; it is only forcing
+the final integer allocation back inside the available slot budget.
+
+Parameters:
+- `internal` - - NEAT controller instance.
+- `allocation` - - Allocation array to adjust.
+- `remainingSlots` - - Total slots available.
+- `minOffspringDefault` - - Default minimum offspring.
+
+Returns: Nothing.

package/src/neat/evolve/runtime/README.md

@@ -36,20 +36,66 @@ flowchart TD
 
 ## neat/evolve/runtime/evolve.runtime.utils.ts
 
-### resolveStartTime
+### buildFittestSnapshot
 
 ```ts
-resolveStartTime(): number
+buildFittestSnapshot(
+  internal: NeatControllerForEvolution,
+): default
 ```
 
-Resolve the start time for an evolution step.
+Build a cloned Network from the current best genome.
 
-Evolve needs one timing origin that works in both browser-like and Node-like
-environments. This helper centralizes that choice so later elapsed-time reads
-can stay simple and the main evolve loop does not have to repeat environment
-detection inline.
+The returned value from `evolve()` is meant to describe the generation that
+was just analyzed, not the mutable genome object that will continue through
+later controller operations. This helper therefore clones the current leader
+into a standalone {@link Network} snapshot and preserves its score so callers
+can inspect, serialize, or replay the champion without depending on mutable
+controller-owned references.
 
-Returns: A timestamp in milliseconds or high-resolution timer units.
+Parameters:
+- `internal` - - NEAT controller instance.
+
+Returns: A detached best-network snapshot for the current generation.
+
+### clearPopulationScores
+
+```ts
+clearPopulationScores(
+  internal: NeatControllerForEvolution,
+): void
+```
+
+Clear genome scores to force re-evaluation.
+
+Once evolve has finished rebuilding and mutating the next population, the old
+scores are no longer trustworthy. This helper makes that contract explicit by
+clearing per-genome scores so the next call into the evolve or evaluate path
+cannot accidentally treat structurally changed genomes as already evaluated.
+
+Parameters:
+- `internal` - - NEAT controller instance.
+
+Returns: Nothing.
+
+### computeElapsedTime
+
+```ts
+computeElapsedTime(
+  startTimestamp: number,
+): number
+```
+
+Compute elapsed time since the start of evolve().
+
+Runtime reporting belongs here because evolve uses the result as generation
+bookkeeping rather than as a telemetry export concern. The helper mirrors the
+start-time environment fallback so timing stays comparable across runtimes.
+
+Parameters:
+- `startTimestamp` - - Start time resolved earlier.
+
+Returns: The elapsed runtime for the generation step.
 
 ### ensurePopulationEvaluated
 
@@ -72,26 +118,30 @@ Parameters:
 
 Returns: A promise that resolves once evaluation is guaranteed.
 
-### updateGlobalBestTracking
+### resolveHighResolutionNow
 
 ```ts
-updateGlobalBestTracking(
-  internal: NeatControllerForEvolution,
-): void
+resolveHighResolutionNow(): (() => number) | undefined
 ```
 
-Update generation-level best score tracking.
+Resolve a high-resolution timer callback when the runtime exposes one.
 
-This helper maintains the controller's lightweight "best score seen in the
-current generation window" markers. Those markers are intentionally separate
-from the cloned best-network snapshot so the evolve loop can cheaply decide
-whether a fresh improvement occurred without conflating score bookkeeping with
-network serialization.
+Returns: Timer callback or `undefined` when only wall-clock time is available.
 
-Parameters:
-- `internal` - - NEAT controller instance.
+### resolveStartTime
 
-Returns: Nothing.
+```ts
+resolveStartTime(): number
+```
+
+Resolve the start time for an evolution step.
+
+Evolve needs one timing origin that works in both browser-like and Node-like
+environments. This helper centralizes that choice so later elapsed-time reads
+can stay simple and the main evolve loop does not have to repeat environment
+detection inline.
+
+Returns: A timestamp in milliseconds or high-resolution timer units.
 
 ### trackGlobalImprovement
 
@@ -116,73 +166,23 @@ Parameters:
 
 Returns: Nothing.
 
-### computeElapsedTime
-
-```ts
-computeElapsedTime(
-  startTimestamp: number,
-): number
-```
-
-Compute elapsed time since the start of evolve().
-
-Runtime reporting belongs here because evolve uses the result as generation
-bookkeeping rather than as a telemetry export concern. The helper mirrors the
-start-time environment fallback so timing stays comparable across runtimes.
-
-Parameters:
-- `startTimestamp` - - Start time resolved earlier.
-
-Returns: The elapsed runtime for the generation step.
-
-### clearPopulationScores
+### updateGlobalBestTracking
 
 ```ts
-clearPopulationScores(
+updateGlobalBestTracking(
   internal: NeatControllerForEvolution,
 ): void
 ```
 
-Clear genome scores to force re-evaluation.
+Update generation-level best score tracking.
 
-Once evolve has finished rebuilding and mutating the next population, the old
-scores are no longer trustworthy. This helper makes that contract explicit by
-clearing per-genome scores so the next call into the evolve or evaluate path
-cannot accidentally treat structurally changed genomes as already evaluated.
+This helper maintains the controller's lightweight "best score seen in the
+current generation window" markers. Those markers are intentionally separate
+from the cloned best-network snapshot so the evolve loop can cheaply decide
+whether a fresh improvement occurred without conflating score bookkeeping with
+network serialization.
 
 Parameters:
 - `internal` - - NEAT controller instance.
 
 Returns: Nothing.
-
-### buildFittestSnapshot
-
-```ts
-buildFittestSnapshot(
-  internal: NeatControllerForEvolution,
-): default
-```
-
-Build a cloned Network from the current best genome.
-
-The returned value from `evolve()` is meant to describe the generation that
-was just analyzed, not the mutable genome object that will continue through
-later controller operations. This helper therefore clones the current leader
-into a standalone {@link Network} snapshot and preserves its score so callers
-can inspect, serialize, or replay the champion without depending on mutable
-controller-owned references.
-
-Parameters:
-- `internal` - - NEAT controller instance.
-
-Returns: A detached best-network snapshot for the current generation.
-
-### resolveHighResolutionNow
-
-```ts
-resolveHighResolutionNow(): (() => number) | undefined
-```
-
-Resolve a high-resolution timer callback when the runtime exposes one.
-
-Returns: Timer callback or `undefined` when only wall-clock time is available.