@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/selection/facade/README.md

@@ -47,38 +47,52 @@ behavior.
 
 ## neat/selection/facade/selection.facade.ts
 
-### sort
+### FittestNetwork
+
+Champion-shaped network returned by the public `getFittest()` facade.
+
+The facade intentionally returns the real network instance from the current
+population rather than a detached summary object. That keeps the stable
+`Neat` contract aligned with long-standing usage patterns where callers read
+the champion's score and then continue inspecting the network itself.
+
+The extra `score` field is called out here so the generated README can name
+the returned shape explicitly instead of falling back to a rough imported
+default-type rendering.
+
+### getAverage
 
 ```ts
-sort(
+getAverage(
   host: NeatPopulationSummaryFacadeHost,
-): void
+): number
 ```
 
-Sort the population in descending fitness order.
+Compute the average score across the current population.
 
-This preserves the historical `neat.sort()` behavior while keeping the
-top-level class free of inline ordering details.
+This is a compact inspection helper for telemetry, tests, and quick
+debugging where the caller only needs the current mean fitness.
 
-Use this wrapper when later reads should see the current population in an
-explicit best-first order, such as before manual inspection, debugging, or a
-deterministic test assertion. The wrapper deliberately stays narrow: it only
-forwards to the shared selection ordering helper and keeps the familiar class
-method available at the stable `Neat` surface.
+Read it as the companion to {@link getFittest}: the champion tells you how
+high the best genome has climbed, while the average tells you whether that
+progress is representative of the wider generation or still concentrated in
+a small leading group. Because this wrapper stays at the summary layer, it
+reports on population state without drifting into parent-choice or breeding
+policy.
 
-This is the facade's one explicit reordering primitive. Everything else in
-the chapter is read-only population inspection.
+Together, `getFittest()` and `getAverage()` are the facade's public promise:
+one read for the leader and one read for the generation as a whole.
 
 Parameters:
-- `host` - - `Neat` instance exposing population sorting state.
+- `host` - - `Neat` instance exposing population and evaluation state.
 
-Returns: Nothing. The population array is reordered in place.
+Returns: Mean score across the current population.
 
 Example:
 
 ```ts
-neat.sort();
-console.log(neat.population[0].score);
+const meanScore = neat.getAverage();
+console.log(`Average score: ${meanScore}`);
 ```
 
 ### getFittest
