@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -42,78 +42,60 @@ flowchart TD
 
 ## neat/mutation/select/mutation.select.ts
 
-### resolveFFWPolicyForSelect
+### applyOperatorAdaptationForSelect
 
 ```ts
-resolveFFWPolicyForSelect(
+applyOperatorAdaptationForSelect(
+  pool: MutationMethod[],
   internal: NeatControllerForMutation,
-  methods: { mutation: unknown; },
-  rawReturnForTest: boolean,
-): MutationMethod | MutationMethod[] | null
+): MutationMethod[]
 ```
 
-Resolve legacy FFW policy behavior, including test-specific returns.
+Apply operator adaptation weighting to the pool when enabled.
 
-Older feed-forward configuration paths can encode mutation policy in shapes
-that do not look like the newer flat operator pool. This helper isolates that
-compatibility layer so the rest of selection can operate on a predictable
-surface.
+Operator adaptation uses recent structural success as a lightweight teaching
+signal. Operators that have enough attempts and a sufficiently high success
+ratio are duplicated into the candidate pool, increasing their sampling
+probability without changing the operator interface itself.
 
-The `rawReturnForTest` flag exists because some tests assert the preserved
-legacy pool shape rather than one sampled method. Production mutation flow,
-by contrast, normally wants one concrete operator.
+The helper intentionally does not compute a fancy score. It just reshapes the
+pool, which keeps the later selection steps simple and preserves compatibility
+with random sampling and bandit-based final choice.
 
 Parameters:
+- `pool` - - base pool
 - `internal` - - neat controller context
-- `methods` - - methods module
-- `rawReturnForTest` - - whether to return raw FFW array for tests
 
-Returns: mutation method or null when not handled
+Returns: augmented pool
 
-### normalizeMutationPoolForSelect
+### applyOperatorBanditForSelect
 
 ```ts
-normalizeMutationPoolForSelect(
+applyOperatorBanditForSelect(
+  pool: MutationMethod[],
+  fallbackMethod: MutationMethod,
   internal: NeatControllerForMutation,
-  methods: { mutation: unknown; },
-  rawReturnForTest: boolean,
-): MutationMethod[]
+): MutationMethod
 ```
 
-Normalize the configured mutation pool to a flat operator list.
-
-This helper is the bridge from loose policy configuration to a concrete
-candidate shelf. It flattens nested legacy arrays and preserves the special
-FFW path when tests explicitly need the historical representation.
-
-Parameters:
-- `internal` - - neat controller context
-- `methods` - - methods module
-- `rawReturnForTest` - - whether to return raw FFW for tests
-
-Returns: normalized mutation pool
-
-### isLegacyFFWPoolForSelect
-
-```ts
-isLegacyFFWPoolForSelect(
-  configuredPool: MutationMethod[],
-  methods: { mutation: unknown; },
-): boolean
-```
+Apply operator bandit selection if enabled.
 
-Check whether a pool matches the legacy FFW operator ordering.
+The operator bandit is the strongest opinionated selector in this chapter.
+Instead of drawing randomly from the shaped pool, it ranks candidate
+operators with a UCB-style score that balances observed success and
+exploration.
 
-The selection boundary uses this check as a compatibility detector, not as a
-generic equality helper. Matching the canonical FFW ordering tells the caller
-that the configured pool is really a feed-forward preset that may deserve
-special handling.
+Early in a run, under-sampled operators receive effectively unbounded
+exploration pressure. Later, the choice shifts toward operators with better
+observed structural payoff. That makes this helper the bridge between simple
+mutation policy configuration and online operator learning.
 
 Parameters:
-- `configuredPool` - - configured operator pool
-- `methods` - - methods module
+- `pool` - - operator pool
+- `fallbackMethod` - - method used when bandit is disabled
+- `internal` - - neat controller context
 
-Returns: true when the pool matches FFW
+Returns: selected method
 
 ### applyPhasedComplexityForSelect
 
@@ -138,52 +120,76 @@ Parameters:
 
 Returns: pool with phased complexity adjustments
 
-### applyOperatorAdaptationForSelect
+### isBlockedByRecurrentPolicyForSelect
 
 ```ts
-applyOperatorAdaptationForSelect(
-  pool: MutationMethod[],
+isBlockedByRecurrentPolicyForSelect(
+  mutationMethod: MutationMethod,
   internal: NeatControllerForMutation,
-): MutationMethod[]
+  methods: { mutation: unknown; },
+): boolean
 ```
 
