@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -178,83 +178,53 @@ The helper flow is intentionally compact:
 3. resolve thresholds and adjustment magnitude,
 4. route the adjustment into epsilon or lineage-pressure mode.
 
-### isCooldownSatisfied
+### applyEpsilonAdjustment
 
 ```ts
-isCooldownSatisfied(
+applyEpsilonAdjustment(
   engine: NeatLikeWithAdaptive,
-  config: { enabled?: boolean | undefined; cooldown?: number | undefined; lowThreshold?: number | undefined; highThreshold?: number | undefined; adjust?: number | undefined; mode?: string | undefined; },
-): boolean
+  ancestorUniq: number,
+  thresholds: { lowThreshold: number; highThreshold: number; },
+  adjustMagnitude: number,
+): void
 ```
 
-Determine whether the cooldown window has elapsed.
+Apply dominance-epsilon adjustments when configured.
 
-Cooldowns prevent the controller from thrashing lineage policy on every
-generation. Once an adjustment has been recorded, later generations must wait
-for the configured gap before another nudge is allowed.
+Epsilon mode nudges the multi-objective dominance tolerance when ancestry is
+too uniform or too diffuse. That lets later Pareto comparisons become slightly
+more or less permissive without changing the current generation directly.
 
 Parameters:
 - `engine` - - NEAT engine instance.
-- `config` - - Ancestor uniqueness adaptive configuration.
+- `ancestorUniq` - - Current ancestor uniqueness metric.
+- `thresholds` - - Threshold bounds for decisions.
+- `adjustMagnitude` - - Adjustment magnitude.
 
-Returns: True when adjustment is allowed.
+Returns: Nothing.
 
-### extractAncestorUniqueness
+### applyLineagePressureAdjustment
 
 ```ts
-extractAncestorUniqueness(
+applyLineagePressureAdjustment(
   engine: NeatLikeWithAdaptive,
-): number | undefined
+  ancestorUniq: number,
+  thresholds: { lowThreshold: number; highThreshold: number; },
+): void
 ```
 
-Extract the latest ancestor-uniqueness metric from telemetry.
+Apply lineage pressure strength adjustments.
 
-Lineage adaptation only trusts the most recent telemetry snapshot because it
-represents the latest scored generation. Missing or non-numeric lineage
-evidence simply disables the adjustment for that cycle.
+Lineage-pressure mode keeps the feedback inside the ancestry-based selection
+settings themselves. Low uniqueness increases spread pressure, while high
+uniqueness relaxes it so the search does not over-penalize related genomes.
 
 Parameters:
 - `engine` - - NEAT engine instance.
+- `ancestorUniq` - - Current ancestor uniqueness metric.
+- `thresholds` - - Threshold bounds for decisions.
 
-Returns: Ancestor uniqueness value or undefined when missing.
-
-### resolveUniquenessThresholds
-
-```ts
-resolveUniquenessThresholds(
-  config: { enabled?: boolean | undefined; cooldown?: number | undefined; lowThreshold?: number | undefined; highThreshold?: number | undefined; adjust?: number | undefined; mode?: string | undefined; },
-): { lowThreshold: number; highThreshold: number; }
-```
-
-Resolve thresholds for ancestor-uniqueness decisions.
-
-These bounds define the acceptable ancestry-diversity band. Values below the
-lower threshold suggest the population is converging onto similar family
-trees, while values above the upper threshold suggest diversity pressure may
-already be stronger than needed.
-
-Parameters:
-- `config` - - Ancestor uniqueness adaptive configuration.
-
-Returns: Threshold bounds.
-
-### resolveAdjustmentMagnitude
-
-```ts
-resolveAdjustmentMagnitude(
-  config: { enabled?: boolean | undefined; cooldown?: number | undefined; lowThreshold?: number | undefined; highThreshold?: number | undefined; adjust?: number | undefined; mode?: string | undefined; },
-): number
-```
-
-Resolve adjustment magnitude for nudging controlled parameters.
-
-Magnitude resolution keeps defaulting logic away from the mode-specific
-adjusters so those helpers can focus on policy semantics.
-
-Parameters:
-- `config` - - Ancestor uniqueness adaptive configuration.
-
-Returns: Adjustment magnitude.
+Returns: Nothing.
 
 ### applyUniquenessAdjustment
 
@@ -283,72 +253,64 @@ Parameters:
 
 Returns: Nothing.
 
-### applyEpsilonAdjustment
+### ensureLineagePressureState
 
 ```ts
-applyEpsilonAdjustment(
+ensureLineagePressureState(
   engine: NeatLikeWithAdaptive,
-  ancestorUniq: number,
-  thresholds: { lowThreshold: number; highThreshold: number; },
-  adjustMagnitude: number,
-): void
+): { enabled?: boolean | undefined; mode?: string | undefined; strength?: number | undefined; }
 ```
 
