@reicek/neataptic-ts 0.1.26 → 0.1.27

package/plans/src-no-explicit-any-cleanup.plans.md

@@ -4,172 +4,34 @@
 
 ## Scope
 
-- Eliminate remaining `@typescript-eslint/no-explicit-any` debt in `src/`.
-- Keep the cleanup aligned with the current folderized architecture instead of pre-split file lists.
-- Treat unrelated ESLint failures as out of scope unless a touched file requires a local fix to validate safely.
+- Remove `@typescript-eslint/no-explicit-any` debt across `src/` and close the
+  remaining explicit-form `any` variants introduced by earlier refactors.
+- Keep the cleanup behavior-preserving and validation-driven.
 
-## Current state
+## Final state
 
-- The old root-level handoff note drifted after the architecture and NEAT refactors and is no longer a reliable file-by-file checklist.
-- A current raw source scan now finds 0 `any` tokens across `src/**/*.ts`.
-- The explicit-form follow-up scan for patterns such as `as any`, `Promise<any>`, `Array<any>`, `Map<any, ...>`, `: any`, and `{any[]}` also returns 0 matches across `src/**/*.ts`.
-- `src/architecture/nodePool.ts`, previously marked as the next target in the legacy note, now lints clean and is no longer the correct starting point.
-- A broad `npx eslint src` run now passes after the follow-up lint-hygiene cleanup removed stale unused imports and empty-interface wrappers that were outside the original explicit-any lane.
+- The tracked `src/` explicit-`any` debt was eliminated and the baseline closed
+  at zero for the targeted forms in this lane.
+- Root NEAT, evolve, adaptive, multiobjective, multithreading, and related
+  hotspots were brought into stronger typed form without reopening unrelated
+  behavior changes.
+- No active backlog remains; this file is now a reopen point if explicit-`any`
+  debt returns.
 
-## Coverage backlog
+## Audit summary
 
-### [DONE] Legacy pre-split cleanup pass
+- Validation used targeted ESLint runs and `npx tsc --noEmit -p tsconfig.json`
+  after durable batches.
+- The lane closed on a green `npx eslint src` final pass.
 
-- The earlier cleanup covered `src/methods/`, `src/multithreading/`, and part of the pre-folderized architecture surface.
-- That historical pass is kept only as a coarse extent note because the old path-by-path checklist no longer matches the current tree.
+## Reopen conditions
 
-### [DONE] Root `src/neat.ts` explicit-any removal pass
+- Future refactors reintroduce explicit `any` or equivalent typed debt in
+  `src/`.
+- Stronger typing regresses in the previously cleaned hotspot files.
+- Lint or type baselines reopen because of source-surface drift.
 
-- Removed the file-wide `@typescript-eslint/no-explicit-any` escape hatch from `src/neat.ts`.
-- Replaced root-surface `any` usage with shared contracts for options, export/import payloads, RNG state, objective accessors, compatibility inputs, and helper `this` delegation.
-- `npx eslint src/neat.ts --rule "@typescript-eslint/no-explicit-any:error"` now passes.
-- `npx tsc --noEmit -p tsconfig.json` passes after the root facade cleanup.
+## Audit log
 