-Apply operator adaptation weighting to the pool when enabled.
-
-Operator adaptation uses recent structural success as a lightweight teaching
-signal. Operators that have enough attempts and a sufficiently high success
-ratio are duplicated into the candidate pool, increasing their sampling
-probability without changing the operator interface itself.
+Check whether a mutation is blocked by recurrent connection policy.
 
-The helper intentionally does not compute a fancy score. It just reshapes the
-pool, which keeps the later selection steps simple and preserves compatibility
-with random sampling and bandit-based final choice.
+Structural capacity limits are not the only hard guard. Some runs prohibit
+recurrent structure entirely, and this helper keeps that policy localized so
+the rest of the selection code can stay focused on scoring and weighting.
 
 Parameters:
-- `pool` - - base pool
+- `mutationMethod` - - mutation operator to check
 - `internal` - - neat controller context
+- `methods` - - methods module
 
-Returns: augmented pool
+Returns: true when the mutation should be blocked
 
-### sampleFromPoolForSelect
+### isBlockedByStructuralLimitsForSelect
 
 ```ts
-sampleFromPoolForSelect(
-  pool: MutationMethod[],
+isBlockedByStructuralLimitsForSelect(
+  mutationMethod: MutationMethod,
+  genome: GenomeWithMetadata,
   internal: NeatControllerForMutation,
-): MutationMethod | null
+  methods: { mutation: unknown; },
+): boolean
 ```
 
-Sample a random method from the pool.
+Check whether a mutation is blocked by structural limits.
 
-This is the uncomplicated fallback selector. It is useful both for direct
-legacy sampling paths and for each configuration that wants weighted random
-choice without the stronger opinion of the operator bandit.
+This helper is one of the hard guard rails after softer policy shaping has
+already happened. Even if an operator is favored by phase bias or adaptation,
+it must still respect controller-wide caps such as maximum nodes,
+connections, or gates.
 
 Parameters:
-- `pool` - - operator pool
+- `mutationMethod` - - mutation operator to check
+- `genome` - - genome to inspect
 - `internal` - - neat controller context
+- `methods` - - methods module
 
-Returns: sampled method or null
+Returns: true when the mutation should be blocked
+
+### isLegacyFFWPoolForSelect
+
+```ts
+isLegacyFFWPoolForSelect(
+  configuredPool: MutationMethod[],
+  methods: { mutation: unknown; },
+): boolean
+```
+
+Check whether a pool matches the legacy FFW operator ordering.
+
+The selection boundary uses this check as a compatibility detector, not as a
+generic equality helper. Matching the canonical FFW ordering tells the caller
+that the configured pool is really a feed-forward preset that may deserve
+special handling.
+
+Parameters:
+- `configuredPool` - - configured operator pool
+- `methods` - - methods module
+
+Returns: true when the pool matches FFW
 
 ### isOperatorNamePrefixedForSelect
 
@@ -206,80 +212,74 @@ Parameters:
 
 Returns: true when the operator name matches the prefix
 
-### isBlockedByStructuralLimitsForSelect
+### normalizeMutationPoolForSelect
 
 ```ts
-isBlockedByStructuralLimitsForSelect(
-  mutationMethod: MutationMethod,
-  genome: GenomeWithMetadata,
+normalizeMutationPoolForSelect(
   internal: NeatControllerForMutation,
   methods: { mutation: unknown; },
-): boolean
+  rawReturnForTest: boolean,
+): MutationMethod[]
 ```
 
-Check whether a mutation is blocked by structural limits.
+Normalize the configured mutation pool to a flat operator list.
 
-This helper is one of the hard guard rails after softer policy shaping has
-already happened. Even if an operator is favored by phase bias or adaptation,
-it must still respect controller-wide caps such as maximum nodes,
-connections, or gates.
+This helper is the bridge from loose policy configuration to a concrete
+candidate shelf. It flattens nested legacy arrays and preserves the special
+FFW path when tests explicitly need the historical representation.
 
 Parameters:
-- `mutationMethod` - - mutation operator to check
-- `genome` - - genome to inspect
 - `internal` - - neat controller context
 - `methods` - - methods module
+- `rawReturnForTest` - - whether to return raw FFW for tests
 
-Returns: true when the mutation should be blocked
+Returns: normalized mutation pool
 
-### applyOperatorBanditForSelect
+### resolveFFWPolicyForSelect
 
 ```ts
-applyOperatorBanditForSelect(
-  pool: MutationMethod[],
-  fallbackMethod: MutationMethod,
+resolveFFWPolicyForSelect(
   internal: NeatControllerForMutation,
-): MutationMethod
+  methods: { mutation: unknown; },
+  rawReturnForTest: boolean,
+): MutationMethod | MutationMethod[] | null
 ```
 
