@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/architecture/network/README.md

@@ -824,6 +824,15 @@ Removes the connection from the network's `gates` list.
 
 ## architecture/network/network.utils.ts
 
+### __trainingInternals
+
+Test-only internal helper bundle.
+
+This is exported so unit tests can cover edge-cases in the smoothing logic without
+running full end-to-end training loops.
+
+Important: this is **not** considered stable public API. It may change between releases.
+
 ### activate
 
 ```ts
@@ -842,66 +851,35 @@ Parameters:
 
 Returns: Output activation values.
 
-### gaussianRand
-
-```ts
-gaussianRand(
-  rng: () => number,
-): number
-```
-
-Produce a normally distributed random sample using the Box-Muller transform.
-
-Parameters:
-- `rng` - Pseudo-random source in the interval [0, 1).
-
-Returns: Standard normal sample with mean 0 and variance 1.
-
-### noTraceActivate
+### activateBatch
 
 ```ts
-noTraceActivate(
-  input: number[],
-): number[]
+activateBatch(
+  inputs: number[][],
+  training: boolean,
+): number[][]
 ```
 
-Perform a forward pass without creating or updating training / gradient traces.
-
-This is the most allocation‑sensitive activation path. Internally it will attempt
-to leverage a compact "fast slab" routine (an optimized, vectorized broadcast over
-contiguous activation buffers) when the Network instance indicates that such a path
-is currently valid. If that attempt fails (for instance because the slab is stale
-after a structural mutation) execution gracefully falls back to a node‑by‑node loop.
+Activate the network over a mini‑batch (array) of input vectors, returning a 2‑D array of outputs.
 
-Algorithm outline:
- 1. (Optional) Refresh cached topological order if the network enforces acyclicity
-    and a structural change marked the order as dirty.
- 2. Validate the input dimensionality.
- 3. Try the fast slab path; if it throws, continue with the standard path.
- 4. Acquire a pooled output buffer sized to the number of output neurons.
- 5. Iterate all nodes in their internal order:
-      - Input nodes: directly assign provided input values.
-      - Hidden nodes: compute activation via Node.noTraceActivate (no bookkeeping).
-      - Output nodes: compute activation and store it (in sequence) inside the
-        pooled output buffer.
- 6. Copy the pooled buffer into a fresh array (detaches user from the pool) and
-    release the pooled buffer back to the pool.
+This helper simply loops, invoking {@link Network.activate} (or its bound variant) for each
+sample. It is intentionally naive: no attempt is made to fuse operations across the batch.
+For very large batch sizes or performance‑critical paths consider implementing a custom
+vectorized backend that exploits SIMD, GPU kernels, or parallel workers.
 
-Complexity considerations:
- - Time: O(N + E) where N = number of nodes, E = number of inbound edges processed
-   inside each Node.noTraceActivate call (not explicit here but inside the node).
- - Space: O(O) transient (O = number of outputs) due to the pooled output buffer.
+Input validation occurs per row to surface the earliest mismatch with a descriptive index.
 
 Parameters:
 - `this` - - Bound Network instance.
-- `input` - - Flat numeric vector whose length must equal network.input.
+- `inputs` - - Array of input vectors; each must have length == network.input.
+- `training` - - Whether each activation should keep training traces.
 
-Returns: Array of output neuron activations (length == network.output).
+Returns: 2‑D array: outputs[i] is the activation result for inputs[i].
 
 Example:
 
-const out = net.noTraceActivate([0.1, 0.2, 0.3]);
-console.log(out); // => e.g. [0.5123, 0.0441]
+const batchOut = net.activateBatch([[0,0,1],[1,0,0],[0,1,0]]);
+console.log(batchOut.length); // 3 rows
 
 ### activateRaw
 
@@ -932,35 +910,94 @@ Example:
 
 const y = net.activateRaw([0,1,0]);
 
-### activateBatch
+### addNodeBetweenImpl
 
 ```ts
-activateBatch(
-  inputs: number[][],
+addNodeBetweenImpl(): void
+```
+
+Split one randomly selected connection by inserting a hidden node.
+
+This preserves the long-standing public `addNodeBetween()` behavior:
+- it does not opt into `ADD_NODE` deterministic-chain policy,
+- it preserves the original source-edge weight on the first new connection,
+- it uses `1` for the hidden-to-target edge to keep the split easy to reason about.
+
+Parameters:
+- `this` - Target network instance.
+
+Returns: Nothing.
+
+### applyGradientClippingImpl
+
+```ts
+applyGradientClippingImpl(
+  net: default,
+  cfg: GradientClipRuntimeConfig,
+): void
+```
+
+Apply gradient clipping to a network using a normalized runtime configuration.
+
+This is a small wrapper that forwards to the concrete implementation used by training.
+
+Parameters:
+- `net` - - Network instance to update.
+- `cfg` - - Normalized clipping settings.
+
+### canUseFastSlab
+
+```ts
+canUseFastSlab(
   training: boolean,
-): number[][]
+): boolean
 ```
 
-Activate the network over a mini‑batch (array) of input vectors, returning a 2‑D array of outputs.
+Public convenience wrapper exposing fast path eligibility.
+Mirrors `_canUseFastSlab` internal predicate.
 
-This helper simply loops, invoking {@link Network.activate} (or its bound variant) for each
-sample. It is intentionally naive: no attempt is made to fuse operations across the batch.
-For very large batch sizes or performance‑critical paths consider implementing a custom
-vectorized backend that exploits SIMD, GPU kernels, or parallel workers.
+Parameters:
+- `training` - Whether caller is performing training (disables fast path if true).
 
-Input validation occurs per row to surface the earliest mismatch with a descriptive index.
+Returns: True when slab fast path predicates hold.
+
+### clearState
+
+```ts
+clearState(): void
+```
+
+Clear all node runtime traces and states.
 
 Parameters:
-- `this` - - Bound Network instance.
-- `inputs` - - Array of input vectors; each must have length == network.input.
-- `training` - - Whether each activation should keep training traces.
+- `this` - Bound network instance.
 
-Returns: 2‑D array: outputs[i] is the activation result for inputs[i].
+### cloneImpl
 
-Example:
+```ts
+cloneImpl(): default
+```
 
-const batchOut = net.activateBatch([[0,0,1],[1,0,0],[0,1,0]]);
-console.log(batchOut.length); // 3 rows
+Create a deep copy of one network through the verbose JSON round-trip.
+
+This keeps cloning behavior aligned with the same versioned payload contract
+used by `toJSON()` and `fromJSON()`, so clone semantics stay stable as the
+serialization chapter evolves.
+
+Parameters:
+- `this` - Target network instance.
+
+Returns: Deep-cloned network instance.
+
+### computeTopoOrder
+
+```ts
+computeTopoOrder(): void
+```
+
+Compute a topological ordering (Kahn's algorithm) for the current directed acyclic graph.
+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.
 
 ### connect
 
@@ -1009,174 +1046,194 @@ Example:
 
 const [edge] = net.connect(nodeA, nodeB, 0.5);
 
-### disconnect
+### createMLP
 
 ```ts
-disconnect(
-  from: default,
-  to: default,
-): void
+createMLP(
+  inputCount: number,
+  hiddenCounts: number[],
+  outputCount: number,
+): default
 ```
 
-Remove (at most) one directed connection from source 'from' to target 'to'.
-
-Only a single direct edge is removed because typical graph configurations maintain at most
-one logical connection between a given pair of nodes (excluding potential future multi‑edge
-semantics). If the target edge is gated we first call {@link Network.ungate} to maintain
-gating invariants (ensuring the gater node's internal gate list remains consistent).
-
-Algorithm outline:
- 1. Choose the correct list (selfconns vs connections) based on whether from === to.
- 2. Linear scan to find the first edge with matching endpoints.
- 3. If gated, ungate to detach gater bookkeeping.
- 4. Splice the edge out; exit loop (only one expected).
- 5. Delegate per‑node cleanup via from.disconnect(to) (clears reverse references, traces, etc.).
- 6. Mark structural caches dirty for lazy recomputation.
-
-Complexity:
- - Time: O(m) where m is length of the searched list (connections or selfconns).
- - Space: O(1) extra.
-
-Idempotence: If no such edge exists we still perform node-level disconnect and flag caches dirty –
-this conservative approach simplifies callers (they need not pre‑check existence).
+Build a strictly layered and fully connected MLP network.
 
 Parameters:
-- `this` - - Bound Network instance.
-- `from` - - Source node.
-- `to` - - Target node.
-
-Example:
+- `this` - Network constructor.
+- `inputCount` - Number of input nodes.
+- `hiddenCounts` - Hidden-layer node counts.
+- `outputCount` - Number of output nodes.
 
-net.disconnect(nodeA, nodeB);
+Returns: Newly created MLP network.
 
-### setSeed
+### crossOver
 
 ```ts
-setSeed(
-  seed: number,
-): void
+crossOver(
+  parentNetwork1: default,
+  parentNetwork2: default,
+  equal: boolean,
+): default
 ```
 
-Sets deterministic randomness for a network by installing a seed-backed RNG.
-
-Overview:
-- Use this before training, mutation, or stochastic operations when you need repeatable runs.
-- The same seed and operation order produce the same random sequence and reproducible outcomes.
-- This method delegates to setup utilities so behavior stays centralized across deterministic APIs.
-
-Parameters:
-- `this` - - Bound network instance whose RNG state is being initialized.
-- `seed` - - Seed value used to derive deterministic RNG state (low 32 bits are applied).
-
-Returns: Nothing.
+NEAT-inspired crossover between two parent networks producing a single offspring.
 
-Example:
+Conceptual model:
+- A "gene" corresponds to either a node choice at a structural index or a connection
+  keyed by innovation identity.
+- The offspring is assembled in two phases: node assignment first, then connection
+  materialization constrained by available offspring endpoints.
+- Fitness controls inheritance pressure unless `equal` is enabled, in which case both
+  parents contribute symmetrically where possible.
 
-```ts
-network.setSeed(42);
-```
+Simplifications relative to canonical NEAT:
+ - Innovation ID is synthesized from (from.index, to.index) via Connection.innovationID instead of
+   maintaining a global innovation number per mutation event.
+ - Node alignment relies on current index ordering. This is weaker than historical innovation
+   tracking, but adequate for many lightweight evolutionary experiments.
 
-### snapshotRNG
+Compatibility assumptions:
+- Both parents must expose identical input/output counts.
+- Parent node index ordering should represent comparable structural positions.
+- Parent fitness scores are interpreted by setup helpers when deciding fitter-parent inheritance.
 
-```ts
-snapshotRNG(): RNGSnapshot
-```
-
-Captures the current deterministic RNG lifecycle state as a portable snapshot.
+High-level algorithm:
+ 1. Validate that parents have identical I/O dimensionality (required for compatibility).
+ 2. Decide offspring node array length:
+      - If equal flag set or scores tied: random length in [minNodes, maxNodes].
+      - Else: length of fitter parent.
+ 3. For each index up to chosen size, pick a node gene from parents per rules:
+      - Input indices: always from parent1 (assumes identical input interface).
+      - Output indices (aligned from end): randomly choose if both present else take existing.
+      - Hidden indices: if both present pick randomly; else inherit from fitter (or either if equal).
+ 4. Reindex offspring nodes.
+ 5. Collect connections (standard + self) from each parent into maps keyed by innovationID capturing
+    weight, enabled flag, and gater index.
+ 6. For overlapping genes (present in both), randomly choose one; if either disabled apply optional
+    re-enable probability (reenableProb) to possibly re-activate.
+ 7. For disjoint/excess genes, inherit only from fitter parent (or both if equal flag set / scores tied).
+ 8. Materialize selected connection genes if their endpoints both exist in offspring; set weight & enabled state.
+ 9. Reattach gating if gater node exists in offspring.
 
-Overview:
-- Use this before temporary experiments, branching simulations, or stateful debug sessions.
-- The snapshot preserves enough information to resume from the same deterministic point later.
-- This is useful when comparing alternate algorithm branches from an identical random timeline.
+Enabled reactivation probability:
+ - Parents may carry disabled connections; offspring may re-enable them with a probability derived
+   from parent-specific _reenableProb (or default 0.25). This allows dormant structures to resurface.
 
 Parameters:
-- `this` - - Bound network instance whose RNG lifecycle state is captured.
+- `parentNetwork1` - - First parent (ties resolved in its favor when scores equal and equal=false for some cases).
+- `parentNetwork2` - - Second parent.
+- `equal` - - Force symmetric treatment regardless of fitness (true => node count random between sizes and both parents equally contribute disjoint genes).
 
-Returns: Snapshot containing deterministic progress metadata and RNG state payload.
+Returns: Offspring network instance.
 
 Example:
 
 ```ts
-const snapshot = network.snapshotRNG();
+const offspring = crossOver(parentA, parentB);
+offspring.mutate();
 ```
 
-### restoreRNG
+### describeArchitecture
 
 ```ts
-restoreRNG(
-  fn: () => number,
-): void
+describeArchitecture(
+  network: default,
+): NetworkArchitectureDescriptor
 ```
 
-Restores deterministic RNG lifecycle behavior from a provided RNG function.
+Describes network architecture for diagnostics, telemetry, and UI rendering.
 
-Overview:
-- Use this when replaying deterministic flows after custom serialization, hydration, or test setup.
-- The restored RNG function becomes the active random source used by the network lifecycle helpers.
-- This keeps deterministic plumbing explicit when external code owns RNG reconstruction.
+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:
-- `this` - - Bound network instance receiving the restored RNG lifecycle function.
-- `fn` - - Deterministic RNG function to install (expected to return values in `[0, 1)`).
+- `network` - - Runtime network instance.
 
-Returns: Nothing.
+Returns: Stable architecture descriptor.
 
 Example:
 
 ```ts
-network.restoreRNG(restoredRandomFunction);
+const descriptor = describeArchitecture(network);
+// descriptor.hiddenLayerSizes -> [8, 4]
+// descriptor.source -> 'layer-metadata' | 'graph-topology' | 'inferred'
 ```
 
-### getRNGState
+### deserialize
 
 ```ts
-getRNGState(): number | undefined
+deserialize(
+  data: CompactSerializedNetworkTuple,
+  inputSize: number | undefined,
+  outputSize: number | undefined,
+): default
 ```
 
-Returns the current deterministic RNG numeric state, when available.
+Rebuilds a network instance from compact tuple form.
 
-Overview:
-- Use this for lightweight checkpointing when full lifecycle snapshots are unnecessary.
-- The value can be persisted and later reapplied through `setRNGState`.
-- This is commonly used by tests that assert deterministic continuity across operations.
+Use this importer for compact payloads produced by `serialize`.
+Optional `inputSize` and `outputSize` let callers enforce shape overrides at import time.
 
 Parameters:
-- `this` - - Bound network instance queried for deterministic RNG numeric state.
+- `data` - - Compact tuple payload.
+- `inputSize` - - Optional input-size override that takes precedence over serialized input.
+- `outputSize` - - Optional output-size override that takes precedence over serialized output.
 
-Returns: Numeric RNG state value, or `undefined` when no deterministic state exists yet.
+Returns: Reconstructed network instance.
 
 Example:
 
 ```ts
