@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/architecture/layer/README.md

@@ -374,38 +374,6 @@ const activationContext: LayerActivationContext = {
 // activateLayer(activationContext, values, true)
 ```
 
-### LayerPropagationContext
-
-Minimal state required to run backpropagation helpers.
-
-Helpers only need access to the node sequence to propagate in reverse order.
-
-Example:
-
-```ts
-const propagationContext: LayerPropagationContext = { nodes: layer.nodes };
-
-// propagateLayer(propagationContext, 0.3, 0.1, targets)
-```
-
-### LayerLike
-
-Structural contract for "layer-like" objects used in utility wiring.
-
-This type avoids direct class coupling while preserving the behaviors needed
-by connection helpers (`input`, `nodes`, and `output`).
-
-Example:
-
-```ts
-// A real layer class typically satisfies this shape.
-const layerLike: LayerLike = {
-  input: (from) => [],
-  nodes: [],
-  output: null,
-};
-```
-
 ### LayerConnectionContext
 
 Context bundle required by connection/disconnection orchestration.
@@ -426,6 +394,23 @@ const connectionContext: LayerConnectionContext = {
 };
 ```
 
+### LayerFactoryContext
+
+Generic factory context used to create layers without circular imports.
+
+`createLayer` builds the target instance, and `isLayer` enables structural
+narrowing whenever helpers accept mixed layer/group values.
+
+Example:
+
+```ts
+const factoryContext: LayerFactoryContext<MyLayer> = {
+  createLayer: () => new MyLayer(),
+  isLayer: (value): value is LayerLike =>
+    !!value && typeof (value as LayerLike).input === 'function',
+};
+```
+
 ### LayerFactoryLayer
 
 Public layer surface required by factory construction helpers.
@@ -439,23 +424,38 @@ Example:
 // (Concrete layer classes typically provide many more helpers.)
 ```
 
-### LayerFactoryContext
+### LayerLike
 
-Generic factory context used to create layers without circular imports.
+Structural contract for "layer-like" objects used in utility wiring.
 
-`createLayer` builds the target instance, and `isLayer` enables structural
-narrowing whenever helpers accept mixed layer/group values.
+This type avoids direct class coupling while preserving the behaviors needed
+by connection helpers (`input`, `nodes`, and `output`).
 
 Example:
 
 ```ts
-const factoryContext: LayerFactoryContext<MyLayer> = {
-  createLayer: () => new MyLayer(),
-  isLayer: (value): value is LayerLike =>
-    !!value && typeof (value as LayerLike).input === 'function',
+// A real layer class typically satisfies this shape.
+const layerLike: LayerLike = {
+  input: (from) => [],
+  nodes: [],
+  output: null,
 };
 ```
 
+### LayerPropagationContext
+
+Minimal state required to run backpropagation helpers.
+
+Helpers only need access to the node sequence to propagate in reverse order.
+
+Example:
+
+```ts
+const propagationContext: LayerPropagationContext = { nodes: layer.nodes };
+
+// propagateLayer(propagationContext, 0.3, 0.1, targets)
+```
+
 ## architecture/layer/layer.utils.ts
 
 ### activateLayer
@@ -498,38 +498,24 @@ Parameters:
 
 Returns: A cloned array of activation values.
 
-### propagateLayer
+### clearLayer
 
 ```ts
-propagateLayer(
-  context: LayerPropagationContext,
-  rate: number,
-  momentum: number,
-  targets: number[] | undefined,
+clearLayer(
+  context: LayerConnectionContext,
 ): void
 ```
 
-Orchestrates layer backpropagation behavior with a high-level flow.
-
-If `targets` is provided, it must be one value per node (output layer).
-If omitted, propagation behaves like a hidden layer.
+Orchestrates clearing node activation state with a high-level flow.
 
-Examples:
+Parameters:
+- `context` - - The layer state needed to reset nodes.
+Example:
 
 ```ts
-// Hidden layer propagation.
-propagateLayer({ nodes: layer.nodes }, 0.3, 0.1);
-
-// Output layer propagation.
-propagateLayer({ nodes: layer.nodes }, 0.3, 0.1, [1, 0, 0]);
+clearLayer(layerConnectionContext);
 ```
 
-Parameters:
-- `context` - - The layer state needed for propagation.
-- `rate` - - The learning rate for weight updates.
-- `momentum` - - The momentum factor for smoothing updates.
-- `targets` - - Optional target values for output layers.
-
 ### connectLayer
 
 ```ts
@@ -560,161 +546,166 @@ Parameters:
 
 Returns: The created connection list.
 
-### gateLayer
+### createAttentionLayer
 
 ```ts
-gateLayer(
-  context: LayerConnectionContext,
-  connections: default[],
-  method: unknown,
-): void
+createAttentionLayer(
+  context: LayerFactoryContext<TLayer>,
+  size: number,
+  heads: number,
+): TLayer
 ```
 
-Orchestrates layer gating behavior with a high-level flow.
+Orchestrates attention layer creation with a high-level flow.
+
+Parameters:
+- `context` - - Factory helpers for constructing the layer instance.
+- `size` - - Number of output nodes.
+- `heads` - - Number of attention heads.
 
+Returns: The configured layer instance.
 Example:
 
 ```ts
-gateLayer(layerConnectionContext, someConnections, method);
+const attention = createAttentionLayer(factoryContext, 8, 4);
 ```
 
-Parameters:
-- `context` - - The layer state needed for gating.
-- `connections` - - The connections to gate.
-- `method` - - The gating method.
-
-### inputLayer
+### createBatchNormLayer
 
 ```ts
-inputLayer(
-  context: LayerConnectionContext,
-  from: default | LayerLike,
-  method: unknown,
-  weight: number | undefined,
-): default[]
+createBatchNormLayer(
+  context: LayerFactoryContext<TLayer>,
+  size: number,
+): TLayer
 ```
 
-Orchestrates layer input wiring with a high-level flow.
+Orchestrates batch normalization layer creation with a high-level flow.
+
+Parameters:
+- `context` - - Factory helpers for constructing the layer instance.
+- `size` - - Number of nodes in the normalization layer.
 
+Returns: The configured layer instance.
 Example:
 
 ```ts
-inputLayer(layerConnectionContext, previousLayerLike);
+const batchNorm = createBatchNormLayer(factoryContext, 16);
 ```
 
-Parameters:
-- `context` - - The layer state needed for input wiring.
-- `from` - - The source layer or group.
-- `method` - - Optional connection method override.
-- `weight` - - Optional fixed weight to apply.
-
-Returns: The created connection list.
-
-### disconnectLayer
+### createConv1dLayer
 
 ```ts
-disconnectLayer(
-  context: LayerConnectionContext,
-  target: default | default,
-  twoSided: boolean,
-): void
+createConv1dLayer(
+  context: LayerFactoryContext<TLayer>,
+  size: number,
+  kernelSize: number,
+  stride: number,
+  padding: number,
+): TLayer
 ```
 
-Orchestrates disconnection behavior with a high-level flow.
+Orchestrates 1D convolution layer creation with a high-level flow.
+
+Parameters:
+- `context` - - Factory helpers for constructing the layer instance.
+- `size` - - Number of output nodes.
+- `kernelSize` - - Size of the convolution kernel.
+- `stride` - - Stride of the convolution.
+- `padding` - - Padding size for the convolution.
 
+Returns: The configured layer instance.
 Example:
 
 ```ts
-disconnectLayer(layerConnectionContext, someGroup, true);
+const conv1d = createConv1dLayer(factoryContext, 8, 3);
 ```
 
-Parameters:
-- `context` - - The layer state needed for disconnecting.
-- `target` - - The group or node to disconnect.
-- `twoSided` - - Whether to remove reciprocal connections as well.
-
-### clearLayer
+### createDenseLayer
 
 ```ts
-clearLayer(
-  context: LayerConnectionContext,
-): void
+createDenseLayer(
+  context: LayerFactoryContext<TLayer>,
+  size: number,
+): TLayer
 ```
 
-Orchestrates clearing node activation state with a high-level flow.
+Orchestrates dense layer creation with a high-level flow.
 
 Parameters:
-- `context` - - The layer state needed to reset nodes.
+- `context` - - Factory helpers for constructing the layer instance.
+- `size` - - Number of nodes in the dense layer.
+
+Returns: The configured layer instance.
 Example:
 
 ```ts
-clearLayer(layerConnectionContext);
+const dense = createDenseLayer(factoryContext, 8);
 ```
 
-### createDenseLayer
+### createGruLayer
 
 ```ts
-createDenseLayer(
+createGruLayer(
   context: LayerFactoryContext<TLayer>,
   size: number,
 ): TLayer
 ```
 
-Orchestrates dense layer creation with a high-level flow.
+Orchestrates GRU layer creation with a high-level flow.
 
 Parameters:
 - `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of nodes in the dense layer.
+- `size` - - Number of units in the GRU layer.
 
 Returns: The configured layer instance.
 Example:
 
 ```ts
-const dense = createDenseLayer(factoryContext, 8);
+const gru = createGruLayer(factoryContext, 8);
 ```
 
-### createLstmLayer
+### createLayerNormLayer
 
 ```ts
-createLstmLayer(
+createLayerNormLayer(
   context: LayerFactoryContext<TLayer>,
   size: number,
 ): TLayer
 ```
 
-Orchestrates LSTM layer creation with a high-level flow.
+Orchestrates layer normalization layer creation with a high-level flow.
 
 Parameters:
 - `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of units in the LSTM layer.
+- `size` - - Number of nodes in the normalization layer.
 
 Returns: The configured layer instance.
 Example:
 
 ```ts
-const lstm = createLstmLayer(factoryContext, 8);
+const layerNorm = createLayerNormLayer(factoryContext, 16);
 ```
 
-### createGruLayer
+### createLstmLayer
 
 ```ts
-createGruLayer(
+createLstmLayer(
   context: LayerFactoryContext<TLayer>,
   size: number,
 ): TLayer
 ```
 
-Orchestrates GRU layer creation with a high-level flow.
+Orchestrates LSTM layer creation with a high-level flow.
 
 Parameters:
 - `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of units in the GRU layer.
+- `size` - - Number of units in the LSTM layer.
 
 Returns: The configured layer instance.
 Example:
 
 ```ts
-const gru = createGruLayer(factoryContext, 8);
+const lstm = createLstmLayer(factoryContext, 8);
 ```
 
 ### createMemoryLayer
@@ -741,102 +732,111 @@ Example:
 const memoryLayer = createMemoryLayer(factoryContext, 4, 3);
 ```
 
-### createBatchNormLayer
+### disconnectLayer
 
 ```ts
-createBatchNormLayer(
-  context: LayerFactoryContext<TLayer>,
-  size: number,
-): TLayer
+disconnectLayer(
+  context: LayerConnectionContext,
+  target: default | default,
+  twoSided: boolean,
+): void
 ```
 
-Orchestrates batch normalization layer creation with a high-level flow.
-
-Parameters:
-- `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of nodes in the normalization layer.
+Orchestrates disconnection behavior with a high-level flow.
 
-Returns: The configured layer instance.
 Example:
 
 ```ts
-const batchNorm = createBatchNormLayer(factoryContext, 16);
+disconnectLayer(layerConnectionContext, someGroup, true);
 ```
 
-### createLayerNormLayer
+Parameters:
+- `context` - - The layer state needed for disconnecting.
+- `target` - - The group or node to disconnect.
+- `twoSided` - - Whether to remove reciprocal connections as well.
+
+### gateLayer
 
 ```ts
-createLayerNormLayer(
-  context: LayerFactoryContext<TLayer>,
-  size: number,
-): TLayer
+gateLayer(
+  context: LayerConnectionContext,
+  connections: default[],
+  method: unknown,
+): void
 ```
 
-Orchestrates layer normalization layer creation with a high-level flow.
-
-Parameters:
-- `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of nodes in the normalization layer.
+Orchestrates layer gating behavior with a high-level flow.
 
-Returns: The configured layer instance.
 Example:
 
 ```ts
-const layerNorm = createLayerNormLayer(factoryContext, 16);
+gateLayer(layerConnectionContext, someConnections, method);
 ```
 
-### createConv1dLayer
+Parameters:
+- `context` - - The layer state needed for gating.
+- `connections` - - The connections to gate.
+- `method` - - The gating method.
+
+### inputLayer
 
 ```ts
-createConv1dLayer(
-  context: LayerFactoryContext<TLayer>,
-  size: number,
-  kernelSize: number,
-  stride: number,
-  padding: number,
-): TLayer
+inputLayer(
+  context: LayerConnectionContext,
+  from: default | LayerLike,
+  method: unknown,
+  weight: number | undefined,
+): default[]
 ```
 
-Orchestrates 1D convolution layer creation with a high-level flow.
-
-Parameters:
-- `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of output nodes.
-- `kernelSize` - - Size of the convolution kernel.
-- `stride` - - Stride of the convolution.
-- `padding` - - Padding size for the convolution.
+Orchestrates layer input wiring with a high-level flow.
 
-Returns: The configured layer instance.
 Example:
 
 ```ts
-const conv1d = createConv1dLayer(factoryContext, 8, 3);
+inputLayer(layerConnectionContext, previousLayerLike);
 ```
 
-### createAttentionLayer
+Parameters:
+- `context` - - The layer state needed for input wiring.
+- `from` - - The source layer or group.
+- `method` - - Optional connection method override.
+- `weight` - - Optional fixed weight to apply.
+
+Returns: The created connection list.
+
+### propagateLayer
 
 ```ts
-createAttentionLayer(
-  context: LayerFactoryContext<TLayer>,
-  size: number,
-  heads: number,
-): TLayer
+propagateLayer(
+  context: LayerPropagationContext,
+  rate: number,
+  momentum: number,
+  targets: number[] | undefined,
+): void
 ```
 
-Orchestrates attention layer creation with a high-level flow.
+Orchestrates layer backpropagation behavior with a high-level flow.
 
-Parameters:
-- `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of output nodes.
-- `heads` - - Number of attention heads.
+If `targets` is provided, it must be one value per node (output layer).
+If omitted, propagation behaves like a hidden layer.
 
-Returns: The configured layer instance.
-Example:
+Examples:
 
 ```ts
-const attention = createAttentionLayer(factoryContext, 8, 4);
+// Hidden layer propagation.
+propagateLayer({ nodes: layer.nodes }, 0.3, 0.1);
+
+// Output layer propagation.
+propagateLayer({ nodes: layer.nodes }, 0.3, 0.1, [1, 0, 0]);
 ```
 
+Parameters:
+- `context` - - The layer state needed for propagation.
+- `rate` - - The learning rate for weight updates.
+- `momentum` - - The momentum factor for smoothing updates.
+- `targets` - - Optional target values for output layers.
+
 ## architecture/layer/layer.guard.utils.ts
 
 ### isGroup
@@ -867,6 +867,61 @@ value.set({ bias: 0 });
 
 ## architecture/layer/layer.activation.utils.ts
 
+### acquireActivationOutput
+
+```ts
+acquireActivationOutput(
+  nodeCount: number,
+): number[]
+```
+
+Acquires a pooled output buffer sized for the current activation call.
+
+Pooling avoids frequent temporary allocations in hot activation paths.
+
+The returned array is owned by the pool. Treat it as **temporary**:
+- Fill it.
+- Clone it (if you need a stable output).
+- Release it back to the pool.
+
+Example (typical pattern):
+
+```ts
+const pooled = acquireActivationOutput(nodes.length);
+fillActivationOutput(nodes, values, pooled);
+const output = cloneActivationOutput(pooled);
+releaseActivationOutput(pooled);
+```
+
+Parameters:
+- `nodeCount` - - Number of nodes in the layer.
+
+Returns: A pooled output array.
+
+### applyLayerMask
+
+```ts
+applyLayerMask(
+  nodeList: default[],
+  mask: number,
+): void
+```
+
+Applies one mask value to every node in the layer.
+
+In this library, a node-level `mask` is used as a lightweight dropout control.
+A mask of `0` effectively disables the node for the current activation step.
+
+Example:
+
+```ts
+applyLayerMask(layer.nodes, 1);
+```
+
+Parameters:
+- `nodeList` - - The layer nodes to update.
+- `mask` - - The mask value to apply.
+
 ### assertActivationInputSize
 
 ```ts
@@ -903,94 +958,59 @@ Parameters:
 - `nodeCount` - - Number of nodes in the layer.
 - `inputValues` - - Optional activation values provided by the caller.
 
-### resolveLayerMask
+### cloneActivationOutput
 
 ```ts
-resolveLayerMask(
-  layerDropout: number,
-  isTraining: boolean,
-): number
+cloneActivationOutput(
+  output: number[],
+): number[]
 ```
 
-Resolves a shared dropout mask for the full layer.
-
-In this layer-level dropout model, all nodes receive the same mask per call,
-which keeps activation behavior synchronized for grouped layer semantics.
+Clones pooled output into a stable caller-owned array.
 
-Notes:
-- Dropout is only applied when `isTraining` is true.
-- A return value of `1` means "keep" and `0` means "drop".
-- This helper intentionally does **not** rescale activations (some dropout
-  implementations divide by $(1 - p)$ during training). In this codebase the
-  mask is a simple on/off switch.
+This is the "escape hatch" that turns a pooled scratch buffer into a normal
+array you can safely return from APIs.
 
 Example:
 
 ```ts
-resolveLayerMask(0.5, false); // => 1 (dropout disabled)
-resolveLayerMask(0.5, true); // => 0 or 1
+const stable = cloneActivationOutput(pooled);
 ```
 
 Parameters:
-- `layerDropout` - - The dropout rate configured for the layer.
-- `isTraining` - - Whether the layer is running in training mode.
+- `output` - - The pooled output array to clone.
 
-Returns: A mask value of 1 or 0 for all nodes in the layer.
+Returns: A cloned output array.
 
-### applyLayerMask
+### fillActivationOutput
 
 ```ts
-applyLayerMask(
+fillActivationOutput(
   nodeList: default[],
-  mask: number,
+  inputValues: number[] | undefined,
+  output: number[],
 ): void
 ```
 
-Applies one mask value to every node in the layer.
-
-In this library, a node-level `mask` is used as a lightweight dropout control.
-A mask of `0` effectively disables the node for the current activation step.
-
-Example:
-
-```ts
-applyLayerMask(layer.nodes, 1);
-```
-
-Parameters:
-- `nodeList` - - The layer nodes to update.
-- `mask` - - The mask value to apply.
-
-### acquireActivationOutput
-
-```ts
-acquireActivationOutput(
-  nodeCount: number,
-): number[]
-```
-
-Acquires a pooled output buffer sized for the current activation call.
+Activates each node and writes outputs into the provided buffer.
 
-Pooling avoids frequent temporary allocations in hot activation paths.
+When `inputValues` is provided, each node receives the corresponding input
+value. Otherwise each node self-activates from incoming state.
 
-The returned array is owned by the pool. Treat it as **temporary**:
-- Fill it.
-- Clone it (if you need a stable output).
-- Release it back to the pool.
+This function is deliberately low-level: it does not allocate and it does not
+return anything. That makes it ideal for hot paths where you want to reuse a
+buffer (typically a pooled one).
 
-Example (typical pattern):
+Example:
 
 ```ts
-const pooled = acquireActivationOutput(nodes.length);
-fillActivationOutput(nodes, values, pooled);
-const output = cloneActivationOutput(pooled);
-releaseActivationOutput(pooled);
+fillActivationOutput(layer.nodes, [0.2, 0.4], pooled);
 ```
 
 Parameters:
-- `nodeCount` - - Number of nodes in the layer.
-
-Returns: A pooled output array.
+- `nodeList` - - Nodes to activate.
+- `inputValues` - - Optional activation values for each node.
+- `output` - - Output buffer to populate.
 
 ### releaseActivationOutput
 
@@ -1009,61 +1029,63 @@ Important: do not keep using `output` after releasing it.
 Parameters:
 - `output` - - The pooled output array to release.
 
-### cloneActivationOutput
+### resolveLayerMask
 
 ```ts
-cloneActivationOutput(
-  output: number[],
-): number[]
+resolveLayerMask(
+  layerDropout: number,
+  isTraining: boolean,
+): number
 ```
 
-Clones pooled output into a stable caller-owned array.
+Resolves a shared dropout mask for the full layer.
 
-This is the "escape hatch" that turns a pooled scratch buffer into a normal
-array you can safely return from APIs.
+In this layer-level dropout model, all nodes receive the same mask per call,
+which keeps activation behavior synchronized for grouped layer semantics.
+
+Notes:
+- Dropout is only applied when `isTraining` is true.
+- A return value of `1` means "keep" and `0` means "drop".
+- This helper intentionally does **not** rescale activations (some dropout
+  implementations divide by $(1 - p)$ during training). In this codebase the
+  mask is a simple on/off switch.
 
 Example:
 
 ```ts
-const stable = cloneActivationOutput(pooled);
+resolveLayerMask(0.5, false); // => 1 (dropout disabled)
+resolveLayerMask(0.5, true); // => 0 or 1
 ```
 
 Parameters:
-- `output` - - The pooled output array to clone.
+- `layerDropout` - - The dropout rate configured for the layer.
+- `isTraining` - - Whether the layer is running in training mode.
 
-Returns: A cloned output array.
+Returns: A mask value of 1 or 0 for all nodes in the layer.
 
-### fillActivationOutput
+## architecture/layer/layer.connection.utils.ts
+
+### clearLayer
 
 ```ts
-fillActivationOutput(
-  nodeList: default[],
-  inputValues: number[] | undefined,
-  output: number[],
+clearLayer(
+  context: LayerConnectionContext,
 ): void
 ```
 
-Activates each node and writes outputs into the provided buffer.
-
-When `inputValues` is provided, each node receives the corresponding input
-value. Otherwise each node self-activates from incoming state.
+Clears activation state for all nodes in a layer.
 
-This function is deliberately low-level: it does not allocate and it does not
-return anything. That makes it ideal for hot paths where you want to reuse a
-buffer (typically a pooled one).
+Use this when you want to reset per-node transient state between runs
+(especially helpful in recurrent networks that keep state across timesteps).
 
 Example:
 
 ```ts
-fillActivationOutput(layer.nodes, [0.2, 0.4], pooled);
+clearLayer(layerContext);
 ```
 
 Parameters:
-- `nodeList` - - Nodes to activate.
-- `inputValues` - - Optional activation values for each node.
-- `output` - - Output buffer to populate.
-
-## architecture/layer/layer.connection.utils.ts
+- `context` - - The layer state needed to reset nodes.
 
 ### connectLayer
 
@@ -1104,6 +1126,74 @@ Parameters:
 
 Returns: The created connection list.
 
+### disconnectFromGroup
+
+```ts
+disconnectFromGroup(
+  layerNodes: default[],
+  targetGroup: default,
+  layerConnections: { in: default[]; out: default[]; self: default[]; },
+  removeTwoSided: boolean,
+): void
+```
+
+Disconnects all layer nodes from a target group.
+
+This is a "cartesian disconnect": every node in this layer is disconnected
+from every node in the target group.
+
+Parameters:
+- `layerNodes` - - Nodes in the layer.
+- `targetGroup` - - Group to disconnect from.
+- `layerConnections` - - Connection tracking for the layer.
+- `removeTwoSided` - - Whether to remove reciprocal connections as well.
+
+### disconnectFromNode
+
+```ts
+disconnectFromNode(
+  layerNodes: default[],
+  targetNode: default,
+  layerConnections: { in: default[]; out: default[]; self: default[]; },
+  removeTwoSided: boolean,
+): void
+```
+
+Disconnects all layer nodes from a target node.
+
+Parameters:
+- `layerNodes` - - Nodes in the layer.
+- `targetNode` - - Node to disconnect from.
+- `layerConnections` - - Connection tracking for the layer.
+- `removeTwoSided` - - Whether to remove reciprocal connections as well.
+
+### disconnectLayer
+
+```ts
+disconnectLayer(
+  context: LayerConnectionContext,
+  target: default | default,
+  twoSided: boolean,
+): void
+```
+
+Disconnects nodes in this layer from a target group or node.
+
+This iterates through this layer's nodes and calls `node.disconnect(...)`.
+It also updates the layer's tracked `connections.in/out` arrays so they
+remain consistent with the underlying node graph.
+
+Example:
+
+```ts
+disconnectLayer(layerContext, someNode, false);
+```
+
+Parameters:
+- `context` - - The layer state needed for disconnecting.
+- `target` - - The group or node to disconnect.
+- `twoSided` - - Whether to remove reciprocal connections as well.
+
 ### gateLayer
 
 ```ts
@@ -1171,85 +1261,17 @@ Parameters:
 
 Returns: The created connection list.
 
-### disconnectLayer
-
-```ts
-disconnectLayer(
-  context: LayerConnectionContext,
-  target: default | default,
-  twoSided: boolean,
-): void
-```
-
-Disconnects nodes in this layer from a target group or node.
-
-This iterates through this layer's nodes and calls `node.disconnect(...)`.
-It also updates the layer's tracked `connections.in/out` arrays so they
-remain consistent with the underlying node graph.
-
-Example:
-
-```ts
-disconnectLayer(layerContext, someNode, false);
-```
-
-Parameters:
-- `context` - - The layer state needed for disconnecting.
-- `target` - - The group or node to disconnect.
-- `twoSided` - - Whether to remove reciprocal connections as well.
-
-### disconnectFromGroup
-
-```ts
-disconnectFromGroup(
-  layerNodes: default[],
-  targetGroup: default,
-  layerConnections: { in: default[]; out: default[]; self: default[]; },
-  removeTwoSided: boolean,
-): void
-```
-
-Disconnects all layer nodes from a target group.
-
-This is a "cartesian disconnect": every node in this layer is disconnected
-from every node in the target group.
-
-Parameters:
-- `layerNodes` - - Nodes in the layer.
-- `targetGroup` - - Group to disconnect from.
-- `layerConnections` - - Connection tracking for the layer.
-- `removeTwoSided` - - Whether to remove reciprocal connections as well.
-
-### disconnectFromNode
-
-```ts
-disconnectFromNode(
-  layerNodes: default[],
-  targetNode: default,
-  layerConnections: { in: default[]; out: default[]; self: default[]; },
-  removeTwoSided: boolean,
-): void
-```
-
-Disconnects all layer nodes from a target node.
-
-Parameters:
-- `layerNodes` - - Nodes in the layer.
-- `targetNode` - - Node to disconnect from.
-- `layerConnections` - - Connection tracking for the layer.
-- `removeTwoSided` - - Whether to remove reciprocal connections as well.
-
-### removeOutgoingConnection
+### removeIncomingConnection
 
 ```ts
-removeOutgoingConnection(
+removeIncomingConnection(
   layerConnections: { in: default[]; out: default[]; self: default[]; },
   sourceNode: default,
   targetNode: default,
 ): void
 ```
 
-Removes an outgoing connection from layer tracking.
+Removes an incoming connection from layer tracking.
 
 This scans in reverse so we can `splice(...)` safely while iterating.
 
@@ -1258,17 +1280,17 @@ Parameters:
 - `sourceNode` - - Source node for the connection.
 - `targetNode` - - Target node for the connection.
 
-### removeIncomingConnection
+### removeOutgoingConnection
 
 ```ts
-removeIncomingConnection(
+removeOutgoingConnection(
   layerConnections: { in: default[]; out: default[]; self: default[]; },
   sourceNode: default,
   targetNode: default,
 ): void
 ```
 
-Removes an incoming connection from layer tracking.
+Removes an outgoing connection from layer tracking.
 
 This scans in reverse so we can `splice(...)` safely while iterating.
 
@@ -1277,28 +1299,6 @@ Parameters:
 - `sourceNode` - - Source node for the connection.
 - `targetNode` - - Target node for the connection.
 
-### clearLayer
-
-```ts
-clearLayer(
-  context: LayerConnectionContext,
-): void
-```
-
-Clears activation state for all nodes in a layer.
-
-Use this when you want to reset per-node transient state between runs
-(especially helpful in recurrent networks that keep state across timesteps).
-
-Example:
-
-```ts
-clearLayer(layerContext);
-```
-
-Parameters:
-- `context` - - The layer state needed to reset nodes.
-
 ## architecture/layer/layer.propagation.utils.ts
 
 ### assertTargetInputSize
@@ -1404,68 +1404,68 @@ dense.input(previousLayerLike);
 
 ## architecture/layer/layer.factory.recurrent.utils.ts
 
-### buildLstmLayer
+### buildGruLayer
 
 ```ts
-buildLstmLayer(
+buildGruLayer(
   context: LayerFactoryContext<TLayer>,
   size: number,
 ): TLayer
 ```
 
-Builds an LSTM layer using the provided factory context.
+Builds a GRU layer using the provided factory context.
 
 Educational overview:
-- **Gates** control information flow (input / forget / output).
-- The **memory cell** stores recurrent state via a self-connection.
-- The **output block** is what this layer exposes as `layer.output`.
-
-This builder wires the classic LSTM topology using `Group` blocks and gating.
-It returns a layer object that is compatible with the rest of the layer
-utilities (`layer.input(...)`, `layer.activate(...)`, `layer.output`, etc.).
+- GRU is a gated recurrent unit with fewer gates than LSTM.
+- This implementation wires update/reset gates and a memory cell, then
+exposes a standard `layer.output` group.
 
 Parameters:
 - `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of units in each LSTM gate and cell.
+- `size` - - Number of units in each GRU gate and cell.
 
 Returns: The configured layer instance.
 
 Example:
 
 ```ts
-const lstm = buildLstmLayer(factoryContext, 8);
-
-// Wire a previous layer (or Group) into the LSTM.
-lstm.input(previousLayerLike);
+const gru = buildGruLayer(factoryContext, 8);
+gru.input(previousLayerLike);
 ```
 
-### buildGruLayer
+### buildLstmLayer
 
 ```ts
-buildGruLayer(
+buildLstmLayer(
   context: LayerFactoryContext<TLayer>,
   size: number,
 ): TLayer
 ```
 
-Builds a GRU layer using the provided factory context.
+Builds an LSTM layer using the provided factory context.
 
 Educational overview:
-- GRU is a gated recurrent unit with fewer gates than LSTM.
-- This implementation wires update/reset gates and a memory cell, then
-exposes a standard `layer.output` group.
+- **Gates** control information flow (input / forget / output).
+- The **memory cell** stores recurrent state via a self-connection.
+- The **output block** is what this layer exposes as `layer.output`.
+
+This builder wires the classic LSTM topology using `Group` blocks and gating.
+It returns a layer object that is compatible with the rest of the layer
+utilities (`layer.input(...)`, `layer.activate(...)`, `layer.output`, etc.).
 
 Parameters:
 - `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of units in each GRU gate and cell.
+- `size` - - Number of units in each LSTM gate and cell.
 
 Returns: The configured layer instance.
 
 Example:
 
 ```ts
-const gru = buildGruLayer(factoryContext, 8);
-gru.input(previousLayerLike);
+const lstm = buildLstmLayer(factoryContext, 8);
+
+// Wire a previous layer (or Group) into the LSTM.
+lstm.input(previousLayerLike);
 ```
 
 ### buildMemoryLayer
@@ -1502,30 +1502,28 @@ const memoryLayer = buildMemoryLayer(factoryContext, 4, 3);
 memoryLayer.input(previousLayerLike);
 ```
 
-### resolveSourceGroup
+### flattenConnections
 
 ```ts
-resolveSourceGroup(
-  factoryContext: LayerFactoryContext<TLayer>,
-  from: default | LayerLike,
-): default
+flattenConnections(
+  connectionLists: default[][],
+): default[]
 ```
 
-Resolves a source group from a layer-like or group input.
+Flattens grouped connection arrays into a single list.
 
-Many wiring helpers accept either a `Group` or a "layer-like" object.
-When a layer is provided, we treat `layer.output` as the actual source group.
+This keeps builder code declarative: build connections per gate/block,
+then flatten once at the end.
 
 Parameters:
-- `factoryContext` - - Factory context providing layer guards.
-- `from` - - Source input candidate.
+- `connectionLists` - - Connection groups to flatten.
 
-Returns: Source group used for connections.
+Returns: Flattened connection list.
 
 Example:
 
 ```ts
-const sourceGroup = resolveSourceGroup(factoryContext, previousLayerLike);
+const connections = flattenConnections([gateConnections, cellConnections]);
 ```
 
 ### resolveConnectionMethod
@@ -1552,70 +1550,56 @@ Example:
 const method = resolveConnectionMethod(undefined);
 ```
 
-### flattenConnections
+### resolveSourceGroup
 
 ```ts
-flattenConnections(
-  connectionLists: default[][],
-): default[]
+resolveSourceGroup(
+  factoryContext: LayerFactoryContext<TLayer>,
+  from: default | LayerLike,
+): default
 ```
 
-Flattens grouped connection arrays into a single list.
+Resolves a source group from a layer-like or group input.
 
-This keeps builder code declarative: build connections per gate/block,
-then flatten once at the end.
+Many wiring helpers accept either a `Group` or a "layer-like" object.
+When a layer is provided, we treat `layer.output` as the actual source group.
 
 Parameters:
-- `connectionLists` - - Connection groups to flatten.
+- `factoryContext` - - Factory context providing layer guards.
+- `from` - - Source input candidate.
 
-Returns: Flattened connection list.
+Returns: Source group used for connections.
 
 Example:
 
 ```ts
-const connections = flattenConnections([gateConnections, cellConnections]);
+const sourceGroup = resolveSourceGroup(factoryContext, previousLayerLike);
 ```
 
 ## architecture/layer/layer.factory.experimental.utils.ts
 
-### buildConv1dLayer
+### activateStubNodes
 
 ```ts
-buildConv1dLayer(
-  context: LayerFactoryContext<TLayer>,
-  size: number,
-  kernelSize: number,
-  stride: number,
-  padding: number,
-): TLayer
+activateStubNodes(
+  layer: TLayer,
+): number[]
 ```
 
-Builds a lightweight Conv1D-style stub layer.
-
-This is an experimental placeholder: it stores Conv1D metadata and returns
-either activated node outputs (no input values) or a bounded slice from
-provided values. It does not perform real convolution math.
+Activates all nodes in a stub layer and returns their outputs.
 
-Educational note: this is designed as an integration seam. It lets you
-prototype graphs that *mention* Conv1D without requiring a full convolution
-implementation yet.
+This helper keeps fallback activation behavior identical across experimental
+layer variants.
 
 Parameters:
-- `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of output nodes (filters).
-- `kernelSize` - - Size of the convolution kernel.
-- `stride` - - Stride of the convolution.
-- `padding` - - Padding size for the convolution.
+- `layer` - - Layer containing nodes to activate.
 
-Returns: The configured layer instance.
+Returns: Activated node outputs.
 
 Example:
 
 ```ts
-const conv = buildConv1dLayer(factoryContext, 8, 3, 1, 1);
-
-// When called with values, the stub returns a slice (not a true convolution).
-const out = conv.activate([10, 11, 12, 13]);
+const outputs = activateStubNodes(layer);
 ```
 
 ### buildAttentionLayer
@@ -1653,116 +1637,160 @@ const out = attention.activate([1, 2, 3, 4]);
 // out is length 8, every entry is the average (2.5)
 ```
 
-### createStubLayer
+### buildConv1dLayer
 
 ```ts
-createStubLayer(
+buildConv1dLayer(
   context: LayerFactoryContext<TLayer>,
   size: number,
+  kernelSize: number,
+  stride: number,
+  padding: number,
 ): TLayer
 ```
 
-Creates shared node/output scaffolding for experimental layers.
+Builds a lightweight Conv1D-style stub layer.
 
-Centralizing this setup keeps the experimental builders focused on their
-metadata and activation behavior.
+This is an experimental placeholder: it stores Conv1D metadata and returns
+either activated node outputs (no input values) or a bounded slice from
+provided values. It does not perform real convolution math.
 
-Implementation detail: the returned layer contains a `nodes` list (for basic
-activation) and an `output` group (for API compatibility with the rest of the
-architecture). In these stubs, the output group is not intended to be a fully
-wired projection of `nodes`.
+Educational note: this is designed as an integration seam. It lets you
+prototype graphs that *mention* Conv1D without requiring a full convolution
+implementation yet.
 
 Parameters:
 - `context` - - Factory helpers for constructing the layer instance.
-- `size` - - Number of output nodes to allocate.
+- `size` - - Number of output nodes (filters).
+- `kernelSize` - - Size of the convolution kernel.
+- `stride` - - Stride of the convolution.
+- `padding` - - Padding size for the convolution.
 
-Returns: Initialized experimental layer.
+Returns: The configured layer instance.
 
-### createConv1dActivator
+Example:
 
 ```ts
-createConv1dActivator(
+const conv = buildConv1dLayer(factoryContext, 8, 3, 1, 1);
+
+// When called with values, the stub returns a slice (not a true convolution).
+const out = conv.activate([10, 11, 12, 13]);
+```
+
+### createAttentionActivator
+
+```ts
+createAttentionActivator(
   layer: TLayer,
   size: number,
 ): (values?: number[] | undefined) => number[]
 ```
 
-Builds the activation function used by the Conv1D stub.
+Builds the activation function used by the attention stub.
 
-When values are provided, this function returns a length-bounded slice.
+When values are provided, all outputs are filled with their average.
 When values are omitted, it delegates to node activation.
 
-This keeps the call signature compatible with real layers while remaining
-intentionally cheap.
+This behavior is *not* meant to represent real attention math; it simply
+produces a stable, shape-correct output while attention internals evolve.
 
 Parameters:
 - `layer` - - Layer whose nodes can self-activate.
 - `size` - - Number of output values to return.
 
-Returns: Activation callback for Conv1D behavior.
+Returns: Activation callback for attention behavior.
 
 Example:
 
 ```ts
-const activate = createConv1dActivator(layer, 3);
-activate([9, 8, 7, 6]); // -> [9, 8, 7]
+const activate = createAttentionActivator(layer, 4);
+activate([1, 3]); // -> [2, 2, 2, 2]
 ```
 
-### createAttentionActivator
+### createConv1dActivator
 
 ```ts
-createAttentionActivator(
+createConv1dActivator(
   layer: TLayer,
   size: number,
 ): (values?: number[] | undefined) => number[]
 ```
 
-Builds the activation function used by the attention stub.
+Builds the activation function used by the Conv1D stub.
 
-When values are provided, all outputs are filled with their average.
+When values are provided, this function returns a length-bounded slice.
 When values are omitted, it delegates to node activation.
 
-This behavior is *not* meant to represent real attention math; it simply
-produces a stable, shape-correct output while attention internals evolve.
+This keeps the call signature compatible with real layers while remaining
+intentionally cheap.
 
 Parameters:
 - `layer` - - Layer whose nodes can self-activate.
 - `size` - - Number of output values to return.
 
-Returns: Activation callback for attention behavior.
+Returns: Activation callback for Conv1D behavior.
 
 Example:
 
 ```ts
-const activate = createAttentionActivator(layer, 4);
-activate([1, 3]); // -> [2, 2, 2, 2]
+const activate = createConv1dActivator(layer, 3);
+activate([9, 8, 7, 6]); // -> [9, 8, 7]
 ```
 
-### activateStubNodes
+### createStubLayer
 
 ```ts
-activateStubNodes(
-  layer: TLayer,
-): number[]
+createStubLayer(
+  context: LayerFactoryContext<TLayer>,
+  size: number,
+): TLayer
 ```
 
-Activates all nodes in a stub layer and returns their outputs.
+Creates shared node/output scaffolding for experimental layers.
 
-This helper keeps fallback activation behavior identical across experimental
-layer variants.
+Centralizing this setup keeps the experimental builders focused on their
+metadata and activation behavior.
+
+Implementation detail: the returned layer contains a `nodes` list (for basic
+activation) and an `output` group (for API compatibility with the rest of the
+architecture). In these stubs, the output group is not intended to be a fully
+wired projection of `nodes`.
 
 Parameters:
-- `layer` - - Layer containing nodes to activate.
+- `context` - - Factory helpers for constructing the layer instance.
+- `size` - - Number of output nodes to allocate.
 
-Returns: Activated node outputs.
+Returns: Initialized experimental layer.
 
-Example:
+## architecture/layer/layer.factory.normalization.utils.ts
+
+### applyNormalizationActivation
 
 ```ts
-const outputs = activateStubNodes(layer);
+applyNormalizationActivation(
+  layer: TLayer,
+): void
 ```
 
-## architecture/layer/layer.factory.normalization.utils.ts
+Wraps a layer activation function with normalization post-processing.
+
+The wrapper preserves existing activation semantics, then applies
+`normalizeActivations(...)` to produce zero-centered, variance-scaled output.
+
+This is implemented as a function wrapper rather than modifying node math.
+That makes it easy to layer normalization behavior onto each dense layer.
+
+Parameters:
+- `layer` - - Dense layer to decorate with normalization behavior.
+
+Returns: No return value.
+
+Example (conceptual flow):
+
+```ts
+// 1) baseActivate(...) computes raw activations
+// 2) wrapper normalizes the vector before returning
+```
 
 ### buildBatchNormLayer
 
@@ -1827,34 +1855,6 @@ Example:
 const normalized = buildLayerNormLayer(factoryContext, 16);
 ```
 
-### applyNormalizationActivation
-
-```ts
-applyNormalizationActivation(
-  layer: TLayer,
-): void
-```
-
-Wraps a layer activation function with normalization post-processing.
-
-The wrapper preserves existing activation semantics, then applies
-`normalizeActivations(...)` to produce zero-centered, variance-scaled output.
-
-This is implemented as a function wrapper rather than modifying node math.
-That makes it easy to layer normalization behavior onto each dense layer.
-
-Parameters:
-- `layer` - - Dense layer to decorate with normalization behavior.
-
-Returns: No return value.
-
-Example (conceptual flow):
-
-```ts
-// 1) baseActivate(...) computes raw activations
-// 2) wrapper normalizes the vector before returning
-```
-
 ### computeMean
 
 ```ts