@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/mutation/add-conn/README.md

@@ -38,69 +38,71 @@ flowchart TD
 
 ## neat/mutation/add-conn/mutation.add-conn.ts
 
-### collectCandidatePairsForConn
+### assignInnovationForConnection
 
 ```ts
-collectCandidatePairsForConn(
-  genomeToInspect: GenomeWithMetadata,
-): [NodeWithMetadata, NodeWithMetadata][]
+assignInnovationForConnection(
+  connection: ConnectionWithMetadata,
+  pairNodes: { symmetricKey: string; legacyForwardKey: string; legacyReverseKey: string; },
+  internal: NeatControllerForMutation,
+): void
 ```
 
-Collect legal (from,to) node pairs not already connected.
+Assign an innovation id for a new connection, reusing when possible.
 
-This helper defines the search space for connection growth. It respects the
-node ordering conventions used by the genome representation so mutation does
-not propose obviously invalid source-target directions before later cycle
-checks even run.
+Innovation assignment is the historical memory for connection growth. If the
+unordered node pair has been seen before, this helper reuses that innovation
+id. Otherwise it allocates a new global id and stores it under both the
+symmetric key and the legacy directional aliases.
 
 Parameters:
-- `genomeToInspect` - - genome to scan
+- `connection` - - newly created connection
+- `pairNodes` - - resolved pair metadata
+- `internal` - - neat controller context
 
-Returns: candidate node pairs
+Returns: void
 
-### filterPairsWithInnovations
+### buildLegacyKeyForConn
 
 ```ts
-filterPairsWithInnovations(
-  pairs: [NodeWithMetadata, NodeWithMetadata][],
-  internal: NeatControllerForMutation,
-): [NodeWithMetadata, NodeWithMetadata][]
+buildLegacyKeyForConn(
+  sourceNode: NodeWithMetadata,
+  targetNode: NodeWithMetadata,
+): string
 ```
 
-Filter candidate pairs that already have innovation reuse keys.
+Build a legacy directional innovation key.
 
-Reuse candidates are especially valuable because they let independently
-discovered structure share the same innovation identity. This helper pulls out
-those historically known pairs so the selection path can favor them when such pairs
-exist.
+Legacy directional keys are still stored so older code paths or preserved
+historical records can resolve to the same innovation id as the modern
+symmetric key.
 
 Parameters:
-- `pairs` - - candidate node pairs
-- `internal` - - neat controller context
+- `sourceNode` - - source node
+- `targetNode` - - target node
 
-Returns: reuse candidates
+Returns: directional innovation key
 
-### selectPairPool
+### buildSymmetricKeyForConn
 
 ```ts
-selectPairPool(
-  allPairs: [NodeWithMetadata, NodeWithMetadata][],
-  reusePairs: [NodeWithMetadata, NodeWithMetadata][],
-): [NodeWithMetadata, NodeWithMetadata][]
+buildSymmetricKeyForConn(
+  sourceNode: NodeWithMetadata,
+  targetNode: NodeWithMetadata,
+): string
 ```
 
-Build the final selection pool based on reuse and hidden-node preference.
+Build a symmetric innovation key for an unordered node pair.
 
-Pool selection is opinionated but still simple: prefer pairs with known
-innovation history, otherwise prefer hidden-to-hidden growth, otherwise fall
-back to the full candidate set. That keeps the chapter's structural bias
-readable in one place.
+The symmetric key is the preferred reuse identity because connection growth
+is treated as one structural relationship between two genes, not as a
+direction-specific novelty record.
 
 Parameters:
-- `allPairs` - - all candidate pairs
-- `reusePairs` - - pairs with historical innovations
+- `sourceNode` - - source node
+- `targetNode` - - target node
 
-Returns: selection pool
+Returns: symmetric innovation key
 
 ### choosePairForConn
 
@@ -122,45 +124,25 @@ Parameters:
 
 Returns: chosen pair or null
 