-const state = network.getRNGState();
+import { deserialize } from './network.serialize.utils';
+
+const rebuiltNetwork = deserialize(compactTuple, 2, 1);
 ```
 
-### setRNGState
+### disconnect
 
 ```ts
-setRNGState(
-  state: number,
+disconnect(
+  from: default,
+  to: default,
 ): void
 ```
 
-Applies a deterministic RNG numeric state to continue from a known checkpoint.
+Remove (at most) one directed connection from source 'from' to target 'to'.
 
-Overview:
-- Pair this with `getRNGState` to pause/resume deterministic sequences.
-- Useful for reproducible tests, multi-stage training workflows, and deterministic replay.
-- Delegation keeps the write path consistent with the rest of deterministic state utilities.
+Only a single direct edge is removed because typical graph configurations maintain at most
+one logical connection between a given pair of nodes (excluding potential future multi‑edge
+semantics). If the target edge is gated we first call {@link Network.ungate} to maintain
+gating invariants (ensuring the gater node's internal gate list remains consistent).
 
-Parameters:
-- `this` - - Bound network instance receiving deterministic RNG state.
-- `state` - - Numeric RNG state checkpoint to install.
+Algorithm outline:
+ 1. Choose the correct list (selfconns vs connections) based on whether from === to.
+ 2. Linear scan to find the first edge with matching endpoints.
+ 3. If gated, ungate to detach gater bookkeeping.
+ 4. Splice the edge out; exit loop (only one expected).
+ 5. Delegate per‑node cleanup via from.disconnect(to) (clears reverse references, traces, etc.).
+ 6. Mark structural caches dirty for lazy recomputation.
 
-Returns: Nothing.
+Complexity:
+ - Time: O(m) where m is length of the searched list (connections or selfconns).
+ - Space: O(1) extra.
+
+Idempotence: If no such edge exists we still perform node-level disconnect and flag caches dirty –
+this conservative approach simplifies callers (they need not pre‑check existence).
+
+Parameters:
+- `this` - - Bound Network instance.
+- `from` - - Source node.
+- `to` - - Target node.
 
 Example:
 
-```ts
-network.setRNGState(savedState);
-```
+net.disconnect(nodeA, nodeB);
 
 ### evolveNetwork
 
@@ -1219,6 +1276,57 @@ const summary = await network.evolve(trainingSet, {
 console.log(summary.error, summary.iterations, summary.time);
 ```
 
+### fastSlabActivate
+
+```ts
+fastSlabActivate(
+  input: number[],
+): number[]
+```
+
+High‑performance forward pass using packed slabs + CSR adjacency.
+
+Fallback Conditions (auto‑detected):
+ - Missing slabs / adjacency structures.
+ - Topology/gating/stochastic predicates fail (see `_canUseFastSlab`).
+ - Gating present, when applicable (explicit guard).
+
+Implementation Notes:
+ - Reuses internal activation/state buffers to reduce per‑step allocation churn.
+ - Applies gain multiplication if optional gain slab exists.
+ - Assumes acyclic graph; topological order recomputed on demand if marked dirty.
+
+Parameters:
+- `input` - Input vector (length must equal `network.input`).
+
+Returns: Output activations (detached plain array) of length `network.output`.
+
+### fromJSONImpl
+
+```ts
+fromJSONImpl(
+  json: NetworkJSON,
+): default
+```
+
+Reconstructs a network instance from the verbose JSON payload.
+
+This importer validates payload shape, restores dropout and topology, and then rebuilds
+connections, gating relationships, and optional enabled flags.
+
+Parameters:
+- `json` - - Verbose JSON payload.
+
+Returns: Reconstructed network instance.
+
+Example:
+
+```ts
+import { fromJSONImpl } from './network.serialize.utils';
+
+const rebuiltNetwork = fromJSONImpl(snapshotJson);
+```
+
 ### gate
 
 ```ts
@@ -1242,110 +1350,152 @@ Parameters:
 - `node` - - Candidate gater node (must belong to network).
 - `connection` - - Connection to gate.
 
-### ungate
+### gaussianRand
 
 ```ts
-ungate(
-  connection: default,
-): void
+gaussianRand(
+  rng: () => number,
+): number
 ```
 
-Remove gating from a connection, restoring its static weight contribution.
+Produce a normally distributed random sample using the Box-Muller transform.
 
-Idempotent: If the connection is not currently gated, the call performs no structural changes
-(and optionally logs a warning). After ungating, the connection's weight will be used directly
-without modulation by a gater activation.
+Parameters:
+- `rng` - Pseudo-random source in the interval [0, 1).
 
-Complexity: O(n) where n = number of gated connections (indexOf lookup) – typically small.
+Returns: Standard normal sample with mean 0 and variance 1.
+
+### generateStandalone
+
+```ts
+generateStandalone(
+  net: default,
+): string
+```
+
+Generate a standalone JavaScript source string that returns an `activate(input:number[])` function.
+
+Implementation Steps:
+ 1. Validate presence of output nodes (must produce something observable).
+ 2. Assign stable sequential indices to nodes (used as array offsets in generated code).
+ 3. Collect initial activation/state values into typed array initializers for warm starting.
+ 4. For each non-input node, build a line computing S[i] (pre-activation sum with bias) and A[i]
+    (post-activation output). Gating multiplies activation by gate activations; self-connection adds
+    recurrent term S[i] * weight before activation.
+ 5. De-duplicate activation functions: each unique squash name is emitted once; references become
+    indices into array F of function references for compactness.
+ 6. Emit an IIFE producing the activate function with internal arrays A (activations) and S (states).
 
 Parameters:
-- `this` - - Bound Network instance.
-- `connection` - - Connection to ungate.
+- `net` - Network instance to snapshot.
 
-### crossOver
+Returns: Source string (ES5-compatible) – safe to eval in sandbox to obtain activate function.
+
+### getConnectionSlab
 
 ```ts
-crossOver(
-  parentNetwork1: default,
-  parentNetwork2: default,
-  equal: boolean,
-): default
+getConnectionSlab(): ConnectionSlabView
 ```
 
-NEAT-inspired crossover between two parent networks producing a single offspring.
+Obtain (and lazily rebuild if dirty) the current packed SoA view of connections.
 
-Conceptual model:
-- A "gene" corresponds to either a node choice at a structural index or a connection
-  keyed by innovation identity.
-- The offspring is assembled in two phases: node assignment first, then connection
-  materialization constrained by available offspring endpoints.
-- Fitness controls inheritance pressure unless `equal` is enabled, in which case both
-  parents contribute symmetrically where possible.
+Gain Omission: If the internal gain slab is absent (all gains neutral) a synthetic
+neutral array is created and returned (NOT retained) to keep external educational
+tooling branch‑free while preserving omission memory savings internally.
 
-Simplifications relative to canonical NEAT:
- - Innovation ID is synthesized from (from.index, to.index) via Connection.innovationID instead of
-   maintaining a global innovation number per mutation event.
- - Node alignment relies on current index ordering. This is weaker than historical innovation
-   tracking, but adequate for many lightweight evolutionary experiments.
+Returns: Read‑only style view (do not mutate) containing typed arrays + metadata.
 
-Compatibility assumptions:
-- Both parents must expose identical input/output counts.
-- Parent node index ordering should represent comparable structural positions.
-- Parent fitness scores are interpreted by setup helpers when deciding fitter-parent inheritance.
+### getCurrentSparsity
 
-High-level algorithm:
- 1. Validate that parents have identical I/O dimensionality (required for compatibility).
- 2. Decide offspring node array length:
-      - If equal flag set or scores tied: random length in [minNodes, maxNodes].
-      - Else: length of fitter parent.
- 3. For each index up to chosen size, pick a node gene from parents per rules:
-      - Input indices: always from parent1 (assumes identical input interface).
-      - Output indices (aligned from end): randomly choose if both present else take existing.
-      - Hidden indices: if both present pick randomly; else inherit from fitter (or either if equal).
- 4. Reindex offspring nodes.
- 5. Collect connections (standard + self) from each parent into maps keyed by innovationID capturing
-    weight, enabled flag, and gater index.
- 6. For overlapping genes (present in both), randomly choose one; if either disabled apply optional
-    re-enable probability (reenableProb) to possibly re-activate.
- 7. For disjoint/excess genes, inherit only from fitter parent (or both if equal flag set / scores tied).
- 8. Materialize selected connection genes if their endpoints both exist in offspring; set weight & enabled state.
- 9. Reattach gating if gater node exists in offspring.
+```ts
+getCurrentSparsity(): number
+```
 
-Enabled reactivation probability:
- - Parents may carry disabled connections; offspring may re-enable them with a probability derived
-   from parent-specific _reenableProb (or default 0.25). This allows dormant structures to resurface.
+Current sparsity fraction relative to the training-time pruning baseline.
+
+Returns: Current sparsity in the [0,1] range when baseline is available.
+
+### getRegularizationStats
+
+```ts
+getRegularizationStats(): Record<string, unknown> | null
+```
+
+Obtain the last recorded regularization / stochastic statistics snapshot.
+
+Returns a defensive deep copy so callers can inspect metrics without risking mutation of the
+internal `_lastStats` object maintained by the training loop (e.g., during pruning, dropout, or
+noise scheduling updates).
+
+Returns: A deep-cloned stats object or null if no stats have been recorded yet.
+
+### getRNGState
+
+```ts
+getRNGState(): number | undefined
+```
+
+Returns the current deterministic RNG numeric state, when available.
+
+Overview:
+- Use this for lightweight checkpointing when full lifecycle snapshots are unnecessary.
+- The value can be persisted and later reapplied through `setRNGState`.
+- This is commonly used by tests that assert deterministic continuity across operations.
 
 Parameters:
-- `parentNetwork1` - - First parent (ties resolved in its favor when scores equal and equal=false for some cases).
-- `parentNetwork2` - - Second parent.
-- `equal` - - Force symmetric treatment regardless of fitness (true => node count random between sizes and both parents equally contribute disjoint genes).
+- `this` - - Bound network instance queried for deterministic RNG numeric state.
 
-Returns: Offspring network instance.
+Returns: Numeric RNG state value, or `undefined` when no deterministic state exists yet.
 
 Example:
 
 ```ts
-const offspring = crossOver(parentA, parentB);
-offspring.mutate();
+const state = network.getRNGState();
 ```
 
-### addNodeBetweenImpl
+### getSlabAllocationStats
 
 ```ts
-addNodeBetweenImpl(): void
+getSlabAllocationStats(): { pool: { [x: string]: PoolKeyMetrics; }; fresh: number; pooled: number; }
 ```
 
-Split one randomly selected connection by inserting a hidden node.
+Allocation statistics snapshot for slab typed arrays.
 
-This preserves the long-standing public `addNodeBetween()` behavior:
-- it does not opt into `ADD_NODE` deterministic-chain policy,
-- it preserves the original source-edge weight on the first new connection,
-- it uses `1` for the hidden-to-target edge to keep the split easy to reason about.
+Includes:
+ - fresh: number of newly constructed typed arrays since process start / metrics reset.
+ - pooled: number of arrays served from the pool.
+ - pool: per‑key metrics (created, reused, maxRetained) for educational inspection.
 
-Parameters:
-- `this` - Target network instance.
+NOTE: Stats are cumulative (not auto‑reset); callers may diff successive snapshots.
 
-Returns: Nothing.
+Returns: Plain object copy (safe to serialize) of current allocator counters.
+
+### hasPath
+
+```ts
+hasPath(
+  from: default,
+  to: default,
+): boolean
+```
+
+Depth-first reachability test (avoids infinite loops via visited set).
+
+### maybePrune
+
+```ts
+maybePrune(
+  iteration: number,
+): void
+```
+
+Perform scheduled pruning at a given training iteration if conditions are met.
+
+Scheduling fields (cfg): start, end, frequency, targetSparsity, method ('magnitude' | 'snip'), regrowFraction.
+The target sparsity ramps linearly from 0 at start to cfg.targetSparsity at end.
+
+Parameters:
+- `iteration` - Current (0-based or 1-based) training iteration counter used for scheduling.
 
 ### mutateImpl
 
@@ -1380,21 +1530,75 @@ network.mutate('ADD_NODE');
 network.mutate({ name: 'MOD_WEIGHT', min: -0.1, max: 0.1 });
 ```
 
-### maybePrune
+### noTraceActivate
 
 ```ts
-maybePrune(
-  iteration: number,
-): void
+noTraceActivate(
+  input: number[],
+): number[]
 ```
 
-Perform scheduled pruning at a given training iteration if conditions are met.
+Perform a forward pass without creating or updating training / gradient traces.
 
-Scheduling fields (cfg): start, end, frequency, targetSparsity, method ('magnitude' | 'snip'), regrowFraction.
-The target sparsity ramps linearly from 0 at start to cfg.targetSparsity at end.
+This is the most allocation‑sensitive activation path. Internally it will attempt
+to leverage a compact "fast slab" routine (an optimized, vectorized broadcast over
+contiguous activation buffers) when the Network instance indicates that such a path
+is currently valid. If that attempt fails (for instance because the slab is stale
+after a structural mutation) execution gracefully falls back to a node‑by‑node loop.
+
+Algorithm outline:
+ 1. (Optional) Refresh cached topological order if the network enforces acyclicity
+    and a structural change marked the order as dirty.
+ 2. Validate the input dimensionality.
+ 3. Try the fast slab path; if it throws, continue with the standard path.
+ 4. Acquire a pooled output buffer sized to the number of output neurons.
+ 5. Iterate all nodes in their internal order:
+      - Input nodes: directly assign provided input values.
+      - Hidden nodes: compute activation via Node.noTraceActivate (no bookkeeping).
+      - Output nodes: compute activation and store it (in sequence) inside the
+        pooled output buffer.
+ 6. Copy the pooled buffer into a fresh array (detaches user from the pool) and
+    release the pooled buffer back to the pool.
+
+Complexity considerations:
+ - Time: O(N + E) where N = number of nodes, E = number of inbound edges processed
+   inside each Node.noTraceActivate call (not explicit here but inside the node).
+ - Space: O(O) transient (O = number of outputs) due to the pooled output buffer.
 
 Parameters:
-- `iteration` - Current (0-based or 1-based) training iteration counter used for scheduling.
+- `this` - - Bound Network instance.
+- `input` - - Flat numeric vector whose length must equal network.input.
+
+Returns: Array of output neuron activations (length == network.output).
+
+Example:
+
+const out = net.noTraceActivate([0.1, 0.2, 0.3]);
+console.log(out); // => e.g. [0.5123, 0.0441]
+
+### propagate
+
+```ts
+propagate(
+  rate: number,
+  momentum: number,
+  update: boolean,
+  target: number[],
+  regularization: number,
+  costDerivative: CostDerivative | undefined,
+): void
+```
+
+Propagate output and hidden errors backward through the network.
+
+Parameters:
+- `this` - Bound network instance.
+- `rate` - Learning rate.
+- `momentum` - Momentum factor.
+- `update` - Whether to apply updates immediately.
+- `target` - Output target values.
+- `regularization` - L2 regularization factor.
+- `costDerivative` - Optional output-node derivative override.
 
 ### pruneToSparsity
 
@@ -1415,496 +1619,309 @@ Parameters:
 
 Returns: Nothing.
 
-### getCurrentSparsity
+### rebuildConnections
 
 ```ts
-getCurrentSparsity(): number
+rebuildConnections(
+  networkInstance: default,
+): void
 ```
 
-Current sparsity fraction relative to the training-time pruning baseline.
+Rebuild the canonical connection array from per-node outgoing lists.
 
-Returns: Current sparsity in the [0,1] range when baseline is available.
+Parameters:
+- `networkInstance` - Target network.
 
-### removeNode
+### rebuildConnectionSlab
 
 ```ts
-removeNode(
-  node: default,
+rebuildConnectionSlab(
+  force: boolean,
 ): void
 ```
 
-Remove a hidden node from the network while minimally repairing connectivity.
+Build (or refresh) the packed connection slabs for the network synchronously.
+
+ACTIONS
+-------
+1. Optionally reindex nodes if structural mutations invalidated indices.
+2. Grow (geometric) or reuse existing typed arrays to ensure capacity >= active connections.
+3. Populate the logical slice [0, connectionCount) with weight/from/to/flag data.
+4. Lazily allocate gain & plastic slabs only on first non‑neutral / plastic encounter; omit otherwise.
+5. Release previously allocated optional slabs when they revert to neutral / unused (omission optimization).
+6. Update internal bookkeeping: logical count, dirty flags, version counter.
+
+PERFORMANCE
+-----------
+O(C) over active connections with amortized allocation cost due to geometric growth.
 
 Parameters:
-- `this` - Network instance (bound implicitly via method-style call).
-- `node` - The node object to remove (must be of type 'hidden').
+- `force` - When true forces rebuild even if network not marked dirty (useful for timing tests).
 
-### serialize
+### rebuildConnectionSlabAsync
 
 ```ts
-serialize(): CompactSerializedNetworkTuple
+rebuildConnectionSlabAsync(
+  chunkSize: number,
+): Promise<void>
 ```
 
-Serializes a network instance into the compact tuple format.
+Cooperative asynchronous slab rebuild (Browser only).
 
-Use this format when payload size and serialization speed matter more than readability.
-The tuple layout is positional and optimized for transport/storage efficiency.
+Strategy:
+ - Perform capacity decision + allocation up front (mirrors sync path).
+ - Populate connection data in microtask slices (yield via resolved Promise) to avoid long main‑thread stalls.
+ - Adaptive slice sizing for very large graphs if `config.browserSlabChunkTargetMs` set.
+
+Metrics: Increments `_slabAsyncBuilds` for observability.
+Fallback: On Node (no `window`) defers to synchronous rebuild for simplicity.
 
 Parameters:
-- `this` - - Bound network instance.
+- `chunkSize` - Initial maximum connections per slice (may be reduced adaptively for huge graphs).
 
-Returns: Compact tuple payload containing activations, states, squash keys, connections, and input/output sizes.
+Returns: Promise resolving once rebuild completes.
 
-Example:
+### removeNode
 
 ```ts
-import Network from '../../network';
-import { deserialize, serialize } from './network.serialize.utils';
-
-const sourceNetwork = new Network(2, 1);
-const compactTuple = serialize.call(sourceNetwork);
-const rebuiltNetwork = deserialize(compactTuple);
+removeNode(
+  node: default,
+): void
 ```
 
-### deserialize
+Remove a hidden node from the network while minimally repairing connectivity.
 
-```ts
-deserialize(
-  data: CompactSerializedNetworkTuple,
-  inputSize: number | undefined,
-  outputSize: number | undefined,
-): default
+Parameters:
+- `this` - Network instance (bound implicitly via method-style call).
+- `node` - The node object to remove (must be of type 'hidden').
+
+### resolveArchitectureDescriptor
+
+```ts
+resolveArchitectureDescriptor(
+  network: default,
+): NetworkArchitectureDescriptor
 ```
 
-Rebuilds a network instance from compact tuple form.
+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.
 
-Use this importer for compact payloads produced by `serialize`.
-Optional `inputSize` and `outputSize` let callers enforce shape overrides at import time.
+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:
-- `data` - - Compact tuple payload.
-- `inputSize` - - Optional input-size override that takes precedence over serialized input.
-- `outputSize` - - Optional output-size override that takes precedence over serialized output.
+- `network` - Runtime network instance.
 
-Returns: Reconstructed network instance.
+Returns: Public architecture descriptor for telemetry and UI consumers.
 
-Example:
+### restoreRNG
 
 ```ts
-import { deserialize } from './network.serialize.utils';
+restoreRNG(
+  fn: () => number,
+): void
+```
 
-const rebuiltNetwork = deserialize(compactTuple, 2, 1);
+Restores deterministic RNG lifecycle behavior from a provided RNG function.
+
+Overview:
+- Use this when replaying deterministic flows after custom serialization, hydration, or test setup.
+- The restored RNG function becomes the active random source used by the network lifecycle helpers.
+- This keeps deterministic plumbing explicit when external code owns RNG reconstruction.
+
+Parameters:
+- `this` - - Bound network instance receiving the restored RNG lifecycle function.
+- `fn` - - Deterministic RNG function to install (expected to return values in `[0, 1)`).
+
+Returns: Nothing.
+
+Example:
+
+```ts
+network.restoreRNG(restoredRandomFunction);
 ```
 
-### toJSONImpl
+### serialize
 
 ```ts
-toJSONImpl(): NetworkJSON
+serialize(): CompactSerializedNetworkTuple
 ```
 
-Serializes a network instance into the verbose JSON format.
+Serializes a network instance into the compact tuple format.
 
-Use this format when you need human-readable snapshots, explicit schema versioning,
-and better forward/backward compatibility handling.
+Use this format when payload size and serialization speed matter more than readability.
+The tuple layout is positional and optimized for transport/storage efficiency.
 
 Parameters:
 - `this` - - Bound network instance.
 
-Returns: Versioned JSON payload with shape metadata, nodes, and connections.
+Returns: Compact tuple payload containing activations, states, squash keys, connections, and input/output sizes.
 
 Example:
 
 ```ts
 import Network from '../../network';
-import { fromJSONImpl, toJSONImpl } from './network.serialize.utils';
+import { deserialize, serialize } from './network.serialize.utils';
 
-const sourceNetwork = new Network(3, 1);
-const snapshotJson = toJSONImpl.call(sourceNetwork);
-const rebuiltNetwork = fromJSONImpl(snapshotJson);
+const sourceNetwork = new Network(2, 1);
+const compactTuple = serialize.call(sourceNetwork);
+const rebuiltNetwork = deserialize(compactTuple);
 ```
 
-### fromJSONImpl
+### setRNGState
 
 ```ts
-fromJSONImpl(
-  json: NetworkJSON,
-): default
+setRNGState(
+  state: number,
+): void
 ```
 
-Reconstructs a network instance from the verbose JSON payload.
+Applies a deterministic RNG numeric state to continue from a known checkpoint.
 
-This importer validates payload shape, restores dropout and topology, and then rebuilds
-connections, gating relationships, and optional enabled flags.
+Overview:
+- Pair this with `getRNGState` to pause/resume deterministic sequences.
+- Useful for reproducible tests, multi-stage training workflows, and deterministic replay.
+- Delegation keeps the write path consistent with the rest of deterministic state utilities.
 
 Parameters:
-- `json` - - Verbose JSON payload.
+- `this` - - Bound network instance receiving deterministic RNG state.
+- `state` - - Numeric RNG state checkpoint to install.
 
-Returns: Reconstructed network instance.
+Returns: Nothing.
 
 Example:
 
 ```ts
-import { fromJSONImpl } from './network.serialize.utils';
-
-const rebuiltNetwork = fromJSONImpl(snapshotJson);
+network.setRNGState(savedState);
 ```
 
-### cloneImpl
+### setSeed
 
 ```ts
-cloneImpl(): default
+setSeed(
+  seed: number,
+): void
 ```
 
-Create a deep copy of one network through the verbose JSON round-trip.
+Sets deterministic randomness for a network by installing a seed-backed RNG.
 
-This keeps cloning behavior aligned with the same versioned payload contract
-used by `toJSON()` and `fromJSON()`, so clone semantics stay stable as the
-serialization chapter evolves.
+Overview:
+- Use this before training, mutation, or stochastic operations when you need repeatable runs.
+- The same seed and operation order produce the same random sequence and reproducible outcomes.
+- This method delegates to setup utilities so behavior stays centralized across deterministic APIs.
 
 Parameters:
-- `this` - Target network instance.
+- `this` - - Bound network instance whose RNG state is being initialized.
+- `seed` - - Seed value used to derive deterministic RNG state (low 32 bits are applied).
 
-Returns: Deep-cloned network instance.
+Returns: Nothing.
 
-### rebuildConnectionSlab
+Example:
 
 ```ts
-rebuildConnectionSlab(
-  force: boolean,
-): void
+network.setSeed(42);
 ```
 
-Build (or refresh) the packed connection slabs for the network synchronously.
-
-ACTIONS
--------
-1. Optionally reindex nodes if structural mutations invalidated indices.
-2. Grow (geometric) or reuse existing typed arrays to ensure capacity >= active connections.
-3. Populate the logical slice [0, connectionCount) with weight/from/to/flag data.
-4. Lazily allocate gain & plastic slabs only on first non‑neutral / plastic encounter; omit otherwise.
-5. Release previously allocated optional slabs when they revert to neutral / unused (omission optimization).
-6. Update internal bookkeeping: logical count, dirty flags, version counter.
-
-PERFORMANCE
------------
-O(C) over active connections with amortized allocation cost due to geometric growth.
-
-Parameters:
-- `force` - When true forces rebuild even if network not marked dirty (useful for timing tests).
-
-### rebuildConnectionSlabAsync
+### snapshotRNG
 
 ```ts
-rebuildConnectionSlabAsync(
-  chunkSize: number,
-): Promise<void>
+snapshotRNG(): RNGSnapshot
 ```
 
-Cooperative asynchronous slab rebuild (Browser only).
-
-Strategy:
- - Perform capacity decision + allocation up front (mirrors sync path).
- - Populate connection data in microtask slices (yield via resolved Promise) to avoid long main‑thread stalls.
- - Adaptive slice sizing for very large graphs if `config.browserSlabChunkTargetMs` set.
+Captures the current deterministic RNG lifecycle state as a portable snapshot.
 
-Metrics: Increments `_slabAsyncBuilds` for observability.
-Fallback: On Node (no `window`) defers to synchronous rebuild for simplicity.
+Overview:
+- Use this before temporary experiments, branching simulations, or stateful debug sessions.
+- The snapshot preserves enough information to resume from the same deterministic point later.
+- This is useful when comparing alternate algorithm branches from an identical random timeline.
 
 Parameters:
-- `chunkSize` - Initial maximum connections per slice (may be reduced adaptively for huge graphs).
+- `this` - - Bound network instance whose RNG lifecycle state is captured.
 
-Returns: Promise resolving once rebuild completes.
+Returns: Snapshot containing deterministic progress metadata and RNG state payload.
 
-### fastSlabActivate
+Example:
 
 ```ts
-fastSlabActivate(
-  input: number[],
-): number[]
+const snapshot = network.snapshotRNG();
 ```
 
-High‑performance forward pass using packed slabs + CSR adjacency.
+### testNetwork
 
-Fallback Conditions (auto‑detected):
- - Missing slabs / adjacency structures.
- - Topology/gating/stochastic predicates fail (see `_canUseFastSlab`).
- - Gating present, when applicable (explicit guard).
+```ts
+testNetwork(
+  set: TestSample[],
+  cost: CostFunction | undefined,
+): TestNetworkResult
+```
 
-Implementation Notes:
- - Reuses internal activation/state buffers to reduce per‑step allocation churn.
- - Applies gain multiplication if optional gain slab exists.
- - Assumes acyclic graph; topological order recomputed on demand if marked dirty.
+Evaluate a dataset and return average error and elapsed time.
 
 Parameters:
-- `input` - Input vector (length must equal `network.input`).
+- `this` - Bound network instance.
+- `set` - Evaluation samples.
+- `cost` - Optional cost function override.
 
-Returns: Output activations (detached plain array) of length `network.output`.
+Returns: Mean error and evaluation duration.
 
-### canUseFastSlab
+### toJSONImpl
 
 ```ts
-canUseFastSlab(
-  training: boolean,
-): boolean
+toJSONImpl(): NetworkJSON
 ```
 
-Public convenience wrapper exposing fast path eligibility.
-Mirrors `_canUseFastSlab` internal predicate.
+Serializes a network instance into the verbose JSON format.
+
+Use this format when you need human-readable snapshots, explicit schema versioning,
+and better forward/backward compatibility handling.
 
 Parameters:
-- `training` - Whether caller is performing training (disables fast path if true).
+- `this` - - Bound network instance.
 
-Returns: True when slab fast path predicates hold.
+Returns: Versioned JSON payload with shape metadata, nodes, and connections.
 
-### getConnectionSlab
+Example:
 
 ```ts
-getConnectionSlab(): ConnectionSlabView
-```
-
-Obtain (and lazily rebuild if dirty) the current packed SoA view of connections.
-
-Gain Omission: If the internal gain slab is absent (all gains neutral) a synthetic
-neutral array is created and returned (NOT retained) to keep external educational
-tooling branch‑free while preserving omission memory savings internally.
+import Network from '../../network';
+import { fromJSONImpl, toJSONImpl } from './network.serialize.utils';
 
-Returns: Read‑only style view (do not mutate) containing typed arrays + metadata.
+const sourceNetwork = new Network(3, 1);
+const snapshotJson = toJSONImpl.call(sourceNetwork);
+const rebuiltNetwork = fromJSONImpl(snapshotJson);
+```
 
-### getSlabAllocationStats
+### trainImpl
 
 ```ts
-getSlabAllocationStats(): { pool: { [x: string]: PoolKeyMetrics; }; fresh: number; pooled: number; }
+trainImpl(
+  net: default,
+  set: TrainingSample[],
+  options: TrainingOptions,
+): { error: number; iterations: number; time: number; }
 ```
 
-Allocation statistics snapshot for slab typed arrays.
+High-level training orchestration with early stopping, smoothing & callbacks.
 
-Includes:
- - fresh: number of newly constructed typed arrays since process start / metrics reset.
- - pooled: number of arrays served from the pool.
- - pool: per‑key metrics (created, reused, maxRetained) for educational inspection.
+This is the main entrypoint used by `Network.train(...)`-style APIs.
 
-NOTE: Stats are cumulative (not auto‑reset); callers may diff successive snapshots.
+Parameters:
+- `net` - - Network instance to train.
+- `set` - - Training dataset.
+- `options` - - Training options (stopping conditions, optimizer, hooks, etc.).
 
-Returns: Plain object copy (safe to serialize) of current allocator counters.
+Returns: Summary payload containing final error, iteration count, and elapsed time.
 
-### generateStandalone
+Example:
 
 ```ts
-generateStandalone(
-  net: default,
-): string
+const result = net.train(set, { iterations: 500, rate: 0.3 });
+console.log(result.error);
 ```
 
-Generate a standalone JavaScript source string that returns an `activate(input:number[])` function.
-
-Implementation Steps:
- 1. Validate presence of output nodes (must produce something observable).
- 2. Assign stable sequential indices to nodes (used as array offsets in generated code).
- 3. Collect initial activation/state values into typed array initializers for warm starting.
- 4. For each non-input node, build a line computing S[i] (pre-activation sum with bias) and A[i]
-    (post-activation output). Gating multiplies activation by gate activations; self-connection adds
-    recurrent term S[i] * weight before activation.
- 5. De-duplicate activation functions: each unique squash name is emitted once; references become
-    indices into array F of function references for compactness.
- 6. Emit an IIFE producing the activate function with internal arrays A (activations) and S (states).
-
-Parameters:
-- `net` - Network instance to snapshot.
-
-Returns: Source string (ES5-compatible) – safe to eval in sandbox to obtain activate function.
-
-### getRegularizationStats
-
-```ts
-getRegularizationStats(): Record<string, unknown> | null
-```
-
-Obtain the last recorded regularization / stochastic statistics snapshot.
-
-Returns a defensive deep copy so callers can inspect metrics without risking mutation of the
-internal `_lastStats` object maintained by the training loop (e.g., during pruning, dropout, or
-noise scheduling updates).
-
-Returns: A deep-cloned stats object or null if no stats have been recorded yet.
-
-### testNetwork
-
-```ts
-testNetwork(
-  set: TestSample[],
-  cost: CostFunction | undefined,
-): TestNetworkResult
-```
-
-Evaluate a dataset and return average error and elapsed time.
-
-Parameters:
-- `this` - Bound network instance.
-- `set` - Evaluation samples.
-- `cost` - Optional cost function override.
-
-Returns: Mean error and evaluation duration.
-
-### computeTopoOrder
-
-```ts
-computeTopoOrder(): void
-```
-
-Compute a topological ordering (Kahn's algorithm) for the current directed acyclic graph.
-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
-
-```ts
-hasPath(
-  from: default,
-  to: default,
-): boolean
-```
-
-Depth-first reachability test (avoids infinite loops via visited set).
-
-### 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.
-
-### 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
-
-```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.
-
-### applyGradientClippingImpl
-
-```ts
-applyGradientClippingImpl(
-  net: default,
-  cfg: GradientClipRuntimeConfig,
-): void
-```
-
-Apply gradient clipping to a network using a normalized runtime configuration.
-
-This is a small wrapper that forwards to the concrete implementation used by training.
-
-Parameters:
-- `net` - - Network instance to update.
-- `cfg` - - Normalized clipping settings.
-
-### propagate
-
-```ts
-propagate(
-  rate: number,
-  momentum: number,
-  update: boolean,
-  target: number[],
-  regularization: number,
-  costDerivative: CostDerivative | undefined,
-): void
-```
-
-Propagate output and hidden errors backward through the network.
-
-Parameters:
-- `this` - Bound network instance.
-- `rate` - Learning rate.
-- `momentum` - Momentum factor.
-- `update` - Whether to apply updates immediately.
-- `target` - Output target values.
-- `regularization` - L2 regularization factor.
-- `costDerivative` - Optional output-node derivative override.
-
-### clearState
-
-```ts
-clearState(): void
-```
-
-Clear all node runtime traces and states.
-
-Parameters:
-- `this` - Bound network instance.
-
-### trainSetImpl
+### trainSetImpl
 
 ```ts
 trainSetImpl(
@@ -1938,1010 +1955,978 @@ Parameters:
 
 Returns: Mean cost across the processed samples.
 
-### trainImpl
+### ungate
 
 ```ts
-trainImpl(
-  net: default,
-  set: TrainingSample[],
-  options: TrainingOptions,
-): { error: number; iterations: number; time: number; }
+ungate(
+  connection: default,
+): void
 ```
 
-High-level training orchestration with early stopping, smoothing & callbacks.
+Remove gating from a connection, restoring its static weight contribution.
 
-This is the main entrypoint used by `Network.train(...)`-style APIs.
+Idempotent: If the connection is not currently gated, the call performs no structural changes
+(and optionally logs a warning). After ungating, the connection's weight will be used directly
+without modulation by a gater activation.
+
+Complexity: O(n) where n = number of gated connections (indexOf lookup) – typically small.
 
 Parameters:
-- `net` - - Network instance to train.
-- `set` - - Training dataset.
-- `options` - - Training options (stopping conditions, optimizer, hooks, etc.).
+- `this` - - Bound Network instance.
+- `connection` - - Connection to ungate.
 
-Returns: Summary payload containing final error, iteration count, and elapsed time.
+## architecture/network/network.types.ts
 
-Example:
+### ActivateNetworkInternals
+
+Runtime interface for activation internals.
+
+### ActivationFunction
 
 ```ts
-const result = net.train(set, { iterations: 500, rate: 0.3 });
-console.log(result.error);
+ActivationFunction(
+  x: number,
+  derivate: boolean | undefined,
+): number
 ```
 
-### __trainingInternals
-
-Test-only internal helper bundle.
+Runtime activation function signature used by ONNX activation import/export paths.
 
-This is exported so unit tests can cover edge-cases in the smoothing logic without
-running full end-to-end training loops.
+Neataptic-style activations support a dual-purpose call pattern:
+- `derivate === false | undefined`: return activation output $f(x)$
+- `derivate === true`: return derivative $f'(x)$
 
-Important: this is **not** considered stable public API. It may change between releases.
+This matches historical Neataptic semantics and keeps ONNX import/export compatible.
 
-## architecture/network/network.types.ts
+Example:
 
-### NetworkRuntimeProps
+```ts
+const y = activation(x);
+const dy = activation(x, true);
+```
 
-Internal runtime properties attached to Network instances.
+### ActivationSquashFunction
 
-### NetworkArchitectureSource
+```ts
+ActivationSquashFunction(
+  x: number,
+  derivate: boolean | undefined,
+): number
+```
 
-Provenance of hidden-layer architecture information.
+Activation function signature used by ONNX layer emission helpers.
 
-### NetworkArchitectureDescriptor
+### BackwardCandidateTraversalContext
 
-Stable architecture descriptor for UI/telemetry consumers.
+Immutable context for backward candidate traversal.
 
-Hidden-layer sizes are ordered from input-side to output-side.
+### BuildAdjacencyContext
 
-### NetworkTopologyIntent
+Shared immutable inputs used across the adjacency build pipeline.
 
-Public topology intent exposed by the network API.
+### CheckpointConfig
 
-Use `feed-forward` when the caller wants the library to preserve an acyclic,
-forward-only contract. Use `unconstrained` when recurrent, gated, or other
-cyclic structures may be introduced.
+Checkpoint callback configuration.
 
-### NetworkConstructorOptions
+Training can periodically call `save(...)` with a serialized network snapshot.
+You can persist these snapshots to disk, upload them, or keep them in-memory.
 
-Public constructor options for `Network`.
+### CompactConnectionRebuildContext
 
-`topologyIntent` is the semantic, DX-first contract. `enforceAcyclic`
-remains available for backward compatibility and must not contradict the
-declared topology intent.
+Context for compact-connection reconstruction.
 
-### NetworkBootstrapInternals
+Connection rows are processed independently so malformed entries can be skipped without aborting import.
 
-Internal constructor-time surface used by bootstrap helpers.
+### CompactNodeRebuildContext
 
-### ConnectionWeightNoiseProps
+Context for compact-node reconstruction.
 
-Internal runtime properties attached to Connection instances.
+Arrays are expected to be index-aligned so each node can be hydrated deterministically.
 
-### ActivateNetworkInternals
+### CompactPayloadContext
 
-Runtime interface for activation internals.
+Context carrying compact payload fields.
 
-### ConnectNetworkInternals
+This named-object form replaces tuple index access in internal orchestration code.
 
-Runtime interface for connect internals.
+### CompactSerializedNetworkTuple
 
-### DeterministicNetworkInternals
+Compact tuple payload used by `serialize` output.
 
-Runtime interface for deterministic internals.
+Tuple slots are intentionally positional to reduce payload size:
+0) activations, 1) states, 2) squash keys, 3) connections, 4) input size, 5) output size.
 
