@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/evaluate/shared/README.md

@@ -29,24 +29,6 @@ stable language without widening into a second full controller facade.
 
 ## neat/evaluate/shared/evaluate.types.ts
 
-### GenomeForEvaluation
-
-Genome with score, novelty, and clearing capabilities.
-
-This interface describes the smallest practical genome shape that the
-evaluate subtree can reason about. It is intentionally permissive so legacy
-genome variants and downstream extensions can still participate in
-evaluation, while the documented fields mark the pieces of evidence that the
-shared helpers actually rely on.
-
-### NoveltyArchiveEntry
-
-Novelty archive entry with descriptor and novelty score.
-
-Entries store one behavior descriptor alongside its novelty score so later
-evaluation passes can keep some memory of previously unusual behavior without
-retaining the entire population history.
-
 ### DiversityStats
 
 Diversity statistics tracked during evaluation.
@@ -56,13 +38,15 @@ a subset of metrics. Tuning chapters read this structure opportunistically,
 which lets the evaluation pipeline add evidence incrementally instead of
 requiring every metric to exist on every pass.
 
-### ObjectiveDef
+### GenomeForEvaluation
 
-Objective definition for multi-objective optimization.
+Genome with score, novelty, and clearing capabilities.
 
-Objectives are registered dynamically so evaluation can surface additional
-evidence, such as entropy, without forcing the entire objective stack to be
-hard-coded at controller construction time.
+This interface describes the smallest practical genome shape that the
+evaluate subtree can reason about. It is intentionally permissive so legacy
+genome variants and downstream extensions can still participate in
+evaluation, while the documented fields mark the pieces of evidence that the
+shared helpers actually rely on.
 
 ### NeatControllerForEval
 
@@ -78,6 +62,22 @@ still much smaller than the full `Neat` surface. That tradeoff keeps the
 evaluate chapters interoperable while preserving a clear boundary between
 evaluation and the rest of the runtime.
 
+### NoveltyArchiveEntry
+
+Novelty archive entry with descriptor and novelty score.
+
+Entries store one behavior descriptor alongside its novelty score so later
+evaluation passes can keep some memory of previously unusual behavior without
+retaining the entire population history.
+
+### ObjectiveDef
+
+Objective definition for multi-objective optimization.
+
+Objectives are registered dynamically so evaluation can surface additional
+evidence, such as entropy, without forcing the entire objective stack to be
+hard-coded at controller construction time.
+
 ## neat/evaluate/shared/evaluate.constants.ts
 
 Shared default constants for the NEAT evaluate chapter.
@@ -101,67 +101,68 @@ The exports below group into four families:
 - entropy-compatibility defaults,
 - auto-distance and variance-baseline defaults.
 
-### NOVELTY_DEFAULT_NEIGHBORS
+### AUTO_COEFF_ADJUST_DEFAULT
 
-Default number of nearest neighbors used when computing novelty.
+Default rate used when auto distance-coefficient tuning rebalances structural distance weights.
 
-Small values keep novelty sensitive to local behavioral differences without requiring a large
-archive or population.
+This shared step size controls how quickly excess and disjoint coefficients react when topology
+variance drifts away from the recent baseline.
 
-### NOVELTY_DEFAULT_BLEND
+### AUTO_COEFF_MAX_DEFAULT
 
-Default blend factor used when mixing novelty into an existing fitness score.
+Maximum structural-distance coefficient allowed during automatic tuning.
 
-A mid-range value keeps novelty influential without letting exploratory behavior completely drown
-out task performance.
+The upper bound prevents excess and disjoint penalties from dominating every later compatibility
+comparison.
 
-### NOVELTY_ARCHIVE_CAP
+### AUTO_COEFF_MIN_DEFAULT
 
-Maximum number of descriptors retained in the novelty archive.
+Minimum structural-distance coefficient allowed during automatic tuning.
 
-The cap keeps novelty history useful for exploration while preventing unbounded memory growth.
+The lower bound keeps structural differences meaningful even when the auto-distance policy is
+softening species pressure.
 
