@reicek/neataptic-ts 0.1.24 → 0.1.26

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

@@ -46,6 +46,19 @@ const restored = importFromONNX(modelRoundTrip);
 
 ## architecture/network/onnx/network.onnx.ts
 
+### Conv2DMapping
+
+Mapping declaration for treating a fully-connected layer as a 2D convolution during export.
+
+This does **not** magically turn an MLP into a convolutional network at runtime.
+It annotates a particular export-layer index with a conv interpretation so that:
+- The exported graph uses conv-shaped tensors/operators, and
+- Import can re-attach pooling/flatten metadata appropriately.
+
+Pitfall: mappings must match the actual layer sizes. If `inHeight * inWidth * inChannels`
+does not correspond to the prior layer width (and similarly for outputs), export or import
+may reject the model.
+
 ### exportToONNX
 
 ```ts
@@ -124,19 +137,6 @@ Parameters:
 
 Returns: Reconstructed network ready for inference/evolution workflows.
 
-### Conv2DMapping
-
-Mapping declaration for treating a fully-connected layer as a 2D convolution during export.
-
-This does **not** magically turn an MLP into a convolutional network at runtime.
-It annotates a particular export-layer index with a conv interpretation so that:
-- The exported graph uses conv-shaped tensors/operators, and
-- Import can re-attach pooling/flatten metadata appropriately.
-
-Pitfall: mappings must match the actual layer sizes. If `inHeight * inWidth * inChannels`
-does not correspond to the prior layer width (and similarly for outputs), export or import
-may reject the model.
-
 ### OnnxExportOptions
 
 Options controlling ONNX-like export.
@@ -253,160 +253,21 @@ Limitations / TODO (tracked for later phases):
 NOTE: Import is only guaranteed to work for models produced by `exportToONNX()`; arbitrary ONNX graphs are
 NOT supported. Experimental fused recurrent nodes are best-effort and may silently degrade if shapes mismatch.
 
-### buildOnnxModel
-
-```ts
-buildOnnxModel(
-  network: default,
-  layers: default[][],
-  options: OnnxExportOptions,
-): OnnxModel
-```
-
-Build an ONNX-like model from a validated layered network view.
-
-Role in the ONNX pipeline:
-- This function is a thin, stable orchestration boundary used by higher-level exporters.
-- It forwards to the implementation module while preserving a predictable public API
-  for callers that import from this compatibility barrel.
-- Keeping this wrapper explicit helps isolate call sites from internal file splits
-  and phased refactors in export internals.
-
-Expected preconditions:
-- `layers` has already been inferred from the same `network` instance.
-- Structural validation (layer homogeneity/connectivity and option gates) is complete.
-- Export options are normalized by the caller according to project defaults.
-
-High-level behavior:
- 1. Receive network, ordered layer matrix, and export options.
- 2. Delegate model construction to the concrete builder implementation.
- 3. Return the resulting ONNX-like JSON graph container unchanged.
-
-Parameters:
-- `network` - - Source network to serialize.
-- `layers` - - Ordered layer matrix produced by layer inference utilities.
-- `options` - - Export options controlling metadata/recurrent/partial-connectivity behavior.
-
-Returns: ONNX-like model object representing graph nodes, tensors, and metadata.
-
-Example:
-
-```ts
-const layers = inferLayerOrdering(network);
-const model = buildOnnxModel(network, layers, { includeMetadata: true });
-```
-
-### OnnxModel
-
-ONNX-like model container (JSON-serializable).
-
-This is the main “wire format” object in this folder. Persist it as JSON text:
-
-```ts
-const jsonText = JSON.stringify(model);
-const restoredModel = JSON.parse(jsonText) as OnnxModel;
-```
-
-Notes:
-- `metadata_props` contains NeatapticTS-specific keys (layer sizes, recurrent flags,
-  conv/pool mappings, etc.). This is where most round-trip hints live.
-- Initializers currently store floating-point weights in `float_data`.
-
-Security/trust boundary:
-- Treat this as untrusted input if it comes from outside your process.
-
-### inferLayerOrdering
-
-```ts
-inferLayerOrdering(
-  network: default,
-): default[][]
-```
-
-Infer strictly layered ordering from a network.
-
-Parameters:
-- `network` - Source network.
-
-Returns: Ordered layers: input, hidden..., output.
-
-### rebuildConnectionsLocal
-
-```ts
-rebuildConnectionsLocal(
-  networkLike: default,
-): void
-```
-
-Rebuild the network's flat connections array from each node's outgoing list.
-
-Parameters:
-- `networkLike` - Network-like instance to mutate.
-
-Returns: Nothing.
-
-### validateLayerHomogeneityAndConnectivity
+### applyModelMetadata
 
 ```ts
