@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -34,6 +34,28 @@ flowchart TD
 
 ## neat/mutation/repair/mutation.dead-ends.ts
 
+### chooseRandomNodeForDeadEnds
+
+```ts
+chooseRandomNodeForDeadEnds(
+  candidates: NodeWithMetadata[],
+  internal: NeatControllerForMutation,
+): NodeWithMetadata | null
+```
+
+Choose a random node from candidates for dead-end repair.
+
+Repair deliberately stays lightweight and non-optimizing. Once a helper has
+found a legal candidate pool, this selector uses the controller RNG to pick
+one reconnection target or source without imposing another ranking policy on
+the maintenance path.
+
+Parameters:
+- `candidates` - - candidate nodes
+- `internal` - - neat controller context
+
+Returns: selected node or null
+
 ### collectNodeGroupsForDeadEnds
 
 ```ts
@@ -53,46 +75,50 @@ Parameters:
 
 Returns: grouped node arrays
 
-### ensureInputConnectivityForDeadEnds
+### connectIfCandidatesExistForDeadEnds
 
 ```ts
-ensureInputConnectivityForDeadEnds(
+connectIfCandidatesExistForDeadEnds(
   networkToEdit: GenomeWithMetadata,
-  nodeGroupsToUse: { inputNodes: NodeWithMetadata[]; outputNodes: NodeWithMetadata[]; hiddenNodes: NodeWithMetadata[]; },
+  anchorNode: NodeWithMetadata,
+  candidates: NodeWithMetadata[],
+  reverse: boolean,
   internal: NeatControllerForMutation,
 ): void
 ```
 
-Ensure all input nodes have at least one outgoing connection.
+Connect a node to a random candidate if candidates exist.
 
-Inputs are the first dead-end family because an input with no outgoing edge
-cannot influence the rest of the network at all. The helper prefers routing
-into hidden nodes when they exist and falls back to direct output links when
-the network has no hidden layer yet.
+This is the chapter's small best-effort wiring primitive. It does not decide
+whether repair should happen; it only applies one candidate connection in the
+requested direction and tolerates incompatible node pairs without turning a
+maintenance pass into a fatal error.
 
 Parameters:
 - `networkToEdit` - - network to edit
-- `nodeGroupsToUse` - - grouped node arrays
+- `anchorNode` - - node to connect from/to
+- `candidates` - - candidate nodes for connection
+- `reverse` - - whether to connect candidate -> anchor
 - `internal` - - neat controller context
 
 Returns: void
 
-### ensureOutputConnectivityForDeadEnds
+### ensureHiddenConnectivityForDeadEnds
 
 ```ts
-ensureOutputConnectivityForDeadEnds(
+ensureHiddenConnectivityForDeadEnds(
   networkToEdit: GenomeWithMetadata,
   nodeGroupsToUse: { inputNodes: NodeWithMetadata[]; outputNodes: NodeWithMetadata[]; hiddenNodes: NodeWithMetadata[]; },
   internal: NeatControllerForMutation,
 ): void
 ```
 
-Ensure all output nodes have at least one incoming connection.
+Ensure hidden nodes have both incoming and outgoing connections.
 
-Outputs are the second dead-end family. An output with no inbound edge can be
-observed by later scoring code, but it carries no meaningful signal. The
-helper therefore reconnects it from hidden nodes first and from inputs when
-no hidden layer exists.
+Hidden nodes are the most delicate repair family because they must stay on a
+usable path through the network. A hidden node with only one side connected
+is structural dead weight, so this helper repairs the missing side without
+disturbing hidden nodes that are already participating in a path.
 
 Parameters:
 - `networkToEdit` - - network to edit
@@ -101,22 +127,22 @@ Parameters:
 
 Returns: void
 
-### ensureHiddenConnectivityForDeadEnds
+### ensureInputConnectivityForDeadEnds
 
 ```ts
-ensureHiddenConnectivityForDeadEnds(
+ensureInputConnectivityForDeadEnds(
   networkToEdit: GenomeWithMetadata,
   nodeGroupsToUse: { inputNodes: NodeWithMetadata[]; outputNodes: NodeWithMetadata[]; hiddenNodes: NodeWithMetadata[]; },
   internal: NeatControllerForMutation,
 ): void
 ```
 
-Ensure hidden nodes have both incoming and outgoing connections.
+Ensure all input nodes have at least one outgoing connection.
 
-Hidden nodes are the most delicate repair family because they must stay on a
-usable path through the network. A hidden node with only one side connected
-is structural dead weight, so this helper repairs the missing side without
-disturbing hidden nodes that are already participating in a path.
+Inputs are the first dead-end family because an input with no outgoing edge
+cannot influence the rest of the network at all. The helper prefers routing
+into hidden nodes when they exist and falls back to direct output links when
+the network has no hidden layer yet.
 
 Parameters:
 - `networkToEdit` - - network to edit
@@ -125,52 +151,30 @@ Parameters:
 
 Returns: void
 
-### connectIfCandidatesExistForDeadEnds
+### ensureOutputConnectivityForDeadEnds
 
 ```ts
-connectIfCandidatesExistForDeadEnds(
+ensureOutputConnectivityForDeadEnds(
   networkToEdit: GenomeWithMetadata,
-  anchorNode: NodeWithMetadata,
-  candidates: NodeWithMetadata[],
-  reverse: boolean,
+  nodeGroupsToUse: { inputNodes: NodeWithMetadata[]; outputNodes: NodeWithMetadata[]; hiddenNodes: NodeWithMetadata[]; },
   internal: NeatControllerForMutation,
 ): void
 ```
 
-Connect a node to a random candidate if candidates exist.
+Ensure all output nodes have at least one incoming connection.
 
-This is the chapter's small best-effort wiring primitive. It does not decide
-whether repair should happen; it only applies one candidate connection in the
-requested direction and tolerates incompatible node pairs without turning a
-maintenance pass into a fatal error.
+Outputs are the second dead-end family. An output with no inbound edge can be
+observed by later scoring code, but it carries no meaningful signal. The
+helper therefore reconnects it from hidden nodes first and from inputs when
+no hidden layer exists.
 
 Parameters:
 - `networkToEdit` - - network to edit
-- `anchorNode` - - node to connect from/to
-- `candidates` - - candidate nodes for connection
-- `reverse` - - whether to connect candidate -> anchor
+- `nodeGroupsToUse` - - grouped node arrays
 - `internal` - - neat controller context
 
 Returns: void
 
-### hasOutgoingForDeadEnds
-
-```ts
-hasOutgoingForDeadEnds(
-  node: NodeWithMetadata,
-): boolean
-```
-
-Check whether a node has outgoing connections.
-
-Dead-end repair uses this as the smallest possible structural predicate: if
-the outgoing list is empty, the node cannot currently send signal forward.
-
-Parameters:
-- `node` - - node to inspect
-
-Returns: true when outgoing connections exist
-
 ### hasIncomingForDeadEnds
 
 ```ts
@@ -190,27 +194,23 @@ Parameters:
 
 Returns: true when incoming connections exist
 
-### chooseRandomNodeForDeadEnds
+### hasOutgoingForDeadEnds
 
 ```ts
-chooseRandomNodeForDeadEnds(
-  candidates: NodeWithMetadata[],
-  internal: NeatControllerForMutation,
-): NodeWithMetadata | null
+hasOutgoingForDeadEnds(
+  node: NodeWithMetadata,
+): boolean
 ```
 
-Choose a random node from candidates for dead-end repair.
+Check whether a node has outgoing connections.
 
-Repair deliberately stays lightweight and non-optimizing. Once a helper has
-found a legal candidate pool, this selector uses the controller RNG to pick
-one reconnection target or source without imposing another ranking policy on
-the maintenance path.
+Dead-end repair uses this as the smallest possible structural predicate: if
+the outgoing list is empty, the node cannot currently send signal forward.
 
 Parameters:
-- `candidates` - - candidate nodes
-- `internal` - - neat controller context
+- `node` - - node to inspect
 
-Returns: selected node or null
+Returns: true when outgoing connections exist
 
 ## neat/mutation/repair/mutation.min-hidden.ts
 
@@ -232,6 +232,27 @@ policy. The helpers here turn policy into concrete edits:
 3. wire those hidden nodes into usable inbound and outbound paths,
 4. rebuild connection caches after the structural edits.
 
+### chooseRandomNodeForMinHidden
+
+```ts
+chooseRandomNodeForMinHidden(
+  candidates: NodeWithMetadata[],
+  internal: NeatControllerForMutation,
+): NodeWithMetadata | null
+```
+
+Choose a random node from a candidate list.
+
+Like the dead-end repair selector, this helper keeps minimum-hidden
+enforcement policy-light: once a legal candidate pool exists, choose one
+using the controller RNG and keep the maintenance pass moving.
+
+Parameters:
+- `candidates` - - candidate nodes
+- `internal` - - neat controller context
+
+Returns: selected node or null
+
 ### collectNodeGroupsForMinHidden
 
 ```ts
@@ -251,81 +272,53 @@ Parameters:
 
 Returns: grouped node arrays
 
-### resolveMaxNodesForMinHidden
+### computeMinimumHiddenSize
 
 ```ts
-resolveMaxNodesForMinHidden(
-  internal: NeatControllerForMutation,
+computeMinimumHiddenSize(
+  inputCount: number,
+  outputCount: number,
+  explicitMinimumHidden: number | undefined,
+  hiddenMultiplier: number | undefined,
 ): number
 ```
 
-Resolve the maximum node limit for the network.
+Compute the minimum hidden node count using explicit or multiplier-based settings.
 
-The hidden-floor policy must stay inside the broader controller cap. This
-helper centralizes that read so later creation logic can treat "unbounded"
-and "explicitly capped" networks with one consistent limit value.
+This is the policy-resolution helper for the file. An explicit minimum wins
+immediately; otherwise the helper derives a hidden target from the visible
+endpoint count and the configured multiplier.
 
 Parameters:
-- `internal` - - neat controller context
+- `inputCount` - - Number of input nodes in the network.
+- `outputCount` - - Number of output nodes in the network.
+- `explicitMinimumHidden` - - Optional explicit minimum hidden count.
+- `hiddenMultiplier` - - Optional multiplier used when explicit minimum is absent.
 
-Returns: maximum node limit
+Returns: Minimum hidden node requirement.
 
-### resolveMinHiddenForMinHidden
+### ensureHiddenConnectivityForMinHidden
 
 ```ts
-resolveMinHiddenForMinHidden(
-  networkToInspect: GenomeWithMetadata,
-  maxNodesLimit: number,
-  multiplier: number | undefined,
+ensureHiddenConnectivityForMinHidden(
+  networkToEdit: GenomeWithMetadata,
+  nodeGroupsToUse: { inputNodes: NodeWithMetadata[]; outputNodes: NodeWithMetadata[]; hiddenNodes: NodeWithMetadata[]; },
   internal: NeatControllerForMutation,
-): number
+): void
 ```
 
-Resolve the minimum hidden node requirement for the network.
+Ensure hidden nodes have both incoming and outgoing connections.
 
-This converts controller policy into one concrete hidden-node target for the
-current network. The result respects both the configured minimum-hidden rule
-and the remaining room beneath the maximum-node limit.
+New hidden nodes are not useful until they sit on an actual path through the
+network. This helper treats the whole hidden set as a post-creation repair
+pass so newly added nodes and previously under-connected nodes both leave the
+function with usable inbound and outbound links.
 
 Parameters:
-- `networkToInspect` - - network to inspect
-- `maxNodesLimit` - - maximum allowed nodes
-- `multiplier` - - optional size multiplier
+- `networkToEdit` - - network to edit
+- `nodeGroupsToUse` - - grouped node arrays
 - `internal` - - neat controller context
 
-Returns: minimum hidden node count
-
-### hasRequiredEndpointsForMinHidden
-
-```ts
-hasRequiredEndpointsForMinHidden(
-  nodeGroupsToCheck: { inputNodes: NodeWithMetadata[]; outputNodes: NodeWithMetadata[]; },
-): boolean
-```
-
-Check whether the network has at least one input and output node.
-
-Minimum-hidden enforcement only makes sense when there is an actual endpoint
-path to support. If either side is missing, the helper chapter stops before
-creating hidden nodes that would have nowhere useful to connect.
-
-Parameters:
-- `nodeGroupsToCheck` - - grouped node arrays
-
-Returns: true when inputs and outputs are present
-
-### warnMissingEndpointsForMinHidden
-
-```ts
-warnMissingEndpointsForMinHidden(): void
-```
-
-Emit a warning when the network lacks input or output nodes.
-
-This preserves the chapter's best-effort maintenance contract: endpoint-free
-networks are notable enough to warn about, but not severe enough to justify a
-hard failure during repair.
-
 Returns: void
 
 ### ensureHiddenNodeCountForMinHidden
@@ -353,55 +346,6 @@ Parameters:
 
 Returns: Promise resolving when nodes are created
 
-### ensureHiddenConnectivityForMinHidden
-
-```ts
-ensureHiddenConnectivityForMinHidden(
-  networkToEdit: GenomeWithMetadata,
-  nodeGroupsToUse: { inputNodes: NodeWithMetadata[]; outputNodes: NodeWithMetadata[]; hiddenNodes: NodeWithMetadata[]; },
-  internal: NeatControllerForMutation,
-): void
-```
-
-Ensure hidden nodes have both incoming and outgoing connections.
-
-New hidden nodes are not useful until they sit on an actual path through the
-network. This helper treats the whole hidden set as a post-creation repair
-pass so newly added nodes and previously under-connected nodes both leave the
-function with usable inbound and outbound links.
-
-Parameters:
-- `networkToEdit` - - network to edit
-- `nodeGroupsToUse` - - grouped node arrays
-- `internal` - - neat controller context
-
-Returns: void
-
-### computeMinimumHiddenSize
-
-```ts
-computeMinimumHiddenSize(
-  inputCount: number,
-  outputCount: number,
-  explicitMinimumHidden: number | undefined,
-  hiddenMultiplier: number | undefined,
-): number
-```
-
-Compute the minimum hidden node count using explicit or multiplier-based settings.
-
-This is the policy-resolution helper for the file. An explicit minimum wins
-immediately; otherwise the helper derives a hidden target from the visible
-endpoint count and the configured multiplier.
-
-Parameters:
-- `inputCount` - - Number of input nodes in the network.
-- `outputCount` - - Number of output nodes in the network.
-- `explicitMinimumHidden` - - Optional explicit minimum hidden count.
-- `hiddenMultiplier` - - Optional multiplier used when explicit minimum is absent.
-
-Returns: Minimum hidden node requirement.
-
 ### ensureIncomingConnectionForMinHidden
 
 ```ts
@@ -452,26 +396,28 @@ Parameters:
 
 Returns: void
 
-### chooseRandomNodeForMinHidden
+### hasRequiredEndpointsForMinHidden
 
 ```ts
-chooseRandomNodeForMinHidden(
-  candidates: NodeWithMetadata[],
-  internal: NeatControllerForMutation,
-): NodeWithMetadata | null
+hasRequiredEndpointsForMinHidden(
+  nodeGroupsToCheck: { inputNodes: NodeWithMetadata[]; outputNodes: NodeWithMetadata[]; },
+): boolean
 ```
 
-Choose a random node from a candidate list.
+Check whether the network has at least one input and output node.
 
-Like the dead-end repair selector, this helper keeps minimum-hidden
-enforcement policy-light: once a legal candidate pool exists, choose one
-using the controller RNG and keep the maintenance pass moving.
+Minimum-hidden enforcement only makes sense when there is an actual endpoint
+path to support. If either side is missing, the helper chapter stops before
+creating hidden nodes that would have nowhere useful to connect.
 
 Parameters:
-- `candidates` - - candidate nodes
-- `internal` - - neat controller context
+- `nodeGroupsToCheck` - - grouped node arrays
 
-Returns: selected node or null
+Returns: true when inputs and outputs are present
+
+### MINIMUM_HIDDEN_BASELINE
+
+Baseline minimum hidden nodes when no configuration is provided.
 
 ### rebuildNetworkConnectionsForMinHidden
 
@@ -492,6 +438,60 @@ Parameters:
 
 Returns: Promise resolving after rebuild completes
 
-### MINIMUM_HIDDEN_BASELINE
+### resolveMaxNodesForMinHidden
 
-Baseline minimum hidden nodes when no configuration is provided.
+```ts
+resolveMaxNodesForMinHidden(
+  internal: NeatControllerForMutation,
+): number
+```
+
+Resolve the maximum node limit for the network.
+
+The hidden-floor policy must stay inside the broader controller cap. This
+helper centralizes that read so later creation logic can treat "unbounded"
+and "explicitly capped" networks with one consistent limit value.
+
+Parameters:
+- `internal` - - neat controller context
+
+Returns: maximum node limit
+
+### resolveMinHiddenForMinHidden
+
+```ts
+resolveMinHiddenForMinHidden(
+  networkToInspect: GenomeWithMetadata,
+  maxNodesLimit: number,
+  multiplier: number | undefined,
+  internal: NeatControllerForMutation,
+): number
+```
+
+Resolve the minimum hidden node requirement for the network.
+
+This converts controller policy into one concrete hidden-node target for the
+current network. The result respects both the configured minimum-hidden rule
+and the remaining room beneath the maximum-node limit.
+
+Parameters:
+- `networkToInspect` - - network to inspect
+- `maxNodesLimit` - - maximum allowed nodes
+- `multiplier` - - optional size multiplier
+- `internal` - - neat controller context
+
+Returns: minimum hidden node count
+
+### warnMissingEndpointsForMinHidden
+
+```ts
+warnMissingEndpointsForMinHidden(): void
+```
+
+Emit a warning when the network lacks input or output nodes.
+
+This preserves the chapter's best-effort maintenance contract: endpoint-free
+networks are notable enough to warn about, but not severe enough to justify a
+hard failure during repair.
+
+Returns: void