-### resolvePairNodes
-
-```ts
-resolvePairNodes(
-  chosenPair: [NodeWithMetadata, NodeWithMetadata],
-): { sourceNode: NodeWithMetadata; targetNode: NodeWithMetadata; symmetricKey: string; legacyForwardKey: string; legacyReverseKey: string; }
-```
-
-Resolve nodes and innovation key details for a chosen pair.
-
-Once selection has picked a pair, the mutation path needs more than the raw
-nodes. It also needs the symmetric key used for modern innovation reuse and
-the directional legacy keys kept for backward-compatible lookups.
-
-Parameters:
-- `chosenPair` - - pair to connect
-
-Returns: resolved pair metadata
-
-### shouldAbortForCycle
+### collectCandidatePairsForConn
 
 ```ts
-shouldAbortForCycle(
+collectCandidatePairsForConn(
   genomeToInspect: GenomeWithMetadata,
-  pairNodes: { sourceNode: NodeWithMetadata; targetNode: NodeWithMetadata; },
-): boolean
+): [NodeWithMetadata, NodeWithMetadata][]
 ```
 
-Determine whether adding the connection would create a cycle.
+Collect legal (from,to) node pairs not already connected.
 
-The add-connection path only enforces cycle checks when the genome requests
-acyclic topology. That keeps recurrent-capable runs permissive while still
-giving feed-forward-style runs one clear abort seam.
+This helper defines the search space for connection growth. It respects the
+node ordering conventions used by the genome representation so mutation does
+not propose obviously invalid source-target directions before later cycle
+checks even run.
 
 Parameters:
-- `genomeToInspect` - - genome to inspect
-- `pairNodes` - - resolved pair nodes
+- `genomeToInspect` - - genome to scan
 
-Returns: true if the connection should be aborted
+Returns: candidate node pairs
 
 ### connectChosenPair
 
@@ -183,89 +165,107 @@ Parameters:
 
 Returns: created connection or undefined
 
-### assignInnovationForConnection
+### createsCycle
 
 ```ts
-assignInnovationForConnection(
-  connection: ConnectionWithMetadata,
-  pairNodes: { symmetricKey: string; legacyForwardKey: string; legacyReverseKey: string; },
+createsCycle(
+  sourceNode: NodeWithMetadata,
+  targetNode: NodeWithMetadata,
+): boolean
+```
+
+Detect whether adding a connection would create a cycle.
+
+The cycle check walks forward from the proposed target node and looks for a
+path back to the proposed source. If one exists, adding the new edge would
+close a loop and the caller can abort the structural edit for acyclic runs.
+
+Parameters:
+- `sourceNode` - - source node of the new connection
+- `targetNode` - - target node of the new connection
+
+Returns: true when a cycle is detected
+
+### filterPairsWithInnovations
+
+```ts
+filterPairsWithInnovations(
+  pairs: [NodeWithMetadata, NodeWithMetadata][],
   internal: NeatControllerForMutation,
-): void
+): [NodeWithMetadata, NodeWithMetadata][]
 ```
 
-Assign an innovation id for a new connection, reusing when possible.
+Filter candidate pairs that already have innovation reuse keys.
 
-Innovation assignment is the historical memory for connection growth. If the
-unordered node pair has been seen before, this helper reuses that innovation
-id. Otherwise it allocates a new global id and stores it under both the
-symmetric key and the legacy directional aliases.
+Reuse candidates are especially valuable because they let independently
+discovered structure share the same innovation identity. This helper pulls out
+those historically known pairs so the selection path can favor them when such pairs
+exist.
 
 Parameters:
-- `connection` - - newly created connection
-- `pairNodes` - - resolved pair metadata
+- `pairs` - - candidate node pairs
 - `internal` - - neat controller context
 
-Returns: void
+Returns: reuse candidates
 
