@reicek/neataptic-ts 0.1.26 → 0.1.27

package/plans/neat-docs.logs.md

@@ -0,0 +1,38 @@
+# NEAT Root Docs Plan Log
+
+**Status:** [DONE]
+
+## Audit scope
+
+- Objective: improve the generated NEAT root and root-facing chapter openings so
+  the public surface teaches orchestration and concepts before raw symbols.
+
+## Durable milestones
+
+### [DONE] Root NEAT controller framing
+
+- Strengthened the root NEAT controller documentation so the generated root
+  surface explains what the NEAT orchestration layer does and how readers
+  should navigate the surrounding chapter set.
+
+### [DONE] Root-facing chapter upgrades
+
+- Upgraded the RNG and lineage openings and related root-facing chapters so
+  they read as conceptual introductions rather than thin compatibility shelves.
+
+### [DONE] Types/defaults and lineage follow-through
+
+- Split or redirected the root-facing types/defaults surfaces where needed and
+  expanded lineage with stronger diagrams, examples, and references.
+
+## Controls and evidence
+
+- Documentation-affecting work was validated with `npm run docs` and
+  `npx tsc --noEmit -p tsconfig.json`.
+- The final result is a stable reopen baseline for future NEAT docs drift.
+
+## Reopen triggers
+
+- Root-facing NEAT chapters regress after future API or structure work.
+- Generator ordering produces weak opening ownership again.
+- Another public NEAT surface needs chapter-map treatment.

package/plans/neat-docs.plans.md

@@ -1,76 +1,34 @@
 # NEAT Root Docs Plan
 
-**Status:** [WIP]
+**Status:** [DONE]
 
 ## Scope
 
-This plan tracks the educational-docs pass for the root NEAT public surface.
-The source of truth is the generated documentation fed by [src/neat.ts](../src/neat.ts),
-which renders into [src/README.md](../src/README.md) after `npm run docs`.
+- Educational-docs pass for root-facing NEAT surfaces and closely related
+  generated chapters.
+- Strengthen chapter openings without changing NEAT runtime behavior.
 
-Primary reader:
+## Final state
 
-- first-time NeatapticTS readers who want to understand how the top-level NEAT controller works before diving into chaptered internals.
+- The NEAT root documentation surfaces now present a clearer controller and
+  chapter-map story instead of a compatibility-first opening.
+- Root-facing chapters such as RNG and lineage now open with stronger
+  educational framing, diagrams, and examples where they mattered.
+- No active backlog remains; this plan is now a reopen point for future
+  root-facing NEAT documentation drift.
 
-Primary surfaces:
+## Audit summary
 
-- [src/neat.ts](../src/neat.ts)
-- [src/README.md](../src/README.md)
+- Documentation updates were validated with `npm run docs` and
+  `npx tsc --noEmit -p tsconfig.json`.
+- The final state is stable enough to stop being a documentation blocker.
 
-Out of scope for this pass:
+## Reopen conditions
 
-- hand-editing generated READMEs under `src/`
-- adding external images or citations unless a concrete teaching gap requires them
-- broad rewrites of every `src/neat/**` chapter README
+- Root-facing NEAT chapters drift below the current educational-docs bar.
+- Generated opening ownership regresses after later structural work.
+- A major NEAT public-surface change needs renewed root chapter framing.
 
-## Assumptions
+## Audit log
 