-### RNGSnapshot
+Example:
 
-Snapshot payload for RNG state restore flows.
+```ts
+const compactTuple: CompactSerializedNetworkTuple = [
+  [0.1, 0.2],
+  [0, 0],
+  ['identity', 'tanh'],
+  [{ from: 0, to: 1, weight: 0.5, gater: null }],
+  1,
+  1,
+];
+```
 
-### NetworkRuntimeControlInternals
+### ConnectionGene
 
-Internal network properties accessed by runtime-control helpers.
+Crossover connection-gene descriptor.
 
-### NetworkRuntimeDiagnosticsInternals
+### ConnectionGeneSelectionContext
 
-Internal network properties accessed by runtime diagnostics helpers.
+Immutable context for selecting inherited genes.
 
-### GatingNetworkProps
+### ConnectionGeneticProps
 
-Internal network properties accessed during gating operations.
+Extended connection shape used during genetic crossover.
 
-### SubNodeMutationConfig
+### ConnectionGroupReinitContext
 
-Mutation keep-gates option surface used by sub-node removal logic.
+Context for reinitializing connection group weights.
 
-### StatsNetworkProps
+### ConnectionInternals
 
-Internal network properties used by stats operations.
+Internal Connection properties accessed during slab operations.
 
-### GlobalThisWithStructuredClone
+### ConnectionInternalsWithEnabled
 
