@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/README.md

@@ -17,27 +17,20 @@ Read the file in three passes:
 
 ## neat/neat.types.ts
 
-### NeatOptions
-
-Public configuration bag accepted by the root `Neat` constructor.
-
-This alias stays intentionally permissive because the public boundary still
-absorbs legacy experiment bags, partially migrated option families, and a
-few chapter-local knobs that do not yet deserve a tighter shared contract.
-
-That looseness is a boundary choice rather than a shared-type ideal. The
-root facade accepts the broad option surface so the deeper helper chapters
-can keep narrowing their own local slices instead of reintroducing one wide
-compatibility bag in multiple places.
+### NeatExportFitnessFunction
 
-### NeatFitnessResult
+```ts
+NeatExportFitnessFunction(
+  network: GenomeWithSerialization,
+): number | Promise<number>
+```
 
-Opaque result shape returned by root-level fitness callbacks.
+Fitness callback shape expected by the export/import restore helpers.
 
-The top-level `Neat` entrypoint has to tolerate both single-genome and
-population-wide fitness styles, including delegates that perform async work
-or side effects before downstream evaluation helpers interpret the result.
-The root contract therefore stays wide on purpose.
+The persistence chapter reconstructs a controller from serialized state and
+then reattaches a scoring delegate. The root surface derives that callback
+type from the export chapter so the static restore helpers stay in lockstep
+with the real persistence contract.
 
 ### NeatFitnessFunction
 
@@ -54,6 +47,15 @@ every legal scoring protocol. The constructor only promises that a scoring
 delegate can be stored and forwarded safely; the stronger semantics live in
 the evaluation and evolve chapters that actually consume the callback.
 
+### NeatFitnessResult
+
+Opaque result shape returned by root-level fitness callbacks.
+
+The top-level `Neat` entrypoint has to tolerate both single-genome and
+population-wide fitness styles, including delegates that perform async work
+or side effects before downstream evaluation helpers interpret the result.
+The root contract therefore stays wide on purpose.
+
 ### NeatMutationSelectionResult
 
 Awaited return shape for the public mutation-method selection wrapper.
@@ -62,6 +64,19 @@ The mutation chapter already owns the concrete union. This alias keeps the
 root class synchronized with that source of truth without repeating a legacy
 compatibility union inline.
 
+### NeatOptions
+
+Public configuration bag accepted by the root `Neat` constructor.
+
+This alias stays intentionally permissive because the public boundary still
+absorbs legacy experiment bags, partially migrated option families, and a
+few chapter-local knobs that do not yet deserve a tighter shared contract.
+
+That looseness is a boundary choice rather than a shared-type ideal. The
+root facade accepts the broad option surface so the deeper helper chapters
+can keep narrowing their own local slices instead of reintroducing one wide
+compatibility bag in multiple places.
+
 ### NeatRngStateSnapshot
 
 Replay token accepted by the public RNG restore and import methods.
@@ -70,21 +85,6 @@ Deriving the token from the RNG facade keeps the root entrypoint aligned with
 the replay chapter instead of maintaining a second hand-written copy of the
 same restore contract.
 
-### NeatExportFitnessFunction
-
-```ts
-NeatExportFitnessFunction(
-  network: GenomeWithSerialization,
-): number | Promise<number>
-```
-
-Fitness callback shape expected by the export/import restore helpers.
-
-The persistence chapter reconstructs a controller from serialized state and
-then reattaches a scoring delegate. The root surface derives that callback
-type from the export chapter so the static restore helpers stay in lockstep
-with the real persistence contract.
-
 ## neat/neat.lineage.ts
 
 ### buildAnc
@@ -262,22 +262,22 @@ Read it as the controller's everyday guard rail: small enough to stay out of
 the way of ordinary calculations, but present anywhere a divide-by-zero or a
 log-of-zero edge could quietly poison downstream training or telemetry.
 
-### PROB_EPSILON
+### EXTRA_CONNECTION_PROBABILITY
 
-Probability-scale safety constant for very small ratios and logarithms.
+Default heuristic for one opportunistic extra add-connection attempt.
 
-This is intentionally smaller than {@link EPSILON} because probability terms
-often need protection without materially changing the magnitude of already
-tiny values.
+This is a heuristic rather than a numerical safety constant. It slightly
+increases the chance that a genome gains new connectivity during mutation
+without making extra-connection attempts mandatory on every pass.
 