@@ -116,41 +130,6 @@ const champion = neat.getFittest();
 console.log(champion.score);
 ```
 
-### getAverage
-
-```ts
-getAverage(
-  host: NeatPopulationSummaryFacadeHost,
-): number
-```
-
-Compute the average score across the current population.
-
-This is a compact inspection helper for telemetry, tests, and quick
-debugging where the caller only needs the current mean fitness.
-
-Read it as the companion to {@link getFittest}: the champion tells you how
-high the best genome has climbed, while the average tells you whether that
-progress is representative of the wider generation or still concentrated in
-a small leading group. Because this wrapper stays at the summary layer, it
-reports on population state without drifting into parent-choice or breeding
-policy.
-
-Together, `getFittest()` and `getAverage()` are the facade's public promise:
-one read for the leader and one read for the generation as a whole.
-
-Parameters:
-- `host` - - `Neat` instance exposing population and evaluation state.
-
-Returns: Mean score across the current population.
-
-Example:
-
-```ts
-const meanScore = neat.getAverage();
-console.log(`Average score: ${meanScore}`);
-```
-
 ### NeatPopulationSummaryFacadeHost
 
 Narrow `Neat` host surface required by the public population-summary facade.
@@ -166,15 +145,36 @@ and lower-level selection policy stay in the root selection boundary and its
 need to preserve long-standing `neat.sort()`, `neat.getFittest()`, and
 `neat.getAverage()` behavior.
 
-### FittestNetwork
+### sort
 
-Champion-shaped network returned by the public `getFittest()` facade.
+```ts
+sort(
+  host: NeatPopulationSummaryFacadeHost,
+): void
+```
 
-The facade intentionally returns the real network instance from the current
-population rather than a detached summary object. That keeps the stable
-`Neat` contract aligned with long-standing usage patterns where callers read
-the champion's score and then continue inspecting the network itself.
+Sort the population in descending fitness order.
 
-The extra `score` field is called out here so the generated README can name
-the returned shape explicitly instead of falling back to a rough imported
-default-type rendering.
+This preserves the historical `neat.sort()` behavior while keeping the
+top-level class free of inline ordering details.
+
+Use this wrapper when later reads should see the current population in an
+explicit best-first order, such as before manual inspection, debugging, or a
+deterministic test assertion. The wrapper deliberately stays narrow: it only
+forwards to the shared selection ordering helper and keeps the familiar class
+method available at the stable `Neat` surface.
+
+This is the facade's one explicit reordering primitive. Everything else in
+the chapter is read-only population inspection.
+
+Parameters:
+- `host` - - `Neat` instance exposing population sorting state.
+
+Returns: Nothing. The population array is reordered in place.
+
+Example:
+
+```ts
+neat.sort();
+console.log(neat.population[0].score);
+```

package/src/neat/shared/README.md

@@ -64,44 +64,84 @@ Practical reading order:
 
 ## neat/shared/neat.shared.types.ts
 
-### SpeciationOptions
+### AnyObj
 
-Speciation options for the NEAT speciation controller.
+Generic map type used as a stop‑gap where the precise shape is still in flux.
+Prefer a specific interface once the surface stabilises.
 
-Extends {@link NeatOptions} with speciation-specific configuration used by:
-- Compatibility-threshold based species assignment
-- Adaptive threshold controllers (PID-like)
-- Species allocation telemetry (history snapshots)
+### ComplexityMetrics
 
-This is the shared policy slice that lets speciation helpers stay narrowly
-typed without importing the full controller configuration object. Read it as
-the option family that shapes how species are formed, protected, and recorded
-over time.
+Aggregate structural complexity metrics capturing size & growth pressure.
 
-### SpeciesLastStats
+### ConnectionLike
 
-Rolling statistics tracked for each species between generations.
-These values inform stagnation heuristics and adaptive controllers.
+Lightweight connection representation used by telemetry and structural helpers.
 
-These are controller-maintenance values rather than polished reporting rows.
-They exist so live speciation logic can remember recent behavior before the
-`species/` chapter later projects that state into user-facing summaries.
+### DiversityStats
 
-### SpeciationHarnessContext
+Diversity statistics captured each generation. Individual fields may be
+omitted in telemetry output if diversity tracking is partially disabled to
+reduce runtime cost.
 
-Minimal runtime surface required by speciation helpers.
-Tests and harnesses can narrow the options type via the generic parameter.
+This contract is the compact summary that lets telemetry, diagnostics, and
+dashboards talk about population spread without rerunning the heavier
+compatibility, entropy, and lineage calculations. The fields are aggregated
+on purpose: they are meant for trend reading, not for reconstructing every
+pairwise comparison after the fact.
 
-This host contract is intentionally more specific than `NeatLike` because
-speciation is one of the most stateful controller phases. The helpers need
-the live population, the species registry, threshold-tuning accumulators,
-and the compatibility read itself, but they still do not need the entire
-public `Neat` facade.
+This is one half of the chapter's evidence language. Diversity tells the
+controller how structurally spread out the population currently looks, which
+is useful for dashboards, adaptive policies, and regression checks even when
+the full pairwise evidence would be too expensive to keep around.
 
-### AnyObj
+### GenomeDetailed
 
-Generic map type used as a stop‑gap where the precise shape is still in flux.
-Prefer a specific interface once the surface stabilises.
+More concrete genome surface used by telemetry and lineage helpers.
+Extends the minimal `GenomeLike` with node/connection shapes and a few
+internal bookkeeping fields used by telemetry.
+
+Use this contract when a helper needs more than anonymous structure. The
+extra fields here are the ones that repeatedly matter to the read-side NEAT
+chapters: stable genome identity, parent tracking, lineage depth, and the
+richer node and connection shapes needed for telemetry, history, and
+compatibility-adjacent reporting.
+
+In chapter terms, `GenomeDetailed` is the point where the shared vocabulary
+stops being merely structural and becomes historically meaningful. Once a
+helper needs `_id`, `_parents`, or `_depth`, it is no longer talking about a
+generic network shape; it is talking about a genome with an evolutionary
+past that later reporting chapters may want to inspect.
+
+### GenomeLike
+
+Minimal genome structural surface used by several helpers (incrementally expanded).
+
+NOTE: `nodes` and `connections` remain intentionally structural/opaque
+until a stable public abstraction is finalised.
+
+Read this as the portable genome contract. It is enough for helpers that
+need counts, loose structural access, or a primary score, but not enough to
+encode every network behavior. More specialized chapters should extend this
+shape only when they truly need richer node, connection, or lineage detail.
+
+That restraint matters because this contract sits near the base of the shared
+vocabulary. If it grows too eager, every downstream chapter inherits more of
+the runtime than it actually needs.
+
+### LineageSnapshot
+
+Snapshot of lineage & ancestry statistics for the current generation.
+
+This is the ancestry companion to `DiversityStats`. Diversity answers how far
+apart genomes currently look; lineage answers how much recent family overlap
+still exists beneath those structures. Telemetry and adaptive controllers use
+both because structural spread and family spread are related but not
+interchangeable signals.
+
+Read `LineageSnapshot` and `DiversityStats` together. One describes present
+structural variety, the other describes how independent that variety really
+is. NEAT benefits from both views because a population can look diverse while
+still clustering around a narrow recent ancestry.
 
 ### NeatLike
 
@@ -119,6 +159,30 @@ Pedagogically, this is the chapter's "start here" host contract. It tells a
 reader that the shared layer values portability over completeness, and that a
 richer local host contract should only appear when a chapter can justify why.
 
+### NeatOptions
+
+Options subset used by telemetry helpers. Kept narrow to avoid leaking
+full runtime options into the helper type surface.
+
+The purpose of this contract is not to model every `Neat` option. It is to
+capture the policy knobs that recur across extracted helper chapters:
+telemetry flags, diversity sampling, compatibility tuning, species history,
+novelty, and a few structural budget fields. If a helper needs more than
+this, that is usually a sign it wants a chapter-local host contract instead
+of a wider shared type.
+
+Read this as the shared policy slice, not the complete public options model.
+It exists so extracted chapters can agree on recurring controller settings
+without smuggling the full `Neat` facade through every helper signature.
+
+### NodeLike
+
+Lightweight node representation used by telemetry and structural helpers.
+
+### ObjAges
+
+Map of objective key to age in generations since introduction.
+
 ### ObjectiveDescriptor
 
 Descriptor for a single optimisation objective (single or multi‑objective runs).
@@ -149,90 +213,24 @@ const complexityObj: ObjectiveDescriptor = {
 };
 ```
 