-GlobalThis extension exposing optional structuredClone.
+Connection view with optional enabled flag.
 
-### TopologyNetworkProps
+Some serialized formats preserve per-edge enablement, while others treat missing values
+as implicitly enabled.
 
-Internal topology state carrier.
+### ConnectionSlabView
 
-### TopologyBuildContext
+Shape returned by getConnectionSlab describing the packed SoA view.
 
-Mutable context used while building topological ordering.
+### ConnectionSplitResult
 
-### PathSearchContext
+Result of replacing a connection with split hidden node.
 
-Mutable context used while running iterative path search.
+### ConnectionWeightNoiseProps
 
-### NetworkStandaloneProps
+Internal runtime properties attached to Connection instances.
 
-Internal standalone generation network view.
+### ConnectNetworkInternals
 
-### NodeWithIndex
+Runtime interface for connect internals.
 
-Node with generated index for standalone-code emission.
+### Conv2DMapping
 
-### StandaloneGenerationContext
+Mapping declaration for treating a fully-connected layer as a 2D convolution during export.
 
-Shared mutable state for standalone source generation.
+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.
 
-### NetworkRemoveProps
+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.
 
-Internal network properties accessed during remove operations.
+### ConvKernelConsistencyContext
 
-### NodeRemovalContext
+Context for kernel-coordinate consistency checks at one output position.
 
-Immutable context for validated node-removal request.
+### ConvLayerPairContext
 
-### NodeConnectionSnapshotContext
+Context for one resolved Conv mapping layer pair.
 
-Snapshot of node adjacency prior to removal.
+### ConvOutputCoordinate
 
-### ReconnectEndpointPairContext
+Coordinate for one Conv output neuron position.
 
-Endpoint pair for reconnecting bridged paths.
+### ConvRepresentativeKernelContext
 
-### PruningMethod
+Context for representative Conv kernel collection per output channel.
 
-Pruning strategy identifiers.
+### ConvSharingValidationContext
 
-### NetworkPruningProps
+Context for validating Conv sharing across all declared mappings.
 
-Internal network properties accessed during pruning operations.
+### ConvSharingValidationResult
 
-### ScheduledTargetContext
+Result of Conv sharing validation across declared mappings.
 
-Context for scheduled-pruning target computation.
+### CostFunction
 
-### ScheduledTargetResult
+```ts
+CostFunction(
+  target: number[],
+  output: number[],
+): number
+```
 
-Result of scheduled-pruning target computation.
+Cost / loss function used during supervised training.
 
-### PruneSelectionContext
+A cost function compares an expected `target` vector with the network's produced `output`
+vector, returning a scalar error where **lower is better**.
 
-Context for selecting prune candidates.
+Design notes:
+- This is called frequently (often once per training sample), so implementations should be
+  **pure** and **allocation-light**.
+- Most built-in training loops assume the returned value is non-negative.
 
-### PruneSelectionResult
+Example (mean squared error):
 
-Result of prune candidate selection.
+```ts
+export const mse: CostFunction = (target, output) => {
+  const sum = target.reduce((acc, targetValue, index) => {
+    const diff = targetValue - (output[index] ?? 0);
+    return acc + diff * diff;
+  }, 0);
+  return sum / Math.max(1, target.length);
+};
+```
 
-### RegrowthPlanContext
+### CostFunctionOrObject
 
-Context for deriving regrowth plan.
+Cost function object compatibility shape.
 
-### RegrowthPlan
+### CostFunctionOrRef
 
-Derived regrowth execution plan.
+Evolve-side serializable cost-function reference.
 
-### RegrowthExecutionContext
+### CrossoverContext
 
-Context for regrowth execution routine.
+Immutable baseline context for one crossover run.
 
-### EvolutionaryTargetContext
+### CrossoverNodeBuildContext
 
-Context for evolutionary sparsity target computation.
+Node-build context derived from crossover baseline.
 
-### EvolutionaryTargetResult
+### DenseActivationContext
 
-Result of evolutionary sparsity target computation.
+Dense activation emission context.
 