-Reach for this when the math is closer to "protect a probability-like term"
-than to "stabilize a general denominator". The smaller offset helps keep
-loss-style or entropy-style quantities numerically safe while staying closer
-to the original scale.
+Treat this as a small statement about controller personality: the default
+search policy is willing to occasionally spend extra effort on connectivity
+growth, but it does not force that gamble on every mutation cycle.
 
-In practice this constant teaches a useful distinction: not every safety fix
-should be equally large. Probability-like quantities often need a gentler
-nudge than general controller arithmetic.
+That makes this constant the policy counterpart to the epsilon family. The
+epsilons say how carefully the controller protects its math; this value says
+how adventurous the default mutation policy is willing to be when a little
+extra connectivity might unlock better search.
 
 ### NORM_EPSILON
 
@@ -296,22 +296,22 @@ spread, and normalization math often benefit from a visibly larger floor than
 probability math, because the goal is smooth controller behavior rather than
 near-exact preservation of microscopic values.
 
-### EXTRA_CONNECTION_PROBABILITY
+### PROB_EPSILON
 
-Default heuristic for one opportunistic extra add-connection attempt.
+Probability-scale safety constant for very small ratios and logarithms.
 
-This is a heuristic rather than a numerical safety constant. It slightly
-increases the chance that a genome gains new connectivity during mutation
-without making extra-connection attempts mandatory on every pass.
+This is intentionally smaller than {@link EPSILON} because probability terms
+often need protection without materially changing the magnitude of already
+tiny values.
 
-Treat this as a small statement about controller personality: the default
-search policy is willing to occasionally spend extra effort on connectivity
-growth, but it does not force that gamble on every mutation cycle.
+Reach for this when the math is closer to "protect a probability-like term"
+than to "stabilize a general denominator". The smaller offset helps keep
+loss-style or entropy-style quantities numerically safe while staying closer
+to the original scale.
 
-That makes this constant the policy counterpart to the epsilon family. The
-epsilons say how carefully the controller protects its math; this value says
-how adventurous the default mutation policy is willing to be when a little
-extra connectivity might unlock better search.
+In practice this constant teaches a useful distinction: not every safety fix
+should be equally large. Probability-like quantities often need a gentler
+nudge than general controller arithmetic.
 
 ## neat/neat.diversity.ts
 
