@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -39,46 +39,48 @@ flowchart TD
 
 ## neat/evolve/adaptive/evolve.adaptive.utils.ts
 
-### applyAdaptiveComplexityControllers
+### adaptReenableProbability
 
 ```ts
-applyAdaptiveComplexityControllers(
+adaptReenableProbability(
   internal: NeatControllerForEvolution,
-): Promise<void>
+  config: { minSamples: number; target: number; min: number; max: number; deltaScale: number; },
+): void
 ```
 
-Apply adaptive complexity controllers if available.
+Adapt the re-enable probability based on recent success ratios.
 
-This helper is the evolve bridge into the root adaptive complexity policies.
-It keeps both optional calls together because they rewrite controller-level
-structure policy rather than one single genome: budget scheduling can change
-allowed network size, and phased complexity can flip the controller between
-growth and simplification modes.
+Re-enable adaptation turns the last generation's connection-revival outcomes
+into one controller-level probability update for the next generation. It
+aggregates success and attempt counters across the whole population, resets
+those per-genome counters once consumed, and only adjusts the shared
+probability when the sample size is large enough to be meaningful.
 
 Parameters:
 - `internal` - - NEAT controller instance.
 
-Returns: A promise that resolves after optional complexity controllers have run.
+Returns: Nothing.
 
-### applyMinimalCriterionAdaptiveSafe
+### applyAdaptiveComplexityControllers
 
 ```ts
-applyMinimalCriterionAdaptiveSafe(
+applyAdaptiveComplexityControllers(
   internal: NeatControllerForEvolution,
 ): Promise<void>
 ```
 
-Apply minimal criterion adaptive controller if available.
+Apply adaptive complexity controllers if available.
 
-Minimal criterion adaptation is one of the few adaptive policies that can
-rewrite the current generation's score landscape immediately. Keeping it in a
-safe wrapper lets evolve apply that pressure when configured without forcing
-every runtime surface to include the full adaptive subtree.
+This helper is the evolve bridge into the root adaptive complexity policies.
+It keeps both optional calls together because they rewrite controller-level
+structure policy rather than one single genome: budget scheduling can change
+allowed network size, and phased complexity can flip the controller between
+growth and simplification modes.
 
 Parameters:
 - `internal` - - NEAT controller instance.
 
-Returns: A promise that resolves after the optional acceptance controller runs.
+Returns: A promise that resolves after optional complexity controllers have run.
 
 ### applyAncestorUniqAdaptiveSafe
 
@@ -128,6 +130,46 @@ Parameters:
 
 Returns: Nothing.
 
