@reicek/neataptic-ts 0.1.26 → 0.1.27

package/src/architecture/activationArrayPool/activationArrayPool.ts

@@ -6,6 +6,43 @@
  * pool is not a new runtime primitive; it is the memory policy that decides
  * when temporary activation storage should be reused instead of reallocated.
  *
+ * Think of this boundary as scratch-space policy for activation-heavy code.
+ * Network execution repeatedly asks for short-lived arrays whose shapes often
+ * repeat from sample to sample. Reallocating those arrays every pass adds
+ * garbage-collector work without changing the model's behavior. This chapter
+ * keeps the reusable buffer story explicit while leaving graph semantics to
+ * the node, layer, and network chapters.
+ *
+ * The key design choice is that pooling happens by array length, not by caller
+ * identity. A network slab path and a layer helper can share the same retained
+ * storage as long as they request the same length and release the buffer after
+ * use. Acquire always returns a zeroed buffer, so the pool promises clean
+ * scratch memory rather than cached activations or memoized results.
+ *
+ * That distinction matters when you are debugging correctness. This folder is
+ * not a semantic cache and it does not preserve intermediate values for later
+ * reads. It only keeps array shells alive long enough to reduce allocation
+ * churn in hot loops, worker batches, and repeated forward passes.
+ *
+ * ```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[Activation request]:::base --> Acquire[acquire by length]:::accent
+ *   Acquire -->|bucket hit| Reuse[Zeroed reused buffer]:::base
+ *   Acquire -->|bucket miss| Fresh[Freshly allocated buffer]:::base
+ *   Reuse --> Execute[Layer or network activation]:::base
+ *   Fresh --> Execute
+ *   Execute --> Release[release buffer]:::accent
+ *   Release --> Bucket[Length bucket]:::base
+ * ```
+ *
+ * For background on the broader software pattern, see Wikipedia contributors,
+ * [Object pool pattern](https://en.wikipedia.org/wiki/Object_pool_pattern).
+ * This chapter applies that idea to activation scratch space, not to long-lived
+ * model parameters.
+ *
  * Read this chapter in three passes:
  *
  * 1. start with `ActivationArray` to see which buffer shapes the runtime can
@@ -14,6 +51,22 @@
  *    the hot-path allocation story,
  * 3. finish with `stats()`, `setMaxPerBucket()`, and `prewarm()` when you want
  *    observability and capacity control.
+ *
+ * Example: reuse one scratch buffer around a custom activation-heavy loop.
+ *
+ * ```ts
+ * const activationArray = activationArrayPool.acquire(128);
+ * // fill and consume the buffer here
+ * activationArrayPool.release(activationArray);
+ * ```
+ *
+ * Example: prewarm one common bucket before a large evaluation batch.
+ *
+ * ```ts
+ * activationArrayPool.setMaxPerBucket(32);
+ * activationArrayPool.prewarm(256, 8);
+ * const stats = activationArrayPool.stats();
+ * ```
  */
 
 import { config } from '../../config';

package/src/architecture/layer/README.md

@@ -8,6 +8,59 @@ this chapter keep activation, connection, propagation, and factory policies
 focused, while this file preserves the orchestration story that readers and
 callers actually meet first.
 
+If `Node` is the single-neuron chapter and `Network` is the whole-graph
+chapter, `Layer` is the middle shelf that lets builders talk in model-sized
+blocks. Dense stages, recurrent cells, normalization passes, and memory-
+shaped motifs all need more intent than a raw list of nodes, but far less
+ceremony than constructing an entire network by hand.
+
+That middle shelf matters for two audiences at once. Callers want one place
+to say "make a dense block" or "connect this stage to that stage" without
+manually pushing node arrays around. Maintainers want activation, wiring,
+propagation, and factory mechanics separated so the public API can stay easy
+to read while the underlying policies continue to evolve. This folderized
+chapter is how the repo serves both goals at the same time.
+
+One useful mental model is to place `Layer` between `Group` and `Network`.
+`Group` exposes a reusable cluster of nodes plus wiring vocabulary. `Layer`
+adds the stronger promise that the cluster represents a recognizable model
+stage with standard entrypoints such as `activate()`, `propagate()`,
+`connect()`, and factory constructors. `Network` then chains many of those
+stages into a runnable, mutable graph.
+
+A second mental model is to treat `layer.ts` as a public facade over several
+helper shelves. Readers should start here because this file owns the stable
+orchestration story. The helper files exist to keep concerns narrow: one set
+handles activation and propagation, another handles wiring and guards, and
+the factory helpers explain how dense, recurrent, normalization, and
+experimental layer families are assembled.
+
+```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;
+
+  Node[Node primitives]:::base --> Group[Group blocks]:::base
+  Group --> Layer[Layer model stage]:::accent
+  Layer --> Network[Network orchestration]:::base
+  Layer --> Architect[Architect presets]:::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;
+
+  LayerFacade[Layer facade]:::accent --> Runtime[activate propagate clear gate input]:::base
+  LayerFacade --> Wiring[connection and guard helpers]:::base
+  LayerFacade --> Factories[dense recurrent normalization experimental factories]:::base
+```
+
+For background on the broader modeling idea, see Wikipedia contributors,
+[Artificial neural network](https://en.wikipedia.org/wiki/Artificial_neural_network).
+This chapter is narrower: it documents the library boundary that packages
+those ideas into reusable blocks and helper-owned policies.
+
 Read this chapter in three passes:
 
 1. start with the `Layer` class overview to understand why the boundary
@@ -17,16 +70,52 @@ Read this chapter in three passes:
 3. finish with the static factory methods when you want named layer shapes
    such as dense, recurrent, normalization, or experimental blocks.
 
+Example: wire a small dense stack using the same block-level API that higher
+level builders depend on.
+
+```ts
+const input = Layer.dense(2);
+input.set({ type: 'input' });
+const hidden = Layer.dense(4);
+const output = Layer.dense(1);
+output.set({ type: 'output' });
+
+input.connect(hidden);
+hidden.connect(output);
+
+input.activate([0, 1]);
+hidden.activate();
+const values = output.activate();
+```
+
+Example: swap in a richer factory-built block without changing the top-level
+layer-to-layer wiring vocabulary.
+
+```ts
+const recurrent = Layer.lstm(8);
+const readout = Layer.dense(2);
+
+recurrent.connect(readout);
+```
+
 ## architecture/layer/layer.ts
 
 ### Layer
 
-Represents a functional layer within a neural network architecture.
+Public block-level facade for layer-oriented architecture building.
+
+`Layer` is the boundary readers reach for when a graph region should behave
+like one model stage rather than a loose collection of neurons. It
+normalizes common operations across dense, recurrent, normalization, and
+experimental factories so higher-level chapters can compose readable graphs
+without depending on each helper shelf's private implementation details.
+
+This makes the class useful when you want to:
 
-Layers act as organizational units for nodes, facilitating the creation of
-complex network structures like Dense, LSTM, GRU, or Memory layers.
-They manage the collective behavior of their nodes, including activation,
-propagation, and connection to other network components.
+- assemble a network from named blocks instead of raw nodes,
+- reuse the same activation, wiring, and propagation vocabulary across layer
+  families,
+- keep factory-specific mechanics below the public API.
 
 ### default
 

package/src/architecture/layer/layer.ts

@@ -7,6 +7,59 @@
  * focused, while this file preserves the orchestration story that readers and
  * callers actually meet first.
  *
+ * If `Node` is the single-neuron chapter and `Network` is the whole-graph
+ * chapter, `Layer` is the middle shelf that lets builders talk in model-sized
+ * blocks. Dense stages, recurrent cells, normalization passes, and memory-
+ * shaped motifs all need more intent than a raw list of nodes, but far less
+ * ceremony than constructing an entire network by hand.
+ *
+ * That middle shelf matters for two audiences at once. Callers want one place
+ * to say "make a dense block" or "connect this stage to that stage" without
+ * manually pushing node arrays around. Maintainers want activation, wiring,
+ * propagation, and factory mechanics separated so the public API can stay easy
+ * to read while the underlying policies continue to evolve. This folderized
+ * chapter is how the repo serves both goals at the same time.
+ *
+ * One useful mental model is to place `Layer` between `Group` and `Network`.
+ * `Group` exposes a reusable cluster of nodes plus wiring vocabulary. `Layer`
+ * adds the stronger promise that the cluster represents a recognizable model
+ * stage with standard entrypoints such as `activate()`, `propagate()`,
+ * `connect()`, and factory constructors. `Network` then chains many of those
+ * stages into a runnable, mutable graph.
+ *
+ * A second mental model is to treat `layer.ts` as a public facade over several
+ * helper shelves. Readers should start here because this file owns the stable
+ * orchestration story. The helper files exist to keep concerns narrow: one set
+ * handles activation and propagation, another handles wiring and guards, and
+ * the factory helpers explain how dense, recurrent, normalization, and
+ * experimental layer families are assembled.
+ *
+ * ```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;
+ *
+ *   Node[Node primitives]:::base --> Group[Group blocks]:::base
+ *   Group --> Layer[Layer model stage]:::accent
+ *   Layer --> Network[Network orchestration]:::base
+ *   Layer --> Architect[Architect presets]:::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;
+ *
+ *   LayerFacade[Layer facade]:::accent --> Runtime[activate propagate clear gate input]:::base
+ *   LayerFacade --> Wiring[connection and guard helpers]:::base
+ *   LayerFacade --> Factories[dense recurrent normalization experimental factories]:::base
+ * ```
+ *
+ * For background on the broader modeling idea, see Wikipedia contributors,
+ * [Artificial neural network](https://en.wikipedia.org/wiki/Artificial_neural_network).
+ * This chapter is narrower: it documents the library boundary that packages
+ * those ideas into reusable blocks and helper-owned policies.
+ *
  * Read this chapter in three passes:
  *
  * 1. start with the `Layer` class overview to understand why the boundary
@@ -15,6 +68,34 @@
  *    you need the runtime wiring surface,
  * 3. finish with the static factory methods when you want named layer shapes
  *    such as dense, recurrent, normalization, or experimental blocks.
+ *
+ * Example: wire a small dense stack using the same block-level API that higher
+ * level builders depend on.
+ *
+ * ```ts
+ * const input = Layer.dense(2);
+ * input.set({ type: 'input' });
+ * const hidden = Layer.dense(4);
+ * const output = Layer.dense(1);
+ * output.set({ type: 'output' });
+ *
+ * input.connect(hidden);
+ * hidden.connect(output);
+ *
+ * input.activate([0, 1]);
+ * hidden.activate();
+ * const values = output.activate();
+ * ```
+ *
+ * Example: swap in a richer factory-built block without changing the top-level
+ * layer-to-layer wiring vocabulary.
+ *
+ * ```ts
+ * const recurrent = Layer.lstm(8);
+ * const readout = Layer.dense(2);
+ *
+ * recurrent.connect(readout);
+ * ```
  */
 
 import Node from '../node/node';
@@ -50,12 +131,20 @@ const NODE_INDEX_START = 0;
 const NODE_INDEX_STEP = 1;
 
 /**
- * Represents a functional layer within a neural network architecture.
+ * Public block-level facade for layer-oriented architecture building.
+ *
+ * `Layer` is the boundary readers reach for when a graph region should behave
+ * like one model stage rather than a loose collection of neurons. It
+ * normalizes common operations across dense, recurrent, normalization, and
+ * experimental factories so higher-level chapters can compose readable graphs
+ * without depending on each helper shelf's private implementation details.
+ *
+ * This makes the class useful when you want to:
  *
- * Layers act as organizational units for nodes, facilitating the creation of
- * complex network structures like Dense, LSTM, GRU, or Memory layers.
- * They manage the collective behavior of their nodes, including activation,
- * propagation, and connection to other network components.
+ * - assemble a network from named blocks instead of raw nodes,
+ * - reuse the same activation, wiring, and propagation vocabulary across layer
+ *   families,
+ * - keep factory-specific mechanics below the public API.
  */
 export default class Layer {
   /**

package/src/architecture/network/README.md

@@ -2,20 +2,91 @@
 
 Core network chapter for the architecture surface.
 
-This folder now owns the public `Network` class that readers and callers use
-to build, activate, evolve, serialize, and export graph-shaped neural
-systems. The surrounding helper chapters keep activation, training,
-topology, pruning, ONNX, and slab execution policy focused, while this file
-preserves the orchestration story that ties those responsibilities into one
-runtime boundary.
-
-Read this chapter in three passes:
-
-1. start here to understand the public `Network` contract and why it sits
-   above nodes, layers, and connections,
-2. continue into the helper chapters when you want one subsystem in detail,
-3. return here when you need to see how the public API composes those
-   subsystem policies back into one runtime object.
+This folder owns the public `Network` class: the boundary where a graph stops
+being only nodes and connections and starts behaving like one runnable,
+mutable, trainable system. Higher-level NEAT code can mutate or score a
+network, but this chapter is where the graph itself learns how to activate,
+accept structural edits, preserve deterministic state, serialize, and cross
+the ONNX boundary.
+
+That boundary matters because the same instance has to serve several jobs
+without changing shape. A caller may want ordinary inference, training-aware
+forward passes, topology edits, reproducible stochastic behavior, sparse
+pruning, or a portable checkpoint. Keeping those responsibilities under one
+facade makes the public API readable while the helper chapters keep each
+policy cluster narrow enough to teach.
+
+A useful mental model is to read `network/` as four cooperating shelves.
+`bootstrap/` explains one-time construction policy. `activate/`, `runtime/`,
+and `training/` explain how a graph is stepped and regularized once it is
+alive. `connect/`, `mutate/`, `remove/`, `prune/`, and `topology/` explain
+graph surgery. `serialize/`, `standalone/`, `onnx/`, and `stats/` explain
+portability, inspection, and reporting.
+
+The performance story is equally important. This chapter deliberately hides
+storage details until they matter. Callers should be able to ask for
+`activate()` or `train()` without first understanding slab packing, pooled
+activation arrays, or cache invalidation. The helper folders then expose how
+the same graph can switch between object traversal and denser typed-array
+paths without changing the surface contract.
+
+```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;
+
+  Build[bootstrap and topology intent]:::base --> NetworkClass[Network facade]:::accent
+  NetworkClass --> Execute[activate runtime and training]:::base
+  Execute --> Edit[connect mutate prune remove]:::base
+  Edit --> Persist[serialize standalone and ONNX]:::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;
+
+  NetworkChapter[network chapter]:::accent --> Bootstrap[bootstrap/ one-time setup]:::base
+  NetworkChapter --> Activate[activate/ forward-pass policy]:::base
+  NetworkChapter --> Runtime[runtime/ training-time controls]:::base
+  NetworkChapter --> Structure[connect mutate topology prune]:::base
+  NetworkChapter --> Interop[serialize standalone onnx stats]:::base
+```
+
+For background on the execution-order side of this chapter, see Wikipedia
+contributors, [Topological sorting](https://en.wikipedia.org/wiki/Topological_sorting).
+Feed-forward network execution, acyclic guards, and some of the helper
+policies in this folder all depend on the same scheduling idea even when the
+public API keeps that detail out of the caller's way.
+
+Example: create a compact layered network and use the ordinary activation
+surface.
+
+```ts
+const network = Network.createMLP(2, [4], 1);
+const outputValues = network.activate([0, 1]);
+```
+
+Example: checkpoint one network, then restore it for another run.
+
+```ts
+const network = new Network(2, 1, { seed: 7 });
+const saved = network.toJSON();
+const restored = Network.fromJSON(saved);
+const replayed = restored.activate([1, 0]);
+```
+
+Practical reading order:
+
+1. Start here for the public `Network` facade and the cross-chapter map.
+2. Continue into `bootstrap/` when the constructor contract is the next
+   question.
+3. Continue into `activate/`, `runtime/`, and `training/` for execution and
+   learning policy.
+4. Continue into `connect/`, `mutate/`, `remove/`, `prune/`, and `topology/`
+   for structural editing.
+5. Finish in `serialize/`, `standalone/`, `onnx/`, and `stats/` for
+   portability, derived reports, and export flows.
 
 ## architecture/network/network.ts