@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -37,6 +37,36 @@ flowchart TD
 
 ## neat/evolve/speciation/evolve.speciation.utils.ts
 
+### applyGlobalStagnationInjectionIfNeeded
+
+```ts
+applyGlobalStagnationInjectionIfNeeded(
+  internal: NeatControllerForEvolution,
+  helpers: { buildFreshGenomeForStagnation: () => Promise<GenomeWithMetadata>; replaceFraction: number; },
+): Promise<void>
+```
+
+Apply global stagnation injection if configured.
+
+This is the evolve loop's constrained recovery valve for long periods without
+global improvement. Instead of discarding the whole population or rebuilding
+the generation logic from scratch, the helper replaces only the worst-ranked
+fraction beyond elitism with fresh genomes, then resets the stagnation window
+so the controller can test whether the new search seeds reopen progress.
+
+The design is intentionally conservative:
+
+- elites are preserved,
+- the replacement fraction is bounded by the caller,
+- injected genomes still pass through the normal later evolution pipeline.
+
+Parameters:
+- `internal` - - NEAT controller instance.
+- `helpers` - - Helper callbacks for stagnation injection.
+- `helpers` - - Genome builder for injection.
+
+Returns: A promise that resolves after bounded replacements are complete.
+
 ### applySpeciationAndSharingIfEnabled
 
 ```ts
@@ -90,80 +120,43 @@ Parameters:
 
 Returns: A new genome prepared for bounded stagnation rescue.
 
-### recordSpeciesHistorySnapshot
-
-```ts
-recordSpeciesHistorySnapshot(
-  internal: NeatControllerForEvolution,
-  maxHistory: number,
-): void
-```
-
-Record a species history snapshot when needed.
-
-This helper preserves a minimal per-generation history row for downstream
-readers that expect species-history evidence even when the heavier extended
-history path is disabled. It deliberately records only lightweight summary
-fields, keeps one row per generation, and trims to a bounded rolling window
-so evolve can maintain export-friendly evidence without turning this bridge
-into the full history-enrichment layer.
-
-Parameters:
-- `internal` - - NEAT controller instance.
-- `maxHistory` - - Maximum history length.
-
-Returns: Nothing.
-
-### updateSpeciesStagnationIfEnabled
+### buildSpeciesHistoryStats
 
 ```ts
-updateSpeciesStagnationIfEnabled(
-  internal: NeatControllerForEvolution,
-): void
+buildSpeciesHistoryStats(
+  speciesList: SpeciesWithMetadata[],
+): { id: number; size: number; avgSharedFitness?: number | undefined; bestScore?: number | undefined; lastImproved?: number | undefined; }[]
 ```
 
-Update species stagnation status when speciation enabled.
-
-The stagnation update remains optional because some evolve configurations use
-the broader selection and replacement machinery without long-lived species
-maintenance. When speciation is active, this helper advances the species-side
-stagnation counters so later allocation and pruning decisions can distinguish
-between active lineages and species that have stopped improving.
+Build the minimal species-history row shape used by evolve-side snapshots.
 
 Parameters:
-- `internal` - - NEAT controller instance.
+- `speciesList` - - Live species registry for the current generation.
 
-Returns: Nothing.
+Returns: Summary rows aligned with the shared species history contract.
 
-### applyGlobalStagnationInjectionIfNeeded
+### ensureHiddenNodeVariance
 
 ```ts
