@reicek/neataptic-ts 0.1.24 → 0.1.26

package/src/architecture/network/topology/README.md

@@ -18,38 +18,38 @@ Design Notes:
 
 ## architecture/network/topology/network.topology.utils.types.ts
 
-### INPUT_NODE_TYPE
-
-Input node-type discriminator used for queue seeding.
-
-### ZERO_COUNT
-
-Zero baseline used for degree counts and empty-size checks.
-
 ### IN_DEGREE_DECREMENT
 
 Unit decrement/increment used for in-degree tally updates.
 
-### TopologyNetworkProps
-
-Internal topology state view carried across helper groups.
-
-### TopologyBuildContext
+### INPUT_NODE_TYPE
 
-Mutable context used while building Kahn topological order.
+Input node-type discriminator used for queue seeding.
 
 ### PathSearchContext
 
 Mutable context used while running iterative DFS reachability checks.
 
+### TopologyBuildContext
+
+Mutable context used while building Kahn topological order.
+
 ### TopologyNetwork
 
 Network instance type used by topology helpers.
 
+### TopologyNetworkProps
+
+Internal topology state view carried across helper groups.
+
 ### TopologyNode
 
 Node instance type used by topology helpers.
 
+### ZERO_COUNT
+
+Zero baseline used for degree counts and empty-size checks.
+
 ## architecture/network/topology/network.topology.utils.ts
 
 ### computeTopoOrder
