@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/pruning/README.md

@@ -37,46 +37,6 @@ flowchart TD
 
 ## neat/pruning/pruning.ts
 
-### applyEvolutionPruning
-
-```ts
-applyEvolutionPruning(): void
-```
-
-Apply evolution-time pruning to the current population.
-
-Use this path when pruning should follow the generation schedule rather than
-a live feedback loop. The evolve orchestration calls into this entrypoint to
-ask a simple controller question: "for this generation, should pruning run,
-and if so, how sparse should genomes become right now?"
-
-This function does not maintain long-lived adaptive controller state. Instead
-it reads the configured `evolutionPruning` schedule, checks whether the
-current generation is inside the active window, computes the ramped target
-sparsity for that moment in the run, and forwards the result to the genomes.
-The host generation counter is read but not mutated here.
-
-Choose this entrypoint when you want pruning to be predictable and tied to
-generation timing. Use `applyAdaptivePruning()` instead when pruning should
-react to observed population size or complexity metrics at runtime.
-
-Returns: Nothing. Compatible genomes may be pruned in place when the schedule is active, but no adaptive controller fields are updated.
-
-Example:
-
-```ts
-host.generation = 40;
-host.options.evolutionPruning = {
-  startGeneration: 20,
-  interval: 5,
-  rampGenerations: 10,
-  targetSparsity: 0.3,
-};
-
-applyEvolutionPruning.call(host);
-// Compatible genomes prune themselves using the schedule-derived sparsity.
-```
-
 ### applyAdaptivePruning
 
 ```ts
@@ -118,3 +78,43 @@ applyAdaptivePruning.call(host);
 // The host may initialize its baseline, update _adaptivePruneLevel,
 // and prune compatible genomes if the metric drift is large enough.
 ```
+
+### applyEvolutionPruning
+
+```ts
+applyEvolutionPruning(): void
+```
+
+Apply evolution-time pruning to the current population.
+
+Use this path when pruning should follow the generation schedule rather than
+a live feedback loop. The evolve orchestration calls into this entrypoint to
+ask a simple controller question: "for this generation, should pruning run,
+and if so, how sparse should genomes become right now?"
+
+This function does not maintain long-lived adaptive controller state. Instead
+it reads the configured `evolutionPruning` schedule, checks whether the
+current generation is inside the active window, computes the ramped target
+sparsity for that moment in the run, and forwards the result to the genomes.
+The host generation counter is read but not mutated here.
+
+Choose this entrypoint when you want pruning to be predictable and tied to
+generation timing. Use `applyAdaptivePruning()` instead when pruning should
+react to observed population size or complexity metrics at runtime.
+
+Returns: Nothing. Compatible genomes may be pruned in place when the schedule is active, but no adaptive controller fields are updated.
+
+Example:
+
+```ts
+host.generation = 40;
+host.options.evolutionPruning = {
+  startGeneration: 20,
+  interval: 5,
+  rampGenerations: 10,
+  targetSparsity: 0.3,
+};
+
+applyEvolutionPruning.call(host);
+// Compatible genomes prune themselves using the schedule-derived sparsity.
+```

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

@@ -22,6 +22,22 @@ which configuration knobs belong to scheduled versus adaptive control.
 
 ## neat/pruning/core/pruning.types.ts
 
+### AdaptivePruningOptions
+
+Adaptive pruning options extracted from the NEAT host.
+
+These options drive the feedback-controller path: which population metric is
+observed, what sparsity target should remain, how large a drift is tolerated,
+and how quickly the shared prune level is allowed to move.
+
+### EvolutionPruningOptions
+
+Evolution pruning options extracted from the NEAT host.
+
+These options drive the calendar-like pruning path: when pruning starts, how
+often it repeats, how quickly the target sparsity ramps in, and which pruning
+method is forwarded to compatible genomes.
+
 ### NeatLikeForPruning
 
 Minimal NEAT host contract required by pruning helpers.
@@ -44,22 +60,6 @@ Read this chapter before `pruning.core.ts` when you need to know which state
 the pruning helpers are allowed to read, which state they may write back, and
 which configuration knobs belong to scheduled versus adaptive control.
 