-applyGlobalStagnationInjectionIfNeeded(
+ensureHiddenNodeVariance(
   internal: NeatControllerForEvolution,
-  helpers: { buildFreshGenomeForStagnation: () => Promise<GenomeWithMetadata>; replaceFraction: number; },
+  genome: GenomeWithMetadata,
 ): Promise<void>
 ```
 
-Apply global stagnation injection if configured.
-
-This is the evolve loop's constrained recovery valve for long periods without
-global improvement. Instead of discarding the whole population or rebuilding
-the generation logic from scratch, the helper replaces only the worst-ranked
-fraction beyond elitism with fresh genomes, then resets the stagnation window
-so the controller can test whether the new search seeds reopen progress.
-
-The design is intentionally conservative:
+Ensure a minimal hidden-node variance in injected genomes.
 
-- elites are preserved,
-- the replacement fraction is bounded by the caller,
-- injected genomes still pass through the normal later evolution pipeline.
+Fresh stagnation-recovery genomes can otherwise collapse into the smallest
+legal topology and fail to contribute structural novelty. This helper adds
+one conservative hidden-node bridge when the injected genome has no hidden
+layer at all, preserving the idea that rescue should re-open search space
+rather than only reshuffle minimal direct input-output paths.
 
 Parameters:
 - `internal` - - NEAT controller instance.
-- `helpers` - - Helper callbacks for stagnation injection.
-- `helpers` - - Genome builder for injection.
+- `genome` - - Genome to adjust.
 
-Returns: A promise that resolves after bounded replacements are complete.
+Returns: A promise that resolves after best-effort variance injection.
 
 ### ensureSpeciesHistorySnapshot
 
@@ -188,40 +181,47 @@ Parameters:
 
 Returns: Nothing.
 
-### ensureHiddenNodeVariance
+### recordSpeciesHistorySnapshot
 
 ```ts
-ensureHiddenNodeVariance(
+recordSpeciesHistorySnapshot(
   internal: NeatControllerForEvolution,
-  genome: GenomeWithMetadata,
-): Promise<void>
+  maxHistory: number,
+): void
 ```
 
-Ensure a minimal hidden-node variance in injected genomes.
+Record a species history snapshot when needed.
 
-Fresh stagnation-recovery genomes can otherwise collapse into the smallest
-legal topology and fail to contribute structural novelty. This helper adds
-one conservative hidden-node bridge when the injected genome has no hidden
-layer at all, preserving the idea that rescue should re-open search space
-rather than only reshuffle minimal direct input-output paths.
+This helper preserves a minimal per-generation history row for downstream
+readers that expect species-history evidence even when the heavier extended
+history path is disabled. It deliberately records only lightweight summary
+fields, keeps one row per generation, and trims to a bounded rolling window
+so evolve can maintain export-friendly evidence without turning this bridge
+into the full history-enrichment layer.
 
 Parameters:
 - `internal` - - NEAT controller instance.
-- `genome` - - Genome to adjust.
+- `maxHistory` - - Maximum history length.
 
-Returns: A promise that resolves after best-effort variance injection.
+Returns: Nothing.
 
-### buildSpeciesHistoryStats
+### updateSpeciesStagnationIfEnabled
 
 ```ts
-buildSpeciesHistoryStats(
-  speciesList: SpeciesWithMetadata[],
-): { id: number; size: number; avgSharedFitness?: number | undefined; bestScore?: number | undefined; lastImproved?: number | undefined; }[]
+updateSpeciesStagnationIfEnabled(
+  internal: NeatControllerForEvolution,
+): void
 ```
 
-Build the minimal species-history row shape used by evolve-side snapshots.
+Update species stagnation status when speciation enabled.
+
+The stagnation update remains optional because some evolve configurations use
+the broader selection and replacement machinery without long-lived species
+maintenance. When speciation is active, this helper advances the species-side
+stagnation counters so later allocation and pruning decisions can distinguish
+between active lineages and species that have stopped improving.
 
 Parameters:
-- `speciesList` - - Live species registry for the current generation.
+- `internal` - - NEAT controller instance.
 
-Returns: Summary rows aligned with the shared species history contract.
+Returns: Nothing.

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

@@ -19,6 +19,16 @@ Read this chapter when you want to understand:
 
 ## neat/evolve/warnings/evolve.warnings.utils.ts
 
+### EVOLVE_NO_BEST_GENOME_WARNING
+
+Warning emitted when evolution finishes without a best genome.
+
+This message signals that the generation loop completed without producing a
+champion snapshot that the controller considers safe to return. That usually
+points to an upstream evaluation or population-state problem rather than to a
+normal low-fitness generation, so the wording intentionally distinguishes
+"no valid best genome" from merely "no improvement."
+
 ### warnIfNoBestGenome
 
 ```ts
@@ -31,13 +41,3 @@ The helper is deliberately conservative: it tries to warn, but it does not
 let missing or restricted console support destabilize the evolve loop further.
 That keeps warning emission informative for normal runtimes while preserving a
 best-effort contract for test harnesses and embedded environments.
-
-### EVOLVE_NO_BEST_GENOME_WARNING
-
-Warning emitted when evolution finishes without a best genome.
-
-This message signals that the generation loop completed without producing a
-champion snapshot that the controller considers safe to return. That usually
-points to an upstream evaluation or population-state problem rather than to a
-normal low-fitness generation, so the wording intentionally distinguishes
-"no valid best genome" from merely "no improvement."

package/src/neat/export/README.md

@@ -70,38 +70,6 @@ fs.writeFileSync('population.json', JSON.stringify(popSnapshot, null, 2));
 
 Returns: Array of genome JSON objects.
 
-### importPopulation
-
-```ts
-importPopulation(
-  populationJSON: GenomeJSON[],
-): Promise<void>
-```
-
-Import (replace) the current population from an array of serialized genomes.
-This does not touch NEAT meta state (generation, innovations, etc.) - only the
-population array and implied `popsize` are updated.
-That makes it the right tool when you want to swap candidate solutions into an
-existing controller context instead of restoring a full historical checkpoint.
-
-Example:
-
-```ts
-const populationData: GenomeJSON[] = JSON.parse(fs.readFileSync('population.json', 'utf8'));
-neat.importPopulation(populationData); // population replaced
-neat.evolve(); // continue evolving with new starting genomes
-```
-
-Edge cases handled:
-- Empty array => becomes an empty population (popsize=0).
-- Malformed entries will throw if `Network.fromJSON` rejects them.
-
-Parameters:
-- `populationJSON` - Array of serialized genome objects.
-
-Returns: Promise that resolves once all genomes have been rehydrated and the
-controller population has been replaced.
-
 ### exportState
 
 ```ts
@@ -128,68 +96,6 @@ const neat2 = Neat.importState(raw, fitnessFn); // identical evolutionary contex
 
 Returns: A  {@link NeatStateJSON} bundle containing meta + population.
 
-### importStateImpl
-
-```ts
-importStateImpl(
-  stateBundle: NeatStateJSON,
-  fitnessFunction: (network: GenomeWithSerialization) => number | Promise<number>,
-): Promise<NeatControllerForExport>
-```
-
-Static-style helper that rehydrates a full evolutionary state previously
-produced by {@link exportState}. Invoke this with the NEAT class (not an
-instance) bound as `this`, e.g. `Neat.importStateImpl(bundle, fitnessFn)`.
-It constructs a new NEAT instance using the meta data, then imports the
-population (if present).
-
-This is the most complete restore path in the chapter. If a saved bundle is
-valid, the caller gets back a fresh controller that knows both where the run
-was in evolutionary time and which genomes were alive at that moment.
-
-Safety and validation:
-- Throws if the bundle is not an object.
-- Silently skips population import if `population` is missing or not an array.
-
-Example:
-
-```ts
-const bundle: NeatStateJSON = JSON.parse(fs.readFileSync('state.json', 'utf8'));
-const neat = Neat.importStateImpl(bundle, fitnessFn);
-neat.evolve();
-```
-
-Parameters:
-- `stateBundle` - Full state bundle from  {@link exportState} .
-- `fitnessFunction` - Fitness evaluation callback used for new instance.
-
-Returns: Rehydrated NEAT instance ready to continue evolving.
-
-### toJSONImpl
-
-```ts
-toJSONImpl(): NeatMetaJSON
-```
-
-Serialize NEAT meta (excluding the mutable population) for persistence of
-innovation history and experiment configuration. This is sufficient to
-recreate a blank NEAT run at the same evolutionary generation with the same
-innovation counters, enabling deterministic continuation when combined later
-with a saved population.
-
-Use this path when the controller context matters but the population payload
-should be stored, transferred, or versioned separately.
-
-Example:
-
-```ts
-const meta = neat.toJSONImpl();
-fs.writeFileSync('neat-meta.json', JSON.stringify(meta));
-// ... later ...
-const metaLoaded = JSON.parse(fs.readFileSync('neat-meta.json', 'utf8')) as NeatMetaJSON;
-const neat2 = Neat.fromJSONImpl(metaLoaded, fitnessFn); // empty population
-```
-
 ### fromJSONImpl
 
 ```ts
@@ -234,21 +140,81 @@ export helpers preserve whatever `Network#toJSON()` emits, which lets the
 broader architecture evolve without forcing this chapter to hard-code every
 possible serialized field.
 
-### NeatMetaJSON
+### GenomeWithSerialization
 
-Serialized meta information describing a NEAT run, excluding the concrete
-population genomes. This allows you to persist and resume experiment context
-without committing to a particular population snapshot.
+Genome with toJSON serialization method.
 
-### NeatStateJSON
+This is the smallest runtime contract needed by the export helpers when they
+only care about turning one genome into a JSON payload.
 
-Top-level bundle containing both NEAT meta information and the full array of
-serialized genomes (population). This is what you get from `exportState()` and
-feed into `importStateImpl()` to resume exactly where you left off.
+### importPopulation
 
-If `NeatMetaJSON` is the controller checkpoint and `GenomeJSON[]` is the pool
-of candidate solutions, `NeatStateJSON` is the combined pause-and-resume
-artifact that preserves both layers together.
+```ts
+importPopulation(
+  populationJSON: GenomeJSON[],
+): Promise<void>
+```
+
+Import (replace) the current population from an array of serialized genomes.
+This does not touch NEAT meta state (generation, innovations, etc.) - only the
+population array and implied `popsize` are updated.
+That makes it the right tool when you want to swap candidate solutions into an
+existing controller context instead of restoring a full historical checkpoint.
+
+Example:
+
+```ts
+const populationData: GenomeJSON[] = JSON.parse(fs.readFileSync('population.json', 'utf8'));
+neat.importPopulation(populationData); // population replaced
+neat.evolve(); // continue evolving with new starting genomes
+```
+
+Edge cases handled:
+- Empty array => becomes an empty population (popsize=0).
+- Malformed entries will throw if `Network.fromJSON` rejects them.
+
+Parameters:
+- `populationJSON` - Array of serialized genome objects.
+
+Returns: Promise that resolves once all genomes have been rehydrated and the
+controller population has been replaced.
+
+### importStateImpl
+
+```ts
+importStateImpl(
+  stateBundle: NeatStateJSON,
+  fitnessFunction: (network: GenomeWithSerialization) => number | Promise<number>,
+): Promise<NeatControllerForExport>
+```
+
+Static-style helper that rehydrates a full evolutionary state previously
+produced by {@link exportState}. Invoke this with the NEAT class (not an
+instance) bound as `this`, e.g. `Neat.importStateImpl(bundle, fitnessFn)`.
+It constructs a new NEAT instance using the meta data, then imports the
+population (if present).
+
+This is the most complete restore path in the chapter. If a saved bundle is
+valid, the caller gets back a fresh controller that knows both where the run
+was in evolutionary time and which genomes were alive at that moment.
+
+Safety and validation:
+- Throws if the bundle is not an object.
+- Silently skips population import if `population` is missing or not an array.
+
+Example:
+
+```ts
+const bundle: NeatStateJSON = JSON.parse(fs.readFileSync('state.json', 'utf8'));
+const neat = Neat.importStateImpl(bundle, fitnessFn);
+neat.evolve();
+```
+
+Parameters:
+- `stateBundle` - Full state bundle from  {@link exportState} .
+- `fitnessFunction` - Fitness evaluation callback used for new instance.
+
+Returns: Rehydrated NEAT instance ready to continue evolving.
 
 ### InnovationMapEntry
 
@@ -257,12 +223,13 @@ Connection innovation map entry.
 Innovation maps are serialized as `[key, value]` tuples so they can round-trip
 cleanly through JSON and later be restored into `Map` instances.
 
-### GenomeWithSerialization
+### NeatConstructor
 
-Genome with toJSON serialization method.
+NEAT class constructor interface.
 
-This is the smallest runtime contract needed by the export helpers when they
-only care about turning one genome into a JSON payload.
+Static-style restore helpers depend on this constructor shape so they can
+rebuild a controller instance from persisted meta data and then optionally
+rehydrate the population.
 
 ### NeatControllerForExport
 
@@ -273,6 +240,22 @@ of the concrete `Neat` class. That keeps export and restore logic reusable in
 tests and static-style helper flows without coupling the file to the full
 controller implementation.
 
+### NeatMetaJSON
+
+Serialized meta information describing a NEAT run, excluding the concrete
+population genomes. This allows you to persist and resume experiment context
+without committing to a particular population snapshot.
+
+### NeatStateJSON
+
+Top-level bundle containing both NEAT meta information and the full array of
+serialized genomes (population). This is what you get from `exportState()` and
+feed into `importStateImpl()` to resume exactly where you left off.
+
+If `NeatMetaJSON` is the controller checkpoint and `GenomeJSON[]` is the pool
+of candidate solutions, `NeatStateJSON` is the combined pause-and-resume
+artifact that preserves both layers together.
+
 ### NetworkClass
 
 Network class with static fromJSON method.
@@ -280,10 +263,27 @@ Network class with static fromJSON method.
 Import helpers use this contract when rebuilding genomes from serialized JSON
 without needing to know the concrete network implementation details.
 
-### NeatConstructor
+### toJSONImpl
 
-NEAT class constructor interface.
+```ts
+toJSONImpl(): NeatMetaJSON
+```
 
-Static-style restore helpers depend on this constructor shape so they can
-rebuild a controller instance from persisted meta data and then optionally
-rehydrate the population.
+Serialize NEAT meta (excluding the mutable population) for persistence of
+innovation history and experiment configuration. This is sufficient to
+recreate a blank NEAT run at the same evolutionary generation with the same
+innovation counters, enabling deterministic continuation when combined later
+with a saved population.
+
+Use this path when the controller context matters but the population payload
+should be stored, transferred, or versioned separately.
+
+Example:
+
+```ts
+const meta = neat.toJSONImpl();
+fs.writeFileSync('neat-meta.json', JSON.stringify(meta));
+// ... later ...
+const metaLoaded = JSON.parse(fs.readFileSync('neat-meta.json', 'utf8')) as NeatMetaJSON;
+const neat2 = Neat.fromJSONImpl(metaLoaded, fitnessFn); // empty population
+```

package/src/neat/helpers/README.md

@@ -51,56 +51,6 @@ cross the boundary into the live population in a normalized state?
 
 ## neat/helpers/neat.helpers.ts
 
-### spawnFromParent
-
-```ts
-spawnFromParent(
-  parentGenome: GenomeWithMetadata,
-  mutateCount: number,
-): Promise<GenomeWithMetadata>
-```
-
-Spawn (clone & mutate) a child genome from an existing parent genome.
-
-Read this helper as the provisional provenance path. It produces a candidate
-offspring whose lineage is already meaningful, but whose membership in the
-active population is still undecided. That split is important when a caller
-wants to preview, filter, score, or compare several children before allowing
-one of them to join the population through {@link addGenome}.
-
-Evolutionary rationale:
-- Cloning preserves the full topology and weights of the parent.
-- A configurable number of mutation passes are applied sequentially; each
-  pass may alter structure (add/remove nodes or connections) or weights.
-- Lineage annotations (`_parents`, `_depth`) enable later analytics such as
-  diversity statistics, genealogy visualization, and pruning heuristics.
-- Cache invalidation happens before the child is returned so later admission
-  or evaluation logic never observes stale derived state from the clone.
-
-Robustness philosophy: individual mutation failures are silently ignored so a
-single stochastic edge case does not derail evolutionary progress.
-
-Parameters:
-- `this` - Bound NEAT instance (inferred when used as a method).
-- `parentGenome` - Parent genome/network to clone. Must implement either
-`clone()` OR a pair of `toJSON()` / static `fromJSON()` for deep copying.
-- `mutateCount` - Number of sequential mutation operations to attempt; each
-iteration chooses a mutation method using the instance's selection
-logic. Defaults to 1 for conservative structural drift.
-
-Returns: A new genome whose score and derived caches are reset, whose lineage
-metadata references the parent, and whose final admission into the
-live population is left to the caller.
-
-Example:
-
-```ts
-// Assume `neat` is an instance implementing NeatLike and `parent` is a genome in neat.population
-const child = neat.spawnFromParent(parent, 3); // apply 3 mutation passes
-// Optionally inspect / filter the child before adding
-neat.addGenome(child, [parent._id]);
-```
-
 ### addGenome
 
 ```ts
@@ -230,3 +180,53 @@ In practice this seam protects two invariants:
 - every entering genome receives the same controller-owned metadata shape,
 - every entry path applies the same best-effort cleanup before later chapters
   read the genome.
+
+### spawnFromParent
+
+```ts
+spawnFromParent(
+  parentGenome: GenomeWithMetadata,
+  mutateCount: number,
+): Promise<GenomeWithMetadata>
+```
+
+Spawn (clone & mutate) a child genome from an existing parent genome.
+
+Read this helper as the provisional provenance path. It produces a candidate
+offspring whose lineage is already meaningful, but whose membership in the
+active population is still undecided. That split is important when a caller
+wants to preview, filter, score, or compare several children before allowing
+one of them to join the population through {@link addGenome}.
+
+Evolutionary rationale:
+- Cloning preserves the full topology and weights of the parent.
+- A configurable number of mutation passes are applied sequentially; each
+  pass may alter structure (add/remove nodes or connections) or weights.
+- Lineage annotations (`_parents`, `_depth`) enable later analytics such as
+  diversity statistics, genealogy visualization, and pruning heuristics.
+- Cache invalidation happens before the child is returned so later admission
+  or evaluation logic never observes stale derived state from the clone.
+
+Robustness philosophy: individual mutation failures are silently ignored so a
+single stochastic edge case does not derail evolutionary progress.
+
+Parameters:
+- `this` - Bound NEAT instance (inferred when used as a method).
+- `parentGenome` - Parent genome/network to clone. Must implement either
+`clone()` OR a pair of `toJSON()` / static `fromJSON()` for deep copying.
+- `mutateCount` - Number of sequential mutation operations to attempt; each
+iteration chooses a mutation method using the instance's selection
+logic. Defaults to 1 for conservative structural drift.
+
+Returns: A new genome whose score and derived caches are reset, whose lineage
+metadata references the parent, and whose final admission into the
+live population is left to the caller.
+
+Example:
+
+```ts
+// Assume `neat` is an instance implementing NeatLike and `parent` is a genome in neat.population
+const child = neat.spawnFromParent(parent, 3); // apply 3 mutation passes
+// Optionally inspect / filter the child before adding
+neat.addGenome(child, [parent._id]);
+```

package/src/neat/init/README.md

@@ -118,6 +118,15 @@ After the call returns, the instance has concrete startup policy, prepared
 controller state, and either an attempted generation-zero pool or a safely
 preserved empty population ready for later work.
 
+### InitializeNeatConstructorRequest
+
+Mutable constructor request packet consumed during bootstrap.
+
+`optionBag` is the live options object that the public facade keeps after the
+constructor returns, `rawOptions` preserves the caller's original intent for
+checks that should not be default-inflated, and `defaults` supplies the
+public baseline constants exported by the surrounding NEAT surface.
+
 ### NeatConstructorDefaults
 
 ### NeatInitializationHost
@@ -129,12 +138,3 @@ helper needs write access to a few controller-owned fields and one pool
 creation hook, but it does not own evaluation, evolution, or persistence.
 Keeping the contract narrow prevents the init chapter from quietly becoming a
 second facade.
-
-### InitializeNeatConstructorRequest
-
-Mutable constructor request packet consumed during bootstrap.
-
-`optionBag` is the live options object that the public facade keeps after the
-constructor returns, `rawOptions` preserves the caller's original intent for
-checks that should not be default-inflated, and `defaults` supplies the
-public baseline constants exported by the surrounding NEAT surface.