-### GenomeLike
-
-Minimal genome structural surface used by several helpers (incrementally expanded).
-
-NOTE: `nodes` and `connections` remain intentionally structural/opaque
-until a stable public abstraction is finalised.
-
-Read this as the portable genome contract. It is enough for helpers that
-need counts, loose structural access, or a primary score, but not enough to
-encode every network behavior. More specialized chapters should extend this
-shape only when they truly need richer node, connection, or lineage detail.
-
-That restraint matters because this contract sits near the base of the shared
-vocabulary. If it grows too eager, every downstream chapter inherits more of
-the runtime than it actually needs.
-
-### NodeLike
-
-Lightweight node representation used by telemetry and structural helpers.
-
-### ConnectionLike
-
-Lightweight connection representation used by telemetry and structural helpers.
-
-### GenomeDetailed
-
-More concrete genome surface used by telemetry and lineage helpers.
-Extends the minimal `GenomeLike` with node/connection shapes and a few
-internal bookkeeping fields used by telemetry.
-
-Use this contract when a helper needs more than anonymous structure. The
-extra fields here are the ones that repeatedly matter to the read-side NEAT
-chapters: stable genome identity, parent tracking, lineage depth, and the
-richer node and connection shapes needed for telemetry, history, and
-compatibility-adjacent reporting.
-
-In chapter terms, `GenomeDetailed` is the point where the shared vocabulary
-stops being merely structural and becomes historically meaningful. Once a
-helper needs `_id`, `_parents`, or `_depth`, it is no longer talking about a
-generic network shape; it is talking about a genome with an evolutionary
-past that later reporting chapters may want to inspect.
-
-### SpeciesLike
-
-Internal species representation used by helpers. Kept minimal and structural.
-
-This is the live registry shape behind the stronger `speciation/` and
-`species/` chapters. It is intentionally not a polished reporting format;
-instead it holds the small amount of state those chapters repeatedly need to
-maintain or summarize: membership, best score, improvement timing, and room
-for implementation-specific bookkeeping.
+### ObjectiveEvent
 
-### NeatOptions
+Objective add/remove lifecycle event for telemetry and auditing.
 
-Options subset used by telemetry helpers. Kept narrow to avoid leaking
-full runtime options into the helper type surface.
+### ObjEvent
 
-The purpose of this contract is not to model every `Neat` option. It is to
-capture the policy knobs that recur across extracted helper chapters:
-telemetry flags, diversity sampling, compatibility tuning, species history,
-novelty, and a few structural budget fields. If a helper needs more than
-this, that is usually a sign it wants a chapter-local host contract instead
-of a wider shared type.
+Dynamic objective lifecycle event (addition or removal).
 
