@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/adaptive/core/README.md

@@ -35,40 +35,22 @@ flowchart TD
 
 ## neat/adaptive/core/adaptive.core.types.ts
 
-### NeatLikeWithAdaptive
-
-Contract map for the adaptive helper boundary.
+### AdaptiveMutationConfig
 
-The adaptive subtree works because each policy chapter can stay focused on a
-single feedback loop while still sharing one precise agreement about what it
-may read, what it may rewrite, and which option family owns each tuning
-decision. This file is that agreement.
+Shared config view for per-genome adaptive mutation helpers.
 
-Read the contracts in three passes:
+The mutation adaptation loop reads this slice to clamp rates, normalize
+perturbation scales, and decide how often genome-local parameters are
+refreshed. It is the mutation-side policy vocabulary before defaults are
+resolved into `MutationSettings`.
 
-- start with `NeatLikeWithAdaptive` to see the runtime host surface and the
-  scratch fields adaptive controllers are allowed to maintain,
-- continue with the exported `*Config` aliases to see how complexity,
-  acceptance, mutation, operator adaptation, and lineage feedback each slice
-  the broader options object,
-- finish with `Genome`, `MutationSettings`, `MutationPartitions`, and
-  `MutationOutcome` when you want the normalized working shapes used inside
-  adaptive mutation helpers.
+### AncestorUniqAdaptiveConfig
 
-The matching defaults and mode labels live in `adaptive.core.constants.ts`.
-This file stays focused on contracts so the generated chapter reads as a
-bounded vocabulary map rather than a second controller implementation.
+Shared config view for ancestor-uniqueness feedback helpers.
 
-```mermaid
-flowchart TD
-  Host[NeatLikeWithAdaptive host] --> Options[Adaptive option families]
-  Host --> Population[Population runtime state]
-  Host --> Scratch[Adaptive scratch fields and telemetry]
-  Options --> Complexity[Complexity and phased schedules]
-  Options --> Acceptance[Acceptance and minimal criterion]
-  Options --> Mutation[Mutation and operator adaptation]
-  Options --> Lineage[Ancestor uniqueness and lineage pressure]
-```
+This captures the thresholds, cooldowns, and mode switches used when the
+controller nudges diversity pressure in response to lineage concentration.
+Read it as the lineage-feedback slice of the broader adaptive options object.
 
 ### ComplexityBudgetConfig
 
@@ -79,13 +61,13 @@ schedule shape, and improvement-window tuning for the adaptive budget loop.
 It is the smallest view needed for the controller that grows or shrinks the
 allowed topology budget over time.
 
-### PhasedComplexityConfig
+### Genome
 
-Shared config view for phased-complexity helpers.
+Shared genome view used by the adaptive helpers.
 
-This isolates the alternating complexify/simplify schedule from the broader
-adaptive options object so phase-oriented helpers can stay narrow and think
-in terms of mode transitions instead of the entire adaptive policy surface.
+This is intentionally opaque beyond the adaptive scratch fields already
+exposed through `NeatLikeWithAdaptive['population']`. The adaptive core cares
+about per-genome scores and adaptive overrides, not full network structure.
 
 ### MinimalCriterionAdaptiveConfig
 
@@ -95,31 +77,21 @@ Helpers use this slice when they are only adjusting the acceptance
 threshold, not inspecting the rest of the controller policy surface. This is
 the acceptance-side tuning vocabulary, not a whole-population runtime view.
 
-### AncestorUniqAdaptiveConfig
-
-Shared config view for ancestor-uniqueness feedback helpers.
-
-This captures the thresholds, cooldowns, and mode switches used when the
-controller nudges diversity pressure in response to lineage concentration.
-Read it as the lineage-feedback slice of the broader adaptive options object.
-
-### AdaptiveMutationConfig
+### MutationOutcome
 
-Shared config view for per-genome adaptive mutation helpers.
+Outcome flags used to detect whether mutation pressure stayed balanced.
 
-The mutation adaptation loop reads this slice to clamp rates, normalize
-perturbation scales, and decide how often genome-local parameters are
-refreshed. It is the mutation-side policy vocabulary before defaults are
-resolved into `MutationSettings`.
+Mutation adaptation uses this tiny result object to summarize whether recent
+adjustments produced both upward and downward movement rather than collapsing
+into one-sided pressure.
 
-### OperatorAdaptationConfig
+### MutationPartitions
 
-Shared config view for operator-stat adaptation helpers.
+Score-ranked population halves used by two-tier and explore-low strategies.
 