-Apply operator bandit selection if enabled.
+Resolve legacy FFW policy behavior, including test-specific returns.
 
-The operator bandit is the strongest opinionated selector in this chapter.
-Instead of drawing randomly from the shaped pool, it ranks candidate
-operators with a UCB-style score that balances observed success and
-exploration.
+Older feed-forward configuration paths can encode mutation policy in shapes
+that do not look like the newer flat operator pool. This helper isolates that
+compatibility layer so the rest of selection can operate on a predictable
+surface.
 
-Early in a run, under-sampled operators receive effectively unbounded
-exploration pressure. Later, the choice shifts toward operators with better
-observed structural payoff. That makes this helper the bridge between simple
-mutation policy configuration and online operator learning.
+The `rawReturnForTest` flag exists because some tests assert the preserved
+legacy pool shape rather than one sampled method. Production mutation flow,
+by contrast, normally wants one concrete operator.
 
 Parameters:
-- `pool` - - operator pool
-- `fallbackMethod` - - method used when bandit is disabled
 - `internal` - - neat controller context
+- `methods` - - methods module
+- `rawReturnForTest` - - whether to return raw FFW array for tests
 
-Returns: selected method
+Returns: mutation method or null when not handled
 
-### isBlockedByRecurrentPolicyForSelect
+### sampleFromPoolForSelect
 
 ```ts
-isBlockedByRecurrentPolicyForSelect(
-  mutationMethod: MutationMethod,
+sampleFromPoolForSelect(
+  pool: MutationMethod[],
   internal: NeatControllerForMutation,
-  methods: { mutation: unknown; },
-): boolean
+): MutationMethod | null
 ```
 
-Check whether a mutation is blocked by recurrent connection policy.
+Sample a random method from the pool.
 
-Structural capacity limits are not the only hard guard. Some runs prohibit
-recurrent structure entirely, and this helper keeps that policy localized so
-the rest of the selection code can stay focused on scoring and weighting.
+This is the uncomplicated fallback selector. It is useful both for direct
+legacy sampling paths and for each configuration that wants weighted random
+choice without the stronger opinion of the operator bandit.
 
 Parameters:
-- `mutationMethod` - - mutation operator to check
+- `pool` - - operator pool
 - `internal` - - neat controller context
-- `methods` - - methods module
 
-Returns: true when the mutation should be blocked
+Returns: sampled method or null

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

@@ -37,6 +37,15 @@ flowchart TD
 
 ## neat/mutation/shared/mutation.types.ts
 
+### ConnectionWithMetadata
+
+Runtime interface for a connection within a genome.
+
+This is the minimum edge metadata required by the structural mutation paths.
+The add-node and add-conn chapters use it to preserve weights, inspect edge
+activation, and attach innovation ids that later support alignment-based
+crossover and speciation.
+
 ### GenomeWithMetadata
 
 Runtime interface for a genome with mutation-related metadata.
@@ -51,24 +60,6 @@ state such as `_mutRate` and `_mutAmount` travels with the genome itself,
 while global innovation tables and policy controls stay on the controller
 host contract.
 
-### NodeWithMetadata
-
-Runtime interface for a node within a genome.
-
-Mutation helpers only need a narrow node view: topology category, optional
-gene identity, adjacency lists, and one projection check. That narrowness is
-what lets the structural chapters reason about connection growth and cycle
-checks without depending on the whole node implementation.
-
-### ConnectionWithMetadata
-
-Runtime interface for a connection within a genome.
-
-This is the minimum edge metadata required by the structural mutation paths.
-The add-node and add-conn chapters use it to preserve weights, inspect edge
-activation, and attach innovation ids that later support alignment-based
-crossover and speciation.
-
 ### MutationMethod
 
 Runtime interface for a mutation method descriptor.
@@ -78,14 +69,17 @@ as enum literals alone. That gives selection helpers room to reason about
 operator families, sample-count hints, and output-mutation behavior without
 having to know the concrete implementation of each operator.
 
-### OperatorStats
+### NeatControllerForMutation
 
-Runtime interface for operator statistics tracking.
+Runtime interface for the NEAT controller used in mutation operations.
 
-These counters support the adaptive side of mutation policy. They do not try
-to capture full fitness impact; instead they record a cheap local proxy for
-whether an attempted operator actually produced structure often enough to be
-favored later by adaptation or bandit logic.
+This host contract is the bridge between local genome edits and global NEAT
+state. It exposes configuration, RNG access, innovation stores, operator
+statistics, and the narrow controller callbacks that the mutation helpers need.
+
+The important boundary is that mutation chapters can mutate controller-owned
+bookkeeping through this interface, but they do not need the entire `Neat`
+class surface to do their work.
 
 ### NodeSplitRecord
 