-### SerializeNetworkInternals
+### DenseActivationNodePayload
 
-Runtime interface for accessing network internals during serialization.
+Strongly typed activation node payload used by dense export helpers.
 
-This is an internal bridge type used by serializer helpers to read and rebuild
-topology without exposing private implementation details in public APIs.
+### DenseGemmNodePayload
 
-### NetworkInternalsWithDropout
+Strongly typed Gemm node payload used by dense export helpers.
 
-Serialize internals with optional dropout field.
+### DenseGraphNames
 
-Verbose JSON snapshots normalize this value so readers can treat dropout as numeric data.
+Dense graph tensor names.
 
-### SerializeNodeInternals
+### DenseInitializerValues
 
-Runtime node internals needed for serialization workflows.
+Dense initializer value arrays.
 
-These fields are the minimal node state required to round-trip compact and JSON payloads.
+### DenseLayerContext
 
-### ConnectionInternalsWithEnabled
+Dense layer context enriched with resolved activation function.
 
-Connection view with optional enabled flag.
+### DenseLayerParams
 
-Some serialized formats preserve per-edge enablement, while others treat missing values
-as implicitly enabled.
+Parameters for dense layer emission.
 
-### SerializedConnection
+### DenseOrderedNodePayload
 
-Serialized connection representation used by compact and JSON formats.
+Dense node payload union used by ordered append helpers.
 
-Endpoints are canonical node indices, which keeps payloads deterministic and language-agnostic.
+### DenseTensorNames
 
-### CompactSerializedNetworkTuple
+Dense initializer tensor names.
 
-Compact tuple payload used by `serialize` output.
+### DenseWeightBuildContext
 
-Tuple slots are intentionally positional to reduce payload size:
-0) activations, 1) states, 2) squash keys, 3) connections, 4) input size, 5) output size.
+Context for building dense layer initializers from two adjacent layers.
 
-Example:
+### DenseWeightBuildResult
 
-```ts
-const compactTuple: CompactSerializedNetworkTuple = [
-  [0.1, 0.2],
-  [0, 0],
-  ['identity', 'tanh'],
-  [{ from: 0, to: 1, weight: 0.5, gater: null }],
-  1,
-  1,
-];
-```
+Dense layer initializer fold output.
 
-### NetworkJSONNode
+### DenseWeightRow
 
-Verbose JSON node representation.
+One collected dense row before fold to flattened initializers.
 
-Node entries are self-describing and intended for readable, versioned snapshots.
+### DenseWeightRowCollectionContext
 
-### NetworkJSONConnection
+Context for collecting one dense row.
 
-Verbose JSON connection representation.
+### DeterministicChainMutationContext
 
-Includes optional gater and explicit enabled state for portability.
+Context for deterministic-chain add-node mutation.
 
-### NetworkJSON
+### DeterministicNetworkInternals
 
-Verbose JSON payload representation used by `toJSONImpl` and `fromJSONImpl`.
+Runtime interface for deterministic internals.
 
-`formatVersion` enables compatibility checks and migration handling.
+### DiagonalRecurrentBuildContext
 
-Example:
+Context for building a diagonal recurrent matrix from self-connections.
 
-```ts
-const payload: NetworkJSON = {
-  formatVersion: 2,
-  input: 2,
-  output: 1,
-  dropout: 0,
-  nodes: [{ type: 'input', bias: 0, squash: 'identity', index: 0 }],
-  connections: [],
-};
-```
+### DirectionalConnectionContext
 
-### CompactPayloadContext
+Indexed context for directional connection metadata.
 
-Context carrying compact payload fields.
+### DistinctNodePair
 
-This named-object form replaces tuple index access in internal orchestration code.
+Selected distinct node pair for swap mutation.
 
-### ResolvedNetworkSizeContext
+### EvolutionaryTargetContext
 
-Resolved input/output sizes for rebuild.
+Context for evolutionary sparsity target computation.
 
-Values reflect override-first resolution semantics used during deserialization.
+### EvolutionaryTargetResult
 
-### CompactNodeRebuildContext
+Result of evolutionary sparsity target computation.
 
-Context for compact-node reconstruction.
+### EvolutionConfig
 
-Arrays are expected to be index-aligned so each node can be hydrated deterministically.
+Internal normalized evolution config.
 
-### CompactConnectionRebuildContext
+### EvolutionFitnessFunction
 
-Context for compact-connection reconstruction.
+```ts
+EvolutionFitnessFunction(
+  arg0: default & default[],
+): number | Promise<void>
+```
 
-Connection rows are processed independently so malformed entries can be skipped without aborting import.
+Unified evolution fitness callback shape.
 
-### JsonNodeRebuildContext
+### EvolutionLoopState
 
-Context for JSON-node reconstruction.
+Mutable state tracked during evolution loop.
 
-Node entries are rebuilt in order and pushed into mutable runtime internals.
+### EvolutionSettings
 
-### JsonConnectionRebuildContext
+Scalar evolution settings used by orchestration.
 
-Context for JSON-connection reconstruction.
+### EvolutionStopConditions
 
-Connection rows may include optional gater and enabled metadata.
+Effective evolution stopping conditions.
 
-### CostFunction
+### EvolveCostFunction
 
 ```ts
-CostFunction(
+EvolveCostFunction(
   target: number[],
   output: number[],
 ): number
 ```
 
-Cost / loss function used during supervised training.
-
-A cost function compares an expected `target` vector with the network's produced `output`
-vector, returning a scalar error where **lower is better**.
-
-Design notes:
-- This is called frequently (often once per training sample), so implementations should be
-  **pure** and **allocation-light**.
-- Most built-in training loops assume the returned value is non-negative.
-
-Example (mean squared error):
-
-```ts
-export const mse: CostFunction = (target, output) => {
-  const sum = target.reduce((acc, targetValue, index) => {
-    const diff = targetValue - (output[index] ?? 0);
-    return acc + diff * diff;
-  }, 0);
-  return sum / Math.max(1, target.length);
-};
-```
+Evolve-side cost function signature.
 
-### GradientClipConfig
+### EvolveOptions
 
-Gradient clipping configuration.
+Evolve options bag.
 
-Clipping prevents rare large gradients from causing unstable weight updates.
-It is most useful for recurrent networks and noisy datasets.
+### FanOutCollectionContext
 
-Conceptual modes:
-- `norm`: clip by a global $L_2$ norm threshold.
-- `percentile`: clip using a running percentile estimate (robust to outliers).
-- `layerwise*`: apply the same idea per-layer (useful when layers have very different scales).
+Context for fan-out collection: build inputs plus the output count buffer.
 
-### MixedPrecisionDynamicConfig
+### FastSlabNodeRuntime
 
-Dynamic mixed-precision configuration.
+Node shape required by fast slab activation kernels.
 
-When enabled, training uses a loss-scaling heuristic that attempts to keep gradients
-in a numerically stable range. If an overflow is detected, the scale is reduced.
+### FitnessSetup
 
-### MixedPrecisionConfig
+Result of fitness-strategy setup.
 
-Mixed-precision configuration.
+### FlattenAfterPoolingContext
 
-Mixed precision can improve throughput by running some math in lower precision while
-keeping a stable FP32 master copy of parameters when needed.
+Flatten emission context after optional pooling.
 
-### OptimizerConfigBase
+### ForwardCandidateTraversalContext
 
-Base optimizer configuration.
+Immutable context for forward candidate traversal.
 
-Training accepts either an optimizer name (`"adam"`, `"sgd"`, ...) or an object.
-This object form is useful when you want to pin numeric hyperparameters or wrap a base
-optimizer (e.g. lookahead).
+### FusedRecurrentEmissionExecutionContext
 
-Example:
+Shared execution context for emitting one fused recurrent layer payload.
 
-```ts
-net.train(set, {
-  iterations: 1_000,
-  rate: 0.001,
-  optimizer: { type: 'adamw', beta1: 0.9, beta2: 0.999, eps: 1e-8, weightDecay: 0.01 },
-});
-```
+### FusedRecurrentGraphNames
 
-Notes:
-- Exact supported `type` values are validated by training utilities.
-- Unspecified fields fall back to sensible defaults per optimizer.
+Context for ONNX fused recurrent node payload names.
 
-### SerializedNetwork
+### FusedRecurrentInitializerNames
 
-Serialized network payload used in checkpoint callbacks.
+Context for ONNX fused recurrent initializer names.
 
-This is intentionally loose: serialization formats evolve and may include nested
-structures. Treat this as an opaque snapshot blob.
+### GatingNetworkProps
 
-### CheckpointConfig
+Internal network properties accessed during gating operations.
 
-Checkpoint callback configuration.
+### GeneEndpointsContext
 
-Training can periodically call `save(...)` with a serialized network snapshot.
-You can persist these snapshots to disk, upload them, or keep them in-memory.
+Endpoints for one gene traversal step.
 
-### ScheduleConfig
+### GeneticNetwork
 
-Schedule callback configuration.
+Runtime network shape used by crossover internals.
 
-A schedule callback is a simple "tick hook" that runs every N iterations.
-Typical uses include logging, custom learning-rate schedules, or diagnostics.
+### GeneTraversalContext
 
-### MetricsHook
+Traversal context for one connection gene.
 
-```ts
-MetricsHook(
-  m: { iteration: number; error: number; plateauError?: number | undefined; gradNorm: number; },
-): void
-```
+### GlobalThisWithStructuredClone
 
-Metrics hook signature.
+GlobalThis extension exposing optional structuredClone.
 
-If provided, this callback receives summarized metrics after each iteration.
-It is designed for lightweight telemetry, not heavy data export.
+### GradientClipConfig
 
-### MovingAverageType
+Gradient clipping configuration.
 
-Moving-average strategy identifier.
+Clipping prevents rare large gradients from causing unstable weight updates.
+It is most useful for recurrent networks and noisy datasets.
 
-These strategies are used to smooth the monitored error curve during training.
-Smoothing can make early stopping and progress logging less noisy.
+Conceptual modes:
+- `norm`: clip by a global $L_2$ norm threshold.
+- `percentile`: clip using a running percentile estimate (robust to outliers).
+- `layerwise*`: apply the same idea per-layer (useful when layers have very different scales).
 
-### TrainingOptions
+### GruEmissionContext
 
-Public training options accepted by the high-level training orchestration.
+Context for heuristic GRU emission when a layer matches expected shape.
 
-Training in this codebase is conceptually:
-1) forward activation
-2) backward propagation
-3) optimizer update
-repeated until a stopping condition is met.
+### HiddenLayerActivationTraversalContext
 
-Minimal example:
+Hidden-layer traversal context for assigning imported activation functions.
 
-```ts
-net.train(set, {
-  iterations: 500,
-  rate: 0.3,
-  batchSize: 16,
-  gradientClip: { mode: 'norm', maxNorm: 1 },
-});
-```
+### HiddenLayerHeuristicContext
 
-Stopping conditions:
-- Provide at least one of `iterations` or `error`.
-- `earlyStopPatience` adds an additional "stop when no improvement" guard.
+Context for one hidden layer during heuristic recurrent emission.
 
-### PrimarySmoothingState
+### IndexedMetadataAppendContext
 
-Mutable smoothing state for monitored error.
+Append-an-index metadata context for JSON-array metadata keys.
 
-### PlateauSmoothingState
+### InputOutputEndpoints
 
-Mutable smoothing state for plateau metric.
+Required endpoint pair for input/output edge seeding.
 
-### MonitoredSmoothingConfig
+### JsonConnectionRebuildContext
 
-Config for monitored smoothing computation.
+Context for JSON-connection reconstruction.
 
-### PlateauSmoothingConfig
+Connection rows may include optional gater and enabled metadata.
 
-Config for plateau smoothing computation.
+### JsonNodeRebuildContext
 
-### TrainingConnectionInternals
+Context for JSON-node reconstruction.
 
-Runtime connection view used by training internals.
+Node entries are rebuilt in order and pushed into mutable runtime internals.
 
-### TrainingNodeInternals
+### LayerActivationContext
 
-Runtime node view used by training internals.
+Activation analysis context for one layer.
 
-### TrainingNetworkInternals
+### LayerActivationValidationContext
 
-Runtime network view used by training internals.
+Activation-homogeneity decision context for one current layer.
 
-### RegularizationConfig
+### LayerBuildContext
 
-L1/L2 regularization configuration.
+Layer build context used while emitting one ONNX graph layer segment.
 
-### CostFunctionOrObject
+### LayerConnectivityValidationContext
 
-Cost function object compatibility shape.
+Connectivity decision context for one source-target node pair.
 
-### TrainingSample
+### LayerOrderingNodeGroups
 
-A single supervised training sample used in evolution scoring.
+Node partitions used by ONNX layered-ordering inference traversal.
 
-### EvolveCostFunction
+### LayerOrderingResolutionContext
 
-```ts
-EvolveCostFunction(
-  target: number[],
-  output: number[],
-): number
-```
+Mutable traversal state while resolving hidden-layer ordering.
 
-Evolve-side cost function signature.
+### LayerRecurrentDecisionContext
 
-### CostFunctionOrRef
+Context used to decide recurrent emission branch usage.
 
-Evolve-side serializable cost-function reference.
+### LayerTraversalContext
 
-### EvolutionConfig
+Layer traversal context with adjacent layers and output classification.
 
-Internal normalized evolution config.
+### LayerValidationTraversalContext
 
-### EvolutionSettings
+Layer-wise validation context for activation and connectivity checks.
 
-Scalar evolution settings used by orchestration.
+### LstmEmissionContext
 
-### EvolutionStopConditions
+Context for heuristic LSTM emission when a layer matches expected shape.
 
-Effective evolution stopping conditions.
+### MetricsHook
 
-### EvolutionLoopState
+```ts
+MetricsHook(
+  m: { iteration: number; error: number; plateauError?: number | undefined; gradNorm: number; },
+): void
+```
 
-Mutable state tracked during evolution loop.
+Metrics hook signature.
 
-### EvolveOptions
+If provided, this callback receives summarized metrics after each iteration.
+It is designed for lightweight telemetry, not heavy data export.
 
-Evolve options bag.
+### MixedPrecisionConfig
 
-### SingleGenomeFitnessFunction
+Mixed-precision configuration.
 
-```ts
-SingleGenomeFitnessFunction(
-  genome: default,
-): number
-```
+Mixed precision can improve throughput by running some math in lower precision while
+keeping a stable FP32 master copy of parameters when needed.
 
-Fitness signature evaluating one genome.
+### MixedPrecisionDynamicConfig
 
-### PopulationFitnessFunction
+Dynamic mixed-precision configuration.
 
-```ts
-PopulationFitnessFunction(
-  population: default[],
-): Promise<void>
-```
+When enabled, training uses a loss-scaling heuristic that attempts to keep gradients
+in a numerically stable range. If an overflow is detected, the scale is reduced.
 