-This is the policy surface for helpers that bias mutation-operator choice
-using historical success and attempt statistics. It stays separate from the
-broader adaptive mutation config because operator-choice decay is a different
-feedback loop from per-genome rate tuning.
+This keeps the mutation strategies' working partitions explicit so helpers
+can talk about "top half" and "bottom half" without recomputing or loosely
+describing that split.
 
 ### MutationSettings
 
@@ -131,29 +103,57 @@ optional config fields. Read it as the mutation chapter's resolved call
 frame: one object with every clamp, sigma, strategy, and baseline already in
 concrete form.
 
-### MutationOutcome
+### NeatLikeWithAdaptive
 
-Outcome flags used to detect whether mutation pressure stayed balanced.
+Contract map for the adaptive helper boundary.
 
-Mutation adaptation uses this tiny result object to summarize whether recent
-adjustments produced both upward and downward movement rather than collapsing
-into one-sided pressure.
+The adaptive subtree works because each policy chapter can stay focused on a
+single feedback loop while still sharing one precise agreement about what it
+may read, what it may rewrite, and which option family owns each tuning
+decision. This file is that agreement.
 
-### MutationPartitions
+Read the contracts in three passes:
 
-Score-ranked population halves used by two-tier and explore-low strategies.
+- start with `NeatLikeWithAdaptive` to see the runtime host surface and the
+  scratch fields adaptive controllers are allowed to maintain,
+- continue with the exported `*Config` aliases to see how complexity,
+  acceptance, mutation, operator adaptation, and lineage feedback each slice
+  the broader options object,
+- finish with `Genome`, `MutationSettings`, `MutationPartitions`, and
+  `MutationOutcome` when you want the normalized working shapes used inside
+  adaptive mutation helpers.
 
-This keeps the mutation strategies' working partitions explicit so helpers
-can talk about "top half" and "bottom half" without recomputing or loosely
-describing that split.
+The matching defaults and mode labels live in `adaptive.core.constants.ts`.
+This file stays focused on contracts so the generated chapter reads as a
+bounded vocabulary map rather than a second controller implementation.
 
-### Genome
+```mermaid
+flowchart TD
+  Host[NeatLikeWithAdaptive host] --> Options[Adaptive option families]
+  Host --> Population[Population runtime state]
+  Host --> Scratch[Adaptive scratch fields and telemetry]
+  Options --> Complexity[Complexity and phased schedules]
+  Options --> Acceptance[Acceptance and minimal criterion]
+  Options --> Mutation[Mutation and operator adaptation]
+  Options --> Lineage[Ancestor uniqueness and lineage pressure]
+```
 
-Shared genome view used by the adaptive helpers.
+### OperatorAdaptationConfig
 
-This is intentionally opaque beyond the adaptive scratch fields already
-exposed through `NeatLikeWithAdaptive['population']`. The adaptive core cares
-about per-genome scores and adaptive overrides, not full network structure.
+Shared config view for operator-stat adaptation helpers.
+
+This is the policy surface for helpers that bias mutation-operator choice
+using historical success and attempt statistics. It stays separate from the
+broader adaptive mutation config because operator-choice decay is a different
+feedback loop from per-genome rate tuning.
+
+### PhasedComplexityConfig
+
+Shared config view for phased-complexity helpers.
+
+This isolates the alternating complexify/simplify schedule from the broader
+adaptive options object so phase-oriented helpers can stay narrow and think
+in terms of mode transitions instead of the entire adaptive policy surface.
 
 ## neat/adaptive/core/adaptive.core.ts
 
@@ -326,262 +326,262 @@ adaptive subtree reuses one glossary for tiny math helpers, schedule timing,
 mode names, and safety clamps instead of scattering unrelated literals across
 each control loop.
 
-### ZERO
+### ACCEPTANCE_LOWER_MULTIPLIER
 
-Zero baseline reused by tiny adaptive arithmetic helpers.
+Lower multiplier used when the controller relaxes acceptance pressure.
 
-### ONE
+### ACCEPTANCE_UPPER_MULTIPLIER
 
-Unit baseline reused by clamp, ratio, and fallback calculations.
+Upper multiplier used when the controller nudges acceptance pressure upward.
 
-### TWO
+### ADJUST_RATE_DEFAULT
 
-Small divisor and offset used by split and normalization helpers.
+Default adjustment step for adaptive minimal-criterion threshold updates.
 
-### THREE
+### ANCESTOR_UNIQ_MODE_EPSILON
 
-Small threshold used by helpers that need a minimal multi-sample floor.
+Mode label for epsilon-style ancestor-uniqueness feedback.
 