-### [DONE] Root `src/neat.ts` polish follow-through
-
-- The root strict-typing pass briefly exposed a small boundary-polish detour in the NEAT entry surface.
-- That follow-through extracted the root compatibility alias shelf into `src/neat/neat.types.ts`, extracted the constructor-default shelf into `src/neat/neat.defaults.constants.ts`, exported constructor bootstrap contracts from `src/neat/init/neat.init.ts`, and centralized `buildEmptyDiversityStats()` in `src/neat/diversity/diversity.ts`.
-- The result kept `src/neat.ts` orchestration-first without creating a second active roadmap lane.
-- Documentation effects from that detour remain tracked in `plans/neat-docs.plans.md`; this tracker keeps only the compact structural note so the strict-typing lane stays self-contained.
-
-### [DONE] `src/neat/evolve/objectives/evolve.objectives.utils.ts` cleanup pass
-
-- Removed the file-wide `@typescript-eslint/no-explicit-any` escape hatch from `src/neat/evolve/objectives/evolve.objectives.utils.ts`.
-- Replaced `any`-based objective, population, entropy-accessor, and cache-reset handling with the existing evolve contracts in `src/neat/evolve/evolve.types.ts`.
-- Kept the runtime behavior narrow by centralizing the entropy accessor as a typed local helper instead of widening the shared controller contract.
-- `npx eslint src/neat/evolve/objectives/evolve.objectives.utils.ts --rule "@typescript-eslint/no-explicit-any:error"` now passes.
-- `npx tsc --noEmit -p tsconfig.json` passes after the evolve-objectives cleanup.
-
-### [DONE] `src/neat/evolve/population/evolve.population.utils.ts` cleanup pass
-
-- Removed the file-wide `@typescript-eslint/no-explicit-any` escape hatch from `src/neat/evolve/population/evolve.population.utils.ts`.
-- Replaced `any`-based species allocation, per-member score folding, remainder budgeting, and lineage bookkeeping with the existing evolve contracts in `src/neat/evolve/evolve.types.ts`.
-- Kept the runtime behavior intact by preserving the existing lineage-id fallback semantics (`?? 0`) where parent ids remain optional on the shared genome contract.
-- `npx eslint src/neat/evolve/population/evolve.population.utils.ts --rule "@typescript-eslint/no-explicit-any:error"` now passes.
-- `npx tsc --noEmit -p tsconfig.json` passes after the evolve-population cleanup.
-
-### [DONE] `src/neat/evolve/adaptive/evolve.adaptive.utils.ts` cleanup pass
-
-- Removed the file-wide `@typescript-eslint/no-explicit-any` escape hatch from `src/neat/evolve/adaptive/evolve.adaptive.utils.ts`.
-- Replaced `any`-based option access, cache invalidation iteration, and re-enable counter resets with the existing evolve contracts in `src/neat/evolve/evolve.types.ts`.
-- Added the narrow per-genome re-enable counters to `GenomeWithMetadata` so the adaptive bridge can reuse the shared evolve runtime metadata instead of reintroducing local casts.
-- Normalized missing compatibility coefficients before auto-tuning updates so the helper no longer relies on `any` to hide optional-option gaps.
-- `npx eslint src/neat/evolve/adaptive/evolve.adaptive.utils.ts --rule "@typescript-eslint/no-explicit-any:error"` now passes.
-- `npx tsc --noEmit -p tsconfig.json` passes after the evolve-adaptive cleanup.
-
-### [DONE] `src/neat/multiobjective/category/multiobjective.category.ts` cleanup pass
-
-- Removed the file-wide `@typescript-eslint/no-explicit-any` escape hatch from `src/neat/multiobjective/category/multiobjective.category.ts`.
-- Replaced `any`-based Pareto snapshot shaping, objective-vector extraction, and objective-removal filtering with the existing evolve genome and objective descriptor contracts.
-- Dropped the unnecessary `undefined as any` cache reset in favor of the native optional objective-list contract.
-- `npx eslint src/neat/multiobjective/category/multiobjective.category.ts --rule "@typescript-eslint/no-explicit-any:error"` now passes.
-- `npx tsc --noEmit -p tsconfig.json` passes after the multi-objective category cleanup.
-
-### [DONE] `src/neat/evolve/speciation/evolve.speciation.utils.ts` cleanup pass
-
-- Removed the file-wide `@typescript-eslint/no-explicit-any` escape hatch from `src/neat/evolve/speciation/evolve.speciation.utils.ts`.
-- Replaced `any`-based node filtering and species-history snapshot shaping with narrow local node typing plus the shared evolve species contracts.
-- Aligned the minimal snapshot rows with `SpeciesHistoryRecord` by writing `bestScore` and `avgSharedFitness` instead of leaking ad hoc fields through `any`.
-- `npx eslint src/neat/evolve/speciation/evolve.speciation.utils.ts --rule "@typescript-eslint/no-explicit-any:error"` now passes.
-- `npx tsc --noEmit -p tsconfig.json` passes after the evolve-speciation cleanup.
-
-### [DONE] `src/neat/evolve/runtime/evolve.runtime.utils.ts` cleanup pass
-
-- Removed the file-wide `@typescript-eslint/no-explicit-any` escape hatch from `src/neat/evolve/runtime/evolve.runtime.utils.ts`.
-- Replaced `any`-based timer access with one typed high-resolution timer resolver shared by both start-time and elapsed-time helpers.
-- Replaced the score-reset callback cast with direct `GenomeWithMetadata` inference across the live population.
-- `npx eslint src/neat/evolve/runtime/evolve.runtime.utils.ts --rule "@typescript-eslint/no-explicit-any:error"` now passes.
-- `npx tsc --noEmit -p tsconfig.json` passes after the evolve-runtime cleanup.
-
-### [DONE] `src/neat/adaptive/adaptive.ts` contract-doc cleanup pass
-
-- Replaced the repeated JSDoc `@this {{ ... any ... }}` object literals in `src/neat/adaptive/adaptive.ts` with the existing `NeatLikeWithAdaptiveType` host contract.
-- Kept the change documentation-only: behavior and implementation types were already routed through the adaptive core contracts.
-- `npx eslint src/neat/adaptive/adaptive.ts --rule "@typescript-eslint/no-explicit-any:error"` now passes.
-- `npx tsc --noEmit -p tsconfig.json` passes after the adaptive-root cleanup.
-
-### [DONE] `src/multithreading/multi.ts` worker-doc cleanup pass
-
-- Replaced stale `Promise<any>` JSDoc return annotations on the worker helpers with `Promise<TestWorkerConstructor>` to match the existing TypeScript signatures.
-- `npx eslint src/multithreading/multi.ts --rule "@typescript-eslint/no-explicit-any:error"` now passes.
-- `npx tsc --noEmit -p tsconfig.json` passes after the multithreading cleanup.
-
-### [DONE] Root `src/neat.ts`, `src/neat/evolve/evolve.ts`, and network-chapter doc cleanup pass
-
-- Removed stale any-focused commentary from `src/neat/evolve/evolve.ts` now that the helper split carries the narrow runtime contracts.
-- Reworded the `_structuralEntropy` compatibility note in `src/neat.ts` so it no longer references loose `(controller as any)` test examples.
-- Updated network chapter examples and JSDoc in `src/architecture/network/network.ts` and `src/architecture/network/slab/network.slab.utils.ts` to use the typed public slab accessors instead of loose-cast examples.
-- `npx tsc --noEmit -p tsconfig.json` passes after the root/network documentation cleanup.
-
-### [DONE] `src/architecture/network/stats/network.stats.utils.ts` doc cleanup pass
-
-- Removed the stale note describing the `_lastStats` bridge as "typed as any" and replaced it with wording that points at the existing `NetworkStatsProps` bridge.
-- `npx eslint src/architecture/network/stats/network.stats.utils.ts --rule "@typescript-eslint/no-explicit-any:error"` now passes.
-- `npx tsc --noEmit -p tsconfig.json` passes after the network-stats cleanup.
-
-### [DONE] Repo-wide prose-only cleanup pass
-
-- Rewrote the remaining ordinary-English `any` phrases across the architecture, NEAT, mutation, telemetry, selection, objectives, and multithreading chapters so the raw `\bany\b` source scan is now clean.
-- Kept this pass documentation-only: comments, examples, and JSDoc were tightened without changing runtime behavior or widening contracts.
-- `grep_search` for raw `\bany\b` across `src/**/*.ts` now returns 0 matches.
-- `grep_search` for explicit forms such as `as any`, `Promise<any>`, `Array<any>`, `Map<any>`, `: any`, and `{any[]}` across `src/**/*.ts` now returns 0 matches.
-- `npx tsc --noEmit -p tsconfig.json` passes after the final prose-only sweep.
-
-### [DONE] Broad `src` lint-hygiene follow-up
-
-- Removed stale unused imports from `src/architecture/network/network.ts`, `src/architecture/network/onnx/export/network.onnx.export.types.ts`, and `src/architecture/network/onnx/network.onnx.utils.types.ts`.
-- Replaced the empty facade interfaces in `src/neat/pruning/facade/pruning.facade.ts` and `src/neat/rng/facade/rng.facade.ts` with equivalent type aliases to satisfy `@typescript-eslint/no-empty-object-type`.
-- `npx eslint src` now passes after the follow-up cleanup.
-- `npx tsc --noEmit -p tsconfig.json` still passes after the lint-hygiene follow-up.
-
-### [DONE] Current hotspots in the refactored tree
-
-- No remaining hotspots in `src/**/*.ts` for raw `any` tokens.
-- No remaining hotspots in `src/**/*.ts` for explicit-form `any` usage.
-- No remaining broad ESLint errors in `src/` after the unused-import and empty-interface follow-up.
-
-### [PLANNED] Validation discipline
-
-- Validate touched files with targeted ESLint runs instead of treating the whole `src/` tree as a single pass/fail gate.
-- Run `npx tsc --noEmit -p tsconfig.json` after each durable batch.
-- Avoid broad test runs for this workstream unless a specific edit changes behavior rather than types.
-
-## Immediate next steps
-
-1. Treat this lane as complete unless future refactors reintroduce explicit-any debt into `src/`.
-2. If later work reopens the lane, resume from current repo state and start with a fresh raw scan instead of replaying this completed tracker.
-
-## Deferred questions
-
-- Decide later whether some remaining `any` usage is genuinely architectural and should be documented with narrowly scoped eslint suppression instead of erased mechanically.
-- If the broader ES2023 modernization pass introduces lint enforcement changes, keep this tracker aligned with the final lint gate instead of duplicating policy here.
-
-## Handoff query
-
-```text
-Continue from the current repo state only. Do not rely on prior chat history.
-Current repo state:
-- The root `src/neat.ts` pass is complete.
-- The root surface-polish follow-through from that pass has been compressed into this tracker; there is no separate active plan for it.
-- `src/neat/evolve/objectives/evolve.objectives.utils.ts` is now clean for `@typescript-eslint/no-explicit-any`.
-- `src/neat/evolve/population/evolve.population.utils.ts` is now clean for `@typescript-eslint/no-explicit-any`.
-- `src/neat/evolve/adaptive/evolve.adaptive.utils.ts` is now clean for `@typescript-eslint/no-explicit-any`.
-- `src/neat/multiobjective/category/multiobjective.category.ts` is now clean for `@typescript-eslint/no-explicit-any`.
-- `src/neat/evolve/speciation/evolve.speciation.utils.ts` is now clean for `@typescript-eslint/no-explicit-any`.
-- `src/neat/evolve/runtime/evolve.runtime.utils.ts` is now clean for `@typescript-eslint/no-explicit-any`.
-- `src/neat/adaptive/adaptive.ts` is now clean for explicit-form `any` usage.
-- `src/multithreading/multi.ts` is now clean for explicit-form `any` usage.
-- `src/architecture/network/stats/network.stats.utils.ts` is now clean for explicit-form `any` usage.
-- The raw `any` baseline is down to 0.
-- The explicit-form scan for `as any`, `Promise<any>`, `Array<any>`, `Map<any>`, `: any`, and `{any[]}` is also at 0.
-- `npx eslint src` passes.
-
-Next target:
-- No active target in this lane. Reopen only if future edits reintroduce explicit-any debt or new broad lint drift into `src/`.
-- If reopened, begin with a fresh raw scan, `npx eslint src`, and `npx tsc --noEmit -p tsconfig.json` before selecting a new target.
-```
+- Durable completion notes now live in
+  [src-no-explicit-any-cleanup.logs.md](src-no-explicit-any-cleanup.logs.md).