@@ -96,14 +90,20 @@ A node-split record is the durable memory that tells the add-node path,
 paired edge innovations is how separate genomes can independently perform the
 same split and still remain historically alignable.
 
-### NeatControllerForMutation
+### NodeWithMetadata
 
-Runtime interface for the NEAT controller used in mutation operations.
+Runtime interface for a node within a genome.
 
-This host contract is the bridge between local genome edits and global NEAT
-state. It exposes configuration, RNG access, innovation stores, operator
-statistics, and the narrow controller callbacks that the mutation helpers need.
+Mutation helpers only need a narrow node view: topology category, optional
+gene identity, adjacency lists, and one projection check. That narrowness is
+what lets the structural chapters reason about connection growth and cycle
+checks without depending on the whole node implementation.
 
-The important boundary is that mutation chapters can mutate controller-owned
-bookkeeping through this interface, but they do not need the entire `Neat`
-class surface to do their work.
+### OperatorStats
+
+Runtime interface for operator statistics tracking.
+
+These counters support the adaptive side of mutation policy. They do not try
+to capture full fitness impact; instead they record a cheap local proxy for
+whether an attempted operator actually produced structure often enough to be
+favored later by adaptation or bandit logic.

package/src/neat/objectives/README.md

@@ -81,6 +81,31 @@ const objectives = neat._getObjectives();
 console.log(objectives.map((objective) => objective.key));
 ```
 
+### clearObjectives
+
+```ts
+clearObjectives(): void
+```
+
+Clear all registered multi-objectives.
+
+Use this when a run should fall back to its default objective behavior or
+when a test needs a clean objective slate before registering a new set. This
+clears the user-defined objective layer and invalidates the cached resolved
+list so the next read rebuilds it from the remaining controller defaults.
+
+Parameters:
+- `this` - - NEAT host exposing multi-objective options and the cached objective list.
+
+Returns: Nothing. Registered user objectives and the cached objective list are cleared.
+
+Example:
+
+```ts
+neat.clearObjectives();
+const objectives = neat._getObjectives();
+```
+
 ### registerObjective
 
 ```ts
@@ -115,28 +140,3 @@ Example:
 ```ts
 neat.registerObjective('energy', 'min', (genome) => genome.cost ?? 0);
 ```
-
-### clearObjectives
-
-```ts
-clearObjectives(): void
-```
-
-Clear all registered multi-objectives.
-
-Use this when a run should fall back to its default objective behavior or
-when a test needs a clean objective slate before registering a new set. This
-clears the user-defined objective layer and invalidates the cached resolved
-list so the next read rebuilds it from the remaining controller defaults.
-
-Parameters:
-- `this` - - NEAT host exposing multi-objective options and the cached objective list.
-
-Returns: Nothing. Registered user objectives and the cached objective list are cleared.
-
-Example:
-
-```ts
-neat.clearObjectives();
-const objectives = neat._getObjectives();
-```

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

@@ -84,6 +84,25 @@ must exist by default, middle helpers gather and validate user intent, and
 later helpers hydrate missing containers or replace one objective without
 mutating an older list in place.
 
+### buildDefaultFitnessObjective
+
+```ts
+buildDefaultFitnessObjective(): ObjectiveDescriptor
+```
+
+Build the default fitness objective descriptor.
+
+The default fitness objective is the anchor that keeps ordinary NEAT runs
+meaningful even when no richer objective policy has been configured yet.
+Core resolution builds it on demand so callers do not need a special
+bootstrap path elsewhere.
+
+Keeping this builder separate from the collection logic also makes the core
+flow easier to teach: one helper decides *whether* the default should exist,
+this helper decides *what* that default descriptor looks like.
+
+Returns: Default fitness objective descriptor.
+
 ### collectDefaultObjectives
 
 ```ts
@@ -130,46 +149,49 @@ Parameters:
 
 Returns: Valid user objective descriptors.
 
-### buildDefaultFitnessObjective
+### ensureMultiObjectiveOptions
 
 ```ts