-### FOUR
+### ANCESTOR_UNIQ_MODE_LINEAGE_PRESSURE
 
-Small multiplier reused by adaptive-budget growth defaults.
+Mode label for ancestor-uniqueness control via lineage-pressure tuning.
 
-### FIVE
+### ANNEAL_BASELINE_GENERATIONS
 
-Small count baseline reused by archive-size and cooldown defaults.
+Baseline generations for annealing progress.
 
-### TEN
+### ANNEAL_PROGRESS_MAX
 
-Round-number default reused by windows and phase lengths.
+Maximum progress ratio used in annealing.
 
-### ONE_HUNDRED
+### BUDGET_GROWTH_MULTIPLIER
 
-Large round-number default for long-horizon scheduling.
+Default budget growth multiplier.
 
-### NEGATIVE_ONE
+### COMPLEXITY_MODE_ADAPTIVE
 
-Last-index sentinel reused when helpers need the final recorded item.
+Mode label for feedback-driven complexity-budget scheduling.
 
-### DEFAULT_IMPROVEMENT_WINDOW
+### COMPLEXITY_MODE_LINEAR
 
-Default score-history window for trend-aware complexity budgeting.
+Mode label for pre-planned linear complexity-budget scheduling.
 
-### HISTORY_MIN_IMPROVEMENT_COUNT
+### DEFAULT_ADAPT_EVERY
 
-Minimum history length to compute improvement.
+Default cadence for refreshing per-genome adaptive mutation settings.
 
-### HISTORY_MIN_SLOPE_COUNT
+### DEFAULT_ANCESTOR_UNIQ_ADJUST
 
-Minimum history length to compute slope.
+Default adjustment magnitude for uniqueness nudges.
 
-### DEFAULT_CB_INCREASE_FACTOR
+### DEFAULT_ANCESTOR_UNIQ_COOLDOWN
 
-Default multiplier used when adaptive complexity budgeting detects improvement.
+Default cooldown (generations) for ancestor-uniqueness adjustments.
 
-### DEFAULT_CB_STAGNATION_FACTOR
+### DEFAULT_ANCESTOR_UNIQ_HIGH_THRESHOLD
 
-Default multiplier used when adaptive complexity budgeting responds to stagnation.
+Default upper bound for acceptable ancestor uniqueness.
 
-### SLOPE_BOOST_MULTIPLIER
+### DEFAULT_ANCESTOR_UNIQ_LOW_THRESHOLD
 
-Slope boost multiplier for adaptive increase factor.
+Default lower bound for acceptable ancestor uniqueness.
 
-### SLOPE_PENALTY_MULTIPLIER
+### DEFAULT_CB_INCREASE_FACTOR
 
-Slope penalty multiplier for stagnation factor.
+Default multiplier used when adaptive complexity budgeting detects improvement.
 
-### SLOPE_NORMALIZE_CLAMP
+### DEFAULT_CB_STAGNATION_FACTOR
 
-Clamp magnitude for slope normalization.
+Default multiplier used when adaptive complexity budgeting responds to stagnation.
 
-### NOVELTY_ARCHIVE_MIN_SIZE
+### DEFAULT_IMPROVEMENT_WINDOW
 
-Novelty archive minimum size.
+Default score-history window for trend-aware complexity budgeting.
 
-### NOVELTY_FACTOR_SMALL
+### DEFAULT_INITIAL_MUTATION_RATE
 
-Novelty factor when archive is small.
+Default initial mutation rate used before adaptive balancing specializes genomes.
 
-### NOVELTY_FACTOR_DEFAULT
+### DEFAULT_LINEAGE_PRESSURE_STRENGTH
 
-Novelty factor when archive is sufficient.
+Default lineage pressure strength when initializing the option.
 
-### MINIMAL_TOPOLOGY_OFFSET
+### DEFAULT_MAX_MUTATION_AMOUNT
 
-Offset added to input/output for minimal topology.
+Default maximum mutation amount.
 
-### BUDGET_GROWTH_MULTIPLIER
+### DEFAULT_MAX_MUTATION_RATE
 
-Default budget growth multiplier.
+Default upper clamp for per-genome adaptive mutation rates.
 
-### LINEAR_HORIZON_DEFAULT
+### DEFAULT_MIN_MUTATION_AMOUNT
 
-Default horizon for linear schedule.
+Default minimum mutation amount.
 
-### PROGRESS_RATIO_MAX
+### DEFAULT_MIN_MUTATION_RATE
 
-Maximum progress ratio for scheduling.
+Default lower clamp for per-genome adaptive mutation rates.
 