-### ENTROPY_VAR_TARGET_DEFAULT
+### COMPAT_MAX_THRESHOLD_DEFAULT
 
-Target variance used by entropy-sharing tuning.
+Maximum compatibility threshold allowed during automatic compatibility tuning.
 
-The controller nudges sharing sigma toward a population whose entropy spread is neither too flat
-nor too unstable.
+The upper clamp prevents compatibility from becoming so permissive that species boundaries lose
+practical meaning.
 
-### ENTROPY_VAR_ADJUST_DEFAULT
+### COMPAT_MIN_THRESHOLD_DEFAULT
 
-Default step size used when entropy-sharing tuning increases or decreases sharing sigma.
+Minimum compatibility threshold allowed during automatic compatibility tuning.
 
-A modest default keeps the sigma controller responsive without letting one noisy variance read
-swing the sharing radius too aggressively.
+The lower clamp prevents the threshold from collapsing until even small structural differences
+force unnecessary species fragmentation.
 
-### ENTROPY_VAR_MIN_SIGMA_DEFAULT
+### COMPAT_THRESHOLD_DEFAULT
 
-Lower bound for the sharing sigma used by entropy-sharing adaptation.
+Baseline compatibility threshold used when no explicit value is configured.
 
-The lower clamp prevents the sharing radius from shrinking so far that later sharing pressure
-becomes hypersensitive to tiny entropy fluctuations.
+This serves as the neutral starting point before entropy-based tuning or explicit user policy
+begins to reshape species pressure.
 
-### ENTROPY_VAR_MAX_SIGMA_DEFAULT
+### DISTANCE_COEFF_DEFAULT
 
-Upper bound for the sharing sigma used by entropy-sharing adaptation.
+Baseline structural-distance coefficient used before automatic tuning occurs.
 
-The upper clamp prevents the radius from widening until entropy sharing loses practical
-contrast across the population.
+This is the neutral starting point for the structural-distance fold before variance-driven
+updates begin to reshape it.
 
-### ENTROPY_VAR_LOW_BAND
+### ENTROPY_ADJUST_DEFAULT
 
-Lower tolerance band for deciding that observed entropy variance is meaningfully low.
+Default rate used when compatibility tuning nudges the threshold upward or downward.
 
-Values below this multiplier mark a population whose entropy spread is flatter than the tuning
-target expects.
+A conservative step size keeps the compatibility-threshold loop gradual enough that later
+speciation reads remain interpretable from one generation to the next.
 
-### ENTROPY_VAR_HIGH_BAND
+### ENTROPY_DEADBAND_DEFAULT
 
-Upper tolerance band for deciding that observed entropy variance is meaningfully high.
+Deadband around the entropy target where compatibility tuning intentionally does nothing.
 
-Values above this multiplier mark a population whose entropy spread is noisier than the tuning
-target expects.
+The deadband reduces threshold jitter by treating small entropy deviations as normal noise
+rather than signals that demand a policy change.
 
 ### ENTROPY_TARGET_DEFAULT
 
@@ -170,68 +171,67 @@ Target mean entropy used when tuning the compatibility threshold.
 The goal is to keep speciation pressure near a stable diversity level instead of drifting toward
 either species collapse or fragmentation.
 
-### ENTROPY_DEADBAND_DEFAULT
+### ENTROPY_VAR_ADJUST_DEFAULT
 
-Deadband around the entropy target where compatibility tuning intentionally does nothing.
+Default step size used when entropy-sharing tuning increases or decreases sharing sigma.
 
-The deadband reduces threshold jitter by treating small entropy deviations as normal noise
-rather than signals that demand a policy change.
+A modest default keeps the sigma controller responsive without letting one noisy variance read
+swing the sharing radius too aggressively.
 
-### ENTROPY_ADJUST_DEFAULT
+### ENTROPY_VAR_HIGH_BAND
 
-Default rate used when compatibility tuning nudges the threshold upward or downward.
+Upper tolerance band for deciding that observed entropy variance is meaningfully high.
 