-Fitness signature evaluating full population asynchronously.
+### MonitoredSmoothingConfig
 
-### EvolutionFitnessFunction
+Config for monitored smoothing computation.
 
-```ts
-EvolutionFitnessFunction(
-  arg0: default & default[],
-): number | Promise<void>
-```
+### MovingAverageType
 
-Unified evolution fitness callback shape.
+Moving-average strategy identifier.
 
-### FitnessSetup
+These strategies are used to smooth the monitored error curve during training.
+Smoothing can make early stopping and progress logging less noisy.
 
-Result of fitness-strategy setup.
+### MutationHandler
 
-### PopulationWorkerEvaluationContext
+```ts
+MutationHandler(
+  method: MutationMethod | undefined,
+): void
+```
 
-Shared context for one population worker evaluation run.
+Mutation handler function contract.
 
-### WorkerTraversalContext
+### MutationMethod
 
-Worker-local traversal context.
+Mutation method descriptor shape.
 
-### NeatRuntime
+### MutationMethodObject
 
-Minimal runtime contract consumed from NEAT in evolve utilities.
+Object-only form of mutation method descriptor.
 
-### NetworkGeneticProps
+### NeatRuntime
 
-Runtime properties used during genetic operations.
+Minimal runtime contract consumed from NEAT in evolve utilities.
 
-### ConnectionGene
+### NetworkActivationRuntime
 
-Crossover connection-gene descriptor.
+Runtime activation contract used by slab-based execution paths.
 
-### ConnectionGeneticProps
+### NetworkArchitectureDescriptor
 
-Extended connection shape used during genetic crossover.
+Stable architecture descriptor for UI/telemetry consumers.
 
-### GeneticNetwork
+Hidden-layer sizes are ordered from input-side to output-side.
 
-Runtime network shape used by crossover internals.
+### NetworkArchitectureSource
 
-### OffspringMaterializationContext
+Provenance of hidden-layer architecture information.
 
-Immutable context for offspring materialization.
+### NetworkBootstrapInternals
 
-### GeneTraversalContext
+Internal constructor-time surface used by bootstrap helpers.
 
-Traversal context for one connection gene.
+### NetworkConstructor
 
-### GeneEndpointsContext
+Constructor signature for runtime Network import.
 
-Endpoints for one gene traversal step.
+### NetworkConstructorOptions
 
-### ConnectionGeneSelectionContext
+Public constructor options for `Network`.
 
-Immutable context for selecting inherited genes.
+`topologyIntent` is the semantic, DX-first contract. `enforceAcyclic`
+remains available for backward compatibility and must not contradict the
+declared topology intent.
 
-### Parent1GeneTraversalContext
+### NetworkGeneticProps
 
-Traversal state for parent-1 innovation walk.
+Runtime properties used during genetic operations.
 
-### Parent1TraversalSelectionResult
+### NetworkInternalsWithDropout
 
-Fold result for parent-1 traversal selection.
+Serialize internals with optional dropout field.
 
-### CrossoverContext
+Verbose JSON snapshots normalize this value so readers can treat dropout as numeric data.
 
-Immutable baseline context for one crossover run.
+### NetworkJSON
 
-### CrossoverNodeBuildContext
+Verbose JSON payload representation used by `toJSONImpl` and `fromJSONImpl`.
 
-Node-build context derived from crossover baseline.
+`formatVersion` enables compatibility checks and migration handling.
 
-### ParentMetrics
+Example:
 
-Compact parent metrics summary.
+```ts
+const payload: NetworkJSON = {
+  formatVersion: 2,
+  input: 2,
+  output: 1,
+  dropout: 0,
+  nodes: [{ type: 'input', bias: 0, squash: 'identity', index: 0 }],
+  connections: [],
+};
+```
 
-### NetworkConstructor
+### NetworkJSONConnection
 
-Constructor signature for runtime Network import.
+Verbose JSON connection representation.
 
-### MutationMethod
+Includes optional gater and explicit enabled state for portability.
 
-Mutation method descriptor shape.
+### NetworkJSONNode
 
-### MutationMethodObject
+Verbose JSON node representation.
 
-Object-only form of mutation method descriptor.
+Node entries are self-describing and intended for readable, versioned snapshots.
 
 ### NetworkMutationProps
 
 Internal network properties accessed during mutations.
 
-### MutationHandler
+### NetworkPruningProps
 
-```ts
-MutationHandler(
-  method: MutationMethod | undefined,
-): void
-```
+Internal network properties accessed during pruning operations.
 
-Mutation handler function contract.
+### NetworkRemoveProps
 
-### ForwardCandidateTraversalContext
+Internal network properties accessed during remove operations.
 
-Immutable context for forward candidate traversal.
+### NetworkRuntimeControlInternals
 
-### BackwardCandidateTraversalContext
+Internal network properties accessed by runtime-control helpers.
 
-Immutable context for backward candidate traversal.
+### NetworkRuntimeDiagnosticsInternals
 
-### DirectionalConnectionContext
+Internal network properties accessed by runtime diagnostics helpers.
 
-Indexed context for directional connection metadata.
+### NetworkRuntimeProps
 
-### InputOutputEndpoints
+Internal runtime properties attached to Network instances.
 
-Required endpoint pair for input/output edge seeding.
+### NetworkSlabProps
 
-### ConnectionSplitResult
+Internal Network properties for slab operations.
 
-Result of replacing a connection with split hidden node.
+### NetworkStandaloneProps
 
-### RecurrentLayerShape
+Internal standalone generation network view.
 
-Minimal recurrent-layer shape used by mutation expanders.
+### NetworkTopologyIntent
 
-### DeterministicChainMutationContext
+Public topology intent exposed by the network API.
 
-Context for deterministic-chain add-node mutation.
+Use `feed-forward` when the caller wants the library to preserve an acyclic,
+forward-only contract. Use `unconstrained` when recurrent, gated, or other
+cyclic structures may be introduced.
 
-### DistinctNodePair
+### NetworkTopoRuntime
 
-Selected distinct node pair for swap mutation.
+Runtime topology contract used to lazily rebuild topological order.
 
-### TargetLayerPeerContext
+### NetworkWithOnnxImportPooling
 
-Context for target-layer peer traversal.
+Network instance augmented with optional imported ONNX pooling metadata.
 
-### SourcePeerConnectionCountContext
+### NodeConnectionSnapshotContext
 
-Context for source-to-peer connection counting.
+Snapshot of node adjacency prior to removal.
 
-### WeightSamplingRangeContext
+### NodeInternals
 
-Context for sampling one random weight value.
+Runtime interface for accessing node internal properties.
 
-### ConnectionGroupReinitContext
+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.
 
-Context for reinitializing connection group weights.
+### NodeInternalsWithExportIndex
+
+Runtime node internals augmented with optional export index metadata.
 
 ### NodePair
 
 Canonical source-target node pair tuple.
 
-### Conv2DMapping
+### NodeRemovalContext
 
-Mapping declaration for treating a fully-connected layer as a 2D convolution during export.
+Immutable context for validated node-removal request.
 
-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.
+### NodeWithIndex
 
-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.
+Node with generated index for standalone-code emission.
 
-### OnnxAttribute
+### OffspringMaterializationContext
 
-ONNX node attribute payload.
+Immutable context for offspring materialization.
 
-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.
+### OnnxActivationAssignmentContext
 
-### OnnxDimension
+Shared activation-assignment context for hidden and output traversal.
 
-One dimension inside an ONNX tensor shape.
+### OnnxActivationLayerOperations
 
-Use `dim_value` for fixed numeric widths and `dim_param` for symbolic names
-such as a batch dimension.
+Layer-indexed activation operator lookup extracted from ONNX graph nodes.
 
-### OnnxGraph
+### OnnxActivationOperation
 
-Graph body of an ONNX-like model.
+Supported ONNX activation operators recognized during activation import.
 
-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.
+### OnnxActivationOperationResolutionContext
 
-### OnnxMetadataProperty
+Activation operation resolution context for one neuron or layer default.
 
-Canonical metadata key-value pair used in ONNX model metadata_props.
+### OnnxActivationParseResult
 
-### OnnxModel
+Parsed ONNX activation-node naming payload.
 
-ONNX-like model container (JSON-serializable).
+### OnnxAttribute
 
-This is the main “wire format” object in this folder. Persist it as JSON text:
+ONNX node attribute payload.
 
-```ts
-const jsonText = JSON.stringify(model);
-const restoredModel = JSON.parse(jsonText) as OnnxModel;
-```
+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.
 
-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`.
+### OnnxBaseModelBuildContext
 
-Security/trust boundary:
-- Treat this as untrusted input if it comes from outside your process.
+Context for constructing a base ONNX model shell.
 
-### OnnxNode
+### OnnxBuildResolvedOptions
 
-One ONNX operator invocation inside the graph.
+Resolved options used by ONNX model build orchestration.
 
-Nodes connect named tensors rather than object references, which keeps the
-exported payload easy to serialize, inspect, and diff as plain JSON.
+### OnnxConvEmissionContext
 
-### OnnxShape
+Context used after resolving Conv mapping for one layer.
 
-ONNX tensor type shape.
+### OnnxConvEmissionParams
 
-### OnnxTensor
+Parameters accepted by Conv layer emission.
 
-Serialized tensor payload stored inside graph initializers.
+### OnnxConvKernelCoordinate
 
-NeatapticTS currently writes floating-point parameter vectors and matrices to
-`float_data`, along with the tensor name, element type, and logical shape.
+Coordinate for one Conv kernel weight lookup.
 
-### OnnxTensorType
+### OnnxConvParameters
 
-ONNX tensor type.
+Flattened Conv parameters for ONNX initializers.
 
-### OnnxValueInfo
+### OnnxConvTensorNames
 
-ONNX value info (input/output description).
+Tensor names generated for Conv parameters.
 
-### Pool2DMapping
+### OnnxDimension
 
-Mapping describing a pooling operation inserted after a given export-layer index.
+One dimension inside an ONNX tensor shape.
 
-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).
+Use `dim_value` for fixed numeric widths and `dim_param` for symbolic names
+such as a batch dimension.
 
-### ActivationSquashFunction
+### OnnxExportOptions
 
-```ts
-ActivationSquashFunction(
-  x: number,
-  derivate: boolean | undefined,
-): number
-```
+Options controlling ONNX-like export.
 
-Activation function signature used by ONNX layer emission helpers.
+These options trade off strictness, portability, and fidelity:
 
-### ConvKernelConsistencyContext
+- **Strict (default-ish)** export tries to keep the graph easy to interpret:
+  layered topology, homogeneous activations per layer, and fully-connected layers.
 
-Context for kernel-coordinate consistency checks at one output position.
+- **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).
 
-### ConvLayerPairContext
+- **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.
 
-Context for one resolved Conv mapping layer pair.
+### OnnxFusedGateApplicationContext
 
-### ConvOutputCoordinate
+Gate-weight application context for one reconstructed fused layer.
 
-Coordinate for one Conv output neuron position.
+### OnnxFusedGateRowAssignmentContext
 
-### ConvRepresentativeKernelContext
+Context for assigning one gate-neuron row from flattened ONNX tensors.
 
-Context for representative Conv kernel collection per output channel.
+### OnnxFusedLayerNeighborhood
 
-### ConvSharingValidationContext
+Hidden-layer neighborhood slices around a reconstructed fused layer.
 
-Context for validating Conv sharing across all declared mappings.
+### OnnxFusedLayerReconstructionContext
 
-### ConvSharingValidationResult
+Execution context for one fused recurrent layer reconstruction.
 
-Result of Conv sharing validation across declared mappings.
+### OnnxFusedLayerRuntime
 
-### DenseActivationContext
+Runtime interface of a reconstructed fused recurrent layer instance.
 
-Dense activation emission context.
+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.
 
-### DenseActivationNodePayload
+### OnnxFusedRecurrentKind
 
-Strongly typed activation node payload used by dense export helpers.
+Supported fused recurrent operator families recognized during ONNX import.
 
-### DenseGemmNodePayload
+### OnnxFusedRecurrentSpec
 
-Strongly typed Gemm node payload used by dense export helpers.
+Fused recurrent family specification used during import reconstruction.
 
-### DenseGraphNames
+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.
 
-Dense graph tensor names.
+### OnnxFusedTensorPayload
 
-### DenseInitializerValues
+Fused recurrent tensor payload read from ONNX initializers.
 
-Dense initializer value arrays.
+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.
 
-### DenseLayerContext
+### OnnxGraph
 
-Dense layer context enriched with resolved activation function.
+Graph body of an ONNX-like model.
 
-### DenseLayerParams
+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.
 
-Parameters for dense layer emission.
+### OnnxGraphDimensionBuildContext
 
-### DenseOrderedNodePayload
+Context for constructing input/output ONNX graph dimensions.
 
-Dense node payload union used by ordered append helpers.
+### OnnxGraphDimensions
 
-### DenseTensorNames
+Output dimensions used by ONNX graph input/output value info payloads.
 
-Dense initializer tensor names.
+### OnnxImportAggregatedLayerAssignmentContext
 
-### DenseWeightBuildContext
+Context for assigning aggregated dense tensors for one layer.
 
-Context for building dense layer initializers from two adjacent layers.
+### OnnxImportAggregatedNeuronAssignmentContext
 
-### DenseWeightBuildResult
+Context for assigning one aggregated dense target neuron row.
 
-Dense layer initializer fold output.
+### OnnxImportArchitectureContext
 
-### DenseWeightRow
+Shared architecture extraction context with resolved graph dimensions.
 
-One collected dense row before fold to flattened initializers.
+### OnnxImportArchitectureResult
 
-### DenseWeightRowCollectionContext
+Parsed architecture dimensions extracted from ONNX import graph payloads.
 
-Context for collecting one dense row.
+### OnnxImportConvCoordinateAssignmentContext
 
-### DiagonalRecurrentBuildContext
+Context for applying Conv weights and bias at one output coordinate.
 
-Context for building a diagonal recurrent matrix from self-connections.
+### OnnxImportConvKernelAssignmentContext
 
-### FlattenAfterPoolingContext
+Context for assigning one concrete Conv kernel connection weight.
 
-Flatten emission context after optional pooling.
+### OnnxImportConvLayerContext
 
-### FusedRecurrentEmissionExecutionContext
+Context for reconstructing one Conv layer's imported connectivity.
 
-Shared execution context for emitting one fused recurrent layer payload.
+### OnnxImportConvLayerContextBuildParams
 
-### FusedRecurrentGraphNames
+Build params for creating one Conv reconstruction layer context.
 
-Context for ONNX fused recurrent node payload names.
+### OnnxImportConvMetadata
 
-### FusedRecurrentInitializerNames
+Parsed Conv metadata payload used for optional reconstruction pass.
 
-Context for ONNX fused recurrent initializer names.
+### OnnxImportConvNodeSlices
 
-### GruEmissionContext
+Layer node slices used while applying Conv reconstruction assignments.
 
-Context for heuristic GRU emission when a layer matches expected shape.
+### OnnxImportConvOutputCoordinate
 
-### HiddenLayerHeuristicContext
+Coordinate for one Conv output neuron traversal position.
 
-Context for one hidden layer during heuristic recurrent emission.
+### OnnxImportConvTensorContext
 
-### IndexedMetadataAppendContext
+Resolved Conv initializer tensors and dimensions for one layer.
 
-Append-an-index metadata context for JSON-array metadata keys.
+### OnnxImportDimensionRecord
 
-### LayerActivationContext
+Loose ONNX shape-dimension record used by legacy import payload access.
 
-Activation analysis context for one layer.
+### OnnxImportHiddenLayerSpan
 
-### LayerBuildContext
+Hidden-layer span payload with one-based layer numbering and global offset.
 
-Layer build context used while emitting one ONNX graph layer segment.
+### OnnxImportHiddenSizeDerivationContext
 
-### LayerRecurrentDecisionContext
+Context for deriving hidden layer sizes from initializer tensors and metadata.
 
-Context used to decide recurrent emission branch usage.
+### OnnxImportInboundConnectionMap
 
-### LayerTraversalContext
+Inbound connection lookup map keyed by source node for one target neuron.
 
-Layer traversal context with adjacent layers and output classification.
+### OnnxImportLayerConnectionContext
 
-### LstmEmissionContext
+Execution context for assigning one hidden-layer recurrent diagonal tensor.
 
-Context for heuristic LSTM emission when a layer matches expected shape.
+### OnnxImportLayerNodePair
 
-### OnnxBaseModelBuildContext
+Node slices for one sequential imported layer assignment pass.
 
-Context for constructing a base ONNX model shell.
+### OnnxImportLayerNodePairBuildParams
 
-### OnnxBuildResolvedOptions
+Build params for one sequential layer node-pair slice operation.
 
-Resolved options used by ONNX model build orchestration.
+### OnnxImportLayerTensorNames
 
-### OnnxConvEmissionContext
+Weight tensor names for one imported layer index.
 
-Context used after resolving Conv mapping for one layer.
+### OnnxImportLayerWeightBucket
 
-### OnnxConvEmissionParams
+Bucketed ONNX dense/per-neuron tensors for one exported layer index.
 
-Parameters accepted by Conv layer emission.
+### OnnxImportPerNeuronAssignmentContext
 
-### OnnxConvParameters
+Context for assigning one per-neuron imported target node.
 
-Flattened Conv parameters for ONNX initializers.
+### OnnxImportPerNeuronLayerAssignmentContext
 
-### OnnxConvTensorNames
+Context for assigning per-neuron tensors for one layer.
 
-Tensor names generated for Conv parameters.
+### OnnxImportPoolingMetadata
 
-### OnnxExportOptions
+Parsed pooling metadata payload attached to imported network instances.
 
-Options controlling ONNX-like export.
+### OnnxImportRecurrentRestorationContext
 
-These options trade off strictness, portability, and fidelity:
+Context for recurrent self-connection restoration from ONNX metadata and tensors.
 
-- **Strict (default-ish)** export tries to keep the graph easy to interpret:
-  layered topology, homogeneous activations per layer, and fully-connected layers.
+### OnnxImportSelfConnectionUpsertContext
 
-- **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).
+Context for upserting one hidden node self-connection from recurrent weight.
 
-- **Recurrent export** (`allowRecurrent`) is intentionally conservative and currently
-  focuses on a constrained single-step representation and optional fused heuristics.
+### OnnxImportWeightAssignmentBuildParams
 
-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.
+Build params for creating shared ONNX import weight-assignment context.
 
-### OnnxGraphDimensionBuildContext
+### OnnxImportWeightAssignmentContext
 
-Context for constructing input/output ONNX graph dimensions.
+Shared weight-assignment context built once per ONNX import.
 
-### OnnxGraphDimensions
+### OnnxIncomingWeightAssignmentContext
 
-Output dimensions used by ONNX graph input/output value info payloads.
+Context for assigning dense incoming weights for one gate-neuron row.
 
 ### OnnxLayerEmissionContext
 
@@ -2951,526 +2936,541 @@ Context for emitting non-input layers during model build.
 
 Result of emitting non-input export layers.
 
-### OnnxModelMetadataContext
-
-Context for applying optional ONNX model metadata.
-
-### OnnxPostProcessingContext
-
-Context for post-processing and export metadata finalization.
-
-### OnnxRecurrentCollectionContext
-
-Context for collecting recurrent layer indices during model build.
-
-### OnnxRecurrentInputValueInfoContext
+### OnnxLayerFactory
 
-Context for constructing one recurrent previous-state graph input payload.
+Runtime factory map used to construct dynamic recurrent layer modules.
 
-### OnnxRecurrentLayerProcessingContext
+### OnnxMetadataProperty
 
-Execution context for processing one hidden recurrent layer.
+Canonical metadata key-value pair used in ONNX model metadata_props.
 
-### OnnxRecurrentLayerTraversalContext
+### OnnxModel
 
-Traversal context for one hidden layer during recurrent-input collection.
+ONNX-like model container (JSON-serializable).
 
-### OptionalLayerOutputParams
+This is the main “wire format” object in this folder. Persist it as JSON text:
 
-Shared parameters for optional pooling/flatten output emission.
+```ts
+const jsonText = JSON.stringify(model);
+const restoredModel = JSON.parse(jsonText) as OnnxModel;
+```
 
-### OptionalPoolingAndFlattenParams
+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`.
 
