@reicek/neataptic-ts 0.1.24 → 0.1.26

package/src/neat/evaluate/README.md

@@ -107,67 +107,68 @@ const bestScore = Math.max(...controller.population.map((genome) => genome.score
 console.log('best score after evaluation:', bestScore);
 ```
 
-### 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
 
@@ -176,68 +177,81 @@ 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
+### NeatControllerForEval
 
-Minimum structural-distance coefficient allowed during automatic tuning.
+NEAT controller interface for evaluation.
 
-The lower bound keeps structural differences meaningful even when the auto-distance policy is
-softening species pressure.
+This interface models the subset of a NEAT controller used by the evaluation
+helpers. It includes the runtime options, population data, lightweight
+evidence caches, and optional hooks that the evaluate subtree needs in order
+to enrich one generation without taking ownership of the whole controller.
 
-### AUTO_COEFF_MAX_DEFAULT
+The contract is intentionally broader than an individual helper needs but
+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.
 
-Maximum structural-distance coefficient allowed during automatic tuning.
+### NOVELTY_ARCHIVE_CAP
 
-The upper bound prevents excess and disjoint penalties from dominating every later compatibility
-comparison.
+Maximum number of descriptors retained in the novelty archive.
 
-### DISTANCE_COEFF_DEFAULT
+The cap keeps novelty history useful for exploration while preventing unbounded memory growth.
 
-Baseline structural-distance coefficient used before automatic tuning occurs.
+### NOVELTY_DEFAULT_BLEND
 
-This is the neutral starting point for the structural-distance fold before variance-driven
-updates begin to reshape it.
+Default blend factor used when mixing novelty into an existing fitness score.
+
+A mid-range value keeps novelty influential without letting exploratory behavior completely drown
+out task performance.
+
+### NOVELTY_DEFAULT_NEIGHBORS
+
+Default number of nearest neighbors used when computing novelty.
+
+Small values keep novelty sensitive to local behavioral differences without requiring a large
+archive or population.
 
 ### VARIANCE_DECREASE_THRESHOLD
 
@@ -252,17 +266,3 @@ Multiplier above which observed variance is treated as a meaningful increase.
 
 Values above this band tell the auto-distance loop that topology sizes are spreading relative to
 the recent baseline.
-
-### NeatControllerForEval
-
-NEAT controller interface for evaluation.
-
-This interface models the subset of a NEAT controller used by the evaluation
-helpers. It includes the runtime options, population data, lightweight
-evidence caches, and optional hooks that the evaluate subtree needs in order
-to enrich one generation without taking ownership of the whole controller.
-
-The contract is intentionally broader than an individual helper needs but
-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.

package/src/neat/evaluate/auto-distance/README.md

@@ -52,40 +52,78 @@ flowchart TD
 
 ## neat/evaluate/auto-distance/evaluate.auto-distance.ts
 
-### runAutoDistanceCoefficientTuning
+### applyAutoDistanceCoefficientTuning
 
 ```ts
-runAutoDistanceCoefficientTuning(
+applyAutoDistanceCoefficientTuning(
   controller: NeatControllerForEval,
-  evaluationOptions: { [key: string]: unknown; fitnessPopulation?: boolean | undefined; clear?: boolean | undefined; novelty?: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; } | undefined; entropySharingTuning?: { enabled?: boolean | undefined; targetEntropyVar?: number | undefined; adjustRate?: number | undefined; minSigma?: number | undefined; maxSigma?: number | undefined; } | undefined; entropyCompatTuning?: { enabled?: boolean | undefined; targetEntropy?: number | undefined; deadband?: number | undefined; adjustRate?: number | undefined; minThreshold?: number | undefined; maxThreshold?: number | undefined; } | undefined; autoDistanceCoeffTuning?: { enabled?: boolean | undefined; adjustRate?: number | undefined; minCoeff?: number | undefined; maxCoeff?: number | undefined; } | undefined; multiObjective?: { enabled?: boolean | undefined; autoEntropy?: boolean | undefined; dynamic?: { enabled?: boolean | undefined; } | undefined; } | undefined; speciation?: boolean | undefined; targetSpecies?: number | undefined; compatAdjust?: boolean | undefined; speciesAllocation?: { extendedHistory?: boolean | undefined; } | undefined; sharingSigma?: number | undefined; compatibilityThreshold?: number | undefined; excessCoeff?: number | undefined; disjointCoeff?: number | undefined; },
+  autoDistanceCoeffOptions: { enabled?: boolean | undefined; adjustRate?: number | undefined; minCoeff?: number | undefined; maxCoeff?: number | undefined; },
+  connectionVariance: number,
 ): void
 ```
 
-Apply variance-driven tuning to the controller's distance coefficients.
+Apply the coefficient-tuning policy using the observed connection variance.
 
-This is the controller-facing entrypoint for auto-distance tuning. It only
-runs when both speciation and auto coefficient tuning are enabled because the
-resulting coefficients are only meaningful when later compatibility reads are
-still part of the runtime policy.
+This helper compares the freshly observed variance with the controller's
+stored baseline. Lower-than-expected variance means topology sizes are
+converging, so excess and disjoint coefficients are increased to make future
+structural differences matter more. Higher-than-expected variance means the
+population is already spreading structurally, so the coefficients are eased
+downward.
 
-The helper preserves several important controller assumptions:
-- genome scores are already complete and are not recomputed here,
-- live species assignments are left intact,
-- population order is left intact,
-- only the structural-distance coefficients and their variance baseline are
-  updated for future passes.
+The comparison is deliberately relative instead of target-based. The policy
+tracks the population's recent structural spread and responds to drift,
+rather than forcing every problem domain toward one global variance number.
 
 Parameters:
 - `controller` - - NEAT controller instance for evaluation.
-- `evaluationOptions` - - Options object for the current evaluation pass.
+- `autoDistanceCoeffOptions` - - Tuning options that define adjustment rate
+and coefficient bounds.
+- `connectionVariance` - - Freshly observed variance of population
+connection counts.
 
-Example:
+### applyDistanceCoefficientDecrease
 
 ```ts
-runAutoDistanceCoefficientTuning(controller, controller.options);
-console.log(controller.options.excessCoeff, controller.options.disjointCoeff);
+applyDistanceCoefficientDecrease(
+  controller: NeatControllerForEval,
+  bounds: { minCoeff: number; maxCoeff: number; },
+  adjustRate: number,
+): void
 ```
 
+Decrease distance coefficients within the configured bounds.
+
+Decreasing these coefficients softens the structural-distance penalty when
+topology sizes are already spreading, which helps keep the controller from
+over-fragmenting species on the next pass.
+
+Parameters:
+- `controller` - - NEAT controller instance for evaluation.
+- `bounds` - - Min and max coefficient bounds.
+- `adjustRate` - - Adjustment rate.
+
+### applyDistanceCoefficientIncrease
+
+```ts
+applyDistanceCoefficientIncrease(
+  controller: NeatControllerForEval,
+  bounds: { minCoeff: number; maxCoeff: number; },
+  adjustRate: number,
+): void
+```
+
+Increase distance coefficients within the configured bounds.
+
+Increasing these coefficients makes later compatibility reads treat excess
+and disjoint structural differences as more important, which helps push back
+when topology sizes are collapsing toward one narrow profile.
+
+Parameters:
+- `controller` - - NEAT controller instance for evaluation.
+- `bounds` - - Min and max coefficient bounds.
+- `adjustRate` - - Adjustment rate.
+
 ### computeMean
 
 ```ts
@@ -126,36 +164,6 @@ Parameters:
 
 Returns: Variance of the values.
 
-### applyAutoDistanceCoefficientTuning
-
-```ts
-applyAutoDistanceCoefficientTuning(
-  controller: NeatControllerForEval,
-  autoDistanceCoeffOptions: { enabled?: boolean | undefined; adjustRate?: number | undefined; minCoeff?: number | undefined; maxCoeff?: number | undefined; },
-  connectionVariance: number,
-): void
-```
-
-Apply the coefficient-tuning policy using the observed connection variance.
-
-This helper compares the freshly observed variance with the controller's
-stored baseline. Lower-than-expected variance means topology sizes are
-converging, so excess and disjoint coefficients are increased to make future
-structural differences matter more. Higher-than-expected variance means the
-population is already spreading structurally, so the coefficients are eased
-downward.
-
-The comparison is deliberately relative instead of target-based. The policy
-tracks the population's recent structural spread and responds to drift,
-rather than forcing every problem domain toward one global variance number.
-
-Parameters:
-- `controller` - - NEAT controller instance for evaluation.
-- `autoDistanceCoeffOptions` - - Tuning options that define adjustment rate
-and coefficient bounds.
-- `connectionVariance` - - Freshly observed variance of population
-connection counts.
-
 ### getDistanceCoefficientBounds
 
 ```ts
@@ -199,44 +207,36 @@ Parameters:
 - `bounds` - - Min and max coefficient bounds.
 - `adjustRate` - - Adjustment rate.
 
-### applyDistanceCoefficientIncrease
+### runAutoDistanceCoefficientTuning
 
 ```ts
-applyDistanceCoefficientIncrease(
+runAutoDistanceCoefficientTuning(
   controller: NeatControllerForEval,
-  bounds: { minCoeff: number; maxCoeff: number; },
-  adjustRate: number,
+  evaluationOptions: { [key: string]: unknown; fitnessPopulation?: boolean | undefined; clear?: boolean | undefined; novelty?: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; } | undefined; entropySharingTuning?: { enabled?: boolean | undefined; targetEntropyVar?: number | undefined; adjustRate?: number | undefined; minSigma?: number | undefined; maxSigma?: number | undefined; } | undefined; entropyCompatTuning?: { enabled?: boolean | undefined; targetEntropy?: number | undefined; deadband?: number | undefined; adjustRate?: number | undefined; minThreshold?: number | undefined; maxThreshold?: number | undefined; } | undefined; autoDistanceCoeffTuning?: { enabled?: boolean | undefined; adjustRate?: number | undefined; minCoeff?: number | undefined; maxCoeff?: number | undefined; } | undefined; multiObjective?: { enabled?: boolean | undefined; autoEntropy?: boolean | undefined; dynamic?: { enabled?: boolean | undefined; } | undefined; } | undefined; speciation?: boolean | undefined; targetSpecies?: number | undefined; compatAdjust?: boolean | undefined; speciesAllocation?: { extendedHistory?: boolean | undefined; } | undefined; sharingSigma?: number | undefined; compatibilityThreshold?: number | undefined; excessCoeff?: number | undefined; disjointCoeff?: number | undefined; },
 ): void
 ```
 
-Increase distance coefficients within the configured bounds.
+Apply variance-driven tuning to the controller's distance coefficients.
 
-Increasing these coefficients makes later compatibility reads treat excess
-and disjoint structural differences as more important, which helps push back
-when topology sizes are collapsing toward one narrow profile.
+This is the controller-facing entrypoint for auto-distance tuning. It only
+runs when both speciation and auto coefficient tuning are enabled because the
+resulting coefficients are only meaningful when later compatibility reads are
+still part of the runtime policy.
+
+The helper preserves several important controller assumptions:
+- genome scores are already complete and are not recomputed here,
+- live species assignments are left intact,
+- population order is left intact,
+- only the structural-distance coefficients and their variance baseline are
+  updated for future passes.
 
 Parameters:
 - `controller` - - NEAT controller instance for evaluation.
-- `bounds` - - Min and max coefficient bounds.
-- `adjustRate` - - Adjustment rate.
+- `evaluationOptions` - - Options object for the current evaluation pass.
 
-### applyDistanceCoefficientDecrease
+Example:
 
 ```ts
-applyDistanceCoefficientDecrease(
-  controller: NeatControllerForEval,
-  bounds: { minCoeff: number; maxCoeff: number; },
-  adjustRate: number,
-): void
+runAutoDistanceCoefficientTuning(controller, controller.options);
+console.log(controller.options.excessCoeff, controller.options.disjointCoeff);
 ```
-
-Decrease distance coefficients within the configured bounds.
-
-Decreasing these coefficients softens the structural-distance penalty when
-topology sizes are already spreading, which helps keep the controller from
-over-fragmenting species on the next pass.
-
-Parameters:
-- `controller` - - NEAT controller instance for evaluation.
-- `bounds` - - Min and max coefficient bounds.
-- `adjustRate` - - Adjustment rate.

package/src/neat/evaluate/entropy-compat/README.md

@@ -47,43 +47,6 @@ flowchart TD
 
 ## neat/evaluate/entropy-compat/evaluate.entropy-compat.ts
 
-### runEntropyCompatibilityTuning
-
-```ts
-runEntropyCompatibilityTuning(
-  controller: NeatControllerForEval,
-  evaluationOptions: { [key: string]: unknown; fitnessPopulation?: boolean | undefined; clear?: boolean | undefined; novelty?: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; } | undefined; entropySharingTuning?: { enabled?: boolean | undefined; targetEntropyVar?: number | undefined; adjustRate?: number | undefined; minSigma?: number | undefined; maxSigma?: number | undefined; } | undefined; entropyCompatTuning?: { enabled?: boolean | undefined; targetEntropy?: number | undefined; deadband?: number | undefined; adjustRate?: number | undefined; minThreshold?: number | undefined; maxThreshold?: number | undefined; } | undefined; autoDistanceCoeffTuning?: { enabled?: boolean | undefined; adjustRate?: number | undefined; minCoeff?: number | undefined; maxCoeff?: number | undefined; } | undefined; multiObjective?: { enabled?: boolean | undefined; autoEntropy?: boolean | undefined; dynamic?: { enabled?: boolean | undefined; } | undefined; } | undefined; speciation?: boolean | undefined; targetSpecies?: number | undefined; compatAdjust?: boolean | undefined; speciesAllocation?: { extendedHistory?: boolean | undefined; } | undefined; sharingSigma?: number | undefined; compatibilityThreshold?: number | undefined; excessCoeff?: number | undefined; disjointCoeff?: number | undefined; },
-): void
-```
-
-Adjust the compatibility threshold when entropy-compatibility tuning is enabled.
-
-This is the controller-facing entrypoint for the entropy-compatibility
-chapter. It behaves like best-effort maintenance after fresh diversity
-evidence has been written, not like a required scoring or speciation phase.
-
-The helper preserves several important controller assumptions:
-- genome scores are already complete and are not recomputed here,
-- current species assignments are left intact,
-- population order is left intact,
-- only `compatibilityThreshold` is prepared for later passes.
-
-That narrow scope lets the evaluation chapter adjust future speciation
-pressure without widening into a full species-rebuild workflow.
-
-Parameters:
-- `controller` - - NEAT controller instance for evaluation.
-- `evaluationOptions` - - Options object for the current evaluation pass.
-
-Example:
-
-```ts
-controller._diversityStats = { meanEntropy: 0.42 };
-
-runEntropyCompatibilityTuning(controller, controller.options);
-console.log(controller.options.compatibilityThreshold);
-```
-
 ### computeNextCompatibilityThreshold
 
 ```ts
@@ -126,3 +89,40 @@ const nextThreshold = computeNextCompatibilityThreshold(
 
 console.log(nextThreshold);
 ```
+
+### runEntropyCompatibilityTuning
+
+```ts
+runEntropyCompatibilityTuning(
+  controller: NeatControllerForEval,
+  evaluationOptions: { [key: string]: unknown; fitnessPopulation?: boolean | undefined; clear?: boolean | undefined; novelty?: { enabled?: boolean | undefined; descriptor?: ((genome: GenomeForEvaluation) => number[]) | undefined; k?: number | undefined; blendFactor?: number | undefined; archiveAddThreshold?: number | undefined; } | undefined; entropySharingTuning?: { enabled?: boolean | undefined; targetEntropyVar?: number | undefined; adjustRate?: number | undefined; minSigma?: number | undefined; maxSigma?: number | undefined; } | undefined; entropyCompatTuning?: { enabled?: boolean | undefined; targetEntropy?: number | undefined; deadband?: number | undefined; adjustRate?: number | undefined; minThreshold?: number | undefined; maxThreshold?: number | undefined; } | undefined; autoDistanceCoeffTuning?: { enabled?: boolean | undefined; adjustRate?: number | undefined; minCoeff?: number | undefined; maxCoeff?: number | undefined; } | undefined; multiObjective?: { enabled?: boolean | undefined; autoEntropy?: boolean | undefined; dynamic?: { enabled?: boolean | undefined; } | undefined; } | undefined; speciation?: boolean | undefined; targetSpecies?: number | undefined; compatAdjust?: boolean | undefined; speciesAllocation?: { extendedHistory?: boolean | undefined; } | undefined; sharingSigma?: number | undefined; compatibilityThreshold?: number | undefined; excessCoeff?: number | undefined; disjointCoeff?: number | undefined; },
+): void
+```
+
+Adjust the compatibility threshold when entropy-compatibility tuning is enabled.
+
+This is the controller-facing entrypoint for the entropy-compatibility
+chapter. It behaves like best-effort maintenance after fresh diversity
+evidence has been written, not like a required scoring or speciation phase.
+
+The helper preserves several important controller assumptions:
+- genome scores are already complete and are not recomputed here,
+- current species assignments are left intact,
+- population order is left intact,
+- only `compatibilityThreshold` is prepared for later passes.
+
+That narrow scope lets the evaluation chapter adjust future speciation
+pressure without widening into a full species-rebuild workflow.
+
+Parameters:
+- `controller` - - NEAT controller instance for evaluation.
+- `evaluationOptions` - - Options object for the current evaluation pass.
+
+Example:
+
+```ts
+controller._diversityStats = { meanEntropy: 0.42 };
+
+runEntropyCompatibilityTuning(controller, controller.options);
+console.log(controller.options.compatibilityThreshold);
+```

package/src/neat/evaluate/entropy-sharing/README.md

@@ -46,6 +46,49 @@ flowchart TD
 
 ## neat/evaluate/entropy-sharing/evaluate.entropy-sharing.ts
 
+### computeNextSharingSigma
+
+```ts
+computeNextSharingSigma(
+  entropySharingOptions: { enabled?: boolean | undefined; targetEntropyVar?: number | undefined; adjustRate?: number | undefined; minSigma?: number | undefined; maxSigma?: number | undefined; },
+  currentVarEntropy: number,
+  currentSigma: number,
+): number
+```
+
+Compute the next sharing sigma value from the observed entropy variance.
+
+The tuning rule is intentionally small and band-driven instead of trying to
+build a full controller inside evaluation. When observed variance drops below
+the low band, sigma is reduced so the next pass applies a tighter sharing
+radius. When variance rises above the high band, sigma is increased so the
+next pass smooths pressure across a wider neighborhood. Values inside the
+band keep the current sigma unchanged.
+
+The returned value is always clamped to the configured minimum and maximum,
+which keeps tuning predictable even when entropy measurements swing sharply.
+
+Parameters:
+- `entropySharingOptions` - - Tuning options that define the target
+entropy variance, adjustment rate, and clamp bounds.
+- `currentVarEntropy` - - Freshly observed variance of structural entropy
+for the current population.
+- `currentSigma` - - Current sharing sigma before this adjustment.
+
+Returns: Next sharing sigma value to carry into later controller passes.
+
+Example:
+
+```ts
+const nextSigma = computeNextSharingSigma(
+  { enabled: true, targetEntropyVar: 0.2, adjustRate: 0.1, minSigma: 0.5, maxSigma: 3 },
+  0.28,
+  1,
+);
+
+console.log(nextSigma);
+```
+
 ### ensureDiversityStatsContainer
 
 ```ts
@@ -102,46 +145,3 @@ controller._diversityStats!.varEntropy = 0.18;
 runEntropySharingTuning(controller, controller.options);
 console.log(controller.options.sharingSigma);
 ```
-
-### computeNextSharingSigma
-
-```ts
-computeNextSharingSigma(
-  entropySharingOptions: { enabled?: boolean | undefined; targetEntropyVar?: number | undefined; adjustRate?: number | undefined; minSigma?: number | undefined; maxSigma?: number | undefined; },
-  currentVarEntropy: number,
-  currentSigma: number,
-): number
-```
-
-Compute the next sharing sigma value from the observed entropy variance.
-
-The tuning rule is intentionally small and band-driven instead of trying to
-build a full controller inside evaluation. When observed variance drops below
-the low band, sigma is reduced so the next pass applies a tighter sharing
-radius. When variance rises above the high band, sigma is increased so the
-next pass smooths pressure across a wider neighborhood. Values inside the
-band keep the current sigma unchanged.
-
-The returned value is always clamped to the configured minimum and maximum,
-which keeps tuning predictable even when entropy measurements swing sharply.
-
-Parameters:
-- `entropySharingOptions` - - Tuning options that define the target
-entropy variance, adjustment rate, and clamp bounds.
-- `currentVarEntropy` - - Freshly observed variance of structural entropy
-for the current population.
-- `currentSigma` - - Current sharing sigma before this adjustment.
-
-Returns: Next sharing sigma value to carry into later controller passes.
-
-Example:
-
-```ts
-const nextSigma = computeNextSharingSigma(
-  { enabled: true, targetEntropyVar: 0.2, adjustRate: 0.1, minSigma: 0.5, maxSigma: 3 },
-  0.28,
-  1,
-);
-
-console.log(nextSigma);
-```