-### PHASE_LENGTH_DEFAULT
+### DEFAULT_MUTATION_AMOUNT
 
-Default phase length in generations for phased complexify/simplify schedules.
+Default mutation amount when genome value is missing.
 
-### TARGET_ACCEPTANCE_DEFAULT
+### DEFAULT_MUTATION_AMOUNT_SIGMA
 
-Default acceptance target for adaptive minimal-criterion control.
+Default perturbation spread for adaptive mutation-amount updates.
 
-### ADJUST_RATE_DEFAULT
+### DEFAULT_MUTATION_SIGMA
 
-Default adjustment step for adaptive minimal-criterion threshold updates.
+Default perturbation spread for adaptive mutation-rate updates.
 
-### ACCEPTANCE_UPPER_MULTIPLIER
+### DENOMINATOR_FALLBACK
 
-Upper multiplier used when the controller nudges acceptance pressure upward.
+Fallback denominator to avoid divide-by-zero.
 
-### ACCEPTANCE_LOWER_MULTIPLIER
+### EXPLORE_LOW_DECREASE_MULTIPLIER
 
-Lower multiplier used when the controller relaxes acceptance pressure.
+Multiplicative decay for explore-low strategy (top half).
 
-### DENOMINATOR_FALLBACK
+### EXPLORE_LOW_INCREASE_MULTIPLIER
 
-Fallback denominator to avoid divide-by-zero.
+Multiplicative boost for explore-low strategy (bottom half).
 
-### OPERATOR_DECAY_DEFAULT
+### FIVE
 
-Default operator decay factor.
+Small count baseline reused by archive-size and cooldown defaults.
 
-### COMPLEXITY_MODE_ADAPTIVE
+### FOUR
 
-Mode label for feedback-driven complexity-budget scheduling.
+Small multiplier reused by adaptive-budget growth defaults.
 
-### COMPLEXITY_MODE_LINEAR
+### HALF_INDEX_DIVISOR
 
-Mode label for pre-planned linear complexity-budget scheduling.
+Divisor used to split populations in half.
 
-### PHASE_COMPLEXIFY
+### HISTORY_MIN_IMPROVEMENT_COUNT
 
-Phase label for the structure-growth side of phased complexity.
+Minimum history length to compute improvement.
 
-### PHASE_SIMPLIFY
+### HISTORY_MIN_SLOPE_COUNT
 
-Phase label for the structure-pruning side of phased complexity.
+Minimum history length to compute slope.
 
-### ANCESTOR_UNIQ_MODE_EPSILON
+### LINEAGE_PRESSURE_DECREASE_MULTIPLIER
 
-Mode label for epsilon-style ancestor-uniqueness feedback.
+Multiplier when decreasing lineage pressure strength.
 
-### ANCESTOR_UNIQ_MODE_LINEAGE_PRESSURE
+### LINEAGE_PRESSURE_INCREASE_MULTIPLIER
 
-Mode label for ancestor-uniqueness control via lineage-pressure tuning.
+Multiplier when increasing lineage pressure strength.
 
 ### LINEAGE_PRESSURE_MODE_SPREAD
 
 Lineage pressure spread mode.
 
-### DEFAULT_ANCESTOR_UNIQ_COOLDOWN
-
-Default cooldown (generations) for ancestor-uniqueness adjustments.
-
-### DEFAULT_ANCESTOR_UNIQ_LOW_THRESHOLD
+### LINEAR_HORIZON_DEFAULT
 
-Default lower bound for acceptable ancestor uniqueness.
+Default horizon for linear schedule.
 
-### DEFAULT_ANCESTOR_UNIQ_HIGH_THRESHOLD
+### MINIMAL_TOPOLOGY_OFFSET
 
-Default upper bound for acceptable ancestor uniqueness.
+Offset added to input/output for minimal topology.
 
-### DEFAULT_ANCESTOR_UNIQ_ADJUST
+### MUTATION_SIGMA_SCALE
 
-Default adjustment magnitude for uniqueness nudges.
+Scale applied to mutation sigma for perturbations.
 
-### DEFAULT_LINEAGE_PRESSURE_STRENGTH
+### MUTATION_STRATEGY_ANNEAL
 
-Default lineage pressure strength when initializing the option.
+Strategy label for annealed mutation pressure across run progress.
 
-### LINEAGE_PRESSURE_INCREASE_MULTIPLIER
+### MUTATION_STRATEGY_EXPLORE_LOW
 
-Multiplier when increasing lineage pressure strength.
+Strategy label for boosting structural risk on the lower-ranked half.
 