-### EvolutionPruningOptions
-
-Evolution pruning options extracted from the NEAT host.
-
-These options drive the calendar-like pruning path: when pruning starts, how
-often it repeats, how quickly the target sparsity ramps in, and which pruning
-method is forwarded to compatible genomes.
-
-### AdaptivePruningOptions
-
-Adaptive pruning options extracted from the NEAT host.
-
-These options drive the feedback-controller path: which population metric is
-observed, what sparsity target should remain, how large a drift is tolerated,
-and how quickly the shared prune level is allowed to move.
-
 ### PopulationMetrics
 
 Summary of population metrics used by adaptive pruning.
@@ -102,66 +102,26 @@ flowchart TD
   Hold --> ApplyAdaptive
 ```
 
-### resolveActiveEvolutionPruningOptions
-
-```ts
-resolveActiveEvolutionPruningOptions(
-  host: NeatLikeForPruning,
-): { startGeneration?: number | undefined; interval?: number | undefined; rampGenerations?: number | undefined; targetSparsity?: number | undefined; method?: string | undefined; } | null
-```
-
-Resolve scheduled pruning options when they are active for the current generation.
-
-This helper is the gatekeeper for the calendar-driven pruning path. It keeps
-the public pruning wrapper simple by answering one precise question: does the
-current generation actually belong to the configured pruning schedule?
-
-Parameters:
-- `host` - - NEAT host exposing generation and pruning options.
-
-Returns: Evolution pruning options when active, otherwise `null`.
-
-### computeTargetSparsityNow
-
-```ts
-computeTargetSparsityNow(
-  host: NeatLikeForPruning,
-  options: { startGeneration?: number | undefined; interval?: number | undefined; rampGenerations?: number | undefined; targetSparsity?: number | undefined; method?: string | undefined; },
-): number
-```
-
-Compute the target sparsity for the current generation.
-
-Scheduled pruning ramps toward its configured sparsity target instead of
-snapping there immediately. This helper converts the current ramp progress
-into the exact target sparsity the active generation should use.
-
-Parameters:
-- `host` - - NEAT host exposing generation state.
-- `options` - - Active scheduled pruning options.
-
-Returns: Target sparsity for the current generation.
-
-### computeRampFraction
+### applyAdaptivePruneLevelToPopulation
 
 ```ts
-computeRampFraction(
+applyAdaptivePruneLevelToPopulation(
   host: NeatLikeForPruning,
-  options: { startGeneration?: number | undefined; interval?: number | undefined; rampGenerations?: number | undefined; targetSparsity?: number | undefined; method?: string | undefined; },
-): number
+  pruneLevel: number,
+): void
 ```
 
-Compute the ramp completion fraction for scheduled pruning.
+Apply the shared adaptive prune level to every compatible genome.
 
-The ramp fraction is the soft-start mechanism for scheduled pruning. It lets
-the controller phase sparsity in gradually over several generations so the
-population does not experience one abrupt structural shock.
+This is the final fan-out step for adaptive pruning. The host maintains one
+shared prune level, and this helper applies that single controller decision
+uniformly across genomes that support sparsity pruning.
 
 Parameters:
-- `host` - - NEAT host exposing generation state.
-- `options` - - Active scheduled pruning options.
+- `host` - - NEAT host exposing the population.
+- `pruneLevel` - - Prune level to apply.
 
-Returns: Fraction in `[0, 1]` indicating ramp completion.
+Returns: Nothing. Compatible genomes are pruned in place.
 
 ### applyPruningToPopulation
 
@@ -186,44 +146,69 @@ Parameters:
 
 Returns: Nothing. Genomes are pruned in place when supported.
 
-### resolveActiveAdaptivePruningOptions
+### computeMeanConnectionCount
 
 ```ts