+### applyMinimalCriterionAdaptiveSafe
+
+```ts
+applyMinimalCriterionAdaptiveSafe(
+  internal: NeatControllerForEvolution,
+): Promise<void>
+```
+
+Apply minimal criterion adaptive controller if available.
+
+Minimal criterion adaptation is one of the few adaptive policies that can
+rewrite the current generation's score landscape immediately. Keeping it in a
+safe wrapper lets evolve apply that pressure when configured without forcing
+every runtime surface to include the full adaptive subtree.
+
+Parameters:
+- `internal` - - NEAT controller instance.
+
+Returns: A promise that resolves after the optional acceptance controller runs.
+
+### applyOperatorAdaptationSafe
+
+```ts
+applyOperatorAdaptationSafe(
+  internal: NeatControllerForEvolution,
+): Promise<void>
+```
+
+Apply operator adaptation if available.
+
+Operator adaptation is another best-effort policy-maintenance bridge. It
+decays long-running operator statistics so later mutation choices weight more
+recent evidence without forcing evolve to know the details of the adaptive
+operator-selection subsystem.
+
+Parameters:
+- `internal` - - NEAT controller instance.
+
+Returns: A promise that resolves after optional operator-stat decay runs.
+
 ### applyPruningAndMutation
 
 ```ts
@@ -175,45 +217,3 @@ Parameters:
 - `internal` - - NEAT controller instance.
 
 Returns: Nothing.
-
-### adaptReenableProbability
-
-```ts
-adaptReenableProbability(
-  internal: NeatControllerForEvolution,
-  config: { minSamples: number; target: number; min: number; max: number; deltaScale: number; },
-): void
-```
-
-Adapt the re-enable probability based on recent success ratios.
-
-Re-enable adaptation turns the last generation's connection-revival outcomes
-into one controller-level probability update for the next generation. It
-aggregates success and attempt counters across the whole population, resets
-those per-genome counters once consumed, and only adjusts the shared
-probability when the sample size is large enough to be meaningful.
-
-Parameters:
-- `internal` - - NEAT controller instance.
-
-Returns: Nothing.
-
-### applyOperatorAdaptationSafe
-
-```ts
-applyOperatorAdaptationSafe(
-  internal: NeatControllerForEvolution,
-): Promise<void>
-```
-
-Apply operator adaptation if available.
-
-Operator adaptation is another best-effort policy-maintenance bridge. It
-decays long-running operator statistics so later mutation choices weight more
-recent evidence without forcing evolve to know the details of the adaptive
-operator-selection subsystem.
-
-Parameters:
-- `internal` - - NEAT controller instance.
-
-Returns: A promise that resolves after optional operator-stat decay runs.

package/src/neat/evolve/objectives/README.md

@@ -31,51 +31,34 @@ flowchart TD
 
 ## neat/evolve/objectives/evolve.objectives.utils.ts
 
-### resetObjectivesCache
+### applyDynamicObjectiveSchedule
 
 ```ts