-- The generated root NEAT story is expected to live in [src/README.md](../src/README.md), not in [src/neat/README.md](../src/neat/README.md).
-- The highest-leverage fix is richer JSDoc in [src/neat.ts](../src/neat.ts), especially module-level and class-level introductions.
-- External sources and Wikipedia media are optional, not mandatory. If none are needed, the safest compliant outcome is to use no external media and no external citations.
-
-## Session Log
-
-### Foundation
-
-- Strengthened [src/neat.ts](../src/neat.ts) so the generated root story in [src/README.md](../src/README.md) reads as a clearer controller overview.
-
-### Generator follow-up
-
-- The docs generator work is complete enough for now: [scripts/generate-docs/generate-docs.ts](../scripts/generate-docs/generate-docs.ts) supports per-folder ordering controls through `docs.order.json`, and the shared-speciation pilot is already live in [src/neat/speciation/shared/docs.order.json](../src/neat/speciation/shared/docs.order.json).
-
-### Latest completed chapter work
-
-- Recent source-first passes strengthened [src/neat/shared/neat.shared.types.ts](../src/neat/shared/neat.shared.types.ts), [src/neat/neat.constants.ts](../src/neat/neat.constants.ts), [src/neat/cache/cache.ts](../src/neat/cache/cache.ts), [src/neat/compat/compat.ts](../src/neat/compat/compat.ts), [src/neat/harness/neat.harness.types.ts](../src/neat/harness/neat.harness.types.ts), [src/neat/init/neat.init.ts](../src/neat/init/neat.init.ts), [src/neat/helpers/neat.helpers.ts](../src/neat/helpers/neat.helpers.ts), and [src/neat/rng/rng.ts](../src/neat/rng/rng.ts); the RNG root now distinguishes caller-owned randomness from controller-owned replay state more explicitly, and the root [src/README.md](../src/README.md) plus [src/neat.ts](../src/neat.ts) story still holds up against the current pedagogical standard. Docs regeneration and TypeScript validation should be kept on every new pass.
-- A bounded root-surface polish split then moved the root compatibility alias shelf into [src/neat/neat.types.ts](../src/neat/neat.types.ts), moved the public defaults shelf into [src/neat/neat.defaults.constants.ts](../src/neat/neat.defaults.constants.ts), and centralized the empty diversity fallback in [src/neat/diversity/diversity.ts](../src/neat/diversity/diversity.ts); [src/README.md](../src/README.md) still presents the stable public root story while [src/neat/README.md](../src/neat/README.md) now carries the deeper root-types and root-defaults chapter docs.
-
-Remaining gaps:
-
-- Most remaining weaknesses are now small chapter-quality revisits, not untouched surfaces.
-- Generator limits still show up in some larger or re-export-heavy chapters, so only use `docs.order.json` when ordering is the real blocker.
-- Keep prioritizing compact runtime, facade, or policy boundaries that still read more like shelves than chapters.
-
-Next step:
-
-- Re-read [src/neat/lineage/README.md](../src/neat/lineage/README.md) and [src/neat/lineage/lineage.ts](../src/neat/lineage/lineage.ts) to decide whether the lineage root is now the next weakest compact controller-facing boundary after the RNG pass.
-
-## Handoff Prompt
-
-```text
-Continue the educational-docs pass for the next adjacent NEAT chapter using plans/neat-docs.plans.md as the source of truth.
-
-Current state:
-- The generator pause is complete enough; use [plans/pedagogical-docs.plans.md](../plans/pedagogical-docs.plans.md) only if a new generator gap appears.
-- Recent local passes already strengthened the shared-contracts, root-constants, cache-root, compatibility-root, harness-root, init-root, helpers-root, and RNG-root chapters, and the root [src/README.md](../src/README.md) story still holds up against the newer pedagogical standard.
-
-What to verify next:
-- Re-read [src/neat/lineage/README.md](../src/neat/lineage/README.md) and [src/neat/lineage/lineage.ts](../src/neat/lineage/lineage.ts).
-- If the lineage root still feels flatter than nearby compatibility and telemetry-facing chapters, improve the source JSDoc in [src/neat/lineage/lineage.ts](../src/neat/lineage/lineage.ts) and add a chart only if it materially clarifies ancestry evidence versus structural-distance evidence faster than the current prose alone.
-- Otherwise move to the next smallest bridge, facade, or policy boundary that still reads like an API shelf, but keep the selection root-first instead of jumping straight into a subfolder.
-- Keep using `docs.order.json` only where compiled order is the real obstacle.
-
-If more work is needed:
-- Make source-first JSDoc improvements in the next weakest NEAT chapter, then run `npm run docs` and `npx tsc --noEmit -p tsconfig.json`.
-- Do not hand-edit generated `src/**/README.md` files.
-- Update [plans/neat-docs.plans.md](../plans/neat-docs.plans.md) with only the latest minimal pass summary.
-```
+- Durable completion notes now live in [neat-docs.logs.md](neat-docs.logs.md).

package/plans/neat-test-surface-repair.logs.md

