@reicek/neataptic-ts 0.1.24 → 0.1.26

package/src/neat/mutation/flow/README.md

@@ -48,264 +48,265 @@ flowchart TD
 
 ## neat/mutation/flow/mutation.flow.ts
 
-### mutateGenome
+### applyAddConnMutation
 
 ```ts
-mutateGenome(
+applyAddConnMutation(
   genome: GenomeWithMetadata,
   internal: NeatControllerForMutation,
   methods: { mutation: unknown; },
-): Promise<void>
+): void
 ```
 
-Mutate a single genome based on configured mutation policies.
-
-This is the orchestration entry point for the `flow/` chapter. It keeps the
-per-genome lifecycle linear: adaptive settings are prepared first, then one
-probability gate decides whether work happens at all, and only then does the
-helper loop ask `select/` for concrete operators.
-
-The important design choice is that mutation amount is resolved after the
-mutate-or-skip gate passes. That keeps genomes with low effective rates from
-paying the full operator-selection cost every generation while still letting
-successful genomes perform multiple edits once they have been admitted into
-the flow.
+Apply an ADD_CONN mutation with reuse and weight nudging.
 
-Each loop iteration captures a before-snapshot, applies one operator,
-performs an extra exploration edge when configured, and finally records whether the genome
-actually grew. That final feedback is what later allows operator adaptation
-and bandit-style policies to reward operators that change structure instead
-of merely consuming attempts.
+This is the connection-growth companion to `applyAddNodeMutation()`. The
+structural edit itself is delegated to the reuse-aware connection helper so
+identical edge discoveries can still share innovation identity across the
+population.
 
 Parameters:
 - `genome` - - genome to mutate
 - `internal` - - neat controller context
 - `methods` - - mutation methods module
 
-Returns: Promise resolving after mutation attempts complete
+Returns: void
 
-### initializeAdaptiveMutation
+### applyAddNodeMutation
 
 ```ts
-initializeAdaptiveMutation(
+applyAddNodeMutation(
   genome: GenomeWithMetadata,
   internal: NeatControllerForMutation,
+  methods: { mutation: unknown; },
 ): void
 ```
 
-Initialize per-genome adaptive mutation parameters if configured.
-
-Adaptive mutation is stateful at the genome level, not just a controller
-default. This helper assigns the first persistent rate and optional amount so
-later generations can treat the genome as carrying its own mutation budget.
+Apply an ADD_NODE mutation with reuse and weight nudging.
 
-The helper only writes when the genome has not yet been initialized. That is
-why it runs at the top of `mutateGenome()` on every pass: it behaves like a
-cheap bootstrap check rather than a repeated reset of evolved mutation
-behavior.
+The add-node path is special because it needs both innovation-aware
+structural growth and a post-split weight nudge that makes the topology
+change observable immediately in downstream behavior and tests. The helper
+intentionally treats cache invalidation as part of the operation rather than
+leaving it to callers.
 
 Parameters:
-- `genome` - - genome to initialize
+- `genome` - - genome to mutate
 - `internal` - - neat controller context
+- `methods` - - mutation methods module
 
 Returns: void
 
-### resolveEffectiveRate
+### applyMutationOperator
 
 ```ts
-resolveEffectiveRate(
+applyMutationOperator(
   genome: GenomeWithMetadata,
+  mutationMethod: MutationMethod,
   internal: NeatControllerForMutation,
-): number
+  methods: { mutation: unknown; },
+): void
 ```
 
-Resolve the effective mutation rate for a genome.
-
-This helper explains the precedence order for rate policy:
+Apply a mutation operator to a genome and invalidate caches as needed.
 
-1. an explicit controller-level `mutationRate` wins,
-2. otherwise an adaptive per-genome `_mutRate` is used when adaptive
-   mutation is enabled,
-3. otherwise the flow falls back to the local default.
+This helper is the dispatch hinge between policy and topology. Structural
+growth operators such as `ADD_NODE` and `ADD_CONN` are routed through the
+innovation-reuse helpers because the controller cares about more than local
+graph edits; it also needs stable innovation history for later crossover and
+speciation.
 
-Keeping that precedence isolated here makes the rest of the mutation flow
-read as orchestration instead of configuration branching.
+Non-structural operators stay delegated to the genome's own `mutate()`
+implementation. Cache invalidation is then handled separately so the flow can
+keep the expensive cleanup targeted to methods that plausibly changed the
+structural view of the genome.
 
 Parameters:
-- `genome` - - genome to resolve for
+- `genome` - - genome to mutate
+- `mutationMethod` - - mutation operator to apply
 - `internal` - - neat controller context
+- `methods` - - mutation methods module
 
-Returns: effective mutation rate
+Returns: void
 
-### resolveEffectiveAmount
+### captureStructuralSizes
 
 ```ts
-resolveEffectiveAmount(
+captureStructuralSizes(
   genome: GenomeWithMetadata,
-  internal: NeatControllerForMutation,
-): number
+): { beforeNodes: number; beforeConns: number; }
 ```
 
-Resolve the effective mutation amount for a genome.
+Capture structural sizes used to evaluate operator success.
 