-A conservative step size keeps the compatibility-threshold loop gradual enough that later
-speciation reads remain interpretable from one generation to the next.
+Values above this multiplier mark a population whose entropy spread is noisier than the tuning
+target expects.
 
-### COMPAT_THRESHOLD_DEFAULT
+### ENTROPY_VAR_LOW_BAND
 
-Baseline compatibility threshold used when no explicit value is configured.
+Lower tolerance band for deciding that observed entropy variance is meaningfully low.
 
-This serves as the neutral starting point before entropy-based tuning or explicit user policy
-begins to reshape species pressure.
+Values below this multiplier mark a population whose entropy spread is flatter than the tuning
+target expects.
 
-### COMPAT_MIN_THRESHOLD_DEFAULT
+### ENTROPY_VAR_MAX_SIGMA_DEFAULT
 
-Minimum compatibility threshold allowed during automatic compatibility tuning.
+Upper bound for the sharing sigma used by entropy-sharing adaptation.
 
-The lower clamp prevents the threshold from collapsing until even small structural differences
-force unnecessary species fragmentation.
+The upper clamp prevents the radius from widening until entropy sharing loses practical
+contrast across the population.
 
-### COMPAT_MAX_THRESHOLD_DEFAULT
+### ENTROPY_VAR_MIN_SIGMA_DEFAULT
 
-Maximum compatibility threshold allowed during automatic compatibility tuning.
+Lower bound for the sharing sigma used by entropy-sharing adaptation.
 
-The upper clamp prevents compatibility from becoming so permissive that species boundaries lose
-practical meaning.
+The lower clamp prevents the sharing radius from shrinking so far that later sharing pressure
+becomes hypersensitive to tiny entropy fluctuations.
 
-### AUTO_COEFF_ADJUST_DEFAULT
+### ENTROPY_VAR_TARGET_DEFAULT
 
-Default rate used when auto distance-coefficient tuning rebalances structural distance weights.
+Target variance used by entropy-sharing tuning.
 
-This shared step size controls how quickly excess and disjoint coefficients react when topology
-variance drifts away from the recent baseline.
+The controller nudges sharing sigma toward a population whose entropy spread is neither too flat
+nor too unstable.
 
-### AUTO_COEFF_MIN_DEFAULT
+### NOVELTY_ARCHIVE_CAP
 
-Minimum structural-distance coefficient allowed during automatic tuning.
+Maximum number of descriptors retained in the novelty archive.
 
-The lower bound keeps structural differences meaningful even when the auto-distance policy is
-softening species pressure.
+The cap keeps novelty history useful for exploration while preventing unbounded memory growth.
 
-### AUTO_COEFF_MAX_DEFAULT
+### NOVELTY_DEFAULT_BLEND
 
-Maximum structural-distance coefficient allowed during automatic tuning.
+Default blend factor used when mixing novelty into an existing fitness score.
 
-The upper bound prevents excess and disjoint penalties from dominating every later compatibility
-comparison.
+A mid-range value keeps novelty influential without letting exploratory behavior completely drown
+out task performance.
 
-### DISTANCE_COEFF_DEFAULT
+### NOVELTY_DEFAULT_NEIGHBORS
 
-Baseline structural-distance coefficient used before automatic tuning occurs.
+Default number of nearest neighbors used when computing novelty.
 
-This is the neutral starting point for the structural-distance fold before variance-driven
-updates begin to reshape it.
+Small values keep novelty sensitive to local behavioral differences without requiring a large
+archive or population.
 
 ### VARIANCE_DECREASE_THRESHOLD
 

package/src/neat/evolve/README.md

@@ -95,24 +95,14 @@ The important boundary is that this interface is richer than the minimal
 shared genome contracts used by read-side chapters, because evolve helpers are
 the place where new runtime metadata is actually attached.
 
-### SpeciesWithMetadata
-
-Runtime interface for species metadata used in allocation and stats.
-
-This is the live species record shape used during one evolve step. Helpers in
-`speciation/`, `population/`, and telemetry-oriented paths rely on it to ask
-practical generation-level questions: which genomes belong together now, how
-much shared fitness does the species have, and how many offspring should it
-receive next?
-
-### SpeciesHistoryRecord
+### MultiObjectiveOptions
 