@@ -0,0 +1,38 @@
+# NEAT Test Surface Repair Log
+
+**Status:** [DONE]
+
+## Audit scope
+
+- Objective: restore the NEAT public TypeScript and import surface expected by
+  the test suite without widening the repair into unrelated example failures.
+
+## Durable milestones
+
+### [DONE] Failure classification
+
+- Grouped the failing diagnostics into public-surface regressions rather than
+  runtime-assertion failures so the repair could stay compatibility-first.
+
+### [DONE] Public-surface restoration
+
+- Widened the public `NeatOptions` shape to match implementation-supported
+  fields used by tests.
+- Reintroduced the thin root compatibility facades needed by legacy imports.
+
+### [DONE] Validation closure
+
+- Cleared the NEAT-specific TypeScript failures in `tsconfig.test.json` and
+  confirmed the full Jest suite still passes.
+- Isolated the remaining diagnostics to the `asciiMaze` example lane instead of
+  leaving ambiguity at closeout.
+
+## Controls and evidence
+
+- Validation used `npx tsc --noEmit -p tsconfig.test.json`,
+  `npx jest test/neat --runInBand`, and `npm test`.
+
+## Reopen triggers
+
+- NEAT public imports or option contracts regress again.
+- New test-facing compatibility errors appear in the NEAT lane.

package/plans/neat-test-surface-repair.plans.md

@@ -4,35 +4,35 @@
 
 ## Scope
 
-Repair the NEAT public TypeScript compatibility surface so the current runtime
-features and root helper facades compile against the existing test suite.
+- Repair the public NEAT compatibility surface so the test suite reflects the
+  implementation-supported option and import contracts.
+- Keep the fixes compatibility-first and isolated from unrelated example-lane
+  failures.
 
-## Current state
+## Final state
 
-- [DONE] Grouped the failures into public-surface regressions instead of runtime assertion failures.
-- [DONE] Confirmed the runtime still reads option fields such as `telemetry.enabled`, `multiObjective.dominanceEpsilon`, `multiObjective.adaptiveEpsilon`, `novelty.descriptor`, `novelty.archiveAddThreshold`, `adaptiveMutation.initialRate`, and `lineagePressure.strength`.
-- [DONE] Confirmed legacy root imports `src/neat/neat.diversity` and `src/neat/neat.lineage` no longer exist even though the folderized modules still do.
-- [DONE] Restored the public type/facade boundary with compatibility-first edits and validated the NEAT test slice.
-- [DONE] Re-ran `npx tsc --noEmit -p tsconfig.test.json` from the current repo state and confirmed the remaining diagnostics are only in `test/examples/asciiMaze/**`.
-- [DONE] Re-ran `npm test` from the current repo state and confirmed the full Jest suite passes.
+- The NEAT public surface once again matches the implementation-supported test
+  expectations for options and root compatibility imports.
+- NEAT-specific TypeScript regressions were cleared without reopening unrelated
+  example diagnostics.
+- No active backlog remains; this file is now a reopen point for future NEAT
+  public-surface compatibility regressions.
 
-## Coverage backlog
+## Audit summary
 
-- [DONE] Widened `src/neat/shared/neat.shared.types.ts` so the public `NeatOptions` surface matches the live implementation-supported fields used by tests.
-- [DONE] Reintroduced thin root compatibility facades for diversity and lineage.
-- [DONE] Cleared the NEAT-specific TypeScript errors in `npx tsc --noEmit -p tsconfig.test.json` output.
-- [DONE] Ran `npx jest test/neat --runInBand` successfully.
-- [DONE] Noted that the repository-wide test TypeScript build still reports unrelated `test/examples/asciiMaze/**` branch errors outside this repair.
-- [DONE] Ran `npm test` successfully across the full repository.
+- Validation used `npx tsc --noEmit -p tsconfig.test.json`, targeted NEAT test
+  execution, and `npm test` from the current repo state.
+- Remaining test TypeScript issues at closeout were intentionally isolated to
+  the `asciiMaze` example lane and later handled separately.
 
-## Immediate next steps
+## Reopen conditions
 