-resolveActiveAdaptivePruningOptions(
+computeMeanConnectionCount(
   host: NeatLikeForPruning,
-): { enabled?: boolean | undefined; metric?: string | undefined; targetSparsity?: number | undefined; learningRate?: number | undefined; tolerance?: number | undefined; adjustRate?: number | undefined; } | null
+): number
 ```
 
-Resolve adaptive pruning options when enabled.
+Compute the average connection count per genome.
 
-This is the narrow on-ramp to the feedback-controller branch. It makes the
-rest of the adaptive helpers read linearly by collapsing disabled or missing
-configuration into one `null` check.
+Connection count is the denser complexity signal commonly used for sparsity
+control. Like node count, it is reduced to a population mean so the adaptive
+controller reacts to trend rather than to one outlier genome.
 
 Parameters:
-- `host` - - NEAT host exposing adaptive pruning options.
+- `host` - - NEAT host exposing the population.
 
-Returns: Adaptive pruning options when enabled, otherwise `null`.
+Returns: Average number of connections per genome.
 
-### initializeAdaptivePruningState
+### computeMeanNodeCount
 
 ```ts
-initializeAdaptivePruningState(
+computeMeanNodeCount(
   host: NeatLikeForPruning,
-): void
+): number
 ```
 
-Ensure the adaptive pruning state exists on the host.
+Compute the average node count per genome.
 
-Adaptive pruning keeps one shared prune level on the host so the whole
-population can react coherently across generations. This helper bootstraps
-that state once, rather than making every downstream helper repeat the same
-initialization guard.
+Node count is one of the two complexity signals the adaptive controller can
+watch. It is intentionally averaged so population size changes do not by
+themselves distort the pruning signal.
 
 Parameters:
-- `host` - - NEAT host exposing adaptive pruning state.
+- `host` - - NEAT host exposing the population.
 
-Returns: Nothing. The shared prune level is initialized when missing.
+Returns: Average number of nodes per genome.
+
+### computeNextAdaptivePruneLevel
+
+```ts
+computeNextAdaptivePruneLevel(
+  options: { enabled?: boolean | undefined; metric?: string | undefined; targetSparsity?: number | undefined; learningRate?: number | undefined; tolerance?: number | undefined; adjustRate?: number | undefined; },
+  currentPruneLevel: number,
+  currentMetricValue: number,
+  targetRemainingMetric: number,
+): number
+```
+
+Compute the next adaptive prune level.
+
+Once the controller decides that drift is large enough, this helper turns the
+direction of that drift into a bounded update of the shared prune level.
+Higher-than-target complexity tightens pruning; lower-than-target complexity
+relaxes it.
+
+Parameters:
+- `options` - - Adaptive pruning options.
+- `currentPruneLevel` - - Current shared prune level.
+- `currentMetricValue` - - Current observed metric value.
+- `targetRemainingMetric` - - Target remaining metric value.
+
+Returns: Updated prune level clamped into the valid sparsity range.
 
 ### computePopulationMetrics
 
@@ -245,64 +230,127 @@ Parameters:
 
 Returns: Summary of mean node and connection counts.
 
-### computeMeanNodeCount
+### computeRampFraction
 
 ```ts