-Species history snapshot record used for telemetry/exports.
+Multi-objective configuration block.
 
-Unlike `SpeciesWithMetadata`, which describes the current live registry, this
-contract is archival. It captures the summarized species view that can be
-retained across generations for telemetry, historical diagnostics, and later
-export.
+This is the policy bundle evolve helpers consult when deciding how dynamic
+objective scheduling, epsilon tuning, and inactive-objective pruning should
+behave during a run. It is broader than one descriptor but narrower than the
+full controller options object.
 
 ### MutationMethod
 
@@ -123,24 +113,6 @@ mutation policy metadata defined in the mutation subtree. That is why this
 local descriptor stays intentionally tiny: evolve orchestration mainly uses it
 as a token when handing work off to mutation-oriented hooks.
 
-### ObjectiveDescriptor
-
-Objective descriptor for multi-objective evaluation.
-
-This is the shared scoring token used when evolve orchestration hands the
-current population to objective-aware ranking logic. Each descriptor couples a
-stable key with the accessor that extracts that objective's numeric evidence
-from one genome.
-
-### MultiObjectiveOptions
-
-Multi-objective configuration block.
-
-This is the policy bundle evolve helpers consult when deciding how dynamic
-objective scheduling, epsilon tuning, and inactive-objective pruning should
-behave during a run. It is broader than one descriptor but narrower than the
-full controller options object.
-
 ### NeatControllerForEvolution
 
 NEAT controller subset used by evolve orchestrations.
@@ -165,6 +137,34 @@ the point where many chapter boundaries meet. Even so, it is still narrower
 than the full public controller API: only the state and callbacks needed for
 one generation step are surfaced here.
 
+### ObjectiveDescriptor
+
+Objective descriptor for multi-objective evaluation.
+
+This is the shared scoring token used when evolve orchestration hands the
+current population to objective-aware ranking logic. Each descriptor couples a
+stable key with the accessor that extracts that objective's numeric evidence
+from one genome.
+
+### SpeciesHistoryRecord
+
+Species history snapshot record used for telemetry/exports.
+
+Unlike `SpeciesWithMetadata`, which describes the current live registry, this
+contract is archival. It captures the summarized species view that can be
+retained across generations for telemetry, historical diagnostics, and later
+export.
+
+### SpeciesWithMetadata
+
+Runtime interface for species metadata used in allocation and stats.
+
+This is the live species record shape used during one evolve step. Helpers in
+`speciation/`, `population/`, and telemetry-oriented paths rely on it to ask
+practical generation-level questions: which genomes belong together now, how
+much shared fitness does the species have, and how many offspring should it
+receive next?
+
 ## neat/evolve/evolve.ts
 
 ### evolve
@@ -224,44 +224,41 @@ console.log('output nodes:', bestNetwork.output);
 Returns: a deep-cloned network snapshot representing the best genome from the
 previous generation, ready for inspection or external evaluation
 
-### EVOLVE_PARETO_ARCHIVE_MAX
-
-Maximum number of Pareto archive snapshots to retain.
+### EVOLVE_AUTO_COMPAT_ADJUST_RATE
 
-This keeps multi-objective history useful for inspection without letting archive state
-grow unbounded during long runs.
+Default rate used when nudging compatibility coefficients toward the desired species count.
 
-### EVOLVE_TARGET_FRONT_MIN
+### EVOLVE_AUTO_COMPAT_MAX_COEFF
 
-Minimum target front size used for adaptive epsilon tuning.
+Maximum compatibility coefficient allowed during automatic tuning.
 
-Small Pareto fronts are easy to overfit, so the epsilon controller never aims below this floor.
+### EVOLVE_AUTO_COMPAT_MIN_COEFF
 
-### EVOLVE_TARGET_FRONT_UPPER_RATIO
+Minimum compatibility coefficient allowed during automatic tuning.
 