-### buildSymmetricKeyForConn
+### resolvePairNodes
 
 ```ts
-buildSymmetricKeyForConn(
-  sourceNode: NodeWithMetadata,
-  targetNode: NodeWithMetadata,
-): string
+resolvePairNodes(
+  chosenPair: [NodeWithMetadata, NodeWithMetadata],
+): { sourceNode: NodeWithMetadata; targetNode: NodeWithMetadata; symmetricKey: string; legacyForwardKey: string; legacyReverseKey: string; }
 ```
 
-Build a symmetric innovation key for an unordered node pair.
+Resolve nodes and innovation key details for a chosen pair.
 
-The symmetric key is the preferred reuse identity because connection growth
-is treated as one structural relationship between two genes, not as a
-direction-specific novelty record.
+Once selection has picked a pair, the mutation path needs more than the raw
+nodes. It also needs the symmetric key used for modern innovation reuse and
+the directional legacy keys kept for backward-compatible lookups.
 
 Parameters:
-- `sourceNode` - - source node
-- `targetNode` - - target node
+- `chosenPair` - - pair to connect
 
-Returns: symmetric innovation key
+Returns: resolved pair metadata
 
-### buildLegacyKeyForConn
+### selectPairPool
 
 ```ts
-buildLegacyKeyForConn(
-  sourceNode: NodeWithMetadata,
-  targetNode: NodeWithMetadata,
-): string
+selectPairPool(
+  allPairs: [NodeWithMetadata, NodeWithMetadata][],
+  reusePairs: [NodeWithMetadata, NodeWithMetadata][],
+): [NodeWithMetadata, NodeWithMetadata][]
 ```
 
-Build a legacy directional innovation key.
+Build the final selection pool based on reuse and hidden-node preference.
 
-Legacy directional keys are still stored so older code paths or preserved
-historical records can resolve to the same innovation id as the modern
-symmetric key.
+Pool selection is opinionated but still simple: prefer pairs with known
+innovation history, otherwise prefer hidden-to-hidden growth, otherwise fall
+back to the full candidate set. That keeps the chapter's structural bias
+readable in one place.
 
 Parameters:
-- `sourceNode` - - source node
-- `targetNode` - - target node
+- `allPairs` - - all candidate pairs
+- `reusePairs` - - pairs with historical innovations
 
-Returns: directional innovation key
+Returns: selection pool
 
-### createsCycle
+### shouldAbortForCycle
 
 ```ts
-createsCycle(
-  sourceNode: NodeWithMetadata,
-  targetNode: NodeWithMetadata,
+shouldAbortForCycle(
+  genomeToInspect: GenomeWithMetadata,
+  pairNodes: { sourceNode: NodeWithMetadata; targetNode: NodeWithMetadata; },
 ): boolean
 ```
 
-Detect whether adding a connection would create a cycle.
+Determine whether adding the connection would create a cycle.
 
-The cycle check walks forward from the proposed target node and looks for a
-path back to the proposed source. If one exists, adding the new edge would
-close a loop and the caller can abort the structural edit for acyclic runs.
+The add-connection path only enforces cycle checks when the genome requests
+acyclic topology. That keeps recurrent-capable runs permissive while still
+giving feed-forward-style runs one clear abort seam.
 
 Parameters:
-- `sourceNode` - - source node of the new connection
-- `targetNode` - - target node of the new connection
+- `genomeToInspect` - - genome to inspect
+- `pairNodes` - - resolved pair nodes
 
-Returns: true when a cycle is detected
+Returns: true if the connection should be aborted

package/src/neat/mutation/add-node/README.md

@@ -42,68 +42,103 @@ flowchart TD
 
 ## neat/mutation/add-node/mutation.add-node.ts
 