-computeMeanNodeCount(
+computeRampFraction(
   host: NeatLikeForPruning,
+  options: { startGeneration?: number | undefined; interval?: number | undefined; rampGenerations?: number | undefined; targetSparsity?: number | undefined; method?: string | undefined; },
 ): number
 ```
 
-Compute the average node count per genome.
+Compute the ramp completion fraction for scheduled pruning.
 
-Node count is one of the two complexity signals the adaptive controller can
-watch. It is intentionally averaged so population size changes do not by
-themselves distort the pruning signal.
+The ramp fraction is the soft-start mechanism for scheduled pruning. It lets
+the controller phase sparsity in gradually over several generations so the
+population does not experience one abrupt structural shock.
 
 Parameters:
-- `host` - - NEAT host exposing the population.
+- `host` - - NEAT host exposing generation state.
+- `options` - - Active scheduled pruning options.
 
-Returns: Average number of nodes per genome.
+Returns: Fraction in `[0, 1]` indicating ramp completion.
 
-### computeMeanConnectionCount
+### computeTargetRemainingMetric
 
 ```ts
-computeMeanConnectionCount(
-  host: NeatLikeForPruning,
+computeTargetRemainingMetric(
+  options: { enabled?: boolean | undefined; metric?: string | undefined; targetSparsity?: number | undefined; learningRate?: number | undefined; tolerance?: number | undefined; adjustRate?: number | undefined; },
+  adaptivePruneBaseline: number,
 ): number
 ```
 
-Compute the average connection count per genome.
+Compute the target remaining metric implied by the desired sparsity.
 
-Connection count is the denser complexity signal commonly used for sparsity
-control. Like node count, it is reduced to a population mean so the adaptive
-controller reacts to trend rather than to one outlier genome.
+Adaptive pruning expresses its goal as desired sparsity, but the feedback loop
+compares live complexity metrics. This helper bridges those two views by
+translating the baseline metric into the remaining amount of structure the
+controller wants to keep.
 
 Parameters:
-- `host` - - NEAT host exposing the population.
+- `options` - - Adaptive pruning options.
+- `adaptivePruneBaseline` - - Baseline metric value.
 
-Returns: Average number of connections per genome.
+Returns: Target remaining metric value.
 
-### resolveObservedMetricValue
+### computeTargetSparsityNow
 
 ```ts
-resolveObservedMetricValue(
-  options: { enabled?: boolean | undefined; metric?: string | undefined; targetSparsity?: number | undefined; learningRate?: number | undefined; tolerance?: number | undefined; adjustRate?: number | undefined; },
-  metrics: PopulationMetrics,
+computeTargetSparsityNow(
+  host: NeatLikeForPruning,
+  options: { startGeneration?: number | undefined; interval?: number | undefined; rampGenerations?: number | undefined; targetSparsity?: number | undefined; method?: string | undefined; },
 ): number
 ```
 
-Resolve the currently observed population metric for adaptive pruning.
+Compute the target sparsity for the current generation.
 
-Adaptive pruning can watch either node count or connection count. This helper
-turns the configured metric name into the actual observed value that the rest
-of the controller math will compare with the target remaining complexity.
+Scheduled pruning ramps toward its configured sparsity target instead of
+snapping there immediately. This helper converts the current ramp progress
+into the exact target sparsity the active generation should use.
 
 Parameters:
-- `options` - - Adaptive pruning options.
-- `metrics` - - Population metric summary.
+- `host` - - NEAT host exposing generation state.
+- `options` - - Active scheduled pruning options.
 
-Returns: Current observed metric value used for adaptation.
+Returns: Target sparsity for the current generation.
+
+### initializeAdaptivePruningState
+
+```ts
+initializeAdaptivePruningState(
+  host: NeatLikeForPruning,
+): void
+```
+
+Ensure the adaptive pruning state exists on the host.
+
+Adaptive pruning keeps one shared prune level on the host so the whole
+population can react coherently across generations. This helper bootstraps
+that state once, rather than making every downstream helper repeat the same
+initialization guard.
+
+Parameters:
+- `host` - - NEAT host exposing adaptive pruning state.
+
+Returns: Nothing. The shared prune level is initialized when missing.
+
+### resolveActiveAdaptivePruningOptions
+
+```ts
+resolveActiveAdaptivePruningOptions(
+  host: NeatLikeForPruning,
+): { enabled?: boolean | undefined; metric?: string | undefined; targetSparsity?: number | undefined; learningRate?: number | undefined; tolerance?: number | undefined; adjustRate?: number | undefined; } | null
+```
+
+Resolve adaptive pruning options when enabled.
+
+This is the narrow on-ramp to the feedback-controller branch. It makes the
+rest of the adaptive helpers read linearly by collapsing disabled or missing
+configuration into one `null` check.
+
+Parameters:
+- `host` - - NEAT host exposing adaptive pruning options.
+
+Returns: Adaptive pruning options when enabled, otherwise `null`.
+
+### resolveActiveEvolutionPruningOptions
+
+```ts
+resolveActiveEvolutionPruningOptions(
+  host: NeatLikeForPruning,
+): { startGeneration?: number | undefined; interval?: number | undefined; rampGenerations?: number | undefined; targetSparsity?: number | undefined; method?: string | undefined; } | null
+```
+
+Resolve scheduled pruning options when they are active for the current generation.
+
+This helper is the gatekeeper for the calendar-driven pruning path. It keeps
+the public pruning wrapper simple by answering one precise question: does the
+current generation actually belong to the configured pruning schedule?
+
+Parameters:
+- `host` - - NEAT host exposing generation and pruning options.
+
+Returns: Evolution pruning options when active, otherwise `null`.
 
 ### resolveAdaptivePruneBaseline
 
@@ -325,27 +373,26 @@ Parameters:
 
 Returns: Baseline metric value used for adaptation.
 
-### computeTargetRemainingMetric
+### resolveObservedMetricValue
 
 ```ts
-computeTargetRemainingMetric(
+resolveObservedMetricValue(
   options: { enabled?: boolean | undefined; metric?: string | undefined; targetSparsity?: number | undefined; learningRate?: number | undefined; tolerance?: number | undefined; adjustRate?: number | undefined; },
-  adaptivePruneBaseline: number,
+  metrics: PopulationMetrics,
 ): number
 ```
 
-Compute the target remaining metric implied by the desired sparsity.
+Resolve the currently observed population metric for adaptive pruning.
 
-Adaptive pruning expresses its goal as desired sparsity, but the feedback loop
-compares live complexity metrics. This helper bridges those two views by
-translating the baseline metric into the remaining amount of structure the
-controller wants to keep.
+Adaptive pruning can watch either node count or connection count. This helper
+turns the configured metric name into the actual observed value that the rest
+of the controller math will compare with the target remaining complexity.
 
 Parameters:
 - `options` - - Adaptive pruning options.
-- `adaptivePruneBaseline` - - Baseline metric value.
+- `metrics` - - Population metric summary.
 
-Returns: Target remaining metric value.
+Returns: Current observed metric value used for adaptation.
 
 ### shouldAdjustAdaptivePruning
 
@@ -371,50 +418,3 @@ Parameters:
 - `adaptivePruneBaseline` - - Baseline metric value.
 
 Returns: `true` when the normalized drift exceeds the configured tolerance.
-
-### computeNextAdaptivePruneLevel
-
-```ts
-computeNextAdaptivePruneLevel(
-  options: { enabled?: boolean | undefined; metric?: string | undefined; targetSparsity?: number | undefined; learningRate?: number | undefined; tolerance?: number | undefined; adjustRate?: number | undefined; },
-  currentPruneLevel: number,
-  currentMetricValue: number,
-  targetRemainingMetric: number,
-): number
-```
-
-Compute the next adaptive prune level.
-
-Once the controller decides that drift is large enough, this helper turns the
-direction of that drift into a bounded update of the shared prune level.
-Higher-than-target complexity tightens pruning; lower-than-target complexity
-relaxes it.
-
-Parameters:
-- `options` - - Adaptive pruning options.
-- `currentPruneLevel` - - Current shared prune level.
-- `currentMetricValue` - - Current observed metric value.
-- `targetRemainingMetric` - - Target remaining metric value.
-
-Returns: Updated prune level clamped into the valid sparsity range.
-
-### applyAdaptivePruneLevelToPopulation
-
-```ts
-applyAdaptivePruneLevelToPopulation(
-  host: NeatLikeForPruning,
-  pruneLevel: number,
-): void
-```
-
-Apply the shared adaptive prune level to every compatible genome.
-
-This is the final fan-out step for adaptive pruning. The host maintains one
-shared prune level, and this helper applies that single controller decision
-uniformly across genomes that support sparsity pruning.
-
-Parameters:
-- `host` - - NEAT host exposing the population.
-- `pruneLevel` - - Prune level to apply.
-
-Returns: Nothing. Compatible genomes are pruned in place.

package/src/neat/pruning/facade/README.md

@@ -38,72 +38,72 @@ its own.
 
 ## neat/pruning/facade/pruning.facade.ts
 
-### applyEvolutionPruning
+### applyAdaptivePruning
 
 ```ts
-applyEvolutionPruning(
+applyAdaptivePruning(
   host: NeatLikeForPruning,
 ): Promise<void>
 ```
 
-Apply evolution-time pruning through the stable public `Neat` facade.
+Run adaptive pruning through the stable public `Neat` facade.
 
-This is the public wrapper for schedule-driven pruning. Use it when the
-caller wants the root pruning chapter to inspect generation timing and apply
-pruning only when the configured evolution schedule says it is active.
+This is the public wrapper for metric-driven pruning. Use it when pruning
+should react to live population complexity signals rather than a fixed
+generation schedule.
 
-The underlying pruning module is loaded lazily so pruning remains optional,
-and the facade preserves the same best-effort behavior as before the pruning
-logic was extracted out of the main `Neat` class.
+The facade keeps the same lazy optional-loading behavior so callers can
+continue to treat adaptive pruning as an additive maintenance feature rather
+than a required runtime dependency.
 
-This wrapper is the predictable pruning entrypoint: it says "consult the
-generation schedule and prune if the current run state says it is time."
-That makes it the better fit for orchestrated evolve loops and deterministic
-experiments where pruning should follow a known calendar.
+This wrapper is the reactive pruning entrypoint: it says "inspect the live
+population metrics and adjust the shared prune level only if the drift is big
+enough to matter." That makes it the better fit for maintenance-style runs
+where pruning should respond to observed complexity rather than the calendar.
 
 Parameters:
-- `host` - - `Neat` instance exposing pruning options, generation state, and population.
+- `host` - - `Neat` instance exposing adaptive pruning state and population metrics.
 
-Returns: Promise that resolves after the best-effort pruning attempt finishes.
+Returns: Promise that resolves after the best-effort adaptive pruning attempt finishes.
 
 Example:
 
 ```ts
-await neat.applyEvolutionPruning();
+await neat.applyAdaptivePruning();
 ```
 
-### applyAdaptivePruning
+### applyEvolutionPruning
 
 ```ts
-applyAdaptivePruning(
+applyEvolutionPruning(
   host: NeatLikeForPruning,
 ): Promise<void>
 ```
 
-Run adaptive pruning through the stable public `Neat` facade.
+Apply evolution-time pruning through the stable public `Neat` facade.
 
-This is the public wrapper for metric-driven pruning. Use it when pruning
-should react to live population complexity signals rather than a fixed
-generation schedule.
+This is the public wrapper for schedule-driven pruning. Use it when the
+caller wants the root pruning chapter to inspect generation timing and apply
+pruning only when the configured evolution schedule says it is active.
 
-The facade keeps the same lazy optional-loading behavior so callers can
-continue to treat adaptive pruning as an additive maintenance feature rather
-than a required runtime dependency.
+The underlying pruning module is loaded lazily so pruning remains optional,
+and the facade preserves the same best-effort behavior as before the pruning
+logic was extracted out of the main `Neat` class.
 
-This wrapper is the reactive pruning entrypoint: it says "inspect the live
-population metrics and adjust the shared prune level only if the drift is big
-enough to matter." That makes it the better fit for maintenance-style runs
-where pruning should respond to observed complexity rather than the calendar.
+This wrapper is the predictable pruning entrypoint: it says "consult the
+generation schedule and prune if the current run state says it is time."
+That makes it the better fit for orchestrated evolve loops and deterministic
+experiments where pruning should follow a known calendar.
 
 Parameters:
-- `host` - - `Neat` instance exposing adaptive pruning state and population metrics.
+- `host` - - `Neat` instance exposing pruning options, generation state, and population.
 
-Returns: Promise that resolves after the best-effort adaptive pruning attempt finishes.
+Returns: Promise that resolves after the best-effort pruning attempt finishes.
 
 Example:
 
 ```ts
-await neat.applyAdaptivePruning();
+await neat.applyEvolutionPruning();
 ```
 
 ### NeatPruningFacadeHost