-Apply dominance-epsilon adjustments when configured.
+Ensure lineage pressure state is available.
 
-Epsilon mode nudges the multi-objective dominance tolerance when ancestry is
-too uniform or too diffuse. That lets later Pareto comparisons become slightly
-more or less permissive without changing the current generation directly.
+Some runs do not seed lineage-pressure options up front. This helper creates a
+minimal spread-oriented state only when lineage-feedback mode actually needs
+one.
 
 Parameters:
 - `engine` - - NEAT engine instance.
-- `ancestorUniq` - - Current ancestor uniqueness metric.
-- `thresholds` - - Threshold bounds for decisions.
-- `adjustMagnitude` - - Adjustment magnitude.
 
-Returns: Nothing.
+Returns: Lineage pressure configuration object.
 
-### applyLineagePressureAdjustment
+### extractAncestorUniqueness
 
 ```ts
-applyLineagePressureAdjustment(
+extractAncestorUniqueness(
   engine: NeatLikeWithAdaptive,
-  ancestorUniq: number,
-  thresholds: { lowThreshold: number; highThreshold: number; },
-): void
+): number | undefined
 ```
 
-Apply lineage pressure strength adjustments.
+Extract the latest ancestor-uniqueness metric from telemetry.
 
-Lineage-pressure mode keeps the feedback inside the ancestry-based selection
-settings themselves. Low uniqueness increases spread pressure, while high
-uniqueness relaxes it so the search does not over-penalize related genomes.
+Lineage adaptation only trusts the most recent telemetry snapshot because it
+represents the latest scored generation. Missing or non-numeric lineage
+evidence simply disables the adjustment for that cycle.
 
 Parameters:
 - `engine` - - NEAT engine instance.
-- `ancestorUniq` - - Current ancestor uniqueness metric.
-- `thresholds` - - Threshold bounds for decisions.
 
-Returns: Nothing.
+Returns: Ancestor uniqueness value or undefined when missing.
 
-### ensureLineagePressureState
+### isCooldownSatisfied
 
 ```ts
-ensureLineagePressureState(
+isCooldownSatisfied(
   engine: NeatLikeWithAdaptive,
-): { enabled?: boolean | undefined; mode?: string | undefined; strength?: number | undefined; }
+  config: { enabled?: boolean | undefined; cooldown?: number | undefined; lowThreshold?: number | undefined; highThreshold?: number | undefined; adjust?: number | undefined; mode?: string | undefined; },
+): boolean
 ```
 
-Ensure lineage pressure state is available.
+Determine whether the cooldown window has elapsed.
 
-Some runs do not seed lineage-pressure options up front. This helper creates a
-minimal spread-oriented state only when lineage-feedback mode actually needs
-one.
+Cooldowns prevent the controller from thrashing lineage policy on every
+generation. Once an adjustment has been recorded, later generations must wait
+for the configured gap before another nudge is allowed.
 
 Parameters:
 - `engine` - - NEAT engine instance.
+- `config` - - Ancestor uniqueness adaptive configuration.
 
-Returns: Lineage pressure configuration object.
+Returns: True when adjustment is allowed.
 
 ### recordAdjustment
 
@@ -367,3 +329,41 @@ Parameters:
 - `engine` - - NEAT engine instance.
 
 Returns: Nothing.
+
+### resolveAdjustmentMagnitude
+
+```ts
+resolveAdjustmentMagnitude(
+  config: { enabled?: boolean | undefined; cooldown?: number | undefined; lowThreshold?: number | undefined; highThreshold?: number | undefined; adjust?: number | undefined; mode?: string | undefined; },
+): number
+```
+
+Resolve adjustment magnitude for nudging controlled parameters.
+
+Magnitude resolution keeps defaulting logic away from the mode-specific
+adjusters so those helpers can focus on policy semantics.
+
+Parameters:
+- `config` - - Ancestor uniqueness adaptive configuration.
+
+Returns: Adjustment magnitude.
+
+### resolveUniquenessThresholds
+
+```ts
+resolveUniquenessThresholds(
+  config: { enabled?: boolean | undefined; cooldown?: number | undefined; lowThreshold?: number | undefined; highThreshold?: number | undefined; adjust?: number | undefined; mode?: string | undefined; },
+): { lowThreshold: number; highThreshold: number; }
+```
+
+Resolve thresholds for ancestor-uniqueness decisions.
+
+These bounds define the acceptable ancestry-diversity band. Values below the
+lower threshold suggest the population is converging onto similar family
+trees, while values above the upper threshold suggest diversity pressure may
+already be stronger than needed.
+
+Parameters:
+- `config` - - Ancestor uniqueness adaptive configuration.
+
+Returns: Threshold bounds.