-Upper ratio threshold for Pareto front size vs target.
+### EVOLVE_AUTO_COMPAT_RANDOM_SCALE
 
-When the first front grows beyond this band, the controller can tighten epsilon to recover pressure.
+Random perturbation scale used when compatibility tuning has no directional error to follow.
 
-### EVOLVE_TARGET_FRONT_LOWER_RATIO
+### EVOLVE_AUTO_COMPAT_TARGET_MIN
 
-Lower ratio threshold for Pareto front size vs target.
+Minimum target species count used by automatic compatibility tuning.
 
-When the first front shrinks below this band, the controller can relax epsilon to avoid over-pruning.
+The controller never tries to collapse diversity below this floor when adjusting coefficients.
 
-### EVOLVE_DEFAULT_EPSILON_ADJUST
+### EVOLVE_AUTO_ENTROPY_ADD_AT
 
-Default adjustment step for dominance epsilon.
+Default generation at which automatic entropy objective scheduling becomes eligible.
 
-The value is intentionally small because epsilon changes should steer ranking gradually rather than jerk it.
+### EVOLVE_CROSS_SPECIES_GUARD_LIMIT
 
-### EVOLVE_DEFAULT_EPSILON_MIN
+Retry limit for cross-species parent sampling before the controller falls back to a safer path.
 
-Minimum dominance epsilon floor used by adaptive Pareto tuning.
+### EVOLVE_DEFAULT_EPSILON_ADJUST
 
-### EVOLVE_DEFAULT_EPSILON_MAX
+Default adjustment step for dominance epsilon.
 
-Maximum dominance epsilon ceiling used by adaptive Pareto tuning.
+The value is intentionally small because epsilon changes should steer ranking gradually rather than jerk it.
 
 ### EVOLVE_DEFAULT_EPSILON_COOLDOWN
 
@@ -269,49 +266,56 @@ Default cooldown in generations between epsilon adjustments.
 
 This prevents the controller from reacting to every short-lived fluctuation in front width.
 
-### EVOLVE_PRUNE_WINDOW_DEFAULT
+### EVOLVE_DEFAULT_EPSILON_MAX
 
-Default inactivity window used before adaptive objective pruning considers removal.
+Maximum dominance epsilon ceiling used by adaptive Pareto tuning.
 
-### EVOLVE_PRUNE_RANGE_EPS_DEFAULT
+### EVOLVE_DEFAULT_EPSILON_MIN
 
-Default numerical range epsilon for deciding whether an objective has effectively gone flat.
+Minimum dominance epsilon floor used by adaptive Pareto tuning.
 
-### EVOLVE_YOUNG_THRESHOLD_DEFAULT
+### EVOLVE_GLOBAL_STAGNATION_REPLACE_FRACTION
 
-Generation threshold below which a species is still treated as young.
+Fraction of the population replaced with fresh genomes when global stagnation rescue triggers.
 
-### EVOLVE_YOUNG_MULTIPLIER_DEFAULT
+### EVOLVE_MIN_OFFSPRING_DEFAULT
 
-Fitness-sharing multiplier applied to species that are still in their early growth window.
+Minimum offspring allocation reserved for a surviving species during speciated reproduction.
+
+### EVOLVE_OLD_MULTIPLIER_DEFAULT
+
+Fitness-sharing multiplier applied to older species so stale lineages lose selection privilege.
 
 ### EVOLVE_OLD_THRESHOLD_DEFAULT
 
 Generation threshold after which a species is treated as old for age-based fitness shaping.
 
-### EVOLVE_OLD_MULTIPLIER_DEFAULT
+### EVOLVE_PARETO_ARCHIVE_MAX
 
-Fitness-sharing multiplier applied to older species so stale lineages lose selection privilege.
+Maximum number of Pareto archive snapshots to retain.
 
-### EVOLVE_MIN_OFFSPRING_DEFAULT
+This keeps multi-objective history useful for inspection without letting archive state
+grow unbounded during long runs.
 