-### ensureBootstrapConnection
+### applySplitWithExistingRecord
 
 ```ts
-ensureBootstrapConnection(
-  genomeToSeed: GenomeWithMetadata,
+applySplitWithExistingRecord(
+  genomeToEdit: GenomeWithMetadata,
+  connectionToSplit: ConnectionWithMetadata,
+  splitDescriptor: { splitKey: string; originalWeight: number; },
+  splitRecord: { newNodeGeneId: number; inInnov: number; outInnov: number; },
+  NodeClass: new (type: "input" | "output" | "hidden") => unknown,
+): void
+```
+
+Apply a split using an existing innovation record.
+
+This is the preferred path when the same structural split has already been
+observed elsewhere in the population history. Reusing the stored node gene id
+and edge innovation ids preserves historical identity, which makes later
+alignment-based operations treat equivalent splits as equivalent structure.
+
+Parameters:
+- `genomeToEdit` - - genome being modified
+- `connectionToSplit` - - connection being split
+- `splitDescriptor` - - metadata for the split
+- `splitRecord` - - existing innovation record
+- `NodeClass` - - node constructor
+
+Returns: void
+
+### applySplitWithNewRecord
+
+```ts
+applySplitWithNewRecord(
+  genomeToEdit: GenomeWithMetadata,
+  connectionToSplit: ConnectionWithMetadata,
+  splitDescriptor: { splitKey: string; originalWeight: number; },
+  NodeClass: new (type: "input" | "output" | "hidden") => unknown,
   internal: NeatControllerForMutation,
 ): void
 ```
 
-Ensure the genome has at least one connection by linking input to output.
+Apply a split and create a new innovation record.
 
-A connection split only makes sense when a genome already has an edge to cut.
-This helper is the bootstrap escape hatch for extremely sparse genomes. It
-seeds the smallest possible forward connection so the add-node path can keep
-behaving like a split-based structural mutation instead of bailing out
-immediately.
+This path handles genuinely novel structural growth. It inserts a fresh
+hidden node, assigns new innovations to the replacement edges, and records
+the resulting identity under the split key so future genomes can reuse it.
 
 Parameters:
-- `genomeToSeed` - - genome that may need a bootstrap connection
-- `internal` - - neat controller context retained for compatibility with existing callers
+- `genomeToEdit` - - genome being modified
+- `connectionToSplit` - - connection being split
+- `splitDescriptor` - - metadata for the split
+- `NodeClass` - - node constructor
+- `internal` - - neat controller context
 
 Returns: void
 
-### findFirstNodeByType
+### assignInnovationsForNewSplit
 
 ```ts
-findFirstNodeByType(
-  genomeToSearch: GenomeWithMetadata,
-  nodeType: "input" | "output" | "hidden",
-): NodeWithMetadata | undefined
+assignInnovationsForNewSplit(
+  newNode: NodeWithMetadata,
+  splitConnections: { incomingConnection?: ConnectionWithMetadata | undefined; outgoingConnection?: ConnectionWithMetadata | undefined; },
+  internal: NeatControllerForMutation,
+): { newNodeGeneId: number; inInnov: number; outInnov: number; }
 ```
 
-Find the first node of a given type.
+Assign new innovations for a split and build the innovation record.
 
-The add-node bootstrap path only needs a minimal node lookup strategy, so
-this helper stays intentionally simple and deterministic.
+New split records are the durable memory that turns a one-off structural edit
+into reusable innovation history. This helper assigns the next global
+innovation ids to the replacement edges and packages those ids together with
+the new node gene id so later equivalent splits can be recognized quickly.
 
 Parameters:
-- `genomeToSearch` - - genome whose nodes are searched
-- `nodeType` - - node type to match
+- `newNode` - - newly created hidden node
+- `splitConnections` - - incoming/outgoing connections
+- `internal` - - neat controller context
 
-Returns: the first matching node or undefined
+Returns: innovation record for the split
 
-### collectEnabledConnections
+### buildSplitDescriptor
 
 ```ts
-collectEnabledConnections(
-  genomeToInspect: GenomeWithMetadata,
-): ConnectionWithMetadata[]
+buildSplitDescriptor(
+  connectionToSplit: ConnectionWithMetadata,
+): { splitKey: string; originalWeight: number; }
 ```
 