-### LINEAGE_PRESSURE_DECREASE_MULTIPLIER
+### MUTATION_STRATEGY_TWO_TIER
 
-Multiplier when decreasing lineage pressure strength.
+Strategy label for ranking-sensitive two-tier adaptive mutation.
 
-### DEFAULT_ADAPT_EVERY
+### NEGATIVE_ONE
 
-Default cadence for refreshing per-genome adaptive mutation settings.
+Last-index sentinel reused when helpers need the final recorded item.
 
-### DEFAULT_MUTATION_SIGMA
+### NOVELTY_ARCHIVE_MIN_SIZE
 
-Default perturbation spread for adaptive mutation-rate updates.
+Novelty archive minimum size.
 
-### MUTATION_SIGMA_SCALE
+### NOVELTY_FACTOR_DEFAULT
 
-Scale applied to mutation sigma for perturbations.
+Novelty factor when archive is sufficient.
 
-### DEFAULT_MIN_MUTATION_RATE
+### NOVELTY_FACTOR_SMALL
 
-Default lower clamp for per-genome adaptive mutation rates.
+Novelty factor when archive is small.
 
-### DEFAULT_MAX_MUTATION_RATE
+### ONE
 
-Default upper clamp for per-genome adaptive mutation rates.
+Unit baseline reused by clamp, ratio, and fallback calculations.
 
-### DEFAULT_INITIAL_MUTATION_RATE
+### ONE_HUNDRED
 
-Default initial mutation rate used before adaptive balancing specializes genomes.
+Large round-number default for long-horizon scheduling.
 
-### DEFAULT_MUTATION_AMOUNT
+### OPERATOR_DECAY_DEFAULT
 
-Default mutation amount when genome value is missing.
+Default operator decay factor.
 
-### DEFAULT_MUTATION_AMOUNT_SIGMA
+### PHASE_COMPLEXIFY
 
-Default perturbation spread for adaptive mutation-amount updates.
+Phase label for the structure-growth side of phased complexity.
 
-### DEFAULT_MIN_MUTATION_AMOUNT
+### PHASE_LENGTH_DEFAULT
 
-Default minimum mutation amount.
+Default phase length in generations for phased complexify/simplify schedules.
 
-### DEFAULT_MAX_MUTATION_AMOUNT
+### PHASE_SIMPLIFY
 
-Default maximum mutation amount.
+Phase label for the structure-pruning side of phased complexity.
 
-### RNG_SPREAD_MULTIPLIER
+### PROGRESS_RATIO_MAX
 
-Random range multiplier for signed deltas.
+Maximum progress ratio for scheduling.
 
 ### RNG_CENTER_OFFSET
 
 Random offset for signed deltas.
 
-### EXPLORE_LOW_INCREASE_MULTIPLIER
+### RNG_SPREAD_MULTIPLIER
 
-Multiplicative boost for explore-low strategy (bottom half).
+Random range multiplier for signed deltas.
 
-### EXPLORE_LOW_DECREASE_MULTIPLIER
+### SLOPE_BOOST_MULTIPLIER
 
-Multiplicative decay for explore-low strategy (top half).
+Slope boost multiplier for adaptive increase factor.
 
-### ANNEAL_BASELINE_GENERATIONS
+### SLOPE_NORMALIZE_CLAMP
 
-Baseline generations for annealing progress.
+Clamp magnitude for slope normalization.
 
-### ANNEAL_PROGRESS_MAX
+### SLOPE_PENALTY_MULTIPLIER
 
-Maximum progress ratio used in annealing.
+Slope penalty multiplier for stagnation factor.
 
-### HALF_INDEX_DIVISOR
+### TARGET_ACCEPTANCE_DEFAULT
 
-Divisor used to split populations in half.
+Default acceptance target for adaptive minimal-criterion control.
 
-### MUTATION_STRATEGY_TWO_TIER
+### TEN
 
-Strategy label for ranking-sensitive two-tier adaptive mutation.
+Round-number default reused by windows and phase lengths.
 
-### MUTATION_STRATEGY_EXPLORE_LOW
+### THREE
 
-Strategy label for boosting structural risk on the lower-ranked half.
+Small threshold used by helpers that need a minimal multi-sample floor.
 
-### MUTATION_STRATEGY_ANNEAL
+### TWO
 
-Strategy label for annealed mutation pressure across run progress.
+Small divisor and offset used by split and normalization helpers.
+
+### ZERO
+
+Zero baseline reused by tiny adaptive arithmetic helpers.