-1. No active NEAT-surface work remains in this tracker.
-2. If needed, handle the unrelated `asciiMaze` branch diagnostics in a separate repair pass.
+- Future NEAT public-surface changes break test-facing option or import
+  compatibility.
+- `tsconfig.test.json` reintroduces NEAT-specific diagnostics.
+- Root compatibility facades need another repair pass.
 
-## Handoff query
+## Audit log
 
-```text
-Continue from the current repo state only. Do not rely on prior chat history.
-The NEAT public-surface repair tracked in plans/neat-test-surface-repair.plans.md is complete. Do not make further NEAT-surface changes unless new evidence appears. If follow-up work is needed, start a separate pass for the remaining TypeScript diagnostics under test/examples/asciiMaze/**. Preserve unrelated user changes.
-```
+- Durable completion notes now live in
+  [neat-test-surface-repair.logs.md](neat-test-surface-repair.logs.md).

package/plans/readme-first-section-pass.logs.md

@@ -0,0 +1,63 @@
+# README First Section Pass Log
+
+**Status:** [DONE]
+
+## Audit scope
+
+- Objective: improve the first section under the top `#` heading for every
+  README surface under `src/` and `test/examples/`.
+- Inventory closed: 181 README surfaces reviewed, including 144 under `src/`
+  and 37 under `test/examples/`.
+- Operating rules: generated `src/**/README.md` files were not hand-edited;
+  improvements were applied through source owners and targeted
+  `docs.order.json` controls only.
+
+## Durable milestones
+
+### [DONE] Root and chapter-map remediation
+
+- Strengthened the intro-owner surfaces for the top-level README chapter maps,
+  including the `src/` roots, multithreading root, architecture root, and the
+  flagship example system roots.
+- Added `docs.order.json` controls only where generated chapters needed a
+  different intro owner to produce a stronger first section.
+- Validation after source edits: `npm run docs` and
+  `npx tsc --noEmit -p tsconfig.json`.
+
+### [DONE] Architecture, methods, multithreading, and NEAT closure
+
+- Closed the architecture subtree with targeted intro-owner improvements in the
+  pool, layer, and selected `network/**` chapters; other chapters were audited
+  and held unchanged when already at the required bar.
+- Closed the methods and multithreading subtree with targeted improvements in
+  `mutation` and worker chapters, including the Node worker intro-owner
+  correction.
+- Closed the NEAT subtree across root-facing and deep implementation chapters;
+  only the needed intro-owner files were strengthened, while the remaining
+  mutation, speciation, species, telemetry, and related leaves were audited and
+  held unchanged.
+
+### [DONE] Example leaf closure
+
+- Closed the remaining `asciiMaze` and `flappy_bird` leaf chapters after
+  re-reading the deeper dashboard, maze-movement, browser-entry, playback,
+  rollout, observation, and trainer-evaluation surfaces.
+- Final example-leaf closure required no additional intro-owner edits,
+  ordering controls, or split escalation.
+
+## Controls and evidence
+
+- Generated README surfaces under `src/` remained read-only throughout the
+  workstream.
+- Every source-affecting documentation pass recorded validation with
+  `npm run docs` and `npx tsc --noEmit -p tsconfig.json`.
+- The final tracker closeout was markdown-only, so no docs regeneration or
+  typecheck rerun was required at archive time.
+
+## Reopen triggers
+
+- A new README surface is added under `src/` or `test/examples/`.
+- A changed boundary causes the generated first section to fall below the
+  current documentation bar.
+- A chapter proves structurally too large for docs-only repair and needs
+  `solid-split` escalation.

package/plans/readme-first-section-pass.plans.md