-Parameters for optional pooling + flatten emission after a layer output.
+Security/trust boundary:
+- Treat this as untrusted input if it comes from outside your process.
 
-### PerNeuronConcatNodePayload
+### OnnxModelMetadataContext
 
-Per-neuron concat node payload.
+Context for applying optional ONNX model metadata.
 
-### PerNeuronGraphNames
+### OnnxNode
 
-Per-neuron graph tensor names.
+One ONNX operator invocation inside the graph.
 
-### PerNeuronLayerContext
+Nodes connect named tensors rather than object references, which keeps the
+exported payload easy to serialize, inspect, and diff as plain JSON.
 
-Per-neuron layer context alias.
+### OnnxPerceptronBuildContext
 
-### PerNeuronLayerParams
+Build context for mapping ONNX layer sizes into a Neataptic MLP factory call.
 
-Parameters for per-neuron layer emission.
+### OnnxPerceptronSizeValidationContext
 
-### PerNeuronNodeContext
+Validation context for perceptron size-list checks during ONNX import.
 
-Per-neuron normalized node context.
+### OnnxPostProcessingContext
 
-### PerNeuronSubgraphContext
+Context for post-processing and export metadata finalization.
 
-Per-neuron subgraph emission context.
+### OnnxRecurrentCollectionContext
 
-### PerNeuronTensorNames
+Context for collecting recurrent layer indices during model build.
 
-Per-neuron initializer tensor names.
+### OnnxRecurrentInputValueInfoContext
 
-### PoolingAttributes
+Context for constructing one recurrent previous-state graph input payload.
 
-Pooling tensor attributes for ONNX node payloads.
+### OnnxRecurrentLayerProcessingContext
 
-### PoolingEmissionContext
+Execution context for processing one hidden recurrent layer.
 
-Pooling emission context resolved for one layer output.
+### OnnxRecurrentLayerTraversalContext
 
-### RecurrentActivationEmissionContext
+Traversal context for one hidden layer during recurrent-input collection.
 
-Context for selecting and emitting recurrent activation node payload.
+### OnnxRuntimeFactories
 
-### RecurrentGateBlockCollectionContext
+Runtime factories consumed during ONNX import network reconstruction.
 
-Context for collecting one gate parameter block.
+### OnnxRuntimeLayerFactory
 
-### RecurrentGateParameterCollectionResult
+```ts
+OnnxRuntimeLayerFactory(
+  size: number,
+): default
+```
 
-Flattened recurrent gate parameter vectors for one fused operator.
+Runtime layer-constructor signature used for recurrent layer reconstruction.
 
-### RecurrentGateRow
+### OnnxRuntimeLayerFactoryMap
 
-One recurrent gate row payload before flatten fold.
+Runtime layer module shape widened for fused-recurrent reconstruction wiring.
 
-### RecurrentGateRowCollectionContext
+### OnnxRuntimeLayerModule
 
-Context for collecting one recurrent gate row (one neuron).
+Runtime layer module shape consumed by ONNX import orchestration.
 
-### RecurrentGemmEmissionContext
+### OnnxRuntimePerceptronFactory
 
-Context for emitting one Gemm node for recurrent single-step export.
+```ts
+OnnxRuntimePerceptronFactory(
+  sizes: number[],
+): default
+```
 
-### RecurrentGraphNames
+Runtime perceptron factory signature used by ONNX import orchestration.
 
-Derived graph names for one recurrent single-step layer payload.
+### OnnxShape
 
-### RecurrentHeuristicEmissionContext
+ONNX tensor type shape.
 
-Context for heuristic recurrent operator emission traversal.
+### OnnxTensor
 
-### RecurrentInitializerEmissionContext
+Serialized tensor payload stored inside graph initializers.
 
-Context for pushing recurrent initializers into ONNX graph state.
+NeatapticTS currently writes floating-point parameter vectors and matrices to
+`float_data`, along with the tensor name, element type, and logical shape.
 
-### RecurrentInitializerNames
+### OnnxTensorType
 
-Initializer tensor names for one single-step recurrent layer.
+ONNX tensor type.
 
-### RecurrentInitializerValues
+### OnnxValueInfo
 
-Collected initializer vectors for one single-step recurrent layer.
+ONNX value info (input/output description).
 
-### RecurrentLayerEmissionContext
+### OptimizerConfigBase
 
-Derived execution context for single-step recurrent layer emission.
+Base optimizer configuration.
 
-### RecurrentLayerEmissionParams
+Training accepts either an optimizer name (`"adam"`, `"sgd"`, ...) or an object.
+This object form is useful when you want to pin numeric hyperparameters or wrap a base
+optimizer (e.g. lookahead).
 
-Parameters for single-step recurrent layer emission.
+Example:
 
-### RecurrentRowCollectionContext
+```ts
+net.train(set, {
+  iterations: 1_000,
+  rate: 0.001,
+  optimizer: { type: 'adamw', beta1: 0.9, beta2: 0.999, eps: 1e-8, weightDecay: 0.01 },
+});
+```
 
-Context for collecting one recurrent matrix row.
+Notes:
+- Exact supported `type` values are validated by training utilities.
+- Unspecified fields fall back to sensible defaults per optimizer.
 
-### SharedActivationNodeBuildParams
+### OptionalLayerOutputParams
 
-Shared parameters for constructing an activation node payload.
+Shared parameters for optional pooling/flatten output emission.
 
-### SharedGemmNodeBuildParams
+### OptionalPoolingAndFlattenParams
 
-Shared parameters for constructing a Gemm node payload.
+Parameters for optional pooling + flatten emission after a layer output.
 
-### SpecMetadataAppendContext
+### OutgoingOrderBuildContext
 
-Append-a-spec metadata context for JSON-array metadata keys.
+Context for constructing source-grouped outgoing connection order.
 
-### WeightToleranceComparisonContext
+### OutputLayerActivationContext
 
-Context for comparing two scalar weights with numeric tolerance.
+Output-layer activation assignment context.
 
-### NetworkWithOnnxImportPooling
+### Parent1GeneTraversalContext
 
-Network instance augmented with optional imported ONNX pooling metadata.
+Traversal state for parent-1 innovation walk.
 
-### OnnxImportArchitectureContext
+### Parent1TraversalSelectionResult
 
-Shared architecture extraction context with resolved graph dimensions.
+Fold result for parent-1 traversal selection.
 
-### OnnxImportArchitectureResult
+### ParentMetrics
 
-Parsed architecture dimensions extracted from ONNX import graph payloads.
+Compact parent metrics summary.
 
-### OnnxImportDimensionRecord
+### PathSearchContext
 
-Loose ONNX shape-dimension record used by legacy import payload access.
+Mutable context used while running iterative path search.
 
-### OnnxImportHiddenLayerSpan
+### PerNeuronConcatNodePayload
 
-Hidden-layer span payload with one-based layer numbering and global offset.
+Per-neuron concat node payload.
 
-### OnnxImportLayerConnectionContext
+### PerNeuronGraphNames
 
-Execution context for assigning one hidden-layer recurrent diagonal tensor.
+Per-neuron graph tensor names.
 
-### OnnxImportPoolingMetadata
+### PerNeuronLayerContext
 
-Parsed pooling metadata payload attached to imported network instances.
+Per-neuron layer context alias.
 
-### OnnxImportRecurrentRestorationContext
+### PerNeuronLayerParams
 
-Context for recurrent self-connection restoration from ONNX metadata and tensors.
+Parameters for per-neuron layer emission.
 
-### OnnxImportSelfConnectionUpsertContext
+### PerNeuronNodeContext
 
-Context for upserting one hidden node self-connection from recurrent weight.
+Per-neuron normalized node context.
 
-### OnnxImportAggregatedLayerAssignmentContext
+### PerNeuronSubgraphContext
 
-Context for assigning aggregated dense tensors for one layer.
+Per-neuron subgraph emission context.
 
-### OnnxImportAggregatedNeuronAssignmentContext
+### PerNeuronTensorNames
 
-Context for assigning one aggregated dense target neuron row.
+Per-neuron initializer tensor names.
 
-### OnnxImportConvCoordinateAssignmentContext
+### PlateauSmoothingConfig
 
-Context for applying Conv weights and bias at one output coordinate.
+Config for plateau smoothing computation.
 
-### OnnxImportConvKernelAssignmentContext
+### PlateauSmoothingState
 
-Context for assigning one concrete Conv kernel connection weight.
+Mutable smoothing state for plateau metric.
 
-### OnnxImportConvLayerContext
+### Pool2DMapping
 
-Context for reconstructing one Conv layer's imported connectivity.
+Mapping describing a pooling operation inserted after a given export-layer index.
 
-### OnnxImportConvLayerContextBuildParams
+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).
 
-Build params for creating one Conv reconstruction layer context.
+### PoolingAttributes
 
-### OnnxImportConvMetadata
+Pooling tensor attributes for ONNX node payloads.
 
-Parsed Conv metadata payload used for optional reconstruction pass.
+### PoolingEmissionContext
 
-### OnnxImportConvNodeSlices
+Pooling emission context resolved for one layer output.
 