@@ -376,6 +376,23 @@ if (diversity) {
 }
 ```
 
+### DiversityStats
+
+Diversity statistics returned by sampled population analysis.
+
+Treat this as a compact population-health report rather than as a single
+scalar "diversity score." The fields are grouped deliberately:
+
+- lineage fields show whether ancestry depth is spreading or collapsing,
+- node and connection fields show average structural size and unevenness,
+- compatibility sampling estimates how genetically separated sampled peers
+  remain,
+- entropy adds a shape signal that raw size counts cannot capture.
+
+In practice, telemetry consumers compare this object across generations to
+see whether mutation, speciation, and pruning are still producing meaningful
+variation without paying for exhaustive all-pairs analysis.
+
 ### MAX_COMPATIBILITY_SAMPLE
 
 Maximum population sample size for compatibility comparisons.
@@ -418,23 +435,6 @@ Parameters:
 
 Returns: Shannon-style entropy of the out-degree distribution.
 
-### DiversityStats
-
-Diversity statistics returned by sampled population analysis.
-
-Treat this as a compact population-health report rather than as a single
-scalar "diversity score." The fields are grouped deliberately:
-
-- lineage fields show whether ancestry depth is spreading or collapsing,
-- node and connection fields show average structural size and unevenness,
-- compatibility sampling estimates how genetically separated sampled peers
-  remain,
-- entropy adds a shape signal that raw size counts cannot capture.
-
-In practice, telemetry consumers compare this object across generations to
-see whether mutation, speciation, and pruning are still producing meaningful
-variation without paying for exhaustive all-pairs analysis.
-
 ## neat/neat.defaults.constants.ts
 
 Public default knobs for the root `Neat` controller.
@@ -455,64 +455,54 @@ Read them as the public defaults shelf, not as hidden implementation trivia.
 These values are the baseline promises the root controller makes when a user
 says, "give me an ordinary NEAT run," without specifying every knob.
 
-### DEFAULT_POPULATION_SIZE
-
-Default population size when caller does not specify `popsize`.
-
-This opens the root defaults shelf's search-volume family. It controls how
-many genomes compete in each generation before elitism, provenance, or
-mutation pressure begin to reshape the population.
-
-### DEFAULT_ELITISM
+### DEFAULT_COMPATIBILITY_THRESHOLD
 
-Default elitism count applied when unspecified.
+Default compatibility threshold controlling speciation distance.
 
-Read this beside {@link DEFAULT_POPULATION_SIZE} and
-{@link DEFAULT_PROVENANCE}: the trio defines how much of each generation is
-reserved for carry-over, how much is freshly injected, and how much capacity
-remains for ordinary offspring.
+This starts the speciation-pressure family of defaults. It is the neutral
+boundary the controller uses before adaptive tuning or custom settings make
+species splits stricter or more permissive.
 
-### DEFAULT_PROVENANCE
+### DEFAULT_DISJOINT_COEFF
 
-Default provenance count applied when unspecified.
+Default disjoint coefficient for NEAT compatibility distance.
 
-Provenance is the root controller's small "fresh seed" policy. A value of
-`0` means the default run does not spend population budget on extra
-generation-zero style injections unless the caller asks for them.
+Matching the excess coefficient by default gives the root controller a
+balanced structural view: excess and disjoint innovation gaps both count as
+first-class evidence during compatibility comparisons.
 
-### DEFAULT_MUTATION_RATE
+### DEFAULT_DIVERSITY_GRAPHLET_SAMPLE
 
-Default mutation rate used by the root controller when no explicit rate is supplied.
+Default graphlet sample size used by diversity metrics in fast mode.
 
-This belongs to the same search-tempo family as
-{@link DEFAULT_MUTATION_AMOUNT}. Together they define how often mutation is
-attempted and how many mutation steps a genome can receive once mutation is
-active.
+Read this beside {@link DEFAULT_DIVERSITY_PAIR_SAMPLE}: pair samples give the
+controller quick distance evidence, while graphlet samples provide a small
+structural texture read without forcing whole-population analysis.
 
-### DEFAULT_MUTATION_AMOUNT
+### DEFAULT_DIVERSITY_PAIR_SAMPLE
 
-Default number of mutation operations applied per genome.
+Default pair-sample size used by diversity metrics in fast mode.
 
-The default keeps the baseline search policy conservative: most runs mutate
-often enough to keep topology moving, but each genome usually pays for only
-one structural or parametric change per mutation pass.
+This starts the observability-sampling family. The root controller uses a
+bounded sample instead of exhaustive pair checks so diversity reads stay
+cheap enough for ordinary runs.
 
-### DEFAULT_COMPATIBILITY_THRESHOLD
+### DEFAULT_ELITISM
 
-Default compatibility threshold controlling speciation distance.
+Default elitism count applied when unspecified.
 
-This starts the speciation-pressure family of defaults. It is the neutral
-boundary the controller uses before adaptive tuning or custom settings make
-species splits stricter or more permissive.
+Read this beside {@link DEFAULT_POPULATION_SIZE} and
+{@link DEFAULT_PROVENANCE}: the trio defines how much of each generation is
+reserved for carry-over, how much is freshly injected, and how much capacity
+remains for ordinary offspring.
 
-### DEFAULT_MAX_NODES
+### DEFAULT_EXCESS_COEFF
 
-Default maximum allowed nodes where `Infinity` means unbounded growth.
+Default excess coefficient for NEAT compatibility distance.
 
-Read the three `DEFAULT_MAX_*` exports as one structural-ceiling family.
-Leaving them unbounded by default tells the root controller to rely on
-mutation policy, pruning, and adaptive limits instead of an immediate hard
-cap.
+This begins the root compatibility-weight family. These coefficients explain
+which kinds of genome disagreement matter most when the controller decides
+whether two genomes still belong in the same species neighborhood.
 
 ### DEFAULT_MAX_CONNS
 
@@ -529,45 +519,39 @@ Default maximum allowed gates where `Infinity` means unbounded growth.
 Gate limits stay in the same family as node and connection limits so the
 whole structural-cap story remains consistent at the root surface.
 
-### DEFAULT_EXCESS_COEFF
-
-Default excess coefficient for NEAT compatibility distance.
-
-This begins the root compatibility-weight family. These coefficients explain
-which kinds of genome disagreement matter most when the controller decides
-whether two genomes still belong in the same species neighborhood.
-
-### DEFAULT_DISJOINT_COEFF
+### DEFAULT_MAX_NODES
 
-Default disjoint coefficient for NEAT compatibility distance.
+Default maximum allowed nodes where `Infinity` means unbounded growth.
 
-Matching the excess coefficient by default gives the root controller a
-balanced structural view: excess and disjoint innovation gaps both count as
-first-class evidence during compatibility comparisons.
+Read the three `DEFAULT_MAX_*` exports as one structural-ceiling family.
+Leaving them unbounded by default tells the root controller to rely on
+mutation policy, pruning, and adaptive limits instead of an immediate hard
+cap.
 
-### DEFAULT_WEIGHT_DIFF_COEFF
+### DEFAULT_MUTATION_AMOUNT
 
-Default average weight difference coefficient for compatibility distance.
+Default number of mutation operations applied per genome.
 
-This keeps parameter drift relevant without letting weight deltas dominate
-the whole speciation read. In the default family, topology disagreement still
-carries more weight than modest edge-weight differences.
+The default keeps the baseline search policy conservative: most runs mutate
+often enough to keep topology moving, but each genome usually pays for only
+one structural or parametric change per mutation pass.
 
-### DEFAULT_DIVERSITY_PAIR_SAMPLE
+### DEFAULT_MUTATION_RATE
 
-Default pair-sample size used by diversity metrics in fast mode.
+Default mutation rate used by the root controller when no explicit rate is supplied.
 
-This starts the observability-sampling family. The root controller uses a
-bounded sample instead of exhaustive pair checks so diversity reads stay
-cheap enough for ordinary runs.
+This belongs to the same search-tempo family as
+{@link DEFAULT_MUTATION_AMOUNT}. Together they define how often mutation is
+attempted and how many mutation steps a genome can receive once mutation is
+active.
 
-### DEFAULT_DIVERSITY_GRAPHLET_SAMPLE
+### DEFAULT_NEAT_CONSTRUCTOR_DEFAULTS
 
-Default graphlet sample size used by diversity metrics in fast mode.
+Shared defaults packet consumed by the constructor bootstrap chapter.
 
-Read this beside {@link DEFAULT_DIVERSITY_PAIR_SAMPLE}: pair samples give the
-controller quick distance evidence, while graphlet samples provide a small
-structural texture read without forcing whole-population analysis.
+The root public surface still exports the individual constants for callers
+and docs, but the constructor now hands one named packet to `init/` instead
+of rebuilding the same object inline inside `src/neat.ts`.
 
 ### DEFAULT_NOVELTY_K
 
@@ -577,10 +561,26 @@ This closes the root observability-and-exploration shelf. It controls how
 many nearby behaviors contribute to novelty before the caller tunes novelty
 search more explicitly.
 
-### DEFAULT_NEAT_CONSTRUCTOR_DEFAULTS
+### DEFAULT_POPULATION_SIZE
 
-Shared defaults packet consumed by the constructor bootstrap chapter.
+Default population size when caller does not specify `popsize`.
 
-The root public surface still exports the individual constants for callers
-and docs, but the constructor now hands one named packet to `init/` instead
-of rebuilding the same object inline inside `src/neat.ts`.
+This opens the root defaults shelf's search-volume family. It controls how
+many genomes compete in each generation before elitism, provenance, or
+mutation pressure begin to reshape the population.
+
+### DEFAULT_PROVENANCE
+
+Default provenance count applied when unspecified.
+
+Provenance is the root controller's small "fresh seed" policy. A value of
+`0` means the default run does not spend population budget on extra
+generation-zero style injections unless the caller asks for them.
+
+### DEFAULT_WEIGHT_DIFF_COEFF
+
+Default average weight difference coefficient for compatibility distance.
+
+This keeps parameter drift relevant without letting weight deltas dominate
+the whole speciation read. In the default family, topology disagreement still
+carries more weight than modest edge-weight differences.