@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -170,6 +170,25 @@ Parameters:
 
 Returns: Nothing.
 
+### resolveNextPhase
+
+```ts
+resolveNextPhase(
+  currentPhase: string,
+): string
+```
+
+Resolve next phase name.
+
+The phase cycle is intentionally binary so the controller can alternate
+between growth and simplification without inventing additional intermediate
+moods here.
+
+Parameters:
+- `currentPhase` - - Current phase label.
+
+Returns: Next phase label.
+
 ### togglePhaseIfNeeded
 
 ```ts
@@ -192,25 +211,6 @@ Parameters:
 
 Returns: Nothing.
 
-### resolveNextPhase
-
-```ts
-resolveNextPhase(
-  currentPhase: string,
-): string
-```
-
-Resolve next phase name.
-
-The phase cycle is intentionally binary so the controller can alternate
-between growth and simplification without inventing additional intermediate
-moods here.
-
-Parameters:
-- `currentPhase` - - Current phase label.
-
-Returns: Next phase label.
-
 ## neat/adaptive/complexity/adaptive.complexity.utils.ts
 
 Schedule helpers for adaptive complexity budgets.
@@ -227,27 +227,62 @@ The schedule pipeline is intentionally compact:
 3. resolve adaptive or linear budget updates,
 4. clamp the result back onto controller state.
 
-### applyComplexityBudgetSchedule
+### adjustConnectionBudget
 
 ```ts