-Mutation amount answers a different question from mutation rate. Rate decides
-whether the genome enters the flow. Amount decides how many operator draws it
-receives once admitted. When adaptive mutation amount is enabled, the genome
-may carry its own evolving attempt budget; otherwise the controller-wide
-amount stays authoritative.
+Operator adaptation in this subtree is intentionally coarse-grained: it asks
+whether an attempted mutation increased structural size, not whether the
+resulting genome later scored better. This helper records the pre-mutation
+node and connection counts that make that local success signal possible.
 
 Parameters:
-- `genome` - - genome to resolve for
-- `internal` - - neat controller context
+- `genome` - - genome to inspect
 
-Returns: effective mutation amount
+Returns: structural size snapshot
 
-### shouldMutateGenome
+### initializeAdaptiveMutation
 
 ```ts
-shouldMutateGenome(
-  effectiveRate: number,
+initializeAdaptiveMutation(
+  genome: GenomeWithMetadata,
   internal: NeatControllerForMutation,
-): boolean
+): void
 ```
 
-Decide whether a genome should be mutated based on probability.
+Initialize per-genome adaptive mutation parameters if configured.
 
-This is the narrow admission gate for the per-genome flow. Keeping the RNG
-comparison in one helper makes the orchestration read clearly and gives tests
-one stable seam for deterministic gating behavior.
+Adaptive mutation is stateful at the genome level, not just a controller
+default. This helper assigns the first persistent rate and optional amount so
+later generations can treat the genome as carrying its own mutation budget.
+
+The helper only writes when the genome has not yet been initialized. That is
+why it runs at the top of `mutateGenome()` on every pass: it behaves like a
+cheap bootstrap check rather than a repeated reset of evolved mutation
+behavior.
 
 Parameters:
-- `effectiveRate` - - effective mutation probability
+- `genome` - - genome to initialize
 - `internal` - - neat controller context
 
-Returns: true when the genome should be mutated
+Returns: void
 
-### selectConcreteMutationMethod
+### maybeAddExtraConnection
 
 ```ts
-selectConcreteMutationMethod(
+maybeAddExtraConnection(
   genome: GenomeWithMetadata,
   internal: NeatControllerForMutation,
-): Promise<MutationMethod | null>
+): void
 ```
 
-Select a concrete mutation method, resolving legacy arrays when present.
-
-The selection boundary may already return one final operator, or it may
-return a legacy array-like pool for backward-compatible paths. This helper is
-the bridge between that policy layer and the execution layer in `flow/`: it
-guarantees the rest of the loop sees either one concrete operator or `null`.
+Optionally add an extra connection to increase exploration.
 
-That normalization keeps `mutateGenome()` focused on lifecycle sequencing
-rather than on legacy selection-shape quirks.
+This small post-operator hook gives the controller one extra chance to add
+connectivity after the main mutation has landed. It is intentionally
+probabilistic and lightweight: the flow uses it as a gentle exploration bump,
+not as a second full operator-selection phase.
 
 Parameters:
-- `genome` - - genome to select for
+- `genome` - - genome to mutate
 - `internal` - - neat controller context
 
-Returns: resolved mutation method or null
+Returns: void
 
-### captureStructuralSizes
+### mutateGenome
 
 ```ts
-captureStructuralSizes(
+mutateGenome(
   genome: GenomeWithMetadata,
-): { beforeNodes: number; beforeConns: number; }
+  internal: NeatControllerForMutation,
+  methods: { mutation: unknown; },
+): Promise<void>
 ```
 
-Capture structural sizes used to evaluate operator success.
+Mutate a single genome based on configured mutation policies.
 
-Operator adaptation in this subtree is intentionally coarse-grained: it asks
-whether an attempted mutation increased structural size, not whether the
-resulting genome later scored better. This helper records the pre-mutation
-node and connection counts that make that local success signal possible.
+This is the orchestration entry point for the `flow/` chapter. It keeps the
+per-genome lifecycle linear: adaptive settings are prepared first, then one
+probability gate decides whether work happens at all, and only then does the
+helper loop ask `select/` for concrete operators.
+
+The important design choice is that mutation amount is resolved after the
+mutate-or-skip gate passes. That keeps genomes with low effective rates from
+paying the full operator-selection cost every generation while still letting
+successful genomes perform multiple edits once they have been admitted into
+the flow.
+
+Each loop iteration captures a before-snapshot, applies one operator,
+performs an extra exploration edge when configured, and finally records whether the genome
+actually grew. That final feedback is what later allows operator adaptation
+and bandit-style policies to reward operators that change structure instead
+of merely consuming attempts.
 
 Parameters:
-- `genome` - - genome to inspect
+- `genome` - - genome to mutate
+- `internal` - - neat controller context
+- `methods` - - mutation methods module
 
-Returns: structural size snapshot
+Returns: Promise resolving after mutation attempts complete
 
-### applyMutationOperator
+### resolveEffectiveAmount
 
 ```ts
-applyMutationOperator(
+resolveEffectiveAmount(
   genome: GenomeWithMetadata,
-  mutationMethod: MutationMethod,
   internal: NeatControllerForMutation,
-  methods: { mutation: unknown; },
-): void
+): number
 ```
 