@@ -0,0 +1,42 @@
+# README First Section Pass
+
+**Status:** [DONE]
+
+## Scope
+
+- Repo-wide educational-docs pass over the first section under the top `#`
+  heading for every README surface under `src/` and `test/examples/`.
+- Source-first only: generated `src/**/README.md` files stayed read-only and
+  intro improvements were made in source owners or `docs.order.json` controls.
+
+## Final state
+
+- Coverage is closed for the tracked inventory: 181 README surfaces reviewed,
+  including 144 under `src/` and 37 under `test/examples/`.
+- Root chapter maps, selected architecture and worker chapters, adaptive core,
+  and flagship example system chapters were strengthened where the generated
+  opening needed a better intro owner or clearer first-section framing.
+- Remaining deeper NEAT and example leaf chapters were re-read and held
+  unchanged when they already met the current documentation bar.
+- No active backlog remains for this workstream.
+
+## Audit summary
+
+- Source-affecting passes regenerated docs with `npm run docs`.
+- Source-affecting passes validated types with
+  `npx tsc --noEmit -p tsconfig.json`.
+- Final closure was audit-only; no source edits or validation rerun were
+  required for the closing tracker update.
+
+## Reopen conditions
+
+- A new README surface is added under `src/` or `test/examples/`.
+- A changed boundary regresses the first section below the current
+  educational-docs bar.
+- A chapter still needs `solid-split` escalation after normal source-first
+  improvement.
+
+## Audit log
+
+- Durable completion notes now live in
+  [readme-first-section-pass.logs.md](readme-first-section-pass.logs.md).

package/plans/render-docs-html-solid-split.logs.md

@@ -0,0 +1,36 @@
+# Render Docs HTML SOLID Split Log
+
+**Status:** [DONE]
+
+## Audit scope
+
+- Objective: move the HTML docs renderer into a folder-owned boundary while
+  keeping the docs site stable and improving renderer-specific UX details.
+
+## Durable milestones
+
+### [DONE] Consolidated renderer split
+
+- Established stable ownership chapters for assets, Mermaid, navigation,
+  pages, shared logic, and types.
+- Kept the root renderer entrypoint stable during the refactor.
+
+### [DONE] Direct-path and cleanup follow-through
+
+- Removed the old flat sidebar ownership after direct-path migration.
+- Simplified the renderer boundary so future work does not reopen the flat-file
+  shape.
+
+### [DONE] UX and correctness fixes
+
+- Fixed content-link rewriting and clarified sidebar labels and behavior as
+  part of the split follow-through.
+
+## Controls and evidence
+
+- Validation used clean file diagnostics and `npm run docs`.
+
+## Reopen triggers
+
+- Docs renderer behavior regresses in links, sidebar behavior, or Mermaid flow.
+- Another renderer subarea needs its own structural split.

package/plans/render-docs-html-solid-split.plans.md

@@ -4,65 +4,31 @@
 
 ## Scope
 
-- Consolidate the HTML docs renderer into a folder-owned boundary rooted at `scripts/render-docs-html/`.
-- Keep `scripts/render-docs-html.ts` as the stable orchestration entrypoint.
-- Remove the flat `scripts/render-docs-html.sidebar.ts` file once the new direct-path chapter imports are in place.
-- Improve link correctness, sidebar clarity, and docs UX where those issues are exposed by the split.
+- Consolidate the HTML docs renderer into a stable folder-owned boundary.
+- Improve link correctness and sidebar behavior while keeping docs rendering
+  behavior stable.
 
-## Current state
+## Final state
 
-- Split root: `scripts/render-docs-html/` with `scripts/render-docs-html.ts` as the stable orchestration entrypoint
-- README inventory for `scripts/`: none under `scripts/**/README.md`
-- Relevant plan: [plans/Interactive_Examples_and_Learning_Path.md](../plans/Interactive_Examples_and_Learning_Path.md)
-- Relevant repo memory: `/memories/repo/scripts_docs_sidebar_boundary.md`
-- Stable entrypoint: `scripts/render-docs-html.ts`
-- Landed chapter files:
-  - `render-docs-html.assets.ts`
-  - `render-docs-html.mermaid.ts`
-  - `render-docs-html.navigation.ts`
-  - `render-docs-html.pages.ts`
-  - `render-docs-html.shared.ts`
-  - `render-docs-html.types.ts`
-- Closed issues in this step:
-  - nested docs content links now resolve through compiled docs targets or repository URLs instead of remaining raw repo-relative hrefs,
-  - deep sidebar labels now use clearer formatted names instead of collapsing to ambiguous leaf-only segments,
-  - examples-first showcase now collapses to a lighter compact mode away from onboarding/example surfaces.
+- The HTML renderer now uses stable chapter ownership for assets, Mermaid,
+  navigation, pages, shared logic, and types.
+- Link rewriting and sidebar behavior were corrected as part of the split
+  follow-through.
+- No active backlog remains; this file is now a reopen point for future docs
+  renderer work.
 