-buildDefaultFitnessObjective(): ObjectiveDescriptor
+ensureMultiObjectiveOptions(
+  neatInstance: NeatLikeWithObjectives,
+): { enabled?: boolean | undefined; objectives?: ObjectiveDescriptor[] | undefined; }
 ```
 
-Build the default fitness objective descriptor.
+Ensure the multi-objective options container exists.
 
-The default fitness objective is the anchor that keeps ordinary NEAT runs
-meaningful even when no richer objective policy has been configured yet.
-Core resolution builds it on demand so callers do not need a special
-bootstrap path elsewhere.
+Objective registration and resolution are allowed to hydrate this container
+lazily so controller construction does not need to eagerly materialize every
+optional configuration branch.
 
-Keeping this builder separate from the collection logic also makes the core
-flow easier to teach: one helper decides *whether* the default should exist,
-this helper decides *what* that default descriptor looks like.
+This is one of the small helpers that keeps the core chapter mutation-safe:
+later logic can assume the container exists without scattering defensive
+object creation throughout the file.
 
-Returns: Default fitness objective descriptor.
+Parameters:
+- `neatInstance` - - NEAT host receiving the multi-objective container.
 
-### isMultiObjectiveEnabled
+Returns: Initialized multi-objective options.
+
+### ensureObjectivesList
 
 ```ts
-isMultiObjectiveEnabled(
-  neatInstance: NeatLikeWithObjectives,
-): boolean
+ensureObjectivesList(
+  multiObjectiveOptions: { enabled?: boolean | undefined; objectives?: ObjectiveDescriptor[] | undefined; },
+): ObjectiveDescriptor[]
 ```
 
-Check whether multi-objective mode is enabled with a candidate list.
+Ensure the objectives list exists on the multi-objective container.
 
-This guard is intentionally strict: enabling multi-objective mode without an
-objective array is treated as incomplete configuration, so downstream helpers
-can avoid reasoning about half-hydrated state.
+This helper complements container hydration by guaranteeing a writable list
+surface for later non-destructive replacement logic.
 
-That strictness keeps later helpers simpler because they can assume that a
-`true` result means both the mode and the candidate container are present.
+It exists so registration code can talk about replacing objectives by key
+instead of repeatedly guarding against `undefined` lists.
 
 Parameters:
-- `neatInstance` - - NEAT host exposing objective settings.
+- `multiObjectiveOptions` - - Multi-objective container to hydrate.
 
-Returns: `true` when multi-objective mode is enabled and an objective list exists.
+Returns: Objectives list ready for non-destructive operations.
 
 ### getObjectiveCandidates
 
@@ -191,6 +213,28 @@ Parameters:
 
 Returns: Objective candidates from configuration.
 
+### isMultiObjectiveEnabled
+
+```ts
+isMultiObjectiveEnabled(
+  neatInstance: NeatLikeWithObjectives,
+): boolean
+```
+
+Check whether multi-objective mode is enabled with a candidate list.
+
+This guard is intentionally strict: enabling multi-objective mode without an
+objective array is treated as incomplete configuration, so downstream helpers
+can avoid reasoning about half-hydrated state.
+
+That strictness keeps later helpers simpler because they can assume that a
+`true` result means both the mode and the candidate container are present.
+
+Parameters:
+- `neatInstance` - - NEAT host exposing objective settings.
+
+Returns: `true` when multi-objective mode is enabled and an objective list exists.
+
 ### isValidObjective
 
 ```ts
@@ -214,50 +258,6 @@ Parameters:
 
 Returns: `true` when the descriptor can be used safely.
 
-### ensureMultiObjectiveOptions
-
-```ts
-ensureMultiObjectiveOptions(
-  neatInstance: NeatLikeWithObjectives,
-): { enabled?: boolean | undefined; objectives?: ObjectiveDescriptor[] | undefined; }
-```
-
-Ensure the multi-objective options container exists.
-
-Objective registration and resolution are allowed to hydrate this container
-lazily so controller construction does not need to eagerly materialize every
-optional configuration branch.
-
-This is one of the small helpers that keeps the core chapter mutation-safe:
-later logic can assume the container exists without scattering defensive
-object creation throughout the file.
-
-Parameters:
-- `neatInstance` - - NEAT host receiving the multi-objective container.
-
-Returns: Initialized multi-objective options.
-
-### ensureObjectivesList
-
-```ts
-ensureObjectivesList(
-  multiObjectiveOptions: { enabled?: boolean | undefined; objectives?: ObjectiveDescriptor[] | undefined; },
-): ObjectiveDescriptor[]
-```
-
-Ensure the objectives list exists on the multi-objective container.
-
-This helper complements container hydration by guaranteeing a writable list
-surface for later non-destructive replacement logic.
-
-It exists so registration code can talk about replacing objectives by key
-instead of repeatedly guarding against `undefined` lists.
-
-Parameters:
-- `multiObjectiveOptions` - - Multi-objective container to hydrate.
-
-Returns: Objectives list ready for non-destructive operations.
-
 ### replaceObjectiveByKey
 
 ```ts