@@ -62,16 +62,25 @@ Compute a topological ordering (Kahn's algorithm) for the current directed acycl
 If cycles are detected (order shorter than node count) we fall back to raw node order to avoid breaking callers.
 In non-acyclic mode we simply clear cached order to signal use of sequential node array.
 
-### hasPath
+### createMLP
 
 ```ts
-hasPath(
-  from: default,
-  to: default,
-): boolean
+createMLP(
+  inputCount: number,
+  hiddenCounts: number[],
+  outputCount: number,
+): default
 ```
 
-Depth-first reachability test (avoids infinite loops via visited set).
+Build a strictly layered and fully connected MLP network.
+
+Parameters:
+- `this` - Network constructor.
+- `inputCount` - Number of input nodes.
+- `hiddenCounts` - Hidden-layer node counts.
+- `outputCount` - Number of output nodes.
+
+Returns: Newly created MLP network.
 
 ### getTopologyIntent
 
@@ -90,6 +99,30 @@ Parameters:
 
 Returns: Current topology intent.
 
+### hasPath
+
+```ts
+hasPath(
+  from: default,
+  to: default,
+): boolean
+```
+
+Depth-first reachability test (avoids infinite loops via visited set).
+
+### rebuildConnections
+
+```ts
+rebuildConnections(
+  networkInstance: default,
+): void
+```
+
+Rebuild the canonical connection array from per-node outgoing lists.
+
+Parameters:
+- `networkInstance` - Target network.
+
 ### setEnforceAcyclic
 
 ```ts
@@ -128,87 +161,58 @@ Parameters:
 
 Returns: Nothing.
 
-### createMLP
-
-```ts
-createMLP(
-  inputCount: number,
-  hiddenCounts: number[],
-  outputCount: number,
-): default
-```
-
-Build a strictly layered and fully connected MLP network.
-
-Parameters:
-- `this` - Network constructor.
-- `inputCount` - Number of input nodes.
-- `hiddenCounts` - Hidden-layer node counts.
-- `outputCount` - Number of output nodes.
-
-Returns: Newly created MLP network.
-
-### rebuildConnections
-
-```ts
-rebuildConnections(
-  networkInstance: default,
-): void
-```
-
-Rebuild the canonical connection array from per-node outgoing lists.
-
-Parameters:
-- `networkInstance` - Target network.
-
 ## architecture/network/topology/network.topology.loop.utils.ts
 
-### seedProcessingQueue
+### appendTopoNode
 
 ```ts
-seedProcessingQueue(
-  buildContext: TopologyBuildContext,
+appendTopoNode(
+  topoOrder: default[],
+  node: default,
 ): void
 ```
 
-Seed Kahn queue with input nodes and zero in-degree nodes.
+Append one node to topological order output.
 
 Parameters:
-- `buildContext` - Mutable build context.
+- `topoOrder` - Accumulated topological order.
+- `node` - Node to append.
 
 Returns: Void.
 
-### processKahnQueue
+### decrementNodeInDegree
 
 ```ts
-processKahnQueue(
+decrementNodeInDegree(
   buildContext: TopologyBuildContext,
-): void
+  node: default,
+): number
 ```
 
-Process queue until all available nodes are emitted.
+Decrement node in-degree and return remaining value.
 
 Parameters:
 - `buildContext` - Mutable build context.
+- `node` - Target node.
 
-Returns: Void.
+Returns: Remaining in-degree after decrement.
 
-### isQueueSeedNode
+### getInDegree
 
 ```ts
-isQueueSeedNode(
-  node: default,
+getInDegree(
   buildContext: TopologyBuildContext,
-): boolean
+  node: default,
+): number
 ```
 
-Determine whether a node belongs in the initial queue.
+Read in-degree for a node with zero fallback.
 
 Parameters:
-- `node` - Candidate node.
 - `buildContext` - Mutable build context.
+- `node` - Candidate node.
 
-Returns: True when node is input-type or has zero in-degree.
+Returns: In-degree value.
 
 ### isInputNode
 
@@ -225,52 +229,52 @@ Parameters:
 
 Returns: True when node type is input.
 
-### getInDegree
+### isQueueSeedNode
 
 ```ts
-getInDegree(
-  buildContext: TopologyBuildContext,
+isQueueSeedNode(
   node: default,
-): number
+  buildContext: TopologyBuildContext,
+): boolean
 ```
 
-Read in-degree for a node with zero fallback.
+Determine whether a node belongs in the initial queue.
 
 Parameters:
-- `buildContext` - Mutable build context.
 - `node` - Candidate node.
+- `buildContext` - Mutable build context.
 
-Returns: In-degree value.
+Returns: True when node is input-type or has zero in-degree.
 
-### takeNextQueueNode
+### isSelfConnection
 
 ```ts
-takeNextQueueNode(
-  processingQueue: default[],
-): default
+isSelfConnection(
+  from: default,
+  to: default,
+): boolean
 ```
 
-Shift and return the next queue node.
+Test whether a connection is a self-loop.
 
 Parameters:
-- `processingQueue` - Queue of pending nodes.
+- `from` - Source node.
+- `to` - Target node.
 
-Returns: Next node.
+Returns: True when source and target are the same node.
 
-### appendTopoNode
+### processKahnQueue
 
 ```ts
-appendTopoNode(
-  topoOrder: default[],
-  node: default,
+processKahnQueue(
+  buildContext: TopologyBuildContext,
 ): void
 ```
 
-Append one node to topological order output.
+Process queue until all available nodes are emitted.
 
 Parameters:
-- `topoOrder` - Accumulated topological order.
-- `node` - Node to append.
+- `buildContext` - Mutable build context.
 
 Returns: Void.
 
@@ -291,39 +295,35 @@ Parameters:
 
 Returns: Void.
 
-### decrementNodeInDegree
+### seedProcessingQueue
 
 ```ts
-decrementNodeInDegree(
+seedProcessingQueue(
   buildContext: TopologyBuildContext,
-  node: default,
-): number
+): void
 ```
 
-Decrement node in-degree and return remaining value.
+Seed Kahn queue with input nodes and zero in-degree nodes.
 
 Parameters:
 - `buildContext` - Mutable build context.
-- `node` - Target node.
 
-Returns: Remaining in-degree after decrement.
+Returns: Void.
 
-### isSelfConnection
+### takeNextQueueNode
 
 ```ts
-isSelfConnection(
-  from: default,
-  to: default,
-): boolean
+takeNextQueueNode(
+  processingQueue: default[],
+): default
 ```
 
-Test whether a connection is a self-loop.
+Shift and return the next queue node.
 
 Parameters:
-- `from` - Source node.
-- `to` - Target node.
+- `processingQueue` - Queue of pending nodes.
 
-Returns: True when source and target are the same node.
+Returns: Next node.
 
 ## architecture/network/topology/network.topology.path.utils.ts
 
@@ -344,20 +344,22 @@ Parameters:
 
 Returns: Initialized path-search context.
 
-### traversePathSearch
+### hasVisitedNode
 
 ```ts
-traversePathSearch(
-  searchContext: PathSearchContext,
+hasVisitedNode(
+  visitedNodes: Set<default>,
+  node: default,
 ): boolean
 ```
 
-Traverse DFS search stack and test reachability.
+Test whether a node has already been visited.
 
 Parameters:
-- `searchContext` - Mutable search context.
+- `visitedNodes` - Visited-node set.
+- `node` - Candidate node.
 
-Returns: True when target node is reachable.
+Returns: True when node is already visited.
 
 ### isSameNode
 
@@ -376,120 +378,118 @@ Parameters:
 
 Returns: True when references are identical.
 
-### takeNextStackNode
+### isSelfConnection
 
 ```ts
-takeNextStackNode(
-  nodesToVisitStack: default[],
-): default
+isSelfConnection(
+  from: default,
+  to: default,
+): boolean
 ```
 
-Pop and return next DFS stack node.
+Test whether a connection is a self-loop.
 
 Parameters:
-- `nodesToVisitStack` - DFS stack.
+- `from` - Source node.
+- `to` - Target node.
 
-Returns: Next node to process.
+Returns: True when source and target are the same node.
 
-### hasVisitedNode
+### markVisited
 
 ```ts
-hasVisitedNode(
+markVisited(
   visitedNodes: Set<default>,
   node: default,
-): boolean
+): void
 ```
 
-Test whether a node has already been visited.
+Mark a node as visited.
 
 Parameters:
 - `visitedNodes` - Visited-node set.
-- `node` - Candidate node.
+- `node` - Node to mark.
 
-Returns: True when node is already visited.
+Returns: Void.
 
-### markVisited
+### pushOutgoingTargets
 
 ```ts
-markVisited(
-  visitedNodes: Set<default>,
-  node: default,
+pushOutgoingTargets(
+  nodesToVisitStack: default[],
+  currentNode: default,
 ): void
 ```
 
-Mark a node as visited.
+Push non-self outgoing targets to DFS stack.
 
 Parameters:
-- `visitedNodes` - Visited-node set.
-- `node` - Node to mark.
+- `nodesToVisitStack` - DFS stack.
+- `currentNode` - Current expanded node.
 
 Returns: Void.
 
-### pushOutgoingTargets
+### takeNextStackNode
 
 ```ts
-pushOutgoingTargets(
+takeNextStackNode(
   nodesToVisitStack: default[],
-  currentNode: default,
-): void
+): default
 ```
 
-Push non-self outgoing targets to DFS stack.
+Pop and return next DFS stack node.
 
 Parameters:
 - `nodesToVisitStack` - DFS stack.
-- `currentNode` - Current expanded node.
 
-Returns: Void.
+Returns: Next node to process.
 
-### isSelfConnection
+### traversePathSearch
 
 ```ts
-isSelfConnection(
-  from: default,
-  to: default,
+traversePathSearch(
+  searchContext: PathSearchContext,
 ): boolean
 ```
 
-Test whether a connection is a self-loop.
+Traverse DFS search stack and test reachability.
 
 Parameters:
-- `from` - Source node.
-- `to` - Target node.
+- `searchContext` - Mutable search context.
 
-Returns: True when source and target are the same node.
+Returns: True when target node is reachable.
 
 ## architecture/network/topology/network.topology.setup.utils.ts
 
-### asTopologyProps
+### applyIncomingEdgeCounts
 
 ```ts
-asTopologyProps(
-  network: default,
-): TopologyNetworkProps
+applyIncomingEdgeCounts(
+  buildContext: TopologyBuildContext,
+): void
 ```
 
-Cast network to internal topology props view.
+Apply in-degree increments from non-self connections.
 
 Parameters:
-- `network` - Network instance.
+- `buildContext` - Mutable build context.
 
-Returns: Internal topology props view.
+Returns: Void.
 
-### shouldUseRawNodeOrder
+### asTopologyProps
 
 ```ts
-shouldUseRawNodeOrder(
-  internalTopologyProps: TopologyNetworkProps,
-): boolean
+asTopologyProps(
+  network: default,
+): TopologyNetworkProps
 ```
 
-Determine whether topological order should be bypassed.
+Cast network to internal topology props view.
 
 Parameters:
-- `internalTopologyProps` - Internal topology props view.
+- `network` - Network instance.
 
-Returns: True when acyclic mode is disabled.
+Returns: Internal topology props view.
 
 ### clearCachedTopoOrder
 
@@ -523,66 +523,53 @@ Parameters:
 
 Returns: Initialized build context.
 
-### initializeAllNodeInDegreeCounts
+### finalizeTopoOrder
 
 ```ts
-initializeAllNodeInDegreeCounts(
+finalizeTopoOrder(
   buildContext: TopologyBuildContext,
 ): void
 ```
 
-Initialize all nodes with zero in-degree.
+Finalize cached order, falling back to raw node order on cycle detection.
 
 Parameters:
 - `buildContext` - Mutable build context.
 
 Returns: Void.
 
-### applyIncomingEdgeCounts
+### incrementNodeInDegree
 
 ```ts
-applyIncomingEdgeCounts(
+incrementNodeInDegree(
   buildContext: TopologyBuildContext,
+  node: default,
 ): void
 ```
 
-Apply in-degree increments from non-self connections.
+Increment in-degree for a node in the tally map.
 
 Parameters:
 - `buildContext` - Mutable build context.
+- `node` - Target node.
 
 Returns: Void.
 
-### finalizeTopoOrder
+### initializeAllNodeInDegreeCounts
 
 ```ts
-finalizeTopoOrder(
+initializeAllNodeInDegreeCounts(
   buildContext: TopologyBuildContext,
 ): void
 ```
 
-Finalize cached order, falling back to raw node order on cycle detection.
+Initialize all nodes with zero in-degree.
 
 Parameters:
 - `buildContext` - Mutable build context.
 
 Returns: Void.
 
-### resolveFinalOrder
-
-```ts
-resolveFinalOrder(
-  buildContext: TopologyBuildContext,
-): default[]
-```
-
-Resolve final topological order with cycle fallback.
-
-Parameters:
-- `buildContext` - Mutable build context.
-
-Returns: Fully valid topological order or raw node order fallback.
-
 ### isSelfConnection
 
 ```ts
@@ -600,127 +587,125 @@ Parameters:
 
 Returns: True when source and target are the same node.
 
-### incrementNodeInDegree
+### resolveFinalOrder
 
 ```ts
-incrementNodeInDegree(
+resolveFinalOrder(
   buildContext: TopologyBuildContext,
-  node: default,
-): void
+): default[]
 ```
 
-Increment in-degree for a node in the tally map.
+Resolve final topological order with cycle fallback.
 
 Parameters:
 - `buildContext` - Mutable build context.
-- `node` - Target node.
 
-Returns: Void.
+Returns: Fully valid topological order or raw node order fallback.
+
+### shouldUseRawNodeOrder
+
+```ts
+shouldUseRawNodeOrder(
+  internalTopologyProps: TopologyNetworkProps,
+): boolean
+```
+
+Determine whether topological order should be bypassed.
+
+Parameters:
+- `internalTopologyProps` - Internal topology props view.
+
+Returns: True when acyclic mode is disabled.
 
 ## architecture/network/topology/network.topology.factory.utils.ts
 
-### createMLP
+### addOutgoingConnectionsToSet
 
 ```ts
-createMLP(
-  inputCount: number,
-  hiddenCounts: number[],
-  outputCount: number,
-): default
+addOutgoingConnectionsToSet(
+  outgoingConnections: default[],
+  allConnections: Set<default>,
+): void
 ```
 
-Build a strictly layered and fully connected MLP network.
+Add all outgoing connections to a deduplication set.
 
 Parameters:
-- `this` - Network constructor.
-- `inputCount` - Number of input nodes.
-- `hiddenCounts` - Hidden-layer node counts.
-- `outputCount` - Number of output nodes.
-
-Returns: Newly created MLP network.
+- `outgoingConnections` - Outgoing connections from one node.
+- `allConnections` - Deduplication set for network connections.
 
-### rebuildConnections
+### assignNetworkNodes
 
 ```ts
-rebuildConnections(
+assignNetworkNodes(
   networkInstance: default,
+  mlpNodeLayers: MlpNodeLayers,
 ): void
 ```
 
-Rebuild the canonical connection array from per-node outgoing lists.
+Assign ordered nodes to the network instance.
 
 Parameters:
 - `networkInstance` - Target network.
+- `mlpNodeLayers` - Grouped node layers for this MLP.
 
-### createMlpNodeLayers
+### collectUniqueOutgoingConnections
 
 ```ts
-createMlpNodeLayers(
-  inputCount: number,
-  hiddenCounts: number[],
-  outputCount: number,
-): MlpNodeLayers
+collectUniqueOutgoingConnections(
+  networkInstance: default,
+): Set<default>
 ```
 
-Build input, hidden, and output node layers for an MLP topology.
+Collect unique outgoing connections across all network nodes.
 
 Parameters:
-- `inputCount` - Number of input nodes.
-- `hiddenCounts` - Hidden-layer node counts.
-- `outputCount` - Number of output nodes.
+- `networkInstance` - Target network.
 
-Returns: Grouped node layers for MLP assembly.
+Returns: Set of unique outgoing connections.
 
-### instantiateNetwork
+### connectLayerPair
 
 ```ts
-instantiateNetwork(
-  networkFactory: NetworkConstructor,
-  inputCount: number,
-  outputCount: number,
-): default
+connectLayerPair(
+  sourceLayer: default[],
+  targetLayer: default[],
+): void
 ```
 
-Instantiate a new network using the runtime constructor.
+Fully connect every source node to every target node.
 
 Parameters:
-- `networkFactory` - Network constructor function.
-- `inputCount` - Number of input nodes.
-- `outputCount` - Number of output nodes.
-
-Returns: Newly instantiated network.
+- `sourceLayer` - Source layer.
+- `targetLayer` - Target layer.
 
-### assignNetworkNodes
+### connectMlpLayers
 
 ```ts
-assignNetworkNodes(
-  networkInstance: default,
+connectMlpLayers(
   mlpNodeLayers: MlpNodeLayers,
 ): void
 ```
 
-Assign ordered nodes to the network instance.
+Fully connect each adjacent layer in MLP order.
 
 Parameters:
-- `networkInstance` - Target network.
 - `mlpNodeLayers` - Grouped node layers for this MLP.
 
-### createNodesOfType
+### convertConnectionSetToArray
 
 ```ts
-createNodesOfType(
-  nodeCount: number,
-  nodeType: "input" | "output" | "hidden",
+convertConnectionSetToArray(
+  uniqueConnections: Set<default>,
 ): default[]
 ```
 
-Create all nodes for a single fixed node type.
+Convert a connection set into the canonical array format.
 
 Parameters:
-- `nodeCount` - Number of nodes to create.
-- `nodeType` - Node type identifier.
+- `uniqueConnections` - Unique network connections.
 
-Returns: Node list of the requested type.
+Returns: Array of network connections.
 
 ### createHiddenLayers
 
@@ -737,121 +722,136 @@ Parameters:
 
 Returns: Hidden layers in forward order.
 
-### createOrderedNodeList
+### createMLP
 
 ```ts
-createOrderedNodeList(
-  mlpNodeLayers: MlpNodeLayers,
-): default[]
+createMLP(
+  inputCount: number,
+  hiddenCounts: number[],
+  outputCount: number,
+): default
 ```
 
-Build the canonical ordered node list used by the network.
+Build a strictly layered and fully connected MLP network.
 
 Parameters:
-- `mlpNodeLayers` - Grouped node layers for this MLP.
+- `this` - Network constructor.
+- `inputCount` - Number of input nodes.
+- `hiddenCounts` - Hidden-layer node counts.
+- `outputCount` - Number of output nodes.
 
-Returns: Ordered node list: input, hidden, then output.
+Returns: Newly created MLP network.
 
-### flattenNodeLayers
+### createMlpNodeLayers
 
 ```ts
-flattenNodeLayers(
-  nodeLayers: default[][],
-): default[]
+createMlpNodeLayers(
+  inputCount: number,
+  hiddenCounts: number[],
+  outputCount: number,
+): MlpNodeLayers
 ```
 
-Flatten layered node collections into a single ordered list.
+Build input, hidden, and output node layers for an MLP topology.
 
 Parameters:
-- `nodeLayers` - Layered node collections.
+- `inputCount` - Number of input nodes.
+- `hiddenCounts` - Hidden-layer node counts.
+- `outputCount` - Number of output nodes.
 
-Returns: Flattened node list.
+Returns: Grouped node layers for MLP assembly.
 
-### connectMlpLayers
+### createNodesOfType
 
 ```ts
-connectMlpLayers(
-  mlpNodeLayers: MlpNodeLayers,
-): void
+createNodesOfType(
+  nodeCount: number,
+  nodeType: "input" | "output" | "hidden",
+): default[]
 ```
 
-Fully connect each adjacent layer in MLP order.
+Create all nodes for a single fixed node type.
 
 Parameters:
-- `mlpNodeLayers` - Grouped node layers for this MLP.
+- `nodeCount` - Number of nodes to create.
+- `nodeType` - Node type identifier.
 
-### connectLayerPair
+Returns: Node list of the requested type.
+
+### createOrderedNodeList
 
 ```ts
-connectLayerPair(
-  sourceLayer: default[],
-  targetLayer: default[],
-): void
+createOrderedNodeList(
+  mlpNodeLayers: MlpNodeLayers,
+): default[]
 ```
 
-Fully connect every source node to every target node.
+Build the canonical ordered node list used by the network.
 
 Parameters:
-- `sourceLayer` - Source layer.
-- `targetLayer` - Target layer.
+- `mlpNodeLayers` - Grouped node layers for this MLP.
 
-### markTopologyDirty
+Returns: Ordered node list: input, hidden, then output.
+
+### flattenNodeLayers
 
 ```ts
-markTopologyDirty(
-  networkInstance: default,
-): void
+flattenNodeLayers(
+  nodeLayers: default[][],
+): default[]
 ```
 
-Mark a network topology as dirty after structural edits.
+Flatten layered node collections into a single ordered list.
 
 Parameters:
-- `networkInstance` - Network instance to mark.
+- `nodeLayers` - Layered node collections.
 
-### collectUniqueOutgoingConnections
+Returns: Flattened node list.
+
+### instantiateNetwork
 
 ```ts
-collectUniqueOutgoingConnections(
-  networkInstance: default,
-): Set<default>
+instantiateNetwork(
+  networkFactory: NetworkConstructor,
+  inputCount: number,
+  outputCount: number,
+): default
 ```
 
-Collect unique outgoing connections across all network nodes.
+Instantiate a new network using the runtime constructor.
 
 Parameters:
-- `networkInstance` - Target network.
+- `networkFactory` - Network constructor function.
+- `inputCount` - Number of input nodes.
+- `outputCount` - Number of output nodes.
 
-Returns: Set of unique outgoing connections.
+Returns: Newly instantiated network.
 
-### addOutgoingConnectionsToSet
+### markTopologyDirty
 
 ```ts
-addOutgoingConnectionsToSet(
-  outgoingConnections: default[],
-  allConnections: Set<default>,
+markTopologyDirty(
+  networkInstance: default,
 ): void
 ```
 
-Add all outgoing connections to a deduplication set.
+Mark a network topology as dirty after structural edits.
 
 Parameters:
-- `outgoingConnections` - Outgoing connections from one node.
-- `allConnections` - Deduplication set for network connections.
+- `networkInstance` - Network instance to mark.
 
-### convertConnectionSetToArray
+### rebuildConnections
 
 ```ts
-convertConnectionSetToArray(
-  uniqueConnections: Set<default>,
-): default[]
+rebuildConnections(
+  networkInstance: default,
+): void
 ```
 
-Convert a connection set into the canonical array format.
+Rebuild the canonical connection array from per-node outgoing lists.
 
 Parameters:
-- `uniqueConnections` - Unique network connections.
-
-Returns: Array of network connections.
+- `networkInstance` - Target network.
 
 ## architecture/network/topology/network.topology.contract.utils.ts
 
@@ -872,25 +872,6 @@ Parameters:
 
 Returns: Current topology intent.
 
-### setTopologyIntent
-
-```ts
-setTopologyIntent(
-  topologyIntent: NetworkTopologyIntent,
-): void
-```
-
-Set the public topology intent and synchronize low-level runtime flags.
-
-Updating the semantic contract also updates acyclic enforcement and marks the
-topological cache dirty so later activation paths rebuild consistent state.
-
-Parameters:
-- `this` - Target network instance.
-- `topologyIntent` - Desired topology intent.
-
-Returns: Nothing.
-
 ### setEnforceAcyclic
 
 ```ts
@@ -910,77 +891,26 @@ Parameters:
 
 Returns: Nothing.
 
-## architecture/network/topology/network.topology.architecture.utils.ts
-
-### describeArchitecture
-
-```ts
-describeArchitecture(
-  network: default,
-): NetworkArchitectureDescriptor
-```
-
-Describes network architecture for diagnostics, telemetry, and UI rendering.
-
-This function prefers factual sources over heuristics so downstream tooling
-can rely on the descriptor while still receiving useful output for partially
-specified runtime graphs.
-
-Resolution priority is intentionally explicit:
-1) node `layer` metadata (factual when present)
-2) graph-derived feed-forward depth layering (factual for acyclic graphs)
-3) hidden-node count fallback (heuristic inference)
-
-Parameters:
-- `network` - - Runtime network instance.
-
-Returns: Stable architecture descriptor.
-
-Example:
-
-```ts
-const descriptor = describeArchitecture(network);
-// descriptor.hiddenLayerSizes -> [8, 4]
-// descriptor.source -> 'layer-metadata' | 'graph-topology' | 'inferred'
-```
-
-### resolveArchitectureDescriptor
+### setTopologyIntent
 
 ```ts
-resolveArchitectureDescriptor(
-  network: default,
-): NetworkArchitectureDescriptor
+setTopologyIntent(
+  topologyIntent: NetworkTopologyIntent,
+): void
 ```
 
-Resolve the public architecture descriptor, preferring live graph facts and
-falling back to hydrated serialization metadata only when the live result is
-still purely inferred.
+Set the public topology intent and synchronize low-level runtime flags.
 
-This helper keeps the descriptor ownership story in one chapter: topology
-owns the live analysis while serialization can optionally hydrate a cached
-descriptor that remains safe to reuse when the runtime graph shape matches.
+Updating the semantic contract also updates acyclic enforcement and marks the
+topological cache dirty so later activation paths rebuild consistent state.
 
 Parameters:
-- `network` - Runtime network instance.
-
-Returns: Public architecture descriptor for telemetry and UI consumers.
-
-### isHydratedDescriptorCompatible
-
-```ts
-isHydratedDescriptorCompatible(
-  network: default,
-  hydratedDescriptor: NetworkArchitectureDescriptor | undefined,
-): boolean
-```
-
-Check whether hydrated descriptor metadata still matches the current graph shape.
+- `this` - Target network instance.
+- `topologyIntent` - Desired topology intent.
 
-Parameters:
-- `network` - Runtime network instance.
-- `hydratedDescriptor` - Optional hydrated descriptor candidate.
+Returns: Nothing.
 
-Returns: True when hydrated descriptor can safely stand in for the inferred result.
+## architecture/network/topology/network.topology.architecture.utils.ts
 
 ### createArchitectureDescriptor
 
@@ -1015,112 +945,152 @@ const descriptor = createArchitectureDescriptor([6, 3], false, 'graph-topology',
 // descriptor.totalNodes === 14
 ```
 
-### resolveHiddenLayerSizesFromLayerMetadata
+### createDirectedEdgeList
 
 ```ts
-resolveHiddenLayerSizesFromLayerMetadata(
-  runtimeNodes: RuntimeNodeLike[],
-): number[]
+createDirectedEdgeList(
+  runtimeConnections: RuntimeConnectionLike[],
+  nodeByIndex: Map<number, RuntimeNodeLike>,
+): { fromIndex: number; toIndex: number; }[]
 ```
 
-Resolves hidden-layer widths from explicit `node.layer` metadata.
+Produces a validated list of enabled directed edges.
 
-This is treated as the most trustworthy source because layer assignment is
-usually produced by architecture-aware builders and does not depend on
-topological reconstruction.
+Invalid references, disabled connections, and self-loops are removed so the
+remaining edge list can be consumed safely by cycle and depth algorithms.
 
 Parameters:
-- `runtimeNodes` - - Runtime nodes.
+- `runtimeConnections` - - Runtime connections.
+- `nodeByIndex` - - Indexed nodes.
 
-Returns: Hidden-layer widths from explicit node.layer metadata.
+Returns: Valid directed edges.
 
 Example:
 
 ```ts
-// Hidden nodes in layers 1, 1, and 2 -> [2, 1]
-const sizes = resolveHiddenLayerSizesFromLayerMetadata(nodes);
+const edges = createDirectedEdgeList(runtimeConnections, nodeByIndex);
+// edges -> [{ fromIndex: 0, toIndex: 3 }, ...]
 ```
 
-### resolveHiddenLayerSizesFromGraphTopology
+### createNodeIndexMap
 
 ```ts
-resolveHiddenLayerSizesFromGraphTopology(
+createNodeIndexMap(
   runtimeNodes: RuntimeNodeLike[],
-  runtimeConnections: RuntimeConnectionLike[],
-): { hiddenLayerSizes: number[]; hasCycles: boolean; }
+): Map<number, RuntimeNodeLike>
 ```
 
-Derives hidden-layer widths from graph topology when no explicit layer
-metadata is available.
+Builds a node lookup table keyed by stable index.
 
-The method computes a topological depth model for acyclic graphs; cyclic
-graphs are flagged and intentionally return no width inference because depth
-is not well-defined in recurrent loops.
+Runtime objects may omit `index`; in that case the current array position is
+used as a deterministic fallback to keep downstream graph logic total.
 
 Parameters:
 - `runtimeNodes` - - Runtime nodes.
-- `runtimeConnections` - - Runtime connections.
 
-Returns: Hidden-layer widths derived from acyclic topology and cycle flag.
+Returns: Node map keyed by stable node index.
 
 Example:
 
 ```ts
-const { hiddenLayerSizes, hasCycles } = resolveHiddenLayerSizesFromGraphTopology(nodes, edges);
+const nodeByIndex = createNodeIndexMap(nodes);
+// nodeByIndex.get(0) -> first node or node with explicit index 0
 ```
 
-### createNodeIndexMap
+### describeArchitecture
 
 ```ts
-createNodeIndexMap(
-  runtimeNodes: RuntimeNodeLike[],
-): Map<number, RuntimeNodeLike>
+describeArchitecture(
+  network: default,
+): NetworkArchitectureDescriptor
 ```
 
-Builds a node lookup table keyed by stable index.
+Describes network architecture for diagnostics, telemetry, and UI rendering.
 
-Runtime objects may omit `index`; in that case the current array position is
-used as a deterministic fallback to keep downstream graph logic total.
+This function prefers factual sources over heuristics so downstream tooling
+can rely on the descriptor while still receiving useful output for partially
+specified runtime graphs.
+
+Resolution priority is intentionally explicit:
+1) node `layer` metadata (factual when present)
+2) graph-derived feed-forward depth layering (factual for acyclic graphs)
+3) hidden-node count fallback (heuristic inference)
 
 Parameters:
-- `runtimeNodes` - - Runtime nodes.
+- `network` - - Runtime network instance.
 
-Returns: Node map keyed by stable node index.
+Returns: Stable architecture descriptor.
 
 Example:
 
 ```ts
-const nodeByIndex = createNodeIndexMap(nodes);
-// nodeByIndex.get(0) -> first node or node with explicit index 0
+const descriptor = describeArchitecture(network);
+// descriptor.hiddenLayerSizes -> [8, 4]
+// descriptor.source -> 'layer-metadata' | 'graph-topology' | 'inferred'
 ```
 
-### createDirectedEdgeList
+### isHiddenNode
 
 ```ts
-createDirectedEdgeList(
-  runtimeConnections: RuntimeConnectionLike[],
-  nodeByIndex: Map<number, RuntimeNodeLike>,
-): { fromIndex: number; toIndex: number; }[]
+isHiddenNode(
+  runtimeNode: RuntimeNodeLike,
+): boolean
 ```
 
-Produces a validated list of enabled directed edges.
-
-Invalid references, disabled connections, and self-loops are removed so the
-remaining edge list can be consumed safely by cycle and depth algorithms.
+Identifies whether a runtime node should be treated as hidden for topology
+reconstruction and fallback inference.
 
 Parameters:
-- `runtimeConnections` - - Runtime connections.
-- `nodeByIndex` - - Indexed nodes.
+- `runtimeNode` - - Candidate node.
 
-Returns: Valid directed edges.
+Returns: True when node type is hidden.
 
 Example:
 
 ```ts
-const edges = createDirectedEdgeList(runtimeConnections, nodeByIndex);
-// edges -> [{ fromIndex: 0, toIndex: 3 }, ...]
+if (isHiddenNode(node)) {
+  // Include in hidden-layer counting
+}
+```
+
+### isHydratedDescriptorCompatible
+
+```ts
+isHydratedDescriptorCompatible(
+  network: default,
+  hydratedDescriptor: NetworkArchitectureDescriptor | undefined,
+): boolean
+```
+
+Check whether hydrated descriptor metadata still matches the current graph shape.
+
+Parameters:
+- `network` - Runtime network instance.
+- `hydratedDescriptor` - Optional hydrated descriptor candidate.
+
+Returns: True when hydrated descriptor can safely stand in for the inferred result.
+
+### resolveArchitectureDescriptor
+
+```ts
+resolveArchitectureDescriptor(
+  network: default,
+): NetworkArchitectureDescriptor
 ```
 
+Resolve the public architecture descriptor, preferring live graph facts and
+falling back to hydrated serialization metadata only when the live result is
+still purely inferred.
+
+This helper keeps the descriptor ownership story in one chapter: topology
+owns the live analysis while serialization can optionally hydrate a cached
+descriptor that remains safe to reuse when the runtime graph shape matches.
+
+Parameters:
+- `network` - Runtime network instance.
+
+Returns: Public architecture descriptor for telemetry and UI consumers.
+
 ### resolveCycleStateAndTopoOrder
 
 ```ts
@@ -1148,80 +1118,110 @@ Example:
 const { topologicalOrder, hasCycles } = resolveCycleStateAndTopoOrder(nodeByIndex, edges);
 ```
 
-### resolveNodeDepthByIndex
+### resolveHiddenCountsByDepth
 
 ```ts
-resolveNodeDepthByIndex(
+resolveHiddenCountsByDepth(
   nodeByIndex: Map<number, RuntimeNodeLike>,
-  directedEdges: { fromIndex: number; toIndex: number; }[],
-  topologicalOrder: number[],
+  depthByNodeIndex: Map<number, number>,
 ): Map<number, number>
 ```
 
-Computes node depth (feed-forward distance from inputs) for an acyclic graph.
+Aggregates hidden-node counts per derived depth.
 
-Depth assignment is parent-driven: each node depth is one plus the maximum
-resolved parent depth. Nodes with no resolved parents are skipped.
+This is the final transformation before emitting architecture widths:
+hidden nodes are grouped by depth and counted in insertion-safe maps.
 
 Parameters:
 - `nodeByIndex` - - Indexed nodes.
-- `directedEdges` - - Directed edges.
-- `topologicalOrder` - - Acyclic topological order.
+- `depthByNodeIndex` - - Derived depths.
 
-Returns: Derived depth by node index.
+Returns: Hidden-node counts by depth.
 
 Example:
 
 ```ts
-const depthByNodeIndex = resolveNodeDepthByIndex(nodeByIndex, edges, topologicalOrder);
+const hiddenCountsByDepth = resolveHiddenCountsByDepth(nodeByIndex, depthByNodeIndex);
 ```
 
-### resolveHiddenCountsByDepth
+### resolveHiddenLayerSizesFromGraphTopology
 
 ```ts
-resolveHiddenCountsByDepth(
-  nodeByIndex: Map<number, RuntimeNodeLike>,
-  depthByNodeIndex: Map<number, number>,
-): Map<number, number>
+resolveHiddenLayerSizesFromGraphTopology(
+  runtimeNodes: RuntimeNodeLike[],
+  runtimeConnections: RuntimeConnectionLike[],
+): { hiddenLayerSizes: number[]; hasCycles: boolean; }
 ```
 
-Aggregates hidden-node counts per derived depth.
+Derives hidden-layer widths from graph topology when no explicit layer
+metadata is available.
 
-This is the final transformation before emitting architecture widths:
-hidden nodes are grouped by depth and counted in insertion-safe maps.
+The method computes a topological depth model for acyclic graphs; cyclic
+graphs are flagged and intentionally return no width inference because depth
+is not well-defined in recurrent loops.
 
 Parameters:
-- `nodeByIndex` - - Indexed nodes.
-- `depthByNodeIndex` - - Derived depths.
+- `runtimeNodes` - - Runtime nodes.
+- `runtimeConnections` - - Runtime connections.
 
-Returns: Hidden-node counts by depth.
+Returns: Hidden-layer widths derived from acyclic topology and cycle flag.
 
 Example:
 
 ```ts
-const hiddenCountsByDepth = resolveHiddenCountsByDepth(nodeByIndex, depthByNodeIndex);
+const { hiddenLayerSizes, hasCycles } = resolveHiddenLayerSizesFromGraphTopology(nodes, edges);
 ```
 
-### isHiddenNode
+### resolveHiddenLayerSizesFromLayerMetadata
 
 ```ts
-isHiddenNode(
-  runtimeNode: RuntimeNodeLike,
-): boolean
+resolveHiddenLayerSizesFromLayerMetadata(
+  runtimeNodes: RuntimeNodeLike[],
+): number[]
 ```
 
-Identifies whether a runtime node should be treated as hidden for topology
-reconstruction and fallback inference.
+Resolves hidden-layer widths from explicit `node.layer` metadata.
+
+This is treated as the most trustworthy source because layer assignment is
+usually produced by architecture-aware builders and does not depend on
+topological reconstruction.
 
 Parameters:
-- `runtimeNode` - - Candidate node.
+- `runtimeNodes` - - Runtime nodes.
 
-Returns: True when node type is hidden.
+Returns: Hidden-layer widths from explicit node.layer metadata.
 
 Example:
 
 ```ts
-if (isHiddenNode(node)) {
-  // Include in hidden-layer counting
-}
+// Hidden nodes in layers 1, 1, and 2 -> [2, 1]
+const sizes = resolveHiddenLayerSizesFromLayerMetadata(nodes);
+```
+
+### resolveNodeDepthByIndex
+
+```ts
+resolveNodeDepthByIndex(
+  nodeByIndex: Map<number, RuntimeNodeLike>,
+  directedEdges: { fromIndex: number; toIndex: number; }[],
+  topologicalOrder: number[],
+): Map<number, number>
+```
+
+Computes node depth (feed-forward distance from inputs) for an acyclic graph.
+
+Depth assignment is parent-driven: each node depth is one plus the maximum
+resolved parent depth. Nodes with no resolved parents are skipped.
+
+Parameters:
+- `nodeByIndex` - - Indexed nodes.
+- `directedEdges` - - Directed edges.
+- `topologicalOrder` - - Acyclic topological order.
+
+Returns: Derived depth by node index.
+
+Example:
+
+```ts
+const depthByNodeIndex = resolveNodeDepthByIndex(nodeByIndex, edges, topologicalOrder);
 ```