-## Coverage backlog
+## Audit summary
 
-### [DONE] Consolidated renderer folder split
+- Validation used file diagnostics and `npm run docs`.
+- The renderer root entrypoint remained stable through the split.
 
-- Created `scripts/render-docs-html/` with focused chapters for shared helpers, navigation, Mermaid handling, page rendering, static assets, and shared contracts.
-- Kept `scripts/render-docs-html.ts` orchestration-first and moved the heavy logic behind direct chapter imports.
-- Deleted `scripts/render-docs-html.sidebar.ts` after the direct-path migration landed.
-- Folded link-rewrite fixes and targeted sidebar UX improvements into the same step.
+## Reopen conditions
 
-### [DONE] Educational docs follow-up
+- Future renderer work makes the current folder structure insufficient.
+- Docs-site link rewriting or sidebar behavior regresses.
+- Mermaid or navigation ownership needs another split.
 
-- Completed the required `educational-docs` follow-up on the touched renderer boundary.
-- Strengthened chapter-level documentation and shared type descriptions so the renderer reads as an intentional docs-tooling subsystem rather than a loose helper shelf.
+## Audit log
 
-## Validation
-
-- File diagnostics: clean for `scripts/render-docs-html.ts` and all files under `scripts/render-docs-html/`.
-- `npm run docs`: passed.
-
-## Immediate next steps
-
-- No further split work is queued for this boundary right now.
-- Future work should start from `scripts/render-docs-html/` and preserve `scripts/render-docs-html.ts` as the stable entrypoint.
-
-## Handoff query
-
-```text
-Continue from the current repo state only. Do not rely on prior chat history.
-
-Use solid-split for #file:render-docs-html.ts and #file:render-docs-html.sidebar.ts.
-Plan: plans/render-docs-html-solid-split.plans.md.
-Current boundary: scripts/render-docs-html.
-Completed context: scripts has no local README surface, the stable entrypoint remains scripts/render-docs-html.ts, the old flat sidebar file is deleted, and the folder boundary now owns assets, Mermaid handling, navigation, shared helpers, page rendering, and shared contracts.
-If this boundary reopens: continue from the folderized renderer, preserving the improved content-link rewriting and the lighter examples/sidebar behavior instead of recreating flat helper files.
-Repo standard: direct-path migration with no compatibility shims by default, and the small-chapter README pattern applies to scripts/tooling boundaries too.
-Required validations: file diagnostics for touched files, then npm run docs.
-Worktree caution: npm run docs rewrites generated docs outputs and there may already be unrelated generated-file drift in the worktree.
-```
+- Durable completion notes now live in
+  [render-docs-html-solid-split.logs.md](render-docs-html-solid-split.logs.md).

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

@@ -0,0 +1,39 @@
+# Source No-Explicit-Any Cleanup Log
+
+**Status:** [DONE]
+
+## Audit scope
+
+- Objective: eliminate the explicit-`any` debt in `src/` and close the related
+  typed-hygiene follow-through left by prior refactors.
+
+## Durable milestones
+
+### [DONE] Root baseline closure
+
+- Closed the root explicit-`any` baseline at zero and removed the remaining
+  explicit-form variants such as `as any` and `Promise<any>` from the tracked
+  lane.
+
+### [DONE] Hotspot cleanup passes
+
+- Cleaned the root `neat.ts` surface and the key evolve, adaptive,
+  multiobjective, and multithreading hotspots with behavior-preserving type
+  strengthening.
+
+### [DONE] Prose and lint-hygiene follow-through
+
+- Completed the prose-only `any` sweep and the later lint-hygiene cleanup such
+  as unused imports and empty-to-type alias follow-through.
+- Closed the lane on a repository-local `src` lint baseline rather than leaving
+  scattered reopen notes.
+
+## Controls and evidence
+
+- Validation used targeted ESLint checks, `npx tsc --noEmit -p tsconfig.json`,
+  and a final green `npx eslint src` pass.
+
+## Reopen triggers
+
+- Explicit-`any` debt returns in `src/` after future refactors.
+- Typing or lint baselines regress in the previously cleaned hotspots.