package/plans/utils-docs.logs.md

@@ -0,0 +1,37 @@
+# Utils Docs Plan Log
+
+**Status:** [DONE]
+
+## Audit scope
+
+- Objective: improve the generated utility chapter openings, especially around
+  memory heuristics and snapshot-layer mechanics, while keeping the lane
+  behavior-neutral.
+
+## Durable milestones
+
+### [DONE] Utility opening upgrades
+
+- Strengthened the `src/utils/memory.ts` and `src/utils/memory.utils.ts`
+  openings so they explain heuristic rationale and aggregation behavior more
+  clearly.
+
+### [DONE] Diagram support in utility chapters
+
+- Added Mermaid-backed visuals where they improved the explanation of snapshot
+  layers and memory behavior.
+
+### [DONE] Docs generation unblock
+
+- Fixed a pre-existing Mermaid rendering failure outside the utility modules so
+  global docs generation could complete reliably again.
+
+## Controls and evidence
+
+- Validation used `npm run docs` and `npx tsc --noEmit -p tsconfig.json`.
+- The pass did not require runtime behavior changes.
+
+## Reopen triggers
+
+- Utility chapter openings drift or new utility surfaces are added.
+- Mermaid or generator behavior causes docs regression in this lane.

package/plans/utils-docs.plans.md