-Minimum offspring allocation reserved for a surviving species during speciated reproduction.
+### EVOLVE_PRUNE_RANGE_EPS_DEFAULT
 
-### EVOLVE_SURVIVAL_THRESHOLD_DEFAULT
+Default numerical range epsilon for deciding whether an objective has effectively gone flat.
 
-Survivor fraction used when choosing the parent pool inside each species.
+### EVOLVE_PRUNE_WINDOW_DEFAULT
 
-### EVOLVE_CROSS_SPECIES_GUARD_LIMIT
+Default inactivity window used before adaptive objective pruning considers removal.
 
-Retry limit for cross-species parent sampling before the controller falls back to a safer path.
+### EVOLVE_REENABLE_DELTA_SCALE
 
-### EVOLVE_AUTO_ENTROPY_ADD_AT
+Scale factor that converts re-enable success error into a probability update.
 
-Default generation at which automatic entropy objective scheduling becomes eligible.
+### EVOLVE_REENABLE_MAX
 
-### EVOLVE_GLOBAL_STAGNATION_REPLACE_FRACTION
+Upper bound for adaptive connection re-enable probability.
 
-Fraction of the population replaced with fresh genomes when global stagnation rescue triggers.
+### EVOLVE_REENABLE_MIN
+
+Lower bound for adaptive connection re-enable probability.
 
 ### EVOLVE_REENABLE_MIN_SAMPLES
 
@@ -321,40 +325,36 @@ Minimum re-enable observations required before the controller trusts its adaptat
 
 Desired success ratio for connection re-enable attempts during adaptive mutation control.
 
-### EVOLVE_REENABLE_DELTA_SCALE
-
-Scale factor that converts re-enable success error into a probability update.
-
-### EVOLVE_REENABLE_MIN
+### EVOLVE_SPECIES_HISTORY_MAX
 
-Lower bound for adaptive connection re-enable probability.
+Maximum number of species-history snapshots to retain for telemetry and later export.
 
-### EVOLVE_REENABLE_MAX
+### EVOLVE_SURVIVAL_THRESHOLD_DEFAULT
 
-Upper bound for adaptive connection re-enable probability.
+Survivor fraction used when choosing the parent pool inside each species.
 
-### EVOLVE_AUTO_COMPAT_TARGET_MIN
+### EVOLVE_TARGET_FRONT_LOWER_RATIO
 
-Minimum target species count used by automatic compatibility tuning.
+Lower ratio threshold for Pareto front size vs target.
 
-The controller never tries to collapse diversity below this floor when adjusting coefficients.
+When the first front shrinks below this band, the controller can relax epsilon to avoid over-pruning.
 
-### EVOLVE_AUTO_COMPAT_ADJUST_RATE
+### EVOLVE_TARGET_FRONT_MIN
 
-Default rate used when nudging compatibility coefficients toward the desired species count.
+Minimum target front size used for adaptive epsilon tuning.
 
-### EVOLVE_AUTO_COMPAT_MIN_COEFF
+Small Pareto fronts are easy to overfit, so the epsilon controller never aims below this floor.
 
-Minimum compatibility coefficient allowed during automatic tuning.
+### EVOLVE_TARGET_FRONT_UPPER_RATIO
 
-### EVOLVE_AUTO_COMPAT_MAX_COEFF
+Upper ratio threshold for Pareto front size vs target.
 
-Maximum compatibility coefficient allowed during automatic tuning.
+When the first front grows beyond this band, the controller can tighten epsilon to recover pressure.
 
-### EVOLVE_AUTO_COMPAT_RANDOM_SCALE
+### EVOLVE_YOUNG_MULTIPLIER_DEFAULT
 
-Random perturbation scale used when compatibility tuning has no directional error to follow.
+Fitness-sharing multiplier applied to species that are still in their early growth window.
 
-### EVOLVE_SPECIES_HISTORY_MAX
+### EVOLVE_YOUNG_THRESHOLD_DEFAULT
 
-Maximum number of species-history snapshots to retain for telemetry and later export.
+Generation threshold below which a species is still treated as young.