-Layer node slices used while applying Conv reconstruction assignments.
+### PoolKeyMetrics
 
-### OnnxImportConvOutputCoordinate
+Per-pool-key allocation & reuse counters (educational / diagnostics).
 
-Coordinate for one Conv output neuron traversal position.
+### PopulationFitnessFunction
 
-### OnnxImportConvTensorContext
+```ts
+PopulationFitnessFunction(
+  population: default[],
+): Promise<void>
+```
 
-Resolved Conv initializer tensors and dimensions for one layer.
+Fitness signature evaluating full population asynchronously.
 
-### OnnxImportHiddenSizeDerivationContext
+### PopulationWorkerEvaluationContext
 
-Context for deriving hidden layer sizes from initializer tensors and metadata.
+Shared context for one population worker evaluation run.
 
-### OnnxImportInboundConnectionMap
+### PrimarySmoothingState
 
-Inbound connection lookup map keyed by source node for one target neuron.
+Mutable smoothing state for monitored error.
 
-### OnnxImportLayerNodePair
+### PruneSelectionContext
 
-Node slices for one sequential imported layer assignment pass.
+Context for selecting prune candidates.
 
-### OnnxImportLayerNodePairBuildParams
+### PruneSelectionResult
 
-Build params for one sequential layer node-pair slice operation.
+Result of prune candidate selection.
 
-### OnnxImportLayerTensorNames
+### PruningMethod
 
-Weight tensor names for one imported layer index.
+Pruning strategy identifiers.
 
-### OnnxImportLayerWeightBucket
+### PublishAdjacencyContext
 
-Bucketed ONNX dense/per-neuron tensors for one exported layer index.
+Context for publishing fully built adjacency slabs to internal network state.
 
-### OnnxImportPerNeuronAssignmentContext
+### ReconnectEndpointPairContext
 
-Context for assigning one per-neuron imported target node.
+Endpoint pair for reconnecting bridged paths.
 
-### OnnxImportPerNeuronLayerAssignmentContext
+### RecurrentActivationEmissionContext
 
-Context for assigning per-neuron tensors for one layer.
+Context for selecting and emitting recurrent activation node payload.
 
-### OnnxImportWeightAssignmentBuildParams
+### RecurrentGateBlockCollectionContext
 
-Build params for creating shared ONNX import weight-assignment context.
+Context for collecting one gate parameter block.
 
-### OnnxImportWeightAssignmentContext
+### RecurrentGateParameterCollectionResult
 
-Shared weight-assignment context built once per ONNX import.
+Flattened recurrent gate parameter vectors for one fused operator.
 
-### OnnxFusedGateApplicationContext
+### RecurrentGateRow
 
-Gate-weight application context for one reconstructed fused layer.
+One recurrent gate row payload before flatten fold.
 
-### OnnxFusedGateRowAssignmentContext
+### RecurrentGateRowCollectionContext
 
-Context for assigning one gate-neuron row from flattened ONNX tensors.
+Context for collecting one recurrent gate row (one neuron).
 
-### OnnxFusedLayerNeighborhood
+### RecurrentGemmEmissionContext
 
-Hidden-layer neighborhood slices around a reconstructed fused layer.
+Context for emitting one Gemm node for recurrent single-step export.
 
-### OnnxFusedLayerReconstructionContext
+### RecurrentGraphNames
 
-Execution context for one fused recurrent layer reconstruction.
+Derived graph names for one recurrent single-step layer payload.
 
-### OnnxFusedLayerRuntime
+### RecurrentHeuristicEmissionContext
 
-Runtime interface of a reconstructed fused recurrent layer instance.
+Context for heuristic recurrent operator emission traversal.
 
-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.
+### RecurrentInitializerEmissionContext
 
-### OnnxFusedRecurrentKind
+Context for pushing recurrent initializers into ONNX graph state.
 
-Supported fused recurrent operator families recognized during ONNX import.
+### RecurrentInitializerNames
 
-### OnnxFusedRecurrentSpec
+Initializer tensor names for one single-step recurrent layer.
 
-Fused recurrent family specification used during import reconstruction.
+### RecurrentInitializerValues
 
-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.
+Collected initializer vectors for one single-step recurrent layer.
 
-### OnnxFusedTensorPayload
+### RecurrentLayerEmissionContext
 
-Fused recurrent tensor payload read from ONNX initializers.
+Derived execution context for single-step recurrent layer emission.
 
-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.
+### RecurrentLayerEmissionParams
 
-### OnnxIncomingWeightAssignmentContext
+Parameters for single-step recurrent layer emission.
 
-Context for assigning dense incoming weights for one gate-neuron row.
+### RecurrentLayerShape
 
-### OnnxPerceptronBuildContext
+Minimal recurrent-layer shape used by mutation expanders.
 
-Build context for mapping ONNX layer sizes into a Neataptic MLP factory call.
+### RecurrentRowCollectionContext
 
-### OnnxPerceptronSizeValidationContext
+Context for collecting one recurrent matrix row.
 
-Validation context for perceptron size-list checks during ONNX import.
+### RegrowthExecutionContext
 
-### OnnxRuntimeFactories
+Context for regrowth execution routine.
 
-Runtime factories consumed during ONNX import network reconstruction.
+### RegrowthPlan
 
-### OnnxRuntimeLayerFactory
+Derived regrowth execution plan.
 
-```ts
-OnnxRuntimeLayerFactory(
-  size: number,
-): default
-```
+### RegrowthPlanContext
 
-Runtime layer-constructor signature used for recurrent layer reconstruction.
+Context for deriving regrowth plan.
 
-### OnnxRuntimeLayerModule
+### RegularizationConfig
 
-Runtime layer module shape consumed by ONNX import orchestration.
+L1/L2 regularization configuration.
 
-### OnnxRuntimePerceptronFactory
+### ResolvedNetworkSizeContext
 
-```ts
-OnnxRuntimePerceptronFactory(
-  sizes: number[],
-): default
-```
+Resolved input/output sizes for rebuild.
 
-Runtime perceptron factory signature used by ONNX import orchestration.
+Values reflect override-first resolution semantics used during deserialization.
 
-### NodeInternals
+### RNGSnapshot
 
-Runtime interface for accessing node internal properties.
+Snapshot payload for RNG state restore flows.
 
-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.
+### ScheduleConfig
 
-### NodeInternalsWithExportIndex
+Schedule callback configuration.
 
-Runtime node internals augmented with optional export index metadata.
+A schedule callback is a simple "tick hook" that runs every N iterations.
+Typical uses include logging, custom learning-rate schedules, or diagnostics.
 
-### ActivationFunction
+### ScheduledTargetContext
 
-```ts
-ActivationFunction(
-  x: number,
-  derivate: boolean | undefined,
-): number
-```
+Context for scheduled-pruning target computation.
 
-Runtime activation function signature used by ONNX activation import/export paths.
+### ScheduledTargetResult
 
-Neataptic-style activations support a dual-purpose call pattern:
-- `derivate === false | undefined`: return activation output $f(x)$
-- `derivate === true`: return derivative $f'(x)$
+Result of scheduled-pruning target computation.
 
-This matches historical Neataptic semantics and keeps ONNX import/export compatible.
+### SerializedConnection
 
-Example:
+Serialized connection representation used by compact and JSON formats.
 
-```ts
-const y = activation(x);
-const dy = activation(x, true);
-```
+Endpoints are canonical node indices, which keeps payloads deterministic and language-agnostic.
 
-### LayerOrderingNodeGroups
+### SerializedNetwork
 
-Node partitions used by ONNX layered-ordering inference traversal.
+Serialized network payload used in checkpoint callbacks.
 
-### LayerOrderingResolutionContext
+This is intentionally loose: serialization formats evolve and may include nested
+structures. Treat this as an opaque snapshot blob.
 
-Mutable traversal state while resolving hidden-layer ordering.
+### SerializeNetworkInternals
 
-### LayerValidationTraversalContext
+Runtime interface for accessing network internals during serialization.
 
-Layer-wise validation context for activation and connectivity checks.
+This is an internal bridge type used by serializer helpers to read and rebuild
+topology without exposing private implementation details in public APIs.
 
-### LayerActivationValidationContext
+### SerializeNodeInternals
 
-Activation-homogeneity decision context for one current layer.
+Runtime node internals needed for serialization workflows.
 
-### LayerConnectivityValidationContext
+These fields are the minimal node state required to round-trip compact and JSON payloads.
 
-Connectivity decision context for one source-target node pair.
+### SharedActivationNodeBuildParams
 
-### OnnxActivationOperation
+Shared parameters for constructing an activation node payload.
 
-Supported ONNX activation operators recognized during activation import.
+### SharedGemmNodeBuildParams
 
-### OnnxActivationLayerOperations
+Shared parameters for constructing a Gemm node payload.
 
-Layer-indexed activation operator lookup extracted from ONNX graph nodes.
+### SingleGenomeFitnessFunction
 
-### OnnxActivationParseResult
+```ts
+SingleGenomeFitnessFunction(
+  genome: default,
+): number
+```
 
-Parsed ONNX activation-node naming payload.
+Fitness signature evaluating one genome.
 
-### OnnxActivationAssignmentContext
+### SLAB_DEFAULT_ASYNC_CHUNK_SIZE
 
-Shared activation-assignment context for hidden and output traversal.
+Default async slab rebuild chunk size when no override is provided.
 
-### HiddenLayerActivationTraversalContext
+### SLAB_GROWTH_FACTOR_BROWSER
 
-Hidden-layer traversal context for assigning imported activation functions.
+Capacity growth factor for browser slab allocations.
 
-### OutputLayerActivationContext
+### SLAB_GROWTH_FACTOR_NODE
 
-Output-layer activation assignment context.
+Capacity growth factor for Node.js slab allocations.
 
-### OnnxActivationOperationResolutionContext
+### SLAB_ONE
 
-Activation operation resolution context for one neuron or layer default.
+Numeric one sentinel used for neutral gain defaults and index math.
 
-### OnnxConvKernelCoordinate
+### SLAB_ZERO
 
-Coordinate for one Conv kernel weight lookup.
+Numeric zero sentinel used across slab orchestration and helper pipelines.
 
-### OnnxLayerFactory
+### SlabBuildContext
 
-Runtime factory map used to construct dynamic recurrent layer modules.
+Immutable inputs required to build or grow connection slab buffers.
 
-### OnnxRuntimeLayerFactoryMap
+### SlabPopulateResult
 
-Runtime layer module shape widened for fused-recurrent reconstruction wiring.
+Result of scanning and populating optional gain/plastic slab arrays.
 
-### SLAB_ZERO
+### SlabWriteArrays
 
-Numeric zero sentinel used across slab orchestration and helper pipelines.
+Writable slab arrays targeted during connection serialization.
 
-### SLAB_ONE
+### SourcePeerConnectionCountContext
 
-Numeric one sentinel used for neutral gain defaults and index math.
+Context for source-to-peer connection counting.
 
-### SLAB_GROWTH_FACTOR_NODE
+### SpecMetadataAppendContext
 
-Capacity growth factor for Node.js slab allocations.
+Append-a-spec metadata context for JSON-array metadata keys.
 
-### SLAB_GROWTH_FACTOR_BROWSER
+### StandaloneGenerationContext
 
-Capacity growth factor for browser slab allocations.
+Shared mutable state for standalone source generation.
 
-### SLAB_DEFAULT_ASYNC_CHUNK_SIZE
+### StartIndicesBuildContext
 
-Default async slab rebuild chunk size when no override is provided.
+Context for constructing CSR start offsets from precomputed fan-out counts.
 
-### ConnectionInternals
+### StatsNetworkProps
 
-Internal Connection properties accessed during slab operations.
+Internal network properties used by stats operations.
 
-### NetworkSlabProps
+### SubNodeMutationConfig
 
-Internal Network properties for slab operations.
+Mutation keep-gates option surface used by sub-node removal logic.
 
-### PoolKeyMetrics
+### TargetLayerPeerContext
 
-Per-pool-key allocation & reuse counters (educational / diagnostics).
+Context for target-layer peer traversal.
 
-### TypedArray
+### TopologyBuildContext
 
-Union of slab typed array element container types.
+Mutable context used while building topological ordering.
 
-### TypedArrayConstructor
+### TopologyNetworkProps
 
-Constructor type for typed arrays used in slabs.
+Internal topology state carrier.
 
-### NetworkActivationRuntime
+### TrainingConnectionInternals
 
-Runtime activation contract used by slab-based execution paths.
+Runtime connection view used by training internals.
 
-### NetworkTopoRuntime
+### TrainingNetworkInternals
 
-Runtime topology contract used to lazily rebuild topological order.
+Runtime network view used by training internals.
 
-### FastSlabNodeRuntime
+### TrainingNodeInternals
 
-Node shape required by fast slab activation kernels.
+Runtime node view used by training internals.
 
-### SlabBuildContext
+### TrainingOptions
 
-Immutable inputs required to build or grow connection slab buffers.
+Public training options accepted by the high-level training orchestration.
 
-### SlabPopulateResult
+Training in this codebase is conceptually:
+1) forward activation
+2) backward propagation
+3) optimizer update
+repeated until a stopping condition is met.
 
-Result of scanning and populating optional gain/plastic slab arrays.
+Minimal example:
 
-### SlabWriteArrays
+```ts
+net.train(set, {
+  iterations: 500,
+  rate: 0.3,
+  batchSize: 16,
+  gradientClip: { mode: 'norm', maxNorm: 1 },
+});
+```
 
-Writable slab arrays targeted during connection serialization.
+Stopping conditions:
+- Provide at least one of `iterations` or `error`.
+- `earlyStopPatience` adds an additional "stop when no improvement" guard.
 
-### ConnectionSlabView
+### TrainingSample
 
-Shape returned by getConnectionSlab describing the packed SoA view.
+A single supervised training sample used in evolution scoring.
 
-### BuildAdjacencyContext
+### TypedArray
 
-Shared immutable inputs used across the adjacency build pipeline.
+Union of slab typed array element container types.
 
-### FanOutCollectionContext
+### TypedArrayConstructor
 
-Context for fan-out collection: build inputs plus the output count buffer.
+Constructor type for typed arrays used in slabs.
 
-### StartIndicesBuildContext
+### WeightSamplingRangeContext
 
-Context for constructing CSR start offsets from precomputed fan-out counts.
+Context for sampling one random weight value.
 
-### OutgoingOrderBuildContext
+### WeightToleranceComparisonContext
 
-Context for constructing source-grouped outgoing connection order.
+Context for comparing two scalar weights with numeric tolerance.
 
-### PublishAdjacencyContext
+### WorkerTraversalContext
 
-Context for publishing fully built adjacency slabs to internal network state.
+Worker-local traversal context.