-Read this as the shared policy slice, not the complete public options model.
-It exists so extracted chapters can agree on recurring controller settings
-without smuggling the full `Neat` facade through every helper signature.
+**Deprecated:** Use `ObjectiveEvent` instead.
 
-### DiversityStats
+### ObjImportance
 
-Diversity statistics captured each generation. Individual fields may be
-omitted in telemetry output if diversity tracking is partially disabled to
-reduce runtime cost.
+Map of objective key to its importance metrics (range / variance).
 
-This contract is the compact summary that lets telemetry, diagnostics, and
-dashboards talk about population spread without rerunning the heavier
-compatibility, entropy, and lineage calculations. The fields are aggregated
-on purpose: they are meant for trend reading, not for reconstructing every
-pairwise comparison after the fact.
+### ObjImportanceEntry
 
-This is one half of the chapter's evidence language. Diversity tells the
-controller how structurally spread out the population currently looks, which
-is useful for dashboards, adaptive policies, and regression checks even when
-the full pairwise evidence would be too expensive to keep around.
+Contribution / dispersion metrics for an objective over a recent window.
+Used to gauge whether an objective meaningfully influences selection.
 
 ### OperatorStat
 
@@ -246,57 +244,89 @@ A high attempt count with low success can indicate constraints becoming tight
 
 Aggregated success / attempt counters over a window or entire run.
 
-### ObjImportanceEntry
+### ParetoArchiveEntry
 
-Contribution / dispersion metrics for an objective over a recent window.
-Used to gauge whether an objective meaningfully influences selection.
+Pareto archive entry capturing a genome plus its objective values.
 
-### ObjImportance
+This contract is intentionally sparse because the archive is primarily a
+preservation boundary. The stored genome captures the candidate itself, while
+`objectives` preserves the exact multi-objective evidence that justified its
+place on the frontier at the time it was archived.
 
-Map of objective key to its importance metrics (range / variance).
+### PerformanceMetrics
 
-### ObjAges
+Timing metrics for coarse evolutionary phases (milliseconds).
 
-Map of objective key to age in generations since introduction.
+These timings are intentionally coarse. They exist to reveal where a run is
+spending time at the chapter level, not to replace a profiler. That makes
+them useful inside telemetry exports and regression-oriented dashboards where
+simple evaluation-versus-evolution trends are more valuable than exhaustive
+trace detail.
 
-### ObjEvent
+### SpeciationHarnessContext
 
-Dynamic objective lifecycle event (addition or removal).
+Minimal runtime surface required by speciation helpers.
+Tests and harnesses can narrow the options type via the generic parameter.
 
-**Deprecated:** Use `ObjectiveEvent` instead.
+This host contract is intentionally more specific than `NeatLike` because
+speciation is one of the most stateful controller phases. The helpers need
+the live population, the species registry, threshold-tuning accumulators,
+and the compatibility read itself, but they still do not need the entire
+public `Neat` facade.
+
+### SpeciationOptions
+
+Speciation options for the NEAT speciation controller.
+
+Extends {@link NeatOptions} with speciation-specific configuration used by:
+- Compatibility-threshold based species assignment
+- Adaptive threshold controllers (PID-like)
+- Species allocation telemetry (history snapshots)
+
+This is the shared policy slice that lets speciation helpers stay narrowly
+typed without importing the full controller configuration object. Read it as
+the option family that shapes how species are formed, protected, and recorded
+over time.
 
 ### SpeciesAlloc
 
 Offspring allocation for a species during reproduction.
 
-### LineageSnapshot
+### SpeciesHistoryEntry
 
-Snapshot of lineage & ancestry statistics for the current generation.
+Species statistics captured for a particular generation.
 
-This is the ancestry companion to `DiversityStats`. Diversity answers how far
-apart genomes currently look; lineage answers how much recent family overlap
-still exists beneath those structures. Telemetry and adaptive controllers use
-both because structural spread and family spread are related but not
-interchangeable signals.
+This is the history-buffer unit used by the `species/` chapter. One entry
+answers "what did the species table look like at this generation boundary?"
+without requiring callers to inspect the live registry directly.
 
-Read `LineageSnapshot` and `DiversityStats` together. One describes present
-structural variety, the other describes how independent that variety really
-is. NEAT benefits from both views because a population can look diverse while
-still clustering around a narrow recent ancestry.
+### SpeciesHistoryStat
 
-### ComplexityMetrics
+Species statistics at a single historical snapshot (generation boundary).
 