-applyComplexityBudgetSchedule(
+adjustConnectionBudget(
   engine: NeatLikeWithAdaptive,
   config: { enabled?: boolean | undefined; mode?: string | undefined; improvementWindow?: number | undefined; increaseFactor?: number | undefined; stagnationFactor?: number | undefined; maxNodesStart?: number | undefined; maxNodesEnd?: number | undefined; minNodes?: number | undefined; maxConnsStart?: number | undefined; maxConnsEnd?: number | undefined; horizon?: number | undefined; },
+  trends: { improvement: number; slope: number; },
+  factors: { increaseFactor: number; stagnationFactor: number; },
+  noveltyFactor: number,
+  history: number[],
 ): void
 ```
 
-Apply the complexity budget schedule for the configured mode.
+Adjust connection budget based on trends and factors.
 
-This is the main dispatcher for the complexity subtree. It keeps the public
-entrypoint easy to scan by delegating immediately into either the adaptive
-schedule or the linear schedule, depending on the configured policy.
+Connection-budget adjustment mirrors the node-budget path so both structural
+ceilings respond coherently to the same improvement and stagnation signals.
 
 Parameters:
 - `engine` - - NEAT engine instance.
 - `config` - - Complexity budget configuration.
+- `trends` - - Improvement and slope metrics.
+- `factors` - - Adjustment factors.
+- `noveltyFactor` - - Novelty multiplier.
+- `history` - - Rolling history for window checks.
 
 Returns: Nothing.
 
+### adjustNodeBudget
+
+```ts
+adjustNodeBudget(
+  engine: NeatLikeWithAdaptive,
+  config: { enabled?: boolean | undefined; mode?: string | undefined; improvementWindow?: number | undefined; increaseFactor?: number | undefined; stagnationFactor?: number | undefined; maxNodesStart?: number | undefined; maxNodesEnd?: number | undefined; minNodes?: number | undefined; maxConnsStart?: number | undefined; maxConnsEnd?: number | undefined; horizon?: number | undefined; },
+  trends: { improvement: number; slope: number; },
+  factors: { increaseFactor: number; stagnationFactor: number; },
+  noveltyFactor: number,
+  history: number[],
+): void
+```
+
+Adjust node budget based on trends and factors.
+
+Node-budget adjustment is where the adaptive policy becomes concrete. When
+improvement or positive slope is present, the helper expands the budget up to
+the configured ceiling; when the observation window is full and the search is
+flat, it contracts back toward the configured minimum.
+
+Parameters:
+- `engine` - - NEAT engine instance.
+- `config` - - Complexity budget configuration.
+- `trends` - - Improvement and slope metrics.
+- `factors` - - Adjustment factors.
+- `noveltyFactor` - - Novelty multiplier.
+- `history` - - Rolling history for window checks.
+
 ### applyAdaptiveSchedule
 
 ```ts
@@ -270,20 +305,20 @@ Parameters:
 
 Returns: Nothing.
 
-### applyLinearSchedule
+### applyComplexityBudgetSchedule
 
 ```ts
-applyLinearSchedule(
+applyComplexityBudgetSchedule(
   engine: NeatLikeWithAdaptive,
   config: { enabled?: boolean | undefined; mode?: string | undefined; improvementWindow?: number | undefined; increaseFactor?: number | undefined; stagnationFactor?: number | undefined; maxNodesStart?: number | undefined; maxNodesEnd?: number | undefined; minNodes?: number | undefined; maxConnsStart?: number | undefined; maxConnsEnd?: number | undefined; horizon?: number | undefined; },
 ): void
 ```
 
-Apply linear complexity budget scheduling.
+Apply the complexity budget schedule for the configured mode.
 
-The linear schedule is the deterministic counterpart to the adaptive mode.
-It ignores run-time improvement signals and simply interpolates between a
-start and end budget across a configured horizon.
+This is the main dispatcher for the complexity subtree. It keeps the public
+entrypoint easy to scan by delegating immediately into either the adaptive
+schedule or the linear schedule, depending on the configured policy.
 
 Parameters:
 - `engine` - - NEAT engine instance.
@@ -291,62 +326,46 @@ Parameters:
 
 Returns: Nothing.
 
-### updateScoreHistory
+### applyLinearSchedule
 
 ```ts
-updateScoreHistory(
+applyLinearSchedule(
   engine: NeatLikeWithAdaptive,
   config: { enabled?: boolean | undefined; mode?: string | undefined; improvementWindow?: number | undefined; increaseFactor?: number | undefined; stagnationFactor?: number | undefined; maxNodesStart?: number | undefined; maxNodesEnd?: number | undefined; minNodes?: number | undefined; maxConnsStart?: number | undefined; maxConnsEnd?: number | undefined; horizon?: number | undefined; },
-): number[]
+): void
 ```
 
-Update rolling score history with current best score.
+Apply linear complexity budget scheduling.
 
-Score history is the minimum evidence the adaptive scheduler needs in order
-to talk about improvement or stagnation. The helper keeps that history bounded
-to the configured window so later slope and delta calculations stay local to
-recent generations.
+The linear schedule is the deterministic counterpart to the adaptive mode.
+It ignores run-time improvement signals and simply interpolates between a
+start and end budget across a configured horizon.
 
 Parameters:
 - `engine` - - NEAT engine instance.
 - `config` - - Complexity budget configuration.
 
-Returns: Rolling history array after update.
+Returns: Nothing.
 
-### computeTrends
+### clampNodeBudget
 
 ```ts
-computeTrends(
-  history: number[],
-): { improvement: number; slope: number; }
+clampNodeBudget(
+  engine: NeatLikeWithAdaptive,
+  config: { enabled?: boolean | undefined; mode?: string | undefined; improvementWindow?: number | undefined; increaseFactor?: number | undefined; stagnationFactor?: number | undefined; maxNodesStart?: number | undefined; maxNodesEnd?: number | undefined; minNodes?: number | undefined; maxConnsStart?: number | undefined; maxConnsEnd?: number | undefined; horizon?: number | undefined; },
+): void
 ```
 
-Compute improvement and slope trends from score history.
-
-Improvement answers whether the window ended above where it started; slope
-answers how strongly the trajectory points upward or downward across the
-window as a whole. The adaptive scheduler uses both so it can distinguish a
-noisy plateau from sustained progress.
-
-Parameters:
-- `history` - - Rolling history of best scores.
-
-Returns: Trend metrics (improvement and slope).
-
-### computeSlope
-
-```ts
-computeSlope(
-  history: number[],
-): number
-```
+Clamp node budget to configured minimum.
 
-Compute linear regression slope using ordinary least squares.
+This final guard keeps the adaptive loop from shrinking below the smallest
+topology the controller can reasonably support.
 
 Parameters:
-- `history` - - Rolling history of best scores.
+- `engine` - - NEAT engine instance.
+- `config` - - Complexity budget configuration.
 
-Returns: OLS slope estimate.
+Returns: Nothing.
 
 ### computeAdjustmentFactors
 
@@ -371,23 +390,6 @@ Parameters:
 
 Returns: Adjustment factors (increase and stagnation multipliers).
 
-### normalizeSlope
-
-```ts
-normalizeSlope(
-  slope: number,
-  initialScore: number,
-): number
-```
-
-Normalize slope magnitude relative to initial score.
-
-Parameters:
-- `slope` - - Raw OLS slope.
-- `initialScore` - - First score in history window.
-
-Returns: Normalized slope clamped to [-2, 2].
-
 ### computeNoveltyFactor
 
 ```ts
@@ -407,62 +409,54 @@ Parameters:
 
 Returns: Novelty multiplier (0.9 if archive small, 1.0 otherwise).
 
-### initializeNodeBudget
+### computeSlope
 
 ```ts
-initializeNodeBudget(
-  engine: NeatLikeWithAdaptive,
-  config: { enabled?: boolean | undefined; mode?: string | undefined; improvementWindow?: number | undefined; increaseFactor?: number | undefined; stagnationFactor?: number | undefined; maxNodesStart?: number | undefined; maxNodesEnd?: number | undefined; minNodes?: number | undefined; maxConnsStart?: number | undefined; maxConnsEnd?: number | undefined; horizon?: number | undefined; },
-): void
+computeSlope(
+  history: number[],
+): number
 ```
 
-Initialize node budget if undefined.
+Compute linear regression slope using ordinary least squares.
 
 Parameters:
-- `engine` - - NEAT engine instance.
-- `config` - - Complexity budget configuration.
+- `history` - - Rolling history of best scores.
 
-### adjustNodeBudget
+Returns: OLS slope estimate.
+
+### computeTrends
 
 ```ts
-adjustNodeBudget(
-  engine: NeatLikeWithAdaptive,
-  config: { enabled?: boolean | undefined; mode?: string | undefined; improvementWindow?: number | undefined; increaseFactor?: number | undefined; stagnationFactor?: number | undefined; maxNodesStart?: number | undefined; maxNodesEnd?: number | undefined; minNodes?: number | undefined; maxConnsStart?: number | undefined; maxConnsEnd?: number | undefined; horizon?: number | undefined; },
-  trends: { improvement: number; slope: number; },
-  factors: { increaseFactor: number; stagnationFactor: number; },
-  noveltyFactor: number,
+computeTrends(
   history: number[],
-): void
+): { improvement: number; slope: number; }
 ```
 
-Adjust node budget based on trends and factors.
+Compute improvement and slope trends from score history.
 
-Node-budget adjustment is where the adaptive policy becomes concrete. When
-improvement or positive slope is present, the helper expands the budget up to
-the configured ceiling; when the observation window is full and the search is
-flat, it contracts back toward the configured minimum.
+Improvement answers whether the window ended above where it started; slope
+answers how strongly the trajectory points upward or downward across the
+window as a whole. The adaptive scheduler uses both so it can distinguish a
+noisy plateau from sustained progress.
 
 Parameters:
-- `engine` - - NEAT engine instance.
-- `config` - - Complexity budget configuration.
-- `trends` - - Improvement and slope metrics.
-- `factors` - - Adjustment factors.
-- `noveltyFactor` - - Novelty multiplier.
-- `history` - - Rolling history for window checks.
+- `history` - - Rolling history of best scores.
 
-### clampNodeBudget
+Returns: Trend metrics (improvement and slope).
+
+### initializeConnectionBudget
 
 ```ts
-clampNodeBudget(
+initializeConnectionBudget(
   engine: NeatLikeWithAdaptive,
   config: { enabled?: boolean | undefined; mode?: string | undefined; improvementWindow?: number | undefined; increaseFactor?: number | undefined; stagnationFactor?: number | undefined; maxNodesStart?: number | undefined; maxNodesEnd?: number | undefined; minNodes?: number | undefined; maxConnsStart?: number | undefined; maxConnsEnd?: number | undefined; horizon?: number | undefined; },
 ): void
 ```
 
-Clamp node budget to configured minimum.
+Initialize connection budget if undefined.
 
-This final guard keeps the adaptive loop from shrinking below the smallest
-topology the controller can reasonably support.
+Connection budgets are optional, so the helper only seeds this state when the
+configuration explicitly opts into a connection-cap schedule.
 
 Parameters:
 - `engine` - - NEAT engine instance.
@@ -470,50 +464,56 @@ Parameters:
 
 Returns: Nothing.
 
-### initializeConnectionBudget
+### initializeNodeBudget
 
 ```ts
-initializeConnectionBudget(
+initializeNodeBudget(
   engine: NeatLikeWithAdaptive,
   config: { enabled?: boolean | undefined; mode?: string | undefined; improvementWindow?: number | undefined; increaseFactor?: number | undefined; stagnationFactor?: number | undefined; maxNodesStart?: number | undefined; maxNodesEnd?: number | undefined; minNodes?: number | undefined; maxConnsStart?: number | undefined; maxConnsEnd?: number | undefined; horizon?: number | undefined; },
 ): void
 ```
 
-Initialize connection budget if undefined.
-
-Connection budgets are optional, so the helper only seeds this state when the
-configuration explicitly opts into a connection-cap schedule.
+Initialize node budget if undefined.
 
 Parameters:
 - `engine` - - NEAT engine instance.
 - `config` - - Complexity budget configuration.
 
-Returns: Nothing.
+### normalizeSlope
 
-### adjustConnectionBudget
+```ts
+normalizeSlope(
+  slope: number,
+  initialScore: number,
+): number
+```
+
+Normalize slope magnitude relative to initial score.
+
+Parameters:
+- `slope` - - Raw OLS slope.
+- `initialScore` - - First score in history window.
+
+Returns: Normalized slope clamped to [-2, 2].
+
+### updateScoreHistory
 
 ```ts
-adjustConnectionBudget(
+updateScoreHistory(
   engine: NeatLikeWithAdaptive,
   config: { enabled?: boolean | undefined; mode?: string | undefined; improvementWindow?: number | undefined; increaseFactor?: number | undefined; stagnationFactor?: number | undefined; maxNodesStart?: number | undefined; maxNodesEnd?: number | undefined; minNodes?: number | undefined; maxConnsStart?: number | undefined; maxConnsEnd?: number | undefined; horizon?: number | undefined; },
-  trends: { improvement: number; slope: number; },
-  factors: { increaseFactor: number; stagnationFactor: number; },
-  noveltyFactor: number,
-  history: number[],
-): void
+): number[]
 ```
 
-Adjust connection budget based on trends and factors.
+Update rolling score history with current best score.
 
-Connection-budget adjustment mirrors the node-budget path so both structural
-ceilings respond coherently to the same improvement and stagnation signals.
+Score history is the minimum evidence the adaptive scheduler needs in order
+to talk about improvement or stagnation. The helper keeps that history bounded
+to the configured window so later slope and delta calculations stay local to
+recent generations.
 
 Parameters:
 - `engine` - - NEAT engine instance.
 - `config` - - Complexity budget configuration.
-- `trends` - - Improvement and slope metrics.
-- `factors` - - Adjustment factors.
-- `noveltyFactor` - - Novelty multiplier.
-- `history` - - Rolling history for window checks.
 
-Returns: Nothing.
+Returns: Rolling history array after update.