@@ -4,46 +4,31 @@
 
 ## Scope
 
-This plan tracks educational-docs passes for the small shared utility surfaces
-under [src/utils/README.md](../src/utils/README.md).
+- Educational-docs pass for the shared utility chapters under `src/utils/`.
+- Raise the generated utility openings without changing runtime behavior.
 
-Primary reader:
+## Final state
 
-- readers who want to understand support utilities as teaching tools rather
-  than as unframed implementation leftovers.
+- The utility chapter openings now explain memory heuristics and snapshot
+  layering more clearly instead of reading as implementation shelves.
+- Mermaid-supported diagrams are part of the generated utility documentation
+  path where they materially improve comprehension.
+- No active backlog remains; this plan is now a reopen point for future utility
+  documentation drift.
 
-Primary surfaces:
+## Audit summary
 
-- [src/utils/memory.ts](../src/utils/memory.ts)
-- [src/utils/memory.utils.ts](../src/utils/memory.utils.ts)
-- [src/utils/README.md](../src/utils/README.md)
+- Documentation updates were validated with `npm run docs` and
+  `npx tsc --noEmit -p tsconfig.json`.
+- A pre-existing Mermaid rendering issue in another docs surface was also fixed
+  during this lane to keep global docs generation healthy.
 
-## Session Log
+## Reopen conditions
 