-resetObjectivesCache(
+applyDynamicObjectiveSchedule(
   internal: NeatControllerForEvolution,
+  currentObjectiveKeys: string[],
+  config: { autoEntropyAddAt: number; },
 ): void
 ```
 
-Clear cached objectives so dynamic schedules can rebuild them.
-
-Objective reads are intentionally cached elsewhere because the resolved list
-is reused across several helpers. Whenever evolve-time policy adds, removes,
-or suppresses an objective, this cache must be cleared so the next
-`_getObjectives()` read reflects the updated configuration rather than the
-earlier generation's list.
-
-Parameters:
-- `internal` - - NEAT controller instance.
-
-Returns: void.
-
-### updateObjectiveScheduleAndAges
-
-```ts
-updateObjectiveScheduleAndAges(
-  internal: NeatControllerForEvolution,
-  helpers: { applyDynamicObjectiveSchedule: (currentObjectiveKeys: string[]) => void; },
-): Promise<void>
-```
-
-Update objective schedule, pending adds/removes, and objective ages.
+Apply dynamic objective scheduling and entropy rules.
 
-This is the small orchestration entrypoint for evolve-time objective
-maintenance. It reads the currently resolved objective keys, applies the
-caller-provided scheduling policy, then updates the age bookkeeping that
-later telemetry or policy helpers may inspect.
+This helper is the main generation-time policy switchboard for objectives.
+When dynamic scheduling is enabled, it decides when to add scheduled
+objectives such as complexity or entropy and then hands off to the entropy
+drop or re-add rules. When dynamic scheduling is disabled but auto-entropy is
+enabled, it applies the simpler fallback rule that adds entropy after a
+configured generation threshold.
 
-The whole pass is wrapped in a best-effort guard because dynamic objective
-tracking is useful metadata, not a requirement for the rest of evolution to
-continue.
+The helper mutates controller policy state in place by registering
+objectives, updating pending-add queues, and delegating entropy maintenance.
+Callers should therefore treat it as a policy update step rather than a pure
+read.
 
 Parameters:
 - `internal` - - NEAT controller instance.
-- `helpers` - - Helper callbacks used by scheduling logic.
-- `helpers` - - Dynamic objective scheduler.
+- `currentObjectiveKeys` - - Keys of active objectives.
+- `config` - - Scheduling constants.
 
 Returns: void.
 
@@ -120,36 +103,25 @@ Parameters:
 
 Returns: void.
 
-### applyDynamicObjectiveSchedule
+### createEntropyAccessor
 
 ```ts
-applyDynamicObjectiveSchedule(
+createEntropyAccessor(
   internal: NeatControllerForEvolution,
-  currentObjectiveKeys: string[],
-  config: { autoEntropyAddAt: number; },
-): void
+): (genome: GenomeWithMetadata) => number
 ```
 
-Apply dynamic objective scheduling and entropy rules.
-
-This helper is the main generation-time policy switchboard for objectives.
-When dynamic scheduling is enabled, it decides when to add scheduled
-objectives such as complexity or entropy and then hands off to the entropy
-drop or re-add rules. When dynamic scheduling is disabled but auto-entropy is
-enabled, it applies the simpler fallback rule that adds entropy after a
-configured generation threshold.
+Build the entropy accessor used by dynamic objective scheduling.
 
-The helper mutates controller policy state in place by registering
-objectives, updating pending-add queues, and delegating entropy maintenance.
-Callers should therefore treat it as a policy update step rather than a pure
-read.
+The evolve controller already advertises `_structuralEntropy` as an optional
+hook. This helper centralizes the non-null assertion so the scheduling logic
+can stay declarative while preserving the existing expectation that entropy
+scheduling only makes sense on hosts exposing that hook.
 
 Parameters:
 - `internal` - - NEAT controller instance.
-- `currentObjectiveKeys` - - Keys of active objectives.
-- `config` - - Scheduling constants.
 
-Returns: void.
+Returns: Accessor that reads structural entropy from one genome.
 
 ### handleEntropyDropAndReadd
 
@@ -183,22 +155,50 @@ Parameters:
 
 Returns: void.
 
-### createEntropyAccessor
+### resetObjectivesCache
 
 ```ts
-createEntropyAccessor(
+resetObjectivesCache(
   internal: NeatControllerForEvolution,
-): (genome: GenomeWithMetadata) => number
+): void
 ```
 
-Build the entropy accessor used by dynamic objective scheduling.
+Clear cached objectives so dynamic schedules can rebuild them.
 
-The evolve controller already advertises `_structuralEntropy` as an optional
-hook. This helper centralizes the non-null assertion so the scheduling logic
-can stay declarative while preserving the existing expectation that entropy
-scheduling only makes sense on hosts exposing that hook.
+Objective reads are intentionally cached elsewhere because the resolved list
+is reused across several helpers. Whenever evolve-time policy adds, removes,
+or suppresses an objective, this cache must be cleared so the next
+`_getObjectives()` read reflects the updated configuration rather than the
+earlier generation's list.
 
 Parameters:
 - `internal` - - NEAT controller instance.
 
-Returns: Accessor that reads structural entropy from one genome.
+Returns: void.
+
+### updateObjectiveScheduleAndAges
+
+```ts
+updateObjectiveScheduleAndAges(
+  internal: NeatControllerForEvolution,
+  helpers: { applyDynamicObjectiveSchedule: (currentObjectiveKeys: string[]) => void; },
+): Promise<void>
+```
+
+Update objective schedule, pending adds/removes, and objective ages.
+
+This is the small orchestration entrypoint for evolve-time objective
+maintenance. It reads the currently resolved objective keys, applies the
+caller-provided scheduling policy, then updates the age bookkeeping that
+later telemetry or policy helpers may inspect.
+
+The whole pass is wrapped in a best-effort guard because dynamic objective
+tracking is useful metadata, not a requirement for the rest of evolution to
+continue.
+
+Parameters:
+- `internal` - - NEAT controller instance.
+- `helpers` - - Helper callbacks used by scheduling logic.
+- `helpers` - - Dynamic objective scheduler.
+
+Returns: void.

package/src/neat/evolve/offspring/README.md

@@ -18,13 +18,12 @@ Read this chapter when you want to understand:
 
 ## neat/evolve/offspring/evolve.offspring.constants.ts
 
-### OFFSPRING_FALLBACK_INDEX
+### LINEAGE_BASE_DEPTH
 
-Index used when falling back to the first genome in the population.
+Baseline lineage depth when parent depth metadata is missing.
 
-The fallback stays explicit so parent selection failure still produces a
-deterministic recovery path before the helper tries more permissive random
-rescue.
+This keeps lineage annotation tolerant of older or narrower runtime surfaces
+that do not carry full parent-depth metadata.
 
 ### LINEAGE_DEPTH_INCREMENT
 
@@ -33,15 +32,41 @@ Depth increment applied when deriving a child from its parents.
 Offspring depth is always one generation deeper than the deepest available
 parent depth so shallow lineage summaries remain monotonic.
 
-### LINEAGE_BASE_DEPTH
+### OFFSPRING_FALLBACK_INDEX
 
-Baseline lineage depth when parent depth metadata is missing.
+Index used when falling back to the first genome in the population.
 
-This keeps lineage annotation tolerant of older or narrower runtime surfaces
-that do not carry full parent-depth metadata.
+The fallback stays explicit so parent selection failure still produces a
+deterministic recovery path before the helper tries more permissive random
+rescue.
 
 ## neat/evolve/offspring/evolve.offspring.utils.ts
 
+### annotateOffspringMetadata
+
+```ts
+annotateOffspringMetadata(
+  context: OffspringContext,
+  offspring: default,
+  parentOne: default,
+  parentTwo: default,
+): void
+```
+
+Attach runtime metadata to a newly crossed child.
+
+The metadata step keeps offspring creation compatible with later lineage,
+telemetry, and inbreeding reads without forcing the crossover call itself to
+know about controller-level bookkeeping.
+
+Parameters:
+- `context` - - NEAT-like host containing population and options.
+- `offspring` - - Newly crossed child genome.
+- `parentOne` - - First selected parent.
+- `parentTwo` - - Second selected parent.
+
+Returns: Nothing.
+
 ### createOffspring
 
 ```ts
@@ -65,6 +90,28 @@ Parameters:
 
 Returns: A newly created offspring genome ready for later mutation and scoring.
 
+### enforceOffspringInvariants
+
+```ts
+enforceOffspringInvariants(
+  context: OffspringContext,
+  offspring: default,
+): void
+```
+
+Reapply minimum structural invariants after crossover.
+
+Crossover can produce a child that is technically valid for heredity but still
+missing the controller's minimum hidden-node or dead-end guarantees. This
+helper keeps that cleanup local to offspring creation so later population code
+can treat returned children as already normalized.
+
+Parameters:
+- `context` - - NEAT-like host containing population and options.
+- `offspring` - - Newly crossed child genome.
+
+Returns: Nothing.
+
 ### OffspringContext
 
 Minimal surface needed for offspring generation.
@@ -96,50 +143,3 @@ Parameters:
 - `populationFallback` - - Optional alternate population to read from.
 
 Returns: A parent genome chosen from the preferred or fallback path.
-
-### annotateOffspringMetadata
-
-```ts
-annotateOffspringMetadata(
-  context: OffspringContext,
-  offspring: default,
-  parentOne: default,
-  parentTwo: default,
-): void
-```
-
-Attach runtime metadata to a newly crossed child.
-
-The metadata step keeps offspring creation compatible with later lineage,
-telemetry, and inbreeding reads without forcing the crossover call itself to
-know about controller-level bookkeeping.
-
-Parameters:
-- `context` - - NEAT-like host containing population and options.
-- `offspring` - - Newly crossed child genome.
-- `parentOne` - - First selected parent.
-- `parentTwo` - - Second selected parent.
-
-Returns: Nothing.
-
-### enforceOffspringInvariants
-
-```ts
-enforceOffspringInvariants(
-  context: OffspringContext,
-  offspring: default,
-): void
-```
-
-Reapply minimum structural invariants after crossover.
-
-Crossover can produce a child that is technically valid for heredity but still
-missing the controller's minimum hidden-node or dead-end guarantees. This
-helper keeps that cleanup local to offspring creation so later population code
-can treat returned children as already normalized.
-
-Parameters:
-- `context` - - NEAT-like host containing population and options.
-- `offspring` - - Newly crossed child genome.
-
-Returns: Nothing.