@reicek/neataptic-ts 0.1.26 → 0.1.27

package/src/architecture/network/activate/docs.order.json

@@ -0,0 +1,9 @@
+{
+  "introFile": "network.activate.utils.ts",
+  "fileOrder": [
+    "network.activate.utils.ts",
+    "network.activate.utils.types.ts",
+    "network.activate.core.utils.ts",
+    "network.activate.helpers.utils.ts"
+  ]
+}

package/src/architecture/network/activate/network.activate.utils.ts

@@ -1,3 +1,93 @@
+/**
+ * Activation chapter for `Network` execution policy.
+ *
+ * This folder answers the moment when a graph already exists and the next
+ * question becomes: how should signal move through it right now? The same
+ * network may be stepped for ordinary inference, training-aware forward passes,
+ * zero-copy raw output reuse, or a sequence of batch rows. Keeping those paths
+ * together makes the execution tradeoffs visible without mixing them into
+ * topology or serialization code.
+ *
+ * The important split is between graph meaning and graph execution. Node and
+ * connection chapters explain what the structure is. `activate/` explains how
+ * that structure is stepped: validate inputs, decide whether the slab fast path
+ * is still legal, preserve or skip training traces, and return outputs in the
+ * shape the caller requested.
+ *
+ * A second useful lens is to read the public exports as four modes.
+ * `activate()` is the ordinary compatibility path. `noTraceActivate()` is the
+ * hot inference path when trace bookkeeping would be wasteful. `activateRaw()`
+ * keeps typed-array reuse available when pooling matters more than boxed
+ * outputs. `activateBatch()` is the clear orchestration layer for repeated
+ * forward passes over many rows.
+ *
+ * The performance lesson here is not "always choose the fastest path." It is
+ * "choose the narrowest path that still matches the caller's semantics." If a
+ * network is slab-ready, this chapter can exploit contiguous typed arrays. If a
+ * structural edit made that layout stale, the same boundary falls back to node
+ * traversal instead of forcing callers to understand storage internals first.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Input[caller input]:::base --> Modes[activate chapter]:::accent
+ *   Modes --> Trace[activate<br/>keep traces]:::base
+ *   Modes --> NoTrace[noTraceActivate<br/>inference hot path]:::base
+ *   Modes --> Raw[activateRaw<br/>typed output reuse]:::base
+ *   Modes --> Batch[activateBatch<br/>repeat over rows]:::base
+ * ```
+ *
+ * ```mermaid
+ * flowchart TD
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   ActivateChapter[activate/]:::accent --> Validation[input validation and contexts]:::base
+ *   ActivateChapter --> FastPath[slab fast path when layout is ready]:::base
+ *   ActivateChapter --> Traversal[node traversal fallback]:::base
+ *   ActivateChapter --> Buffers[pooled activation buffers]:::base
+ * ```
+ *
+ * For background on why some activation paths preserve training traces while
+ * others skip them, see Wikipedia contributors,
+ * [Backpropagation](https://en.wikipedia.org/wiki/Backpropagation). This
+ * chapter sits at the forward-pass side of that story and decides how much
+ * training bookkeeping each call should carry along.
+ *
+ * Example: use the no-trace path when you only need inference outputs.
+ *
+ * ```ts
+ * const network = Network.createMLP(2, [3], 1);
+ * const outputValues = network.noTraceActivate([0.2, 0.8]);
+ * ```
+ *
+ * Example: run the same network over several input rows with one orchestration
+ * call.
+ *
+ * ```ts
+ * const network = Network.createMLP(2, [3], 1);
+ * const batchOutputs = network.activateBatch(
+ *   [
+ *     [0, 1],
+ *     [1, 0],
+ *   ],
+ *   true,
+ * );
+ * ```
+ *
+ * Practical reading order:
+ *
+ * 1. Start here for the public activation modes and their semantic differences.
+ * 2. Continue into `network.activate.core.utils.ts` when you want the ordinary
+ *    forward-pass pipeline.
+ * 3. Continue into `network.activate.raw.utils.ts` and the no-trace helpers
+ *    when typed-array reuse or inference hot paths are the next question.
+ * 4. Finish with the context and helper files when you want the orchestration
+ *    details behind validation, batching, and fallback behavior.
+ */
+
 import type Network from '../../network/network';
 export { activate, gaussianRand } from './network.activate.core.utils';
 import {

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

@@ -1,10 +1,81 @@
 # architecture/network/connect
 
-## architecture/network/connect/network.connect.utils.types.ts
+Connection-editing chapter for single-edge graph surgery.
+
+This folder owns the smallest structural change a `Network` can make: add or
+remove one directed edge while keeping graph invariants, gating state, and
+execution caches honest. Higher-level builders may connect layers or groups
+in bulk, but they still depend on the legality and bookkeeping rules taught
+here.
+
+The important distinction is between edge creation and edge registration.
+`Node.connect()` can manufacture one or more low-level connection objects,
+but the network still has to decide whether those edges are legal in the
+current topology policy, whether they belong in normal or self-connection
+storage, and whether cached topological or slab views must be invalidated.
+
+Acyclic mode makes that policy visible. In feed-forward configurations this
+chapter refuses back-edges and self-edges that would violate the intended
+execution order. In unconstrained mode the same surface accepts those edits
+and simply keeps the runtime collections synchronized. That lets callers ask
+for structural edits without duplicating the topology rules everywhere else.
+
+The matching remove path is equally educational. Disconnecting one edge is
+not just a splice from an array. If the edge is gated, the gating linkage has
+to be released first. After that, structural caches are marked dirty so the
+next activation or slab rebuild sees the new graph instead of a stale one.
+
+```mermaid
+flowchart LR
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  Request[connect request]:::base --> Guard[acyclic legality check]:::accent
+  Guard --> Create[Node.connect creates low-level edges]:::base
+  Create --> Register[classify self-edge or standard edge]:::base
+  Register --> Dirty[mark topology and slab caches dirty]:::base
+```
 
-### NetworkInternals
+```mermaid
+flowchart TD
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
 
-Internal network state shape shared by connect utility helper modules.
+  Mode[topology mode]:::accent --> FeedForward[feed-forward<br/>reject back-edges]:::base
+  Mode --> Unconstrained[unconstrained<br/>allow recurrent edits]:::base
+  FeedForward --> Collections[network collections stay valid]:::base
+  Unconstrained --> Collections
+```
+
+For background on the scheduling constraint behind acyclic mode, see
+Wikipedia contributors,
+[Topological sorting](https://en.wikipedia.org/wiki/Topological_sorting).
+The legality checks in this folder protect the execution order assumptions
+that feed-forward activation relies on.
+
+Example: add one explicit edge between two nodes.
+
+```ts
+const [edge] = network.connect(sourceNode, targetNode, 0.5);
+console.log(edge.weight);
+```
+
+Example: remove one existing edge and let the network invalidate its cached
+structure for the next run.
+
+```ts
+network.disconnect(sourceNode, targetNode);
+```
+
+Practical reading order:
+
+1. Start here for the public `connect()` and `disconnect()` semantics.
+2. Continue into `network.connect.create.utils.ts` for edge creation,
+   registration, and acyclic guards.
+3. Continue into `network.connect.remove.utils.ts` for disconnect cleanup and
+   gated-edge removal behavior.
+4. Finish with `network.connect.utils.types.ts` when you need the internal
+   state shape shared across both flows.
 
 ## architecture/network/connect/network.connect.utils.ts
 
@@ -95,6 +166,12 @@ Example:
 
 net.disconnect(nodeA, nodeB);
 
+## architecture/network/connect/network.connect.utils.types.ts
+
+### NetworkInternals
+
+Internal network state shape shared by connect utility helper modules.
+
 ## architecture/network/connect/network.connect.create.utils.ts
 
 ### createConnectionsFromSourceNode

package/src/architecture/network/connect/docs.order.json

@@ -0,0 +1,9 @@
+{
+  "introFile": "network.connect.utils.ts",
+  "fileOrder": [
+    "network.connect.utils.ts",
+    "network.connect.utils.types.ts",
+    "network.connect.create.utils.ts",
+    "network.connect.remove.utils.ts"
+  ]
+}

package/src/architecture/network/connect/network.connect.utils.ts

@@ -1,3 +1,82 @@
+/**
+ * Connection-editing chapter for single-edge graph surgery.
+ *
+ * This folder owns the smallest structural change a `Network` can make: add or
+ * remove one directed edge while keeping graph invariants, gating state, and
+ * execution caches honest. Higher-level builders may connect layers or groups
+ * in bulk, but they still depend on the legality and bookkeeping rules taught
+ * here.
+ *
+ * The important distinction is between edge creation and edge registration.
+ * `Node.connect()` can manufacture one or more low-level connection objects,
+ * but the network still has to decide whether those edges are legal in the
+ * current topology policy, whether they belong in normal or self-connection
+ * storage, and whether cached topological or slab views must be invalidated.
+ *
+ * Acyclic mode makes that policy visible. In feed-forward configurations this
+ * chapter refuses back-edges and self-edges that would violate the intended
+ * execution order. In unconstrained mode the same surface accepts those edits
+ * and simply keeps the runtime collections synchronized. That lets callers ask
+ * for structural edits without duplicating the topology rules everywhere else.
+ *
+ * The matching remove path is equally educational. Disconnecting one edge is
+ * not just a splice from an array. If the edge is gated, the gating linkage has
+ * to be released first. After that, structural caches are marked dirty so the
+ * next activation or slab rebuild sees the new graph instead of a stale one.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Request[connect request]:::base --> Guard[acyclic legality check]:::accent
+ *   Guard --> Create[Node.connect creates low-level edges]:::base
+ *   Create --> Register[classify self-edge or standard edge]:::base
+ *   Register --> Dirty[mark topology and slab caches dirty]:::base
+ * ```
+ *
+ * ```mermaid
+ * flowchart TD
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Mode[topology mode]:::accent --> FeedForward[feed-forward<br/>reject back-edges]:::base
+ *   Mode --> Unconstrained[unconstrained<br/>allow recurrent edits]:::base
+ *   FeedForward --> Collections[network collections stay valid]:::base
+ *   Unconstrained --> Collections
+ * ```
+ *
+ * For background on the scheduling constraint behind acyclic mode, see
+ * Wikipedia contributors,
+ * [Topological sorting](https://en.wikipedia.org/wiki/Topological_sorting).
+ * The legality checks in this folder protect the execution order assumptions
+ * that feed-forward activation relies on.
+ *
+ * Example: add one explicit edge between two nodes.
+ *
+ * ```ts
+ * const [edge] = network.connect(sourceNode, targetNode, 0.5);
+ * console.log(edge.weight);
+ * ```
+ *
+ * Example: remove one existing edge and let the network invalidate its cached
+ * structure for the next run.
+ *
+ * ```ts
+ * network.disconnect(sourceNode, targetNode);
+ * ```
+ *
+ * Practical reading order:
+ *
+ * 1. Start here for the public `connect()` and `disconnect()` semantics.
+ * 2. Continue into `network.connect.create.utils.ts` for edge creation,
+ *    registration, and acyclic guards.
+ * 3. Continue into `network.connect.remove.utils.ts` for disconnect cleanup and
+ *    gated-edge removal behavior.
+ * 4. Finish with `network.connect.utils.types.ts` when you need the internal
+ *    state shape shared across both flows.
+ */
+
 import type Network from '../../network/network';
 import Node from '../../node';
 import Connection from '../../connection';

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

@@ -1,28 +1,94 @@
 # architecture/network/deterministic
 
-## architecture/network/deterministic/network.deterministic.utils.types.ts
+Deterministic RNG chapter for replayable `Network` behavior.
+
+This folder keeps random state explicit so stochastic network behavior can be
+repeated instead of merely hoped for. The same graph may use randomness for
+dropout, stochastic depth, weight noise, training-time perturbations, or
+mutation-adjacent helpers. Deterministic utilities give those flows a common
+seed, checkpoint, and restore surface.
+
+The important design split is between setup, state access, and lifecycle
+capture. `setSeed()` installs a reproducible random stream. `getRNGState()`
+and `setRNGState()` expose lightweight numeric checkpoints for pause-resume
+workflows. `snapshotRNG()` and `restoreRNG()` support the slightly richer
+lifecycle case where external tooling wants to branch or reconstruct the
+active random function more deliberately.
+
+This chapter matters because deterministic behavior is only useful when it is
+applied consistently. A seed is not enough if callers cannot checkpoint the
+current stream, resume it later, or understand which helper owns the active
+random function. By keeping those responsibilities together, the network
+surface stays reproducible across tests, debugging sessions, and long-running
+experiments.
+
+Another useful lens is to think in terms of branching timelines. Training or
+evolution often needs to ask, "what happens if I continue from exactly this
+stochastic point but change one later decision?" The deterministic helpers in
+this folder are the bridge that makes that question answerable instead of
+approximate.
+
+```mermaid
+flowchart LR
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  Seed[setSeed]:::accent --> RandomOps[stochastic network operations]:::base
+  RandomOps --> State[getRNGState checkpoint]:::base
+  RandomOps --> Snapshot[snapshotRNG lifecycle snapshot]:::base
+  State --> Resume[setRNGState resume]:::accent
+  Snapshot --> Restore[restoreRNG external restore]:::accent
+```
 
-### NetworkInternals
+```mermaid
+flowchart TD
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
 
-Internal deterministic network state shape used across deterministic utility modules.
+  DeterministicChapter[deterministic/]:::accent --> Setup[setup utils<br/>install seed-backed RNG]:::base
+  DeterministicChapter --> State[state utils<br/>read and write numeric state]:::base
+  DeterministicChapter --> Lifecycle[lifecycle utils<br/>snapshot and restore]:::base
+```
 
-### RNG_WEYL_INCREMENT
+For background on why this chapter can stay reproducible with a small state
+surface, see Wikipedia contributors,
+[Pseudorandom number generator](https://en.wikipedia.org/wiki/Pseudorandom_number_generator).
+The exported helpers here are about managing one deterministic stream, not
+about generating cryptographic randomness.
 
-Fixed Weyl increment used to advance deterministic PRNG state.
+Example: initialize one reproducible random stream and checkpoint its numeric
+state for later reuse.
 
-### RNGSnapshot
+```ts
+network.setSeed(42);
+const checkpoint = network.getRNGState();
 
-Snapshot payload for RNG state restore flows.
+if (checkpoint !== undefined) {
+  network.setRNGState(checkpoint);
+}
+```
 
-### UINT32_NORMALIZER
+Example: capture a portable snapshot before branching into a debugging or
+replay workflow.
 
-Divisor used to normalize uint32 PRNG output into [0, 1).
+```ts
+network.setSeed(7);
+const snapshot = network.snapshotRNG();
 
-## architecture/network/deterministic/network.deterministic.utils.ts
+console.log(snapshot.state, snapshot.step);
+```
+
+Practical reading order:
 
-### network.deterministic.utils
+1. Start here for the public deterministic helpers and their intended use.
+2. Continue into `network.deterministic.setup.utils.ts` for seed-backed RNG
+   installation.
+3. Continue into `network.deterministic.state.utils.ts` for numeric
+   checkpoint accessors.
+4. Finish in `network.deterministic.lifecycle.utils.ts` when you want the
+   richer snapshot and restore plumbing.
 
-Default export bundle for convenient named imports.
+## architecture/network/deterministic/network.deterministic.utils.ts
 
 ### getRandomFn
 
@@ -181,6 +247,24 @@ Example:
 const snapshot = network.snapshotRNG();
 ```
 
+## architecture/network/deterministic/network.deterministic.utils.types.ts
+
+### NetworkInternals
+
+Internal deterministic network state shape used across deterministic utility modules.
+
+### RNG_WEYL_INCREMENT
+
+Fixed Weyl increment used to advance deterministic PRNG state.
+
+### RNGSnapshot
+
+Snapshot payload for RNG state restore flows.
+
+### UINT32_NORMALIZER
+
+Divisor used to normalize uint32 PRNG output into [0, 1).
+
 ## architecture/network/deterministic/network.deterministic.setup.utils.ts
 
 ### advanceStateWithWeylIncrement

package/src/architecture/network/deterministic/docs.order.json

@@ -0,0 +1,10 @@
+{
+  "introFile": "network.deterministic.utils.ts",
+  "fileOrder": [
+    "network.deterministic.utils.ts",
+    "network.deterministic.utils.types.ts",
+    "network.deterministic.setup.utils.ts",
+    "network.deterministic.state.utils.ts",
+    "network.deterministic.lifecycle.utils.ts"
+  ]
+}

package/src/architecture/network/deterministic/network.deterministic.utils.ts

@@ -1,3 +1,93 @@
+/**
+ * Deterministic RNG chapter for replayable `Network` behavior.
+ *
+ * This folder keeps random state explicit so stochastic network behavior can be
+ * repeated instead of merely hoped for. The same graph may use randomness for
+ * dropout, stochastic depth, weight noise, training-time perturbations, or
+ * mutation-adjacent helpers. Deterministic utilities give those flows a common
+ * seed, checkpoint, and restore surface.
+ *
+ * The important design split is between setup, state access, and lifecycle
+ * capture. `setSeed()` installs a reproducible random stream. `getRNGState()`
+ * and `setRNGState()` expose lightweight numeric checkpoints for pause-resume
+ * workflows. `snapshotRNG()` and `restoreRNG()` support the slightly richer
+ * lifecycle case where external tooling wants to branch or reconstruct the
+ * active random function more deliberately.
+ *
+ * This chapter matters because deterministic behavior is only useful when it is
+ * applied consistently. A seed is not enough if callers cannot checkpoint the
+ * current stream, resume it later, or understand which helper owns the active
+ * random function. By keeping those responsibilities together, the network
+ * surface stays reproducible across tests, debugging sessions, and long-running
+ * experiments.
+ *
+ * Another useful lens is to think in terms of branching timelines. Training or
+ * evolution often needs to ask, "what happens if I continue from exactly this
+ * stochastic point but change one later decision?" The deterministic helpers in
+ * this folder are the bridge that makes that question answerable instead of
+ * approximate.
+ *
+ * ```mermaid
+ * flowchart LR
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   Seed[setSeed]:::accent --> RandomOps[stochastic network operations]:::base
+ *   RandomOps --> State[getRNGState checkpoint]:::base
+ *   RandomOps --> Snapshot[snapshotRNG lifecycle snapshot]:::base
+ *   State --> Resume[setRNGState resume]:::accent
+ *   Snapshot --> Restore[restoreRNG external restore]:::accent
+ * ```
+ *
+ * ```mermaid
+ * flowchart TD
+ *   classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+ *   classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+ *
+ *   DeterministicChapter[deterministic/]:::accent --> Setup[setup utils<br/>install seed-backed RNG]:::base
+ *   DeterministicChapter --> State[state utils<br/>read and write numeric state]:::base
+ *   DeterministicChapter --> Lifecycle[lifecycle utils<br/>snapshot and restore]:::base
+ * ```
+ *
+ * For background on why this chapter can stay reproducible with a small state
+ * surface, see Wikipedia contributors,
+ * [Pseudorandom number generator](https://en.wikipedia.org/wiki/Pseudorandom_number_generator).
+ * The exported helpers here are about managing one deterministic stream, not
+ * about generating cryptographic randomness.
+ *
+ * Example: initialize one reproducible random stream and checkpoint its numeric
+ * state for later reuse.
+ *
+ * ```ts
+ * network.setSeed(42);
+ * const checkpoint = network.getRNGState();
+ *
+ * if (checkpoint !== undefined) {
+ *   network.setRNGState(checkpoint);
+ * }
+ * ```
+ *
+ * Example: capture a portable snapshot before branching into a debugging or
+ * replay workflow.
+ *
+ * ```ts
+ * network.setSeed(7);
+ * const snapshot = network.snapshotRNG();
+ *
+ * console.log(snapshot.state, snapshot.step);
+ * ```
+ *
+ * Practical reading order:
+ *
+ * 1. Start here for the public deterministic helpers and their intended use.
+ * 2. Continue into `network.deterministic.setup.utils.ts` for seed-backed RNG
+ *    installation.
+ * 3. Continue into `network.deterministic.state.utils.ts` for numeric
+ *    checkpoint accessors.
+ * 4. Finish in `network.deterministic.lifecycle.utils.ts` when you want the
+ *    richer snapshot and restore plumbing.
+ */
+
 import type Network from '../../network/network';
 import type { RNGSnapshot } from './network.deterministic.utils.types';
 import { setSeed as setupSeed } from './network.deterministic.setup.utils';