-### Latest completed chapter work
+- New utility modules are added under `src/utils/`.
+- Utility README openings drift below the current documentation bar.
+- Mermaid or generated-doc ownership regressions reappear.
 
-- Strengthened the root [src/utils/memory.ts](../src/utils/memory.ts) opening so
-  the generated [src/utils/README.md](../src/utils/README.md) now explains why
-  heuristic memory instrumentation exists, which questions it answers, and how
-  to read the snapshot in layers.
-- Added a real module introduction to
-  [src/utils/memory.utils.ts](../src/utils/memory.utils.ts) so the helper file
-  reads as aggregation and snapshot mechanics rather than a flat export shelf.
-- Added Mermaid teaching diagrams to both module openings.
-- Regenerated docs and re-ran `npx tsc --noEmit -p tsconfig.json` successfully.
-- Fixed an existing Mermaid rendering failure in
-  [src/neat/init/neat.init.ts](../src/neat/init/neat.init.ts) that had been
-  blocking global docs generation.
+## Audit log
 
-Remaining gaps:
-
-- The `src/utils` folder is now small and reasonably aligned; future work here
-  is more likely to be refinement than rescue.
-- If additional utility modules are added later, keep this plan focused on
-  chapter quality instead of growing a long historical log.
-
-Next step:
-
-- Move to the next small cross-cutting folder that still reads more like a
-  helper shelf than a chapter, using [src/utils/README.md](../src/utils/README.md)
-  as the quality bar for support modules.
+- Durable completion notes now live in [utils-docs.logs.md](utils-docs.logs.md).