-Collect all enabled connections from a genome.
+Build the split descriptor used for innovation lookup and connection creation.
 
-Split mutations only operate on live structural edges. Disabled connections
-remain historical artifacts and should not become split candidates because
-doing so would grow new structure from topology the runtime is not currently
-using.
+The descriptor is the compact identity packet for a split. Its key captures
+which source and target genes were separated, while its preserved weight lets
+the outgoing replacement edge inherit the old signal strength.
 
 Parameters:
-- `genomeToInspect` - - genome to inspect
+- `connectionToSplit` - - connection being split
 
-Returns: enabled connections list
+Returns: split descriptor
 
 ### chooseConnectionForSplit
 
@@ -126,24 +161,51 @@ Parameters:
 
 Returns: selected connection or null
 
-### buildSplitDescriptor
+### collectEnabledConnections
 
 ```ts
-buildSplitDescriptor(
+collectEnabledConnections(
+  genomeToInspect: GenomeWithMetadata,
+): ConnectionWithMetadata[]
+```
+
+Collect all enabled connections from a genome.
+
+Split mutations only operate on live structural edges. Disabled connections
+remain historical artifacts and should not become split candidates because
+doing so would grow new structure from topology the runtime is not currently
+using.
+
+Parameters:
+- `genomeToInspect` - - genome to inspect
+
+Returns: enabled connections list
+
+### connectSplitEdges
+
+```ts
+connectSplitEdges(
+  genomeToEdit: GenomeWithMetadata,
   connectionToSplit: ConnectionWithMetadata,
-): { splitKey: string; originalWeight: number; }
+  newNode: NodeWithMetadata,
+  originalWeight: number,
+): { incomingConnection?: ConnectionWithMetadata | undefined; outgoingConnection?: ConnectionWithMetadata | undefined; }
 ```
 
-Build the split descriptor used for innovation lookup and connection creation.
+Create the incoming and outgoing split connections.
 
-The descriptor is the compact identity packet for a split. Its key captures
-which source and target genes were separated, while its preserved weight lets
-the outgoing replacement edge inherit the old signal strength.
+A split replaces one edge with two edges. The incoming edge starts with the
+chapter's default bootstrap weight, while the outgoing edge preserves the
+original connection weight so the pre-split signal can still pass forward in
+a comparable way.
 
 Parameters:
+- `genomeToEdit` - - genome being modified
 - `connectionToSplit` - - connection being split
+- `newNode` - - newly created hidden node
+- `originalWeight` - - weight to preserve on the outgoing connection
 
-Returns: split descriptor
+Returns: incoming/outgoing connection handles
 
 ### disconnectOriginalConnection
 
@@ -166,60 +228,48 @@ Parameters:
 
 Returns: void
 
-### applySplitWithExistingRecord
+### ensureBootstrapConnection
 
 ```ts
-applySplitWithExistingRecord(
-  genomeToEdit: GenomeWithMetadata,
-  connectionToSplit: ConnectionWithMetadata,
-  splitDescriptor: { splitKey: string; originalWeight: number; },
-  splitRecord: { newNodeGeneId: number; inInnov: number; outInnov: number; },
-  NodeClass: new (type: "input" | "output" | "hidden") => unknown,
+ensureBootstrapConnection(
+  genomeToSeed: GenomeWithMetadata,
+  internal: NeatControllerForMutation,
 ): void
 ```
 
-Apply a split using an existing innovation record.
+Ensure the genome has at least one connection by linking input to output.
 
-This is the preferred path when the same structural split has already been
-observed elsewhere in the population history. Reusing the stored node gene id
-and edge innovation ids preserves historical identity, which makes later
-alignment-based operations treat equivalent splits as equivalent structure.
+A connection split only makes sense when a genome already has an edge to cut.
+This helper is the bootstrap escape hatch for extremely sparse genomes. It
+seeds the smallest possible forward connection so the add-node path can keep
+behaving like a split-based structural mutation instead of bailing out
+immediately.
 
 Parameters:
-- `genomeToEdit` - - genome being modified
-- `connectionToSplit` - - connection being split
-- `splitDescriptor` - - metadata for the split
-- `splitRecord` - - existing innovation record
-- `NodeClass` - - node constructor
+- `genomeToSeed` - - genome that may need a bootstrap connection
+- `internal` - - neat controller context retained for compatibility with existing callers
 
 Returns: void
 
-### applySplitWithNewRecord
+### findFirstNodeByType
 
 ```ts
-applySplitWithNewRecord(
-  genomeToEdit: GenomeWithMetadata,
-  connectionToSplit: ConnectionWithMetadata,
-  splitDescriptor: { splitKey: string; originalWeight: number; },
-  NodeClass: new (type: "input" | "output" | "hidden") => unknown,
-  internal: NeatControllerForMutation,
-): void
+findFirstNodeByType(
+  genomeToSearch: GenomeWithMetadata,
+  nodeType: "input" | "output" | "hidden",
+): NodeWithMetadata | undefined
 ```
 
-Apply a split and create a new innovation record.
+Find the first node of a given type.
 
-This path handles genuinely novel structural growth. It inserts a fresh
-hidden node, assigns new innovations to the replacement edges, and records
-the resulting identity under the split key so future genomes can reuse it.
+The add-node bootstrap path only needs a minimal node lookup strategy, so
+this helper stays intentionally simple and deterministic.
 
 Parameters:
-- `genomeToEdit` - - genome being modified
-- `connectionToSplit` - - connection being split
-- `splitDescriptor` - - metadata for the split
-- `NodeClass` - - node constructor
-- `internal` - - neat controller context
+- `genomeToSearch` - - genome whose nodes are searched
+- `nodeType` - - node type to match
 
-Returns: void
+Returns: the first matching node or undefined
 
 ### resolveInsertIndex
 
@@ -241,53 +291,3 @@ Parameters:
 - `targetNode` - - original target node of the split connection
 
 Returns: insertion index
-
-### connectSplitEdges
-
-```ts
-connectSplitEdges(
-  genomeToEdit: GenomeWithMetadata,
-  connectionToSplit: ConnectionWithMetadata,
-  newNode: NodeWithMetadata,
-  originalWeight: number,
-): { incomingConnection?: ConnectionWithMetadata | undefined; outgoingConnection?: ConnectionWithMetadata | undefined; }
-```
-
-Create the incoming and outgoing split connections.
-
-A split replaces one edge with two edges. The incoming edge starts with the
-chapter's default bootstrap weight, while the outgoing edge preserves the
-original connection weight so the pre-split signal can still pass forward in
-a comparable way.
-
-Parameters:
-- `genomeToEdit` - - genome being modified
-- `connectionToSplit` - - connection being split
-- `newNode` - - newly created hidden node
-- `originalWeight` - - weight to preserve on the outgoing connection
-
-Returns: incoming/outgoing connection handles
-
-### assignInnovationsForNewSplit
-
-```ts
-assignInnovationsForNewSplit(
-  newNode: NodeWithMetadata,
-  splitConnections: { incomingConnection?: ConnectionWithMetadata | undefined; outgoingConnection?: ConnectionWithMetadata | undefined; },
-  internal: NeatControllerForMutation,
-): { newNodeGeneId: number; inInnov: number; outInnov: number; }
-```
-
-Assign new innovations for a split and build the innovation record.
-
-New split records are the durable memory that turns a one-off structural edit
-into reusable innovation history. This helper assigns the next global
-innovation ids to the replacement edges and packages those ids together with
-the new node gene id so later equivalent splits can be recognized quickly.
-
-Parameters:
-- `newNode` - - newly created hidden node
-- `splitConnections` - - incoming/outgoing connections
-- `internal` - - neat controller context
-
-Returns: innovation record for the split