-validateLayerHomogeneityAndConnectivity(
-  layers: default[][],
-  network: default,
-  options: OnnxExportOptions,
+applyModelMetadata(
+  context: OnnxModelMetadataContext,
 ): void
 ```
 
-Validate connectivity and activation homogeneity constraints per layer.
+Attach producer and opset metadata to a model when metadata emission is enabled.
 
 Parameters:
-- `layers` - Layered node arrays.
-- `network` - Source network (reserved for compatibility).
-- `options` - Export options.
+- `context` - Metadata application context.
 
 Returns: Nothing.
 
-### runOnnxExportFlow
-
-```ts
-runOnnxExportFlow(
-  network: default,
-  options: OnnxExportOptions,
-): OnnxModel
-```
-
-Execute the complete ONNX export flow for one network instance.
-
-High-level behavior:
- 1. Rebuild runtime connection caches and assign stable export indices.
- 2. Infer layered ordering and collect recurrent-pattern stubs.
- 3. Validate structural constraints for the requested export options.
- 4. Build ONNX graph payload and append inference-oriented metadata.
-
-Parameters:
-- `network` - Source network to serialize.
-- `options` - Optional ONNX export controls.
-
-Returns: ONNX-like model payload.
-
-### runOnnxImportFlow
-
-```ts
-runOnnxImportFlow(
-  onnx: OnnxModel,
-): default
-```
-
-Execute the complete ONNX import flow and reconstruct a runtime network.
-
-High-level behavior:
- 1. Extract architecture dimensions and build a perceptron scaffold.
- 2. Restore dense parameters and activation functions.
- 3. Reconstruct recurrent/pooling metadata and rebuild connection caches.
-
-Parameters:
-- `onnx` - ONNX-like model payload to reconstruct.
-
-Returns: Reconstructed network instance.
-
 ### assignActivationFunctions
 
 ```ts
@@ -447,37 +308,48 @@ Parameters:
 
 Returns: Nothing.
 
-### deriveHiddenLayerSizes
+### buildOnnxModel
 
 ```ts
-deriveHiddenLayerSizes(
-  initializers: OnnxTensor[],
-  metadataProps: OnnxMetadataProperty[] | undefined,
-): number[]
+buildOnnxModel(
+  network: default,
+  layers: default[][],
+  options: OnnxExportOptions,
+): OnnxModel
 ```
 
-Extract hidden layer sizes from ONNX initializers (weight tensors).
+Build an ONNX-like model from a validated layered network view.
 
-Parameters:
-- `initializers` - ONNX initializer tensors.
-- `metadataProps` - Optional ONNX metadata properties.
+Role in the ONNX pipeline:
+- This function is a thin, stable orchestration boundary used by higher-level exporters.
+- It forwards to the implementation module while preserving a predictable public API
+  for callers that import from this compatibility barrel.
+- Keeping this wrapper explicit helps isolate call sites from internal file splits
+  and phased refactors in export internals.
 
-Returns: Hidden layer sizes in order.
+Expected preconditions:
+- `layers` has already been inferred from the same `network` instance.
+- Structural validation (layer homogeneity/connectivity and option gates) is complete.
+- Export options are normalized by the caller according to project defaults.
 
-### applyModelMetadata
+High-level behavior:
+ 1. Receive network, ordered layer matrix, and export options.
+ 2. Delegate model construction to the concrete builder implementation.
+ 3. Return the resulting ONNX-like JSON graph container unchanged.
 
-```ts
-applyModelMetadata(
-  context: OnnxModelMetadataContext,
-): void
-```
+Parameters:
+- `network` - - Source network to serialize.
+- `layers` - - Ordered layer matrix produced by layer inference utilities.
+- `options` - - Export options controlling metadata/recurrent/partial-connectivity behavior.
 
-Attach producer and opset metadata to a model when metadata emission is enabled.
+Returns: ONNX-like model object representing graph nodes, tensors, and metadata.
 
-Parameters:
-- `context` - Metadata application context.
+Example:
 
-Returns: Nothing.
+```ts
+const layers = inferLayerOrdering(network);
+const model = buildOnnxModel(network, layers, { includeMetadata: true });
+```
 
 ### collectRecurrentLayerIndices
 
@@ -524,49 +396,22 @@ Parameters:
 
 Returns: Input and output dimension arrays for ONNX value info.
 
-### emitLayerGraph
+### deriveHiddenLayerSizes
 
 ```ts
-emitLayerGraph(
-  context: LayerBuildContext,
-): string
+deriveHiddenLayerSizes(
+  initializers: OnnxTensor[],
+  metadataProps: OnnxMetadataProperty[] | undefined,
+): number[]
 ```
 
-Emit one export layer graph segment by routing the layer through the correct
-ONNX emission strategy.
-
-Dispatch order matters:
-- explicit Conv mappings win first,
-- recurrent single-step export is considered only for hidden layers with
-  self-connections,
-- non-recurrent layers fall back to compact dense emission or mixed-activation
-  per-neuron decomposition.
-
-Important invariants:
-- recurrent mixed activations are rejected elsewhere rather than silently
-  decomposed here,
-- `allowMixedActivations` only affects the dense-family fallback path,
-- the returned tensor name is the canonical input for the next layer.
+Extract hidden layer sizes from ONNX initializers (weight tensors).
 
 Parameters:
-- `context` - Layer build context.
+- `initializers` - ONNX initializer tensors.
+- `metadataProps` - Optional ONNX metadata properties.
 
-Returns: Output tensor name produced by this layer.
-
-Example:
-
-```ts
-const outputName = emitLayerGraph({
-  model,
-  layers,
-  layerIndex: 2,
-  previousOutputName: 'Layer_1',
-  options: { allowMixedActivations: true },
-  recurrentLayerIndices: [],
-  batchDimension: false,
-  legacyNodeOrdering: false,
-});
-```
+Returns: Hidden layer sizes in order.
 
 ### emitFusedRecurrentHeuristics
 
@@ -589,6 +434,50 @@ Parameters:
 
 Returns: Nothing.
 
+### emitLayerGraph
+
+```ts
+emitLayerGraph(
+  context: LayerBuildContext,
+): string
+```
+
+Emit one export layer graph segment by routing the layer through the correct
+ONNX emission strategy.
+
+Dispatch order matters:
+- explicit Conv mappings win first,
+- recurrent single-step export is considered only for hidden layers with
+  self-connections,
+- non-recurrent layers fall back to compact dense emission or mixed-activation
+  per-neuron decomposition.
+
+Important invariants:
+- recurrent mixed activations are rejected elsewhere rather than silently
+  decomposed here,
+- `allowMixedActivations` only affects the dense-family fallback path,
+- the returned tensor name is the canonical input for the next layer.
+
+Parameters:
+- `context` - Layer build context.
+
+Returns: Output tensor name produced by this layer.
+
+Example:
+
+```ts
+const outputName = emitLayerGraph({
+  model,
+  layers,
+  layerIndex: 2,
+  previousOutputName: 'Layer_1',
+  options: { allowMixedActivations: true },
+  recurrentLayerIndices: [],
+  batchDimension: false,
+  legacyNodeOrdering: false,
+});
+```
+
 ### finalizeExportMetadata
 
 ```ts
@@ -614,6 +503,117 @@ Parameters:
 
 Returns: Nothing.
 
+### inferLayerOrdering
+
+```ts
+inferLayerOrdering(
+  network: default,
+): default[][]
+```
+
+Infer strictly layered ordering from a network.
+
+Parameters:
+- `network` - Source network.
+
+Returns: Ordered layers: input, hidden..., output.
+
+### OnnxModel
+
+ONNX-like model container (JSON-serializable).
+
+This is the main “wire format” object in this folder. Persist it as JSON text:
+
+```ts
+const jsonText = JSON.stringify(model);
+const restoredModel = JSON.parse(jsonText) as OnnxModel;
+```
+
+Notes:
+- `metadata_props` contains NeatapticTS-specific keys (layer sizes, recurrent flags,
+  conv/pool mappings, etc.). This is where most round-trip hints live.
+- Initializers currently store floating-point weights in `float_data`.
+
+Security/trust boundary:
+- Treat this as untrusted input if it comes from outside your process.
+
+### rebuildConnectionsLocal
+
+```ts
+rebuildConnectionsLocal(
+  networkLike: default,
+): void
+```
+
+Rebuild the network's flat connections array from each node's outgoing list.
+
+Parameters:
+- `networkLike` - Network-like instance to mutate.
+
+Returns: Nothing.
+
+### runOnnxExportFlow
+
+```ts
+runOnnxExportFlow(
+  network: default,
+  options: OnnxExportOptions,
+): OnnxModel
+```
+
+Execute the complete ONNX export flow for one network instance.
+
+High-level behavior:
+ 1. Rebuild runtime connection caches and assign stable export indices.
+ 2. Infer layered ordering and collect recurrent-pattern stubs.
+ 3. Validate structural constraints for the requested export options.
+ 4. Build ONNX graph payload and append inference-oriented metadata.
+
+Parameters:
+- `network` - Source network to serialize.
+- `options` - Optional ONNX export controls.
+
+Returns: ONNX-like model payload.
+
+### runOnnxImportFlow
+
+```ts
+runOnnxImportFlow(
+  onnx: OnnxModel,
+): default
+```
+
+Execute the complete ONNX import flow and reconstruct a runtime network.
+
+High-level behavior:
+ 1. Extract architecture dimensions and build a perceptron scaffold.
+ 2. Restore dense parameters and activation functions.
+ 3. Reconstruct recurrent/pooling metadata and rebuild connection caches.
+
+Parameters:
+- `onnx` - ONNX-like model payload to reconstruct.
+
+Returns: Reconstructed network instance.
+
+### validateLayerHomogeneityAndConnectivity
+
+```ts
+validateLayerHomogeneityAndConnectivity(
+  layers: default[][],
+  network: default,
+  options: OnnxExportOptions,
+): void
+```
+
+Validate connectivity and activation homogeneity constraints per layer.
+
+Parameters:
+- `layers` - Layered node arrays.
+- `network` - Source network (reserved for compatibility).
+- `options` - Export options.
+
+Returns: Nothing.
+
 ## architecture/network/onnx/network.onnx.utils.types.ts
 
 Types for NeatapticTS’s ONNX-like JSON export/import.
@@ -654,99 +654,29 @@ Stability & compatibility expectations:
 - The schema is JSON-first and may evolve; prefer re-exporting/importing through the
   library rather than hand-editing blobs.
 
-### Conv2DMapping
-
-Mapping declaration for treating a fully-connected layer as a 2D convolution during export.
-
-This does **not** magically turn an MLP into a convolutional network at runtime.
-It annotates a particular export-layer index with a conv interpretation so that:
-- The exported graph uses conv-shaped tensors/operators, and
-- Import can re-attach pooling/flatten metadata appropriately.
-
-Pitfall: mappings must match the actual layer sizes. If `inHeight * inWidth * inChannels`
-does not correspond to the prior layer width (and similarly for outputs), export or import
-may reject the model.
-
-### OnnxAttribute
-
-ONNX node attribute payload.
-
-This simplified JSON-first shape is enough for the operators emitted by the
-current exporter. It intentionally avoids protobuf-level complexity while
-still preserving the attribute variants needed by the importer.
-
-### OnnxDimension
-
-One dimension inside an ONNX tensor shape.
-
-Use `dim_value` for fixed numeric widths and `dim_param` for symbolic names
-such as a batch dimension.
-
-### OnnxGraph
-
-Graph body of an ONNX-like model.
-
-The exporter writes three main collections here:
-- `inputs` and `outputs` describe graph boundaries,
-- `initializer` stores constant tensors such as weights and biases,
-- `node` stores the ordered operator payloads that consume those tensors.
-
-### OnnxMetadataProperty
-
-Canonical metadata key-value pair used in ONNX model metadata_props.
-
-### OnnxModel
-
-ONNX-like model container (JSON-serializable).
-
-This is the main “wire format” object in this folder. Persist it as JSON text:
+### ActivationFunction
 
 ```ts
-const jsonText = JSON.stringify(model);
-const restoredModel = JSON.parse(jsonText) as OnnxModel;
+ActivationFunction(
+  x: number,
+  derivate: boolean | undefined,
+): number
 ```
 
-Notes:
-- `metadata_props` contains NeatapticTS-specific keys (layer sizes, recurrent flags,
-  conv/pool mappings, etc.). This is where most round-trip hints live.
-- Initializers currently store floating-point weights in `float_data`.
-
-Security/trust boundary:
-- Treat this as untrusted input if it comes from outside your process.
-
-### OnnxNode
-
-One ONNX operator invocation inside the graph.
-
-Nodes connect named tensors rather than object references, which keeps the
-exported payload easy to serialize, inspect, and diff as plain JSON.
-
-### OnnxShape
-
-ONNX tensor type shape.
-
-### OnnxTensor
-
-Serialized tensor payload stored inside graph initializers.
-
-NeatapticTS currently writes floating-point parameter vectors and matrices to
-`float_data`, along with the tensor name, element type, and logical shape.
-
-### OnnxTensorType
-
-ONNX tensor type.
-
-### OnnxValueInfo
+Runtime activation function signature used by ONNX activation import/export paths.
 
-ONNX value info (input/output description).
+Neataptic-style activations support a dual-purpose call pattern:
+- `derivate === false | undefined`: return activation output $f(x)$
+- `derivate === true`: return derivative $f'(x)$
 
-### Pool2DMapping
+This matches historical Neataptic semantics and keeps ONNX import/export compatible.
 
-Mapping describing a pooling operation inserted after a given export-layer index.
+Example:
 
-This is represented as metadata and optional graph nodes during export.
-Import uses it to attach pooling-related runtime metadata back onto the reconstructed
-network (when supported).
+```ts
+const y = activation(x);
+const dy = activation(x, true);
+```
 
 ### ActivationSquashFunction
 
@@ -759,6 +689,19 @@ ActivationSquashFunction(
 
 Activation function signature used by ONNX layer emission helpers.
 
+### Conv2DMapping
+
+Mapping declaration for treating a fully-connected layer as a 2D convolution during export.
+
+This does **not** magically turn an MLP into a convolutional network at runtime.
+It annotates a particular export-layer index with a conv interpretation so that:
+- The exported graph uses conv-shaped tensors/operators, and
+- Import can re-attach pooling/flatten metadata appropriately.
+
+Pitfall: mappings must match the actual layer sizes. If `inHeight * inWidth * inChannels`
+does not correspond to the prior layer width (and similarly for outputs), export or import
+may reject the model.
+
 ### ConvKernelConsistencyContext
 
 Context for kernel-coordinate consistency checks at one output position.
@@ -859,6 +802,10 @@ Context for ONNX fused recurrent initializer names.
 
 Context for heuristic GRU emission when a layer matches expected shape.
 
+### HiddenLayerActivationTraversalContext
+
+Hidden-layer traversal context for assigning imported activation functions.
+
 ### HiddenLayerHeuristicContext
 
 Context for one hidden layer during heuristic recurrent emission.
@@ -871,261 +818,205 @@ Append-an-index metadata context for JSON-array metadata keys.
 
 Activation analysis context for one layer.
 
-### LayerBuildContext
-
-Layer build context used while emitting one ONNX graph layer segment.
-
-### LayerRecurrentDecisionContext
-
-Context used to decide recurrent emission branch usage.
-
-### LayerTraversalContext
-
-Layer traversal context with adjacent layers and output classification.
-
-### LstmEmissionContext
-
-Context for heuristic LSTM emission when a layer matches expected shape.
-
-### OnnxBaseModelBuildContext
-
-Context for constructing a base ONNX model shell.
-
-### OnnxBuildResolvedOptions
-
-Resolved options used by ONNX model build orchestration.
-
-### OnnxConvEmissionContext
-
-Context used after resolving Conv mapping for one layer.
-
-### OnnxConvEmissionParams
-
-Parameters accepted by Conv layer emission.
-
-### OnnxConvParameters
-
-Flattened Conv parameters for ONNX initializers.
-
-### OnnxConvTensorNames
-
-Tensor names generated for Conv parameters.
-
-### OnnxExportOptions
-
-Options controlling ONNX-like export.
-
-These options trade off strictness, portability, and fidelity:
-
-- **Strict (default-ish)** export tries to keep the graph easy to interpret:
-  layered topology, homogeneous activations per layer, and fully-connected layers.
-
-- **Relaxed** export (`allowPartialConnectivity` / `allowMixedActivations`) can represent
-  more networks, but it may generate graphs that are primarily meant for NeatapticTS’s
-  importer (and may be less friendly to external ONNX tooling).
-
-- **Recurrent export** (`allowRecurrent`) is intentionally conservative and currently
-  focuses on a constrained single-step representation and optional fused heuristics.
-
-Key fields (high-level):
-- `includeMetadata`: includes `metadata_props` with architecture hints.
-- `opset`: numeric opset version stored in the exported model metadata (default is
-  resolved by the exporter; commonly 18 in this codebase).
-- `legacyNodeOrdering`: keeps older node ordering for backward compatibility.
-- `conv2dMappings` / `pool2dMappings`: encode conv/pool semantics for fully-connected
-  layers via explicit mapping declarations.
-
-### OnnxGraphDimensionBuildContext
-
-Context for constructing input/output ONNX graph dimensions.
-
-### OnnxGraphDimensions
-
-Output dimensions used by ONNX graph input/output value info payloads.
-
-### OnnxLayerEmissionContext
-
-Context for emitting non-input layers during model build.
-
-### OnnxLayerEmissionResult
-
-Result of emitting non-input export layers.
-
-### OnnxModelMetadataContext
+### LayerActivationValidationContext
 
-Context for applying optional ONNX model metadata.
+Activation-homogeneity decision context for one current layer.
 
-### OnnxPostProcessingContext
+### LayerBuildContext
 
-Context for post-processing and export metadata finalization.
+Layer build context used while emitting one ONNX graph layer segment.
 
-### OnnxRecurrentCollectionContext
+### LayerConnectivityValidationContext
 
-Context for collecting recurrent layer indices during model build.
+Connectivity decision context for one source-target node pair.
 
-### OnnxRecurrentInputValueInfoContext
+### LayerOrderingNodeGroups
 
-Context for constructing one recurrent previous-state graph input payload.
+Node partitions used by ONNX layered-ordering inference traversal.
 
-### OnnxRecurrentLayerProcessingContext
+### LayerOrderingResolutionContext
 
-Execution context for processing one hidden recurrent layer.
+Mutable traversal state while resolving hidden-layer ordering.
 
-### OnnxRecurrentLayerTraversalContext
+### LayerRecurrentDecisionContext
 
-Traversal context for one hidden layer during recurrent-input collection.
+Context used to decide recurrent emission branch usage.
 
-### OptionalLayerOutputParams
+### LayerTraversalContext
 
-Shared parameters for optional pooling/flatten output emission.
+Layer traversal context with adjacent layers and output classification.
 
-### OptionalPoolingAndFlattenParams
+### LayerValidationTraversalContext
 
-Parameters for optional pooling + flatten emission after a layer output.
+Layer-wise validation context for activation and connectivity checks.
 
-### PerNeuronConcatNodePayload
+### LstmEmissionContext
 
-Per-neuron concat node payload.
+Context for heuristic LSTM emission when a layer matches expected shape.
 
-### PerNeuronGraphNames
+### NetworkWithOnnxImportPooling
 
-Per-neuron graph tensor names.
+Network instance augmented with optional imported ONNX pooling metadata.
 
-### PerNeuronLayerContext
+### NodeInternals
 
-Per-neuron layer context alias.
+Runtime interface for accessing node internal properties.
 
-### PerNeuronLayerParams
+This is intentionally "internal": it exposes mutable fields that the ONNX exporter/importer
+needs (connections, bias, squash). Regular library users should generally interact with
+the public `Node` API instead.
 
-Parameters for per-neuron layer emission.
+### NodeInternalsWithExportIndex
 
-### PerNeuronNodeContext
+Runtime node internals augmented with optional export index metadata.
 
-Per-neuron normalized node context.
+### OnnxActivationAssignmentContext
 
-### PerNeuronSubgraphContext
+Shared activation-assignment context for hidden and output traversal.
 
-Per-neuron subgraph emission context.
+### OnnxActivationLayerOperations
 
-### PerNeuronTensorNames
+Layer-indexed activation operator lookup extracted from ONNX graph nodes.
 
-Per-neuron initializer tensor names.
+### OnnxActivationOperation
 
-### PoolingAttributes
+Supported ONNX activation operators recognized during activation import.
 
-Pooling tensor attributes for ONNX node payloads.
+### OnnxActivationOperationResolutionContext
 
-### PoolingEmissionContext
+Activation operation resolution context for one neuron or layer default.
 
-Pooling emission context resolved for one layer output.
+### OnnxActivationParseResult
 
-### RecurrentActivationEmissionContext
+Parsed ONNX activation-node naming payload.
 
-Context for selecting and emitting recurrent activation node payload.
+### OnnxAttribute
 
-### RecurrentGateBlockCollectionContext
+ONNX node attribute payload.
 
-Context for collecting one gate parameter block.
+This simplified JSON-first shape is enough for the operators emitted by the
+current exporter. It intentionally avoids protobuf-level complexity while
+still preserving the attribute variants needed by the importer.
 
-### RecurrentGateParameterCollectionResult
+### OnnxBaseModelBuildContext
 
-Flattened recurrent gate parameter vectors for one fused operator.
+Context for constructing a base ONNX model shell.
 
-### RecurrentGateRow
+### OnnxBuildResolvedOptions
 
-One recurrent gate row payload before flatten fold.
+Resolved options used by ONNX model build orchestration.
 
-### RecurrentGateRowCollectionContext
+### OnnxConvEmissionContext
 
-Context for collecting one recurrent gate row (one neuron).
+Context used after resolving Conv mapping for one layer.
 
-### RecurrentGemmEmissionContext
+### OnnxConvEmissionParams
 
-Context for emitting one Gemm node for recurrent single-step export.
+Parameters accepted by Conv layer emission.
 
-### RecurrentGraphNames
+### OnnxConvKernelCoordinate
 
-Derived graph names for one recurrent single-step layer payload.
+Coordinate for one Conv kernel weight lookup.
 
-### RecurrentHeuristicEmissionContext
+### OnnxConvParameters
 
-Context for heuristic recurrent operator emission traversal.
+Flattened Conv parameters for ONNX initializers.
 
-### RecurrentInitializerEmissionContext
+### OnnxConvTensorNames
 
-Context for pushing recurrent initializers into ONNX graph state.
+Tensor names generated for Conv parameters.
 
-### RecurrentInitializerNames
+### OnnxDimension
 
-Initializer tensor names for one single-step recurrent layer.
+One dimension inside an ONNX tensor shape.
 
-### RecurrentInitializerValues
+Use `dim_value` for fixed numeric widths and `dim_param` for symbolic names
+such as a batch dimension.
 
-Collected initializer vectors for one single-step recurrent layer.
+### OnnxExportOptions
 
-### RecurrentLayerEmissionContext
+Options controlling ONNX-like export.
 
-Derived execution context for single-step recurrent layer emission.
+These options trade off strictness, portability, and fidelity:
 
-### RecurrentLayerEmissionParams
+- **Strict (default-ish)** export tries to keep the graph easy to interpret:
+  layered topology, homogeneous activations per layer, and fully-connected layers.
 
-Parameters for single-step recurrent layer emission.
+- **Relaxed** export (`allowPartialConnectivity` / `allowMixedActivations`) can represent
+  more networks, but it may generate graphs that are primarily meant for NeatapticTS’s
+  importer (and may be less friendly to external ONNX tooling).
 
-### RecurrentRowCollectionContext
+- **Recurrent export** (`allowRecurrent`) is intentionally conservative and currently
+  focuses on a constrained single-step representation and optional fused heuristics.
 
-Context for collecting one recurrent matrix row.
+Key fields (high-level):
+- `includeMetadata`: includes `metadata_props` with architecture hints.
+- `opset`: numeric opset version stored in the exported model metadata (default is
+  resolved by the exporter; commonly 18 in this codebase).
+- `legacyNodeOrdering`: keeps older node ordering for backward compatibility.
+- `conv2dMappings` / `pool2dMappings`: encode conv/pool semantics for fully-connected
+  layers via explicit mapping declarations.
 
-### SharedActivationNodeBuildParams
+### OnnxFusedGateApplicationContext
 
-Shared parameters for constructing an activation node payload.
+Gate-weight application context for one reconstructed fused layer.
 
-### SharedGemmNodeBuildParams
+### OnnxFusedGateRowAssignmentContext
 
-Shared parameters for constructing a Gemm node payload.
+Context for assigning one gate-neuron row from flattened ONNX tensors.
 
-### SpecMetadataAppendContext
+### OnnxFusedLayerNeighborhood
 
-Append-a-spec metadata context for JSON-array metadata keys.
+Hidden-layer neighborhood slices around a reconstructed fused layer.
 
-### WeightToleranceComparisonContext
+### OnnxFusedLayerReconstructionContext
 
-Context for comparing two scalar weights with numeric tolerance.
+Execution context for one fused recurrent layer reconstruction.
 
-### NetworkWithOnnxImportPooling
+### OnnxFusedLayerRuntime
 
-Network instance augmented with optional imported ONNX pooling metadata.
+Runtime interface of a reconstructed fused recurrent layer instance.
 
-### OnnxImportArchitectureContext
+The importer only relies on a narrow runtime contract: access to the
+reconstructed nodes, an input wiring hook, and an optional output group that
+can be reconnected to the next restored layer.
 
-Shared architecture extraction context with resolved graph dimensions.
+### OnnxFusedRecurrentKind
 
-### OnnxImportArchitectureResult
+Supported fused recurrent operator families recognized during ONNX import.
 
-Parsed architecture dimensions extracted from ONNX import graph payloads.
+### OnnxFusedRecurrentSpec
 
-### OnnxImportDimensionRecord
+Fused recurrent family specification used during import reconstruction.
 
-Loose ONNX shape-dimension record used by legacy import payload access.
+This tells the importer how to interpret one emitted ONNX recurrent family:
+how many gates to expect, what order those gates were serialized in, and
+which gate owns the self-recurrent diagonal replay.
 
-### OnnxImportHiddenLayerSpan
+### OnnxFusedTensorPayload
 
-Hidden-layer span payload with one-based layer numbering and global offset.
+Fused recurrent tensor payload read from ONNX initializers.
 
-### OnnxImportLayerConnectionContext
+The importer resolves the three recurrent tensor families up front so the
+reconstruction pass can focus on wiring and row assignment instead of
+repeatedly re-looking up initializers.
 
-Execution context for assigning one hidden-layer recurrent diagonal tensor.
+### OnnxGraph
 
-### OnnxImportPoolingMetadata
+Graph body of an ONNX-like model.
 
-Parsed pooling metadata payload attached to imported network instances.
+The exporter writes three main collections here:
+- `inputs` and `outputs` describe graph boundaries,
+- `initializer` stores constant tensors such as weights and biases,
+- `node` stores the ordered operator payloads that consume those tensors.
 
-### OnnxImportRecurrentRestorationContext
+### OnnxGraphDimensionBuildContext
 
-Context for recurrent self-connection restoration from ONNX metadata and tensors.
+Context for constructing input/output ONNX graph dimensions.
 
-### OnnxImportSelfConnectionUpsertContext
+### OnnxGraphDimensions
 
-Context for upserting one hidden node self-connection from recurrent weight.
+Output dimensions used by ONNX graph input/output value info payloads.
 
 ### OnnxImportAggregatedLayerAssignmentContext
 
@@ -1135,6 +1026,14 @@ Context for assigning aggregated dense tensors for one layer.
 
 Context for assigning one aggregated dense target neuron row.
 
+### OnnxImportArchitectureContext
+
+Shared architecture extraction context with resolved graph dimensions.
+
+### OnnxImportArchitectureResult
+
+Parsed architecture dimensions extracted from ONNX import graph payloads.
+
 ### OnnxImportConvCoordinateAssignmentContext
 
 Context for applying Conv weights and bias at one output coordinate.
@@ -1167,6 +1066,14 @@ Coordinate for one Conv output neuron traversal position.
 
 Resolved Conv initializer tensors and dimensions for one layer.
 
+### OnnxImportDimensionRecord
+
+Loose ONNX shape-dimension record used by legacy import payload access.
+
+### OnnxImportHiddenLayerSpan
+
+Hidden-layer span payload with one-based layer numbering and global offset.
+
 ### OnnxImportHiddenSizeDerivationContext
 
 Context for deriving hidden layer sizes from initializer tensors and metadata.
@@ -1175,6 +1082,10 @@ Context for deriving hidden layer sizes from initializer tensors and metadata.
 
 Inbound connection lookup map keyed by source node for one target neuron.
 
+### OnnxImportLayerConnectionContext
+
+Execution context for assigning one hidden-layer recurrent diagonal tensor.
+
 ### OnnxImportLayerNodePair
 
 Node slices for one sequential imported layer assignment pass.
@@ -1199,6 +1110,18 @@ Context for assigning one per-neuron imported target node.
 
 Context for assigning per-neuron tensors for one layer.
 
+### OnnxImportPoolingMetadata
+
+Parsed pooling metadata payload attached to imported network instances.
+
+### OnnxImportRecurrentRestorationContext
+
+Context for recurrent self-connection restoration from ONNX metadata and tensors.
+
+### OnnxImportSelfConnectionUpsertContext
+
+Context for upserting one hidden node self-connection from recurrent weight.
+
 ### OnnxImportWeightAssignmentBuildParams
 
 Build params for creating shared ONNX import weight-assignment context.
@@ -1207,61 +1130,83 @@ Build params for creating shared ONNX import weight-assignment context.
 
 Shared weight-assignment context built once per ONNX import.
 
-### OnnxFusedGateApplicationContext
+### OnnxIncomingWeightAssignmentContext
 
-Gate-weight application context for one reconstructed fused layer.
+Context for assigning dense incoming weights for one gate-neuron row.
 
-### OnnxFusedGateRowAssignmentContext
+### OnnxLayerEmissionContext
 
-Context for assigning one gate-neuron row from flattened ONNX tensors.
+Context for emitting non-input layers during model build.
 
-### OnnxFusedLayerNeighborhood
+### OnnxLayerEmissionResult
 
-Hidden-layer neighborhood slices around a reconstructed fused layer.
+Result of emitting non-input export layers.
 
-### OnnxFusedLayerReconstructionContext
+### OnnxLayerFactory
 
-Execution context for one fused recurrent layer reconstruction.
+Runtime factory map used to construct dynamic recurrent layer modules.
 
-### OnnxFusedLayerRuntime
+### OnnxMetadataProperty
 
-Runtime interface of a reconstructed fused recurrent layer instance.
+Canonical metadata key-value pair used in ONNX model metadata_props.
 
-The importer only relies on a narrow runtime contract: access to the
-reconstructed nodes, an input wiring hook, and an optional output group that
-can be reconnected to the next restored layer.
+### OnnxModel
 
-### OnnxFusedRecurrentKind
+ONNX-like model container (JSON-serializable).
 
-Supported fused recurrent operator families recognized during ONNX import.
+This is the main “wire format” object in this folder. Persist it as JSON text:
 
-### OnnxFusedRecurrentSpec
+```ts
+const jsonText = JSON.stringify(model);
+const restoredModel = JSON.parse(jsonText) as OnnxModel;
+```
 
-Fused recurrent family specification used during import reconstruction.
+Notes:
+- `metadata_props` contains NeatapticTS-specific keys (layer sizes, recurrent flags,
+  conv/pool mappings, etc.). This is where most round-trip hints live.
+- Initializers currently store floating-point weights in `float_data`.
 
-This tells the importer how to interpret one emitted ONNX recurrent family:
-how many gates to expect, what order those gates were serialized in, and
-which gate owns the self-recurrent diagonal replay.
+Security/trust boundary:
+- Treat this as untrusted input if it comes from outside your process.
 
-### OnnxFusedTensorPayload
+### OnnxModelMetadataContext
 
-Fused recurrent tensor payload read from ONNX initializers.
+Context for applying optional ONNX model metadata.
 
-The importer resolves the three recurrent tensor families up front so the
-reconstruction pass can focus on wiring and row assignment instead of
-repeatedly re-looking up initializers.
+### OnnxNode
 
-### OnnxIncomingWeightAssignmentContext
+One ONNX operator invocation inside the graph.
+
+Nodes connect named tensors rather than object references, which keeps the
+exported payload easy to serialize, inspect, and diff as plain JSON.
+
+### OnnxPerceptronBuildContext
+
+Build context for mapping ONNX layer sizes into a Neataptic MLP factory call.
+
+### OnnxPerceptronSizeValidationContext
+
+Validation context for perceptron size-list checks during ONNX import.
+
+### OnnxPostProcessingContext
+
+Context for post-processing and export metadata finalization.
+
+### OnnxRecurrentCollectionContext
+
+Context for collecting recurrent layer indices during model build.
+
+### OnnxRecurrentInputValueInfoContext
 
-Context for assigning dense incoming weights for one gate-neuron row.
+Context for constructing one recurrent previous-state graph input payload.
 
-### OnnxPerceptronBuildContext
+### OnnxRecurrentLayerProcessingContext
 
-Build context for mapping ONNX layer sizes into a Neataptic MLP factory call.
+Execution context for processing one hidden recurrent layer.
 
-### OnnxPerceptronSizeValidationContext
+### OnnxRecurrentLayerTraversalContext
 
-Validation context for perceptron size-list checks during ONNX import.
+Traversal context for one hidden layer during recurrent-input collection.
 
 ### OnnxRuntimeFactories
 
@@ -1277,6 +1222,10 @@ OnnxRuntimeLayerFactory(
 
 Runtime layer-constructor signature used for recurrent layer reconstruction.
 
+### OnnxRuntimeLayerFactoryMap
+
+Runtime layer module shape widened for fused-recurrent reconstruction wiring.
+
 ### OnnxRuntimeLayerModule
 
 Runtime layer module shape consumed by ONNX import orchestration.
@@ -1291,242 +1240,261 @@ OnnxRuntimePerceptronFactory(
 
 Runtime perceptron factory signature used by ONNX import orchestration.
 
-### NodeInternals
+### OnnxShape
 
-Runtime interface for accessing node internal properties.
+ONNX tensor type shape.
 
-This is intentionally "internal": it exposes mutable fields that the ONNX exporter/importer
-needs (connections, bias, squash). Regular library users should generally interact with
-the public `Node` API instead.
+### OnnxTensor
 
-### NodeInternalsWithExportIndex
+Serialized tensor payload stored inside graph initializers.
 
-Runtime node internals augmented with optional export index metadata.
+NeatapticTS currently writes floating-point parameter vectors and matrices to
+`float_data`, along with the tensor name, element type, and logical shape.
 
-### ActivationFunction
+### OnnxTensorType
 
-```ts
-ActivationFunction(
-  x: number,
-  derivate: boolean | undefined,
-): number
-```
+ONNX tensor type.
 
-Runtime activation function signature used by ONNX activation import/export paths.
+### OnnxValueInfo
 
-Neataptic-style activations support a dual-purpose call pattern:
-- `derivate === false | undefined`: return activation output $f(x)$
-- `derivate === true`: return derivative $f'(x)$
+ONNX value info (input/output description).
 
-This matches historical Neataptic semantics and keeps ONNX import/export compatible.
+### OptionalLayerOutputParams
 
-Example:
+Shared parameters for optional pooling/flatten output emission.
 
-```ts
-const y = activation(x);
-const dy = activation(x, true);
-```
+### OptionalPoolingAndFlattenParams
 
-### LayerOrderingNodeGroups
+Parameters for optional pooling + flatten emission after a layer output.
 
-Node partitions used by ONNX layered-ordering inference traversal.
+### OutputLayerActivationContext
 
-### LayerOrderingResolutionContext
+Output-layer activation assignment context.
 
-Mutable traversal state while resolving hidden-layer ordering.
+### PerNeuronConcatNodePayload
 
-### LayerValidationTraversalContext
+Per-neuron concat node payload.
 
-Layer-wise validation context for activation and connectivity checks.
+### PerNeuronGraphNames
 
-### LayerActivationValidationContext
+Per-neuron graph tensor names.
 
-Activation-homogeneity decision context for one current layer.
+### PerNeuronLayerContext
 
-### LayerConnectivityValidationContext
+Per-neuron layer context alias.
 
-Connectivity decision context for one source-target node pair.
+### PerNeuronLayerParams
 
-### OnnxActivationOperation
+Parameters for per-neuron layer emission.
 
-Supported ONNX activation operators recognized during activation import.
+### PerNeuronNodeContext
 
-### OnnxActivationLayerOperations
+Per-neuron normalized node context.
 
-Layer-indexed activation operator lookup extracted from ONNX graph nodes.
+### PerNeuronSubgraphContext
 
-### OnnxActivationParseResult
+Per-neuron subgraph emission context.
 
-Parsed ONNX activation-node naming payload.
+### PerNeuronTensorNames
 
-### OnnxActivationAssignmentContext
+Per-neuron initializer tensor names.
 
-Shared activation-assignment context for hidden and output traversal.
+### Pool2DMapping
 
-### HiddenLayerActivationTraversalContext
+Mapping describing a pooling operation inserted after a given export-layer index.
 
-Hidden-layer traversal context for assigning imported activation functions.
+This is represented as metadata and optional graph nodes during export.
+Import uses it to attach pooling-related runtime metadata back onto the reconstructed
+network (when supported).
 
-### OutputLayerActivationContext
+### PoolingAttributes
 
-Output-layer activation assignment context.
+Pooling tensor attributes for ONNX node payloads.
 
-### OnnxActivationOperationResolutionContext
+### PoolingEmissionContext
 
-Activation operation resolution context for one neuron or layer default.
+Pooling emission context resolved for one layer output.
 
-### OnnxConvKernelCoordinate
+### RecurrentActivationEmissionContext
 
-Coordinate for one Conv kernel weight lookup.
+Context for selecting and emitting recurrent activation node payload.
 
-### OnnxLayerFactory
+### RecurrentGateBlockCollectionContext
 
-Runtime factory map used to construct dynamic recurrent layer modules.
+Context for collecting one gate parameter block.
 
-### OnnxRuntimeLayerFactoryMap
+### RecurrentGateParameterCollectionResult
 
-Runtime layer module shape widened for fused-recurrent reconstruction wiring.
+Flattened recurrent gate parameter vectors for one fused operator.
 
-## architecture/network/onnx/network.onnx.layer-analysis.utils.ts
+### RecurrentGateRow
 
-### rebuildConnectionsLocal
+One recurrent gate row payload before flatten fold.
 
-```ts
-rebuildConnectionsLocal(
-  networkLike: default,
-): void
-```
+### RecurrentGateRowCollectionContext
 
-Rebuild the network's flat connections array from each node's outgoing list.
+Context for collecting one recurrent gate row (one neuron).
 
-Parameters:
-- `networkLike` - Network-like instance to mutate.
+### RecurrentGemmEmissionContext
 
-Returns: Nothing.
+Context for emitting one Gemm node for recurrent single-step export.
 
-### mapActivationToOnnx
+### RecurrentGraphNames
 
-```ts
-mapActivationToOnnx(
-  squash: ((x: number, derivate?: boolean | undefined) => number) & { name?: string | undefined; },
-): OnnxActivationOperation
-```
+Derived graph names for one recurrent single-step layer payload.
 
-Map an internal activation function (squash) to an ONNX op_type.
+### RecurrentHeuristicEmissionContext
 
-Parameters:
-- `squash` - Activation function reference.
+Context for heuristic recurrent operator emission traversal.
 
-Returns: ONNX activation operator name.
+### RecurrentInitializerEmissionContext
 
-### inferLayerOrdering
+Context for pushing recurrent initializers into ONNX graph state.
+
+### RecurrentInitializerNames
+
+Initializer tensor names for one single-step recurrent layer.
+
+### RecurrentInitializerValues
+
+Collected initializer vectors for one single-step recurrent layer.
+
+### RecurrentLayerEmissionContext
+
+Derived execution context for single-step recurrent layer emission.
+
+### RecurrentLayerEmissionParams
+
+Parameters for single-step recurrent layer emission.
+
+### RecurrentRowCollectionContext
+
+Context for collecting one recurrent matrix row.
+
+### SharedActivationNodeBuildParams
+
+Shared parameters for constructing an activation node payload.
+
+### SharedGemmNodeBuildParams
+
+Shared parameters for constructing a Gemm node payload.
+
+### SpecMetadataAppendContext
+
+Append-a-spec metadata context for JSON-array metadata keys.
+
+### WeightToleranceComparisonContext
+
+Context for comparing two scalar weights with numeric tolerance.
+
+## architecture/network/onnx/network.onnx.layer-analysis.utils.ts
+
+### appendLastResolvedLayer
 
 ```ts
-inferLayerOrdering(
-  network: default,
-): default[][]
+appendLastResolvedLayer(
+  resolutionContext: LayerOrderingResolutionContext,
+): LayerOrderingResolutionContext
 ```
 
-Infer strictly layered ordering from a network.
+Append the final resolved hidden layer into ordered layer output.
 
 Parameters:
-- `network` - Source network.
+- `resolutionContext` - Final traversal state before append.
 
-Returns: Ordered layers: input, hidden..., output.
+Returns: Traversal state with last hidden layer persisted.
 
-### validateLayerHomogeneityAndConnectivity
+### buildLayerValidationContexts
 
 ```ts
-validateLayerHomogeneityAndConnectivity(
+buildLayerValidationContexts(
   layers: default[][],
-  network: default,
   options: OnnxExportOptions,
-): void
+): LayerValidationTraversalContext[]
 ```
 
-Validate connectivity and activation homogeneity constraints per layer.
+Build per-layer validation contexts for all non-input layers.
 
 Parameters:
-- `layers` - Layered node arrays.
-- `network` - Source network (reserved for compatibility).
-- `options` - Export options.
+- `layers` - Ordered network layers.
+- `options` - ONNX export options.
 
-Returns: Nothing.
+Returns: Traversal contexts used by layer validators.
 
-### collectUniqueOutgoingConnections
+### collectCurrentResolvableHiddenLayer
 
 ```ts
-collectUniqueOutgoingConnections(
-  nodes: default[],
+collectCurrentResolvableHiddenLayer(
+  resolutionContext: LayerOrderingResolutionContext,
 ): default[]
 ```
 
-Collect unique outgoing connections across a node list.
+Collect unresolved hidden nodes that can be placed in the next layer.
 
 Parameters:
-- `nodes` - Nodes to traverse.
+- `resolutionContext` - Current hidden-layer resolution context.
 
-Returns: Stable array of unique connections.
+Returns: Hidden nodes that are resolvable in this pass.
 
-### normalizeActivationName
+### collectLayerOrderingNodeGroups
 
 ```ts
-normalizeActivationName(
-  squash: ((x: number, derivate?: boolean | undefined) => number) & { name?: string | undefined; },
-): string
+collectLayerOrderingNodeGroups(
+  network: default,
+): LayerOrderingNodeGroups
 ```
 
-Normalize activation function name to uppercase for token matching.
+Partition all network nodes into input/hidden/output groups.
 
 Parameters:
-- `squash` - Runtime activation function reference.
+- `network` - Source network.
 
-Returns: Uppercased activation name or empty string.
+Returns: Node groups used by layered-ordering inference.
 
-### resolveOnnxActivationOperation
+### collectUniqueOutgoingConnections
 
 ```ts
-resolveOnnxActivationOperation(
-  normalizedActivationName: string,
-): OnnxActivationOperation
+collectUniqueOutgoingConnections(
+  nodes: default[],
+): default[]
 ```
 
-Resolve ONNX activation op from a normalized activation name token.
+Collect unique outgoing connections across a node list.
 
 Parameters:
-- `normalizedActivationName` - Uppercased activation name.
+- `nodes` - Nodes to traverse.
 
-Returns: ONNX activation operation.
+Returns: Stable array of unique connections.
 
-### warnWhenActivationFallbackIsUsed
+### createLayerActivationValidationContext
 
 ```ts
-warnWhenActivationFallbackIsUsed(
-  context: { squash: ((x: number, derivate?: boolean | undefined) => number) & { name?: string | undefined; }; resolvedActivationOperation: OnnxActivationOperation; },
-): void
+createLayerActivationValidationContext(
+  layerValidationContext: LayerValidationTraversalContext,
+): LayerActivationValidationContext
 ```
 
-Emit a warning when activation export falls back to Identity.
+Create activation validation context from one layer traversal context.
 
 Parameters:
-- `context` - Activation fallback evaluation context.
+- `layerValidationContext` - Layer validation context.
 
-Returns: Nothing.
+Returns: Activation validation context.
 
-### collectLayerOrderingNodeGroups
+### ensureLayerWasResolved
 
 ```ts
-collectLayerOrderingNodeGroups(
-  network: default,
-): LayerOrderingNodeGroups
+ensureLayerWasResolved(
+  currentLayerNodes: default[],
+): void
 ```
 
-Partition all network nodes into input/hidden/output groups.
+Ensure current hidden-layer resolution pass produced at least one node.
 
 Parameters:
-- `network` - Source network.
+- `currentLayerNodes` - Nodes resolved for current layer.
 
-Returns: Node groups used by layered-ordering inference.
+Returns: Nothing.
 
 ### filterNodesByType
 
@@ -1545,20 +1513,20 @@ Parameters:
 
 Returns: Matching nodes.
 
-### hasNoHiddenNodes
+### filterUnresolvedHiddenNodes
 
 ```ts
-hasNoHiddenNodes(
-  nodeGroups: LayerOrderingNodeGroups,
-): boolean
+filterUnresolvedHiddenNodes(
+  context: { remainingHiddenNodes: default[]; currentLayerNodes: default[]; },
+): default[]
 ```
 
-Check whether the layer groups contain no hidden nodes.
+Remove just-resolved hidden nodes from unresolved candidates.
 
 Parameters:
-- `nodeGroups` - Partitioned node groups.
+- `context` - Remaining/just-resolved hidden node context.
 
-Returns: True when hidden layer traversal can be skipped.
+Returns: Hidden nodes still unresolved.
 
 ### finalizeOrderingWithoutHiddenNodes
 
@@ -1575,215 +1543,247 @@ Parameters:
 
 Returns: Input and output layers only.
 
-### initializeLayerOrderingResolutionContext
+### finalizeOrderingWithOutputLayer
 
 ```ts
-initializeLayerOrderingResolutionContext(
+finalizeOrderingWithOutputLayer(
+  context: { orderedLayers: default[][]; outputNodes: default[]; },
+): default[][]
+```
+
+Append output layer to resolved input/hidden ordering.
+
+Parameters:
+- `context` - Final ordering context.
+
+Returns: Full layer ordering including output layer.
+
+### hasAllIncomingConnectionsFromPreviousLayer
+
+```ts
+hasAllIncomingConnectionsFromPreviousLayer(
+  context: { hiddenNode: default; previousLayerNodes: default[]; },
+): boolean
+```
+
+Check whether a hidden node receives all inputs from the previous layer.
+
+Parameters:
+- `context` - Hidden-node connectivity check context.
+
+Returns: True when the hidden node is layer-resolvable.
+
+### hasNoHiddenNodes
+
+```ts
+hasNoHiddenNodes(
   nodeGroups: LayerOrderingNodeGroups,
-): LayerOrderingResolutionContext
+): boolean
 ```
 
-Create initial hidden-layer resolution context.
+Check whether the layer groups contain no hidden nodes.
 
 Parameters:
 - `nodeGroups` - Partitioned node groups.
 
-Returns: Initial mutable state for hidden-layer resolution.
+Returns: True when hidden layer traversal can be skipped.
 
-### resolveAllHiddenLayers
+### inferLayerOrdering
 
 ```ts
-resolveAllHiddenLayers(
-  initialContext: LayerOrderingResolutionContext,
-): LayerOrderingResolutionContext
+inferLayerOrdering(
+  network: default,
+): default[][]
 ```
 
-Resolve all hidden layers in dependency order.
+Infer strictly layered ordering from a network.
 
 Parameters:
-- `initialContext` - Starting hidden-layer resolution context.
+- `network` - Source network.
 
-Returns: Final resolved layer-ordering context.
+Returns: Ordered layers: input, hidden..., output.
 
-### resolveNextHiddenLayer
+### initializeLayerOrderingResolutionContext
 
 ```ts
-resolveNextHiddenLayer(
-  resolutionContext: LayerOrderingResolutionContext,
+initializeLayerOrderingResolutionContext(
+  nodeGroups: LayerOrderingNodeGroups,
 ): LayerOrderingResolutionContext
 ```
 
-Resolve the next hidden layer from unresolved candidates.
+Create initial hidden-layer resolution context.
 
 Parameters:
-- `resolutionContext` - Current resolution state.
+- `nodeGroups` - Partitioned node groups.
 
-Returns: Updated resolution state.
+Returns: Initial mutable state for hidden-layer resolution.
 
-### collectCurrentResolvableHiddenLayer
+### mapActivationToOnnx
 
 ```ts
-collectCurrentResolvableHiddenLayer(
-  resolutionContext: LayerOrderingResolutionContext,
-): default[]
+mapActivationToOnnx(
+  squash: ((x: number, derivate?: boolean | undefined) => number) & { name?: string | undefined; },
+): OnnxActivationOperation
 ```
 
-Collect unresolved hidden nodes that can be placed in the next layer.
+Map an internal activation function (squash) to an ONNX op_type.
 
 Parameters:
-- `resolutionContext` - Current hidden-layer resolution context.
+- `squash` - Activation function reference.
 
-Returns: Hidden nodes that are resolvable in this pass.
+Returns: ONNX activation operator name.
 
-### hasAllIncomingConnectionsFromPreviousLayer
+### normalizeActivationName
 
 ```ts
-hasAllIncomingConnectionsFromPreviousLayer(
-  context: { hiddenNode: default; previousLayerNodes: default[]; },
-): boolean
+normalizeActivationName(
+  squash: ((x: number, derivate?: boolean | undefined) => number) & { name?: string | undefined; },
+): string
 ```
 
-Check whether a hidden node receives all inputs from the previous layer.
+Normalize activation function name to uppercase for token matching.
 
 Parameters:
-- `context` - Hidden-node connectivity check context.
+- `squash` - Runtime activation function reference.
 
-Returns: True when the hidden node is layer-resolvable.
+Returns: Uppercased activation name or empty string.
 
-### ensureLayerWasResolved
+### rebuildConnectionsLocal
 
 ```ts
-ensureLayerWasResolved(
-  currentLayerNodes: default[],
+rebuildConnectionsLocal(
+  networkLike: default,
 ): void
 ```
 
-Ensure current hidden-layer resolution pass produced at least one node.
+Rebuild the network's flat connections array from each node's outgoing list.
 
 Parameters:
-- `currentLayerNodes` - Nodes resolved for current layer.
+- `networkLike` - Network-like instance to mutate.
 
 Returns: Nothing.
 
-### filterUnresolvedHiddenNodes
+### resolveAllHiddenLayers
 
 ```ts
-filterUnresolvedHiddenNodes(
-  context: { remainingHiddenNodes: default[]; currentLayerNodes: default[]; },
-): default[]
+resolveAllHiddenLayers(
+  initialContext: LayerOrderingResolutionContext,
+): LayerOrderingResolutionContext
 ```
 
-Remove just-resolved hidden nodes from unresolved candidates.
+Resolve all hidden layers in dependency order.
 
 Parameters:
-- `context` - Remaining/just-resolved hidden node context.
+- `initialContext` - Starting hidden-layer resolution context.
 
-Returns: Hidden nodes still unresolved.
+Returns: Final resolved layer-ordering context.
 
-### appendLastResolvedLayer
+### resolveNextHiddenLayer
 
 ```ts
-appendLastResolvedLayer(
+resolveNextHiddenLayer(
   resolutionContext: LayerOrderingResolutionContext,
 ): LayerOrderingResolutionContext
 ```
 
-Append the final resolved hidden layer into ordered layer output.
+Resolve the next hidden layer from unresolved candidates.
 
 Parameters:
-- `resolutionContext` - Final traversal state before append.
+- `resolutionContext` - Current resolution state.
 
-Returns: Traversal state with last hidden layer persisted.
+Returns: Updated resolution state.
 
-### finalizeOrderingWithOutputLayer
+### resolveOnnxActivationOperation
 
 ```ts
-finalizeOrderingWithOutputLayer(
-  context: { orderedLayers: default[][]; outputNodes: default[]; },
-): default[][]
+resolveOnnxActivationOperation(
+  normalizedActivationName: string,
+): OnnxActivationOperation
 ```
 
-Append output layer to resolved input/hidden ordering.
+Resolve ONNX activation op from a normalized activation name token.
 
 Parameters:
-- `context` - Final ordering context.
+- `normalizedActivationName` - Uppercased activation name.
 
-Returns: Full layer ordering including output layer.
+Returns: ONNX activation operation.
 
-### buildLayerValidationContexts
+### validateLayerActivationHomogeneity
 
 ```ts
-buildLayerValidationContexts(
-  layers: default[][],
-  options: OnnxExportOptions,
-): LayerValidationTraversalContext[]
+validateLayerActivationHomogeneity(
+  activationValidationContext: LayerActivationValidationContext,
+): void
 ```
 
-Build per-layer validation contexts for all non-input layers.
+Validate that a layer has homogeneous activation unless explicitly allowed.
 
 Parameters:
-- `layers` - Ordered network layers.
-- `options` - ONNX export options.
+- `activationValidationContext` - Activation validation context.
 
-Returns: Traversal contexts used by layer validators.
+Returns: Nothing.
 
-### validateSingleLayer
+### validateLayerConnectivity
 
 ```ts
-validateSingleLayer(
+validateLayerConnectivity(
   layerValidationContext: LayerValidationTraversalContext,
 ): void
 ```
 
-Validate one current layer against activation/connectivity constraints.
+Validate that each current-layer node has required incoming connectivity.
 
 Parameters:
-- `layerValidationContext` - Layer validation context.
+- `layerValidationContext` - Layer connectivity traversal context.
 
 Returns: Nothing.
 
-### createLayerActivationValidationContext
+### validateLayerHomogeneityAndConnectivity
 
 ```ts
-createLayerActivationValidationContext(
-  layerValidationContext: LayerValidationTraversalContext,
-): LayerActivationValidationContext
+validateLayerHomogeneityAndConnectivity(
+  layers: default[][],
+  network: default,
+  options: OnnxExportOptions,
+): void
 ```
 
-Create activation validation context from one layer traversal context.
+Validate connectivity and activation homogeneity constraints per layer.
 
 Parameters:
-- `layerValidationContext` - Layer validation context.
+- `layers` - Layered node arrays.
+- `network` - Source network (reserved for compatibility).
+- `options` - Export options.
 
-Returns: Activation validation context.
+Returns: Nothing.
 
-### validateLayerActivationHomogeneity
+### validateSingleLayer
 
 ```ts
-validateLayerActivationHomogeneity(
-  activationValidationContext: LayerActivationValidationContext,
+validateSingleLayer(
+  layerValidationContext: LayerValidationTraversalContext,
 ): void
 ```
 
-Validate that a layer has homogeneous activation unless explicitly allowed.
+Validate one current layer against activation/connectivity constraints.
 
 Parameters:
-- `activationValidationContext` - Activation validation context.
+- `layerValidationContext` - Layer validation context.
 
 Returns: Nothing.
 
-### validateLayerConnectivity
+### validateSourceToTargetConnectivity
 
 ```ts
-validateLayerConnectivity(
-  layerValidationContext: LayerValidationTraversalContext,
+validateSourceToTargetConnectivity(
+  connectivityValidationContext: LayerConnectivityValidationContext,
 ): void
 ```
 
-Validate that each current-layer node has required incoming connectivity.
+Validate one source->target connection pair under export constraints.
 
 Parameters:
-- `layerValidationContext` - Layer connectivity traversal context.
+- `connectivityValidationContext` - Source/target connectivity context.
 
 Returns: Nothing.
 
@@ -1802,17 +1802,17 @@ Parameters:
 
 Returns: Nothing.
 
-### validateSourceToTargetConnectivity
+### warnWhenActivationFallbackIsUsed
 
 ```ts
-validateSourceToTargetConnectivity(
-  connectivityValidationContext: LayerConnectivityValidationContext,
+warnWhenActivationFallbackIsUsed(
+  context: { squash: ((x: number, derivate?: boolean | undefined) => number) & { name?: string | undefined; }; resolvedActivationOperation: OnnxActivationOperation; },
 ): void
 ```
 
-Validate one source->target connection pair under export constraints.
+Emit a warning when activation export falls back to Identity.
 
 Parameters:
-- `connectivityValidationContext` - Source/target connectivity context.
+- `context` - Activation fallback evaluation context.
 
 Returns: Nothing.