package/src/README.md

@@ -2,34 +2,100 @@
 
 Root orchestration surface for NeuroEvolution of Augmenting Topologies (NEAT) in NeatapticTS.
 
-Within the broader `src` surface, this file is the public chapter map for the
-library's evolutionary controller.
-The heavy algorithmic work lives in focused `src/neat/**` modules, but this
-root surface keeps the user-facing workflow readable: configure a population,
-evaluate genomes, evolve the next generation, inspect telemetry, and persist
-the state when a run becomes worth keeping.
-
-What this file covers:
-- the high-level lifecycle of a NEAT run,
-- the default knobs that shape population growth and speciation,
-- reproducibility helpers such as seeded RNG snapshots and state export,
-- educational inspection hooks for telemetry, species history, diversity, and Pareto fronts.
-
-What you can learn here:
-- how the top-level controller stays orchestration-first even after the internal SOLID split,
-- which public methods belong to setup, evolution, diagnostics, and persistence,
-- which subsystem README to open next when you want the underlying mechanics.
+This root chapter is the public control desk for the library. The
+architecture surfaces explain what a network graph is. The `src/neat/**`
+chapters explain how evaluation, reproduction, speciation, telemetry, and
+persistence work in detail. This file sits between those two layers and
+answers the first practical reader question: how do I run one evolutionary
+experiment without learning every subsystem in the same breath?
+
+That boundary matters because a useful NEAT run is more than "mutate a
+network." A controller has to keep a population alive, protect enough
+diversity to avoid early collapse, score genomes fairly, record what
+happened, and give the caller a deterministic way to pause or resume the
+search. The root surface is where those responsibilities become one readable
+workflow instead of a pile of helper calls.
+
+One helpful mental model is to read the controller as four shelves. The setup
+shelf decides population size, defaults, and reproducibility. The search
+shelf drives `evaluate()`, `evolve()`, and the public mutation hooks. The
+observability shelf exposes telemetry, lineage, diversity, species, and
+Pareto views. The persistence shelf turns a live run into replayable state
+through `toJSON()`, `exportState()`, and RNG snapshots.
+
+The chapter also exists to keep the public class orchestration-first after
+the internal split. `src/neat/**` now owns the heavier policy chapters:
+`evaluate/` scores genomes, `evolve/` creates the next generation,
+`speciation/` manages compatibility pressure, `telemetry/` records what the
+run did, and `export/` plus `rng/` keep experiments reproducible. If you can
+read the root workflow first, the subchapters become "why does this step
+work?" reads instead of "where do I even start?" reads.
+
+The guiding historical idea comes from Stanley and Miikkulainen's NEAT
+paper: evolve both weights and topology while protecting innovation long
+enough for new structures to prove useful. See Stanley and Miikkulainen,
+[Evolving Neural Networks through Augmenting Topologies](https://nn.cs.utexas.edu/?stanley:ec02),
+for the compact background behind the controller vocabulary that appears all
+through this surface.
+
+Read this root when you want to answer one of three questions quickly: how to
+start a run, how to move it forward generation by generation, or how to
+inspect and persist it without diving into every implementation chapter. Read
+the narrower `src/neat/**` READMEs when the next question becomes about one
+specific policy family rather than the whole experiment loop.
 
 ```mermaid
 flowchart LR
-  Configure["Configure run<br/>sizes + fitness + options"] --> Seed["Seed or restore<br/>constructor / createPool / import"]
-  Seed --> Score["Score population<br/>evaluate()"]
-  Score --> Breed["Breed next generation<br/>evolve() / mutate()"]
-  Breed --> Observe["Observe search pressure<br/>telemetry / species / diversity / Pareto"]
-  Observe --> Persist["Persist or replay<br/>exportState() / toJSON() / RNG state"]
+  classDef base fill:#08131f,stroke:#1ea7ff,color:#dff6ff,stroke-width:1px;
+  classDef accent fill:#0f2233,stroke:#ffd166,color:#fff4cc,stroke-width:1.5px;
+
+  Configure["Configure run<br/>sizes + fitness + options"]:::accent --> Seed["Seed or restore<br/>constructor / createPool / import"]:::base
+  Seed --> Score["Score population<br/>evaluate()"]:::base
+  Score --> Breed["Breed next generation<br/>evolve() / mutate()"]:::accent
+  Breed --> Observe["Observe pressure<br/>telemetry / species / diversity / Pareto"]:::base
+  Observe --> Persist["Persist or replay<br/>exportState() / toJSON() / RNG state"]:::base
   Breed --> Score
 ```
 
+```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;
+
+  Root["src root controller"]:::accent --> Setup["Defaults and initialization<br/>constructor / createPool / import"]:::base
+  Root --> Search["Search loop<br/>evaluate / evolve / mutate"]:::base
+  Root --> Observe["Diagnostics<br/>telemetry / species / lineage / Pareto"]:::base
+  Root --> Replay["Persistence<br/>toJSON / exportState / RNG"]:::base
+  Search --> Chapters["Detailed policy chapters<br/>src/neat/**"]:::base
+```
+
+Example: start a small deterministic run and inspect the best score after one
+generation.
+
+```ts
+const neat = new Neat(2, 1, fitness, {
+  popsize: 50,
+  seed: 7,
+  fastMode: true,
+});
+
+await neat.evaluate();
+const bestGenome = await neat.evolve();
+
+console.log(bestGenome.score);
+```
+
+Example: capture telemetry and a replayable snapshot after the current run
+step.
+
+```ts
+const latestTelemetry = neat.getTelemetry().at(-1);
+const exportedState = neat.exportState();
+
+console.log(latestTelemetry?.generation);
+console.log(exportedState.neat.generation);
+```
+
 Recommended reading after this root chapter:
 - `./neat/evaluate/README.md` for scoring flow and objective handling
 - `./neat/evolve/README.md` for reproduction orchestration

package/src/architecture/README.md

@@ -2,20 +2,97 @@
 
 Architecture root chapter map and compatibility surface.
 
-This folder gathers the core runtime building blocks that most NeatapticTS
-networks are composed from: `Network` orchestration, `Node` and
-`Connection` graph primitives, `Group` and `Layer` composition helpers,
-`Architect` presets, and the shared allocation pools that keep hot paths
-leaner during training and inference.
-
-How to read this chapter:
-- Start here for the high-level map of the architecture package.
-- Continue into `network/` for the main orchestration surface and its
-  runtime, training, mutation, serialization, and ONNX subchapters.
-- Continue into `node/`, `connection/`, `group/`, and `layer/` for the graph
-  building blocks.
-- Continue into `architect/` for preset builders and into `nodePool/` and
-  `activationArrayPool/` for allocation-oriented helpers.
-- Treat the flat `src/architecture/*.ts` files as compatibility facades that
-  keep public imports stable while the implementation lives in narrower,
-  teachable chapters.
+This root answers the first structural question behind the whole library:
+what are the durable building blocks a NeatapticTS network is made from
+before NEAT, training, workers, or ONNX translation start adding policy
+around it? The answer is a small graph vocabulary. Nodes and connections hold
+local signal semantics. Groups and layers organize repeated structure.
+`Network` orchestrates the whole graph. `Architect` offers common presets.
+The pool chapters keep allocation-heavy hot paths from turning runtime work
+into needless object churn.
+
+Read this folder as a map between two kinds of knowledge. One kind is graph
+anatomy: what a node, connection, group, or layer means. The other kind is
+graph orchestration: how those parts become a runnable, mutable, trainable,
+serializable network. The architecture root exists so a reader can see both
+at once before diving into the heavier subchapters.
+
+That boundary matters because the rest of the repo reuses architecture in
+several different ways. The NEAT controller mutates and evaluates graphs.
+The methods chapter defines reusable activation and structural vocabulary.
+Browser examples step and visualize networks. ONNX import and export
+translate networks across ecosystems. If the architecture layer is unclear,
+everything above it feels like policy without a substrate. This root chapter
+makes the substrate legible first.
+
+One helpful mental model is to split the folder into four shelves: graph
+primitives (`node`, `connection`), composition helpers (`group`, `layer`,
+`architect`), orchestration (`network`), and runtime-efficiency helpers
+(`nodePool`, `activationArrayPool`). The flat `src/architecture/*.ts` files
+are compatibility facades that keep imports stable while the real ownership
+and longer explanations live in the chaptered subfolders.
+
+```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;
+
+  Architecture[architecture root]:::accent --> Primitives[Node and Connection<br/>graph primitives]:::base
+  Architecture --> Composition[Group Layer Architect<br/>composition helpers]:::base
+  Architecture --> Orchestration[Network<br/>runtime orchestration]:::base
+  Architecture --> Pools[NodePool and ActivationArrayPool<br/>allocation helpers]:::base
+```
+
+The second useful lens is ownership versus compatibility. This root folder
+intentionally still exposes flat compatibility files because public imports,
+tests, and examples rely on them. But those files are no longer the best
+place to learn the subsystem. They are the stable front desk. The chaptered
+subfolders are where the real guided tour now lives.
+
+```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;
+
+  Caller[Caller import]:::base --> Facade[Flat compatibility facade]:::accent
+  Facade --> Chapter[Chapter-owned implementation folder]:::base
+  Chapter --> Details[Runtime training mutation serialize ONNX details]:::base
+```
+
+For background reading, the most relevant mathematical ideas are the directed
+graph itself and the ordering questions that appear once a graph has to be
+executed. See Wikipedia contributors,
+[Directed graph](https://en.wikipedia.org/wiki/Directed_graph), and
+Wikipedia contributors,
+[Topological sorting](https://en.wikipedia.org/wiki/Topological_sorting),
+for compact background on the graph and scheduling ideas that sit underneath
+this chapter's public surface.
+
+Example: start from a preset builder when you want architecture first and
+wiring details second.
+
+```ts
+const perceptron = new Architect.Perceptron(2, 3, 1);
+const outputValues = perceptron.activate([0, 1]);
+```
+
+Example: start from `Network` when you want the orchestration surface and
+plan to inspect or mutate the graph more directly.
+
+```ts
+const network = new Network(2, 1);
+const outputValues = network.activate([0, 1]);
+```
+
+Practical reading order:
+
+1. Start here for the high-level map of the architecture package.
+2. Continue into `network/` for the main orchestration surface and its
+   runtime, training, mutation, serialization, and ONNX subchapters.
+3. Continue into `node/`, `connection/`, `group/`, and `layer/` for the
+   graph building blocks.
+4. Continue into `architect/` for preset builders and into `nodePool/` and
+   `activationArrayPool/` for allocation-oriented helpers.
+5. Treat the flat `src/architecture/*.ts` files as compatibility facades that
+   keep public imports stable while the implementation lives in narrower,
+   teachable chapters.

package/src/architecture/activationArrayPool/README.md

@@ -7,6 +7,43 @@ activation paths. It sits beside the network and layer chapters because the
 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
@@ -16,6 +53,22 @@ Read this chapter in three passes:
 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();
+```
+
 ## architecture/activationArrayPool/activationArrayPool.ts
 
 ### ActivationArray