-Apply a mutation operator to a genome and invalidate caches as needed.
-
-This helper is the dispatch hinge between policy and topology. Structural
-growth operators such as `ADD_NODE` and `ADD_CONN` are routed through the
-innovation-reuse helpers because the controller cares about more than local
-graph edits; it also needs stable innovation history for later crossover and
-speciation.
+Resolve the effective mutation amount for a genome.
 
-Non-structural operators stay delegated to the genome's own `mutate()`
-implementation. Cache invalidation is then handled separately so the flow can
-keep the expensive cleanup targeted to methods that plausibly changed the
-structural view of the genome.
+Mutation amount answers a different question from mutation rate. Rate decides
+whether the genome enters the flow. Amount decides how many operator draws it
+receives once admitted. When adaptive mutation amount is enabled, the genome
+may carry its own evolving attempt budget; otherwise the controller-wide
+amount stays authoritative.
 
 Parameters:
-- `genome` - - genome to mutate
-- `mutationMethod` - - mutation operator to apply
+- `genome` - - genome to resolve for
 - `internal` - - neat controller context
-- `methods` - - mutation methods module
 
-Returns: void
+Returns: effective mutation amount
 
-### applyAddNodeMutation
+### resolveEffectiveRate
 
 ```ts
-applyAddNodeMutation(
+resolveEffectiveRate(
   genome: GenomeWithMetadata,
   internal: NeatControllerForMutation,
-  methods: { mutation: unknown; },
-): void
+): number
 ```
 
-Apply an ADD_NODE mutation with reuse and weight nudging.
+Resolve the effective mutation rate for a genome.
 
-The add-node path is special because it needs both innovation-aware
-structural growth and a post-split weight nudge that makes the topology
-change observable immediately in downstream behavior and tests. The helper
-intentionally treats cache invalidation as part of the operation rather than
-leaving it to callers.
+This helper explains the precedence order for rate policy:
+
+1. an explicit controller-level `mutationRate` wins,
+2. otherwise an adaptive per-genome `_mutRate` is used when adaptive
+   mutation is enabled,
+3. otherwise the flow falls back to the local default.
+
+Keeping that precedence isolated here makes the rest of the mutation flow
+read as orchestration instead of configuration branching.
 
 Parameters:
-- `genome` - - genome to mutate
+- `genome` - - genome to resolve for
 - `internal` - - neat controller context
-- `methods` - - mutation methods module
 
-Returns: void
+Returns: effective mutation rate
 
-### applyAddConnMutation
+### selectConcreteMutationMethod
 
 ```ts
-applyAddConnMutation(
+selectConcreteMutationMethod(
   genome: GenomeWithMetadata,
   internal: NeatControllerForMutation,
-  methods: { mutation: unknown; },
-): void
+): Promise<MutationMethod | null>
 ```
 
-Apply an ADD_CONN mutation with reuse and weight nudging.
+Select a concrete mutation method, resolving legacy arrays when present.
 
-This is the connection-growth companion to `applyAddNodeMutation()`. The
-structural edit itself is delegated to the reuse-aware connection helper so
-identical edge discoveries can still share innovation identity across the
-population.
+The selection boundary may already return one final operator, or it may
+return a legacy array-like pool for backward-compatible paths. This helper is
+the bridge between that policy layer and the execution layer in `flow/`: it
+guarantees the rest of the loop sees either one concrete operator or `null`.
+
+That normalization keeps `mutateGenome()` focused on lifecycle sequencing
+rather than on legacy selection-shape quirks.
 
 Parameters:
-- `genome` - - genome to mutate
+- `genome` - - genome to select for
 - `internal` - - neat controller context
-- `methods` - - mutation methods module
 
-Returns: void
+Returns: resolved mutation method or null
 
 ### shouldInvalidateCaches
 
@@ -329,27 +330,26 @@ Parameters:
 
 Returns: true when caches should be invalidated
 
-### maybeAddExtraConnection
+### shouldMutateGenome
 
 ```ts
-maybeAddExtraConnection(
-  genome: GenomeWithMetadata,
+shouldMutateGenome(
+  effectiveRate: number,
   internal: NeatControllerForMutation,
-): void
+): boolean
 ```
 
-Optionally add an extra connection to increase exploration.
+Decide whether a genome should be mutated based on probability.
 
-This small post-operator hook gives the controller one extra chance to add
-connectivity after the main mutation has landed. It is intentionally
-probabilistic and lightweight: the flow uses it as a gentle exploration bump,
-not as a second full operator-selection phase.
+This is the narrow admission gate for the per-genome flow. Keeping the RNG
+comparison in one helper makes the orchestration read clearly and gives tests
+one stable seam for deterministic gating behavior.
 
 Parameters:
-- `genome` - - genome to mutate
+- `effectiveRate` - - effective mutation probability
 - `internal` - - neat controller context
 
-Returns: void
+Returns: true when the genome should be mutated
 
 ### updateOperatorStatsIfNeeded