-Aggregate structural complexity metrics capturing size & growth pressure.
+### SpeciesHistoryStatExtended
 
-### PerformanceMetrics
+Extended per-species historical snapshot with optional backfilled metrics
+that may be computed lazily (innovationRange, enabledRatio).
 
-Timing metrics for coarse evolutionary phases (milliseconds).
+### SpeciesLastStats
 
-These timings are intentionally coarse. They exist to reveal where a run is
-spending time at the chapter level, not to replace a profiler. That makes
-them useful inside telemetry exports and regression-oriented dashboards where
-simple evaluation-versus-evolution trends are more valuable than exhaustive
-trace detail.
+Rolling statistics tracked for each species between generations.
+These values inform stagnation heuristics and adaptive controllers.
+
+These are controller-maintenance values rather than polished reporting rows.
+They exist so live speciation logic can remember recent behavior before the
+`species/` chapter later projects that state into user-facing summaries.
+
+### SpeciesLike
+
+Internal species representation used by helpers. Kept minimal and structural.
+
+This is the live registry shape behind the stronger `speciation/` and
+`species/` chapters. It is intentionally not a polished reporting format;
+instead it holds the small amount of state those chapters repeatedly need to
+maintain or summarize: membership, best score, improvement timing, and room
+for implementation-specific bookkeeping.
 
 ### TelemetryEntry
 
@@ -329,33 +359,3 @@ function logSummary(t: TelemetryEntry) {
   if (t.diversity) console.log('Mean compat', t.diversity.meanCompat);
 }
 ```
-
-### SpeciesHistoryStat
-
-Species statistics at a single historical snapshot (generation boundary).
-
-### SpeciesHistoryEntry
-
-Species statistics captured for a particular generation.
-
-This is the history-buffer unit used by the `species/` chapter. One entry
-answers "what did the species table look like at this generation boundary?"
-without requiring callers to inspect the live registry directly.
-
-### SpeciesHistoryStatExtended
-
-Extended per-species historical snapshot with optional backfilled metrics
-that may be computed lazily (innovationRange, enabledRatio).
-
-### ParetoArchiveEntry
-
-Pareto archive entry capturing a genome plus its objective values.
-
-This contract is intentionally sparse because the archive is primarily a
-preservation boundary. The stored genome captures the candidate itself, while
-`objectives` preserves the exact multi-objective evidence that justified its
-place on the frontier at the time it was archived.
-
-### ObjectiveEvent
-
-Objective add/remove lifecycle event for telemetry and auditing.

package/src/neat/speciation/README.md

@@ -57,37 +57,6 @@ neat._updateSpeciesStagnation();
 
 ## neat/speciation/speciation.ts
 
-### _speciate
-
-```ts
-_speciate(): void
-```
-
-Assign genomes into species based on compatibility distance.
-
-This is the main controller-facing speciation pass. It preserves the previous
-species snapshot for telemetry and history, rebuilds memberships against the
-current representatives, adjusts the compatibility threshold, refreshes the
-live representatives, applies optional age-based protection, records a new
-history row, and trims the history buffer.
-
-In other words, this helper does not merely "cluster genomes." It keeps the
-long-lived species registry coherent across generations so later phases such
-as selection, pruning, telemetry, and archive inspection can reason about a
-stable notion of species identity.
-
-Parameters:
-- `this` - - Speciation harness context.
-
-Returns: Nothing.
-
-Example:
-
-```ts
-neat._speciate();
-console.log(neat._species.length);
-```
-
 ### _applyFitnessSharing
 
 ```ts
@@ -142,6 +111,37 @@ Example:
 neat._sortSpeciesMembers(neat._species[0]);
 ```
 
+### _speciate
+
+```ts
+_speciate(): void
+```
+
+Assign genomes into species based on compatibility distance.
+
+This is the main controller-facing speciation pass. It preserves the previous
+species snapshot for telemetry and history, rebuilds memberships against the
+current representatives, adjusts the compatibility threshold, refreshes the
+live representatives, applies optional age-based protection, records a new
+history row, and trims the history buffer.
+
+In other words, this helper does not merely "cluster genomes." It keeps the
+long-lived species registry coherent across generations so later phases such
+as selection, pruning, telemetry, and archive inspection can reason about a
+stable notion of species identity.
+
+Parameters:
+- `this` - - Speciation harness context.
+
+Returns: Nothing.
+
+Example:
+
+```ts
+neat._speciate();
+console.log(neat._species.length);
+```
+
 ### _updateSpeciesStagnation
 
 ```ts