@reicek/neataptic-ts 0.1.24 → 0.1.26

package/src/neat/speciation/threshold/README.md

@@ -100,6 +100,41 @@ adjustCompatibilityThreshold(
 );
 ```
 
+### clampCompatibilityThreshold
+
+```ts
+clampCompatibilityThreshold(
+  options: SpeciationOptions,
+  minCompatibilityThreshold: number,
+  maxCompatibilityThreshold: number,
+): void
+```
+
+Clamp the compatibility threshold to configured bounds.
+
+This is the final safety rail for callers that already have a threshold value
+but need to ensure it remains inside the allowed range. Unlike the PID clamp
+above, this helper only limits the option value itself; it does not interpret
+species-count error or recalculate the integral term.
+
+Read this as the small "no surprises" helper at the end of the loop. Once
+the controller has chosen a new threshold candidate, this function makes the
+public option safe to persist into the next generation even if the caller did
+not come through the full PID path.
+
+Parameters:
+- `options` - - Speciation options.
+- `minCompatibilityThreshold` - - Lower clamp bound.
+- `maxCompatibilityThreshold` - - Upper clamp bound.
+
+Returns: Nothing.
+
+Example:
+
+```ts
+clampCompatibilityThreshold(neat.options, 1, 10);
+```
+
 ### computePidThreshold
 
 ```ts
@@ -152,38 +187,3 @@ const nextThreshold = computePidThreshold(
   10,
 );
 ```
-
-### clampCompatibilityThreshold
-
-```ts
-clampCompatibilityThreshold(
-  options: SpeciationOptions,
-  minCompatibilityThreshold: number,
-  maxCompatibilityThreshold: number,
-): void
-```
-
-Clamp the compatibility threshold to configured bounds.
-
-This is the final safety rail for callers that already have a threshold value
-but need to ensure it remains inside the allowed range. Unlike the PID clamp
-above, this helper only limits the option value itself; it does not interpret
-species-count error or recalculate the integral term.
-
-Read this as the small "no surprises" helper at the end of the loop. Once
-the controller has chosen a new threshold candidate, this function makes the
-public option safe to persist into the next generation even if the caller did
-not come through the full PID path.
-
-Parameters:
-- `options` - - Speciation options.
-- `minCompatibilityThreshold` - - Lower clamp bound.
-- `maxCompatibilityThreshold` - - Upper clamp bound.
-
-Returns: Nothing.
-
-Example:
-
-```ts
-clampCompatibilityThreshold(neat.options, 1, 10);
-```

package/src/neat/species/README.md

@@ -53,31 +53,6 @@ const history = neat.getSpeciesHistory();
 
 ## neat/species/species.ts
 
-### getSpeciesStats
-
-```ts
-getSpeciesStats(): { id: number; size: number; bestScore: number; lastImproved: number; }[]
-```
-
-Get lightweight per-species statistics for the current population.
-
-This is the shortest read path into the species system. It is useful when a
-caller needs dashboard-friendly snapshots such as current species sizes,
-recent improvement timestamps, or the best score per species without pulling
-the heavier generation-by-generation history buffer.
-
-Parameters:
-- `this` - - NEAT host exposing the internal species registry.
-
-Returns: Compact per-species summaries suitable for reporting.
-
-Example:
-
-```ts
-const speciesSummaries = neat.getSpeciesStats();
-console.table(speciesSummaries);
-```
-
 ### getSpeciesHistory
 
 ```ts
@@ -111,3 +86,28 @@ Example:
 const speciesHistory = neat.getSpeciesHistory();
 console.log(speciesHistory.at(-1));
 ```
+
+### getSpeciesStats
+
+```ts
+getSpeciesStats(): { id: number; size: number; bestScore: number; lastImproved: number; }[]
+```
+
+Get lightweight per-species statistics for the current population.
+
+This is the shortest read path into the species system. It is useful when a
+caller needs dashboard-friendly snapshots such as current species sizes,
+recent improvement timestamps, or the best score per species without pulling
+the heavier generation-by-generation history buffer.
+
+Parameters:
+- `this` - - NEAT host exposing the internal species registry.
+
+Returns: Compact per-species summaries suitable for reporting.
+
+Example:
+
+```ts
+const speciesSummaries = neat.getSpeciesStats();
+console.table(speciesSummaries);
+```

package/src/neat/species/core/README.md

@@ -36,26 +36,6 @@ flowchart TD
 
 ## neat/species/core/species.core.ts
 
-### shouldAugmentExtendedHistory
-
-```ts
-shouldAugmentExtendedHistory(
-  options: NeatOptions | undefined,
-): boolean
-```
-
-Check whether extended species history should be augmented.
-
-This is the policy gate for the whole chapter. The read-side species history
-flow uses it to decide whether returning the recorded rows is already enough
-or whether the caller explicitly asked for the richer innovation-range and
-enabled-ratio view.
-
-Parameters:
-- `options` - - Current NEAT options.
-
-Returns: `true` when extended history is enabled.
-
 ### backfillExtendedHistory
 
 ```ts
@@ -90,3 +70,23 @@ if (shouldAugmentExtendedHistory(neat.options)) {
   backfillExtendedHistory(history, neat);
 }
 ```
+
+### shouldAugmentExtendedHistory
+
+```ts
+shouldAugmentExtendedHistory(
+  options: NeatOptions | undefined,
+): boolean
+```
+
+Check whether extended species history should be augmented.
+
+This is the policy gate for the whole chapter. The read-side species history
+flow uses it to decide whether returning the recorded rows is already enough
+or whether the caller explicitly asked for the richer innovation-range and
+enabled-ratio view.
+
+Parameters:
+- `options` - - Current NEAT options.
+
+Returns: `true` when extended history is enabled.

package/src/neat/species/core/shared/README.md

@@ -33,6 +33,24 @@ flowchart TD
 
 ## neat/species/core/shared/species.core.shared.ts
 
+### SpeciesConnectionSummary
+
+Aggregated innovation coverage for the genomes currently assigned to one species.
+
+The history backfill path uses this compact shape to answer two questions that
+are useful in telemetry dashboards:
+
+- how wide the inherited innovation span is across the species members,
+- how many of those structural genes are still enabled.
+
+Those two values are enough to make extended history rows much more
+explanatory without forcing the species-reporting surface to retain every
+connection-level detail from every generation.
+
+Treat it as a reporting summary, not as a lossless reconstruction format.
+The goal is to explain structural breadth and retention at a glance, not to
+preserve every innovation id for downstream mutation logic.
+
 ### summarizeSpeciesConnections
 
 ```ts
@@ -72,21 +90,3 @@ Example:
 const summary = summarizeSpeciesConnections(species.members, neat._fallbackInnov);
 console.log(summary.innovationRange, summary.enabledRatio);
 ```
-
-### SpeciesConnectionSummary
-
-Aggregated innovation coverage for the genomes currently assigned to one species.
-
-The history backfill path uses this compact shape to answer two questions that
-are useful in telemetry dashboards:
-
-- how wide the inherited innovation span is across the species members,
-- how many of those structural genes are still enabled.
-
-Those two values are enough to make extended history rows much more
-explanatory without forcing the species-reporting surface to retain every
-connection-level detail from every generation.
-
-Treat it as a reporting summary, not as a lossless reconstruction format.
-The goal is to explain structural breadth and retention at a glance, not to
-preserve every innovation id for downstream mutation logic.

package/src/neat/species/history/context/README.md

@@ -23,6 +23,28 @@ Read this chapter in two steps:
 
 ## neat/species/history/context/species.history.context.ts
 
+### ResolvedSpeciesHistoryContext
+
+Resolved host data needed to serve a species-history read.
+
+The public `getSpeciesHistory()` facade should not need to know how the NEAT
+controller stores its history buffer or which internal fields are required to
+support optional extended-history augmentation. This context keeps that
+plumbing in one place.
+
+The three fields map to the three setup concerns behind a history read:
+
+- `speciesHistory` is the stored generation-by-generation buffer,
+- `backfillContext` carries the internal data needed only when extended
+  history enrichment is allowed,
+- `neatOptions` carries the policy switches that decide whether that
+  enrichment path should run.
+
+Read this type as the boundary between raw controller storage and the richer
+history-read logic. Once this object has been resolved, later helpers can ask
+"should we augment?" and "what data do we already have?" without knowing
+where the controller originally stored each ingredient.
+
 ### resolveSpeciesHistoryContext
 
 ```ts
@@ -62,25 +84,3 @@ if (historyContext.neatOptions?.enableSpeciesAugmentation) {
 
 console.log(historyContext.speciesHistory.length);
 ```
-
-### ResolvedSpeciesHistoryContext
-
-Resolved host data needed to serve a species-history read.
-
-The public `getSpeciesHistory()` facade should not need to know how the NEAT
-controller stores its history buffer or which internal fields are required to
-support optional extended-history augmentation. This context keeps that
-plumbing in one place.
-
-The three fields map to the three setup concerns behind a history read:
-
-- `speciesHistory` is the stored generation-by-generation buffer,
-- `backfillContext` carries the internal data needed only when extended
-  history enrichment is allowed,
-- `neatOptions` carries the policy switches that decide whether that
-  enrichment path should run.
-
-Read this type as the boundary between raw controller storage and the richer
-history-read logic. Once this object has been resolved, later helpers can ask
-"should we augment?" and "what data do we already have?" without knowing
-where the controller originally stored each ingredient.

package/src/neat/telemetry/accessors/README.md

@@ -26,30 +26,32 @@ exposes cached diversity and coarse timing data.
 
 ## neat/telemetry/accessors/telemetry.accessors.ts
 
-### getTelemetryBuffer
+### buildLineageSnapshot
 
 ```ts
-getTelemetryBuffer(
-  host: TelemetryAccessorHost,
-): TelemetryEntry[]
+buildLineageSnapshot(
+  population: { _id?: number | undefined; _parents?: number[] | undefined; }[],
+  limit: number,
+): { id: number; parents: number[]; }[]
 ```
 
-Return the telemetry buffer, defaulting to an empty array when missing.
+Snapshot lineage metadata for the first `limit` genomes.
 
-This is the lowest-level read for recent telemetry history. It gives callers
-a stable way to inspect the current in-memory buffer without forcing every
-consumer to reimplement null checks.
+The accessor deliberately returns only `{ id, parents }` pairs. That keeps
+lineage snapshots lightweight enough for telemetry entries, tests, and quick
+debugging while still exposing the key teaching signal: which genomes share
+ancestry and how recent offspring connect back to parents.
 
 Parameters:
-- `host` - - Telemetry host that may or may not have initialized its buffer.
+- `population` - - Population slice containing optional runtime lineage metadata.
+- `limit` - - Maximum number of genomes to sample from the front of the population.
 
-Returns: Telemetry entries recorded so far, or an empty array when telemetry
-has not been started yet.
+Returns: Compact lineage entries with genome ids and parent ids.
 
 Example:
 
-const recentEntries = getTelemetryBuffer(neat).slice(-3);
-console.log(recentEntries.length);
+const lineage = buildLineageSnapshot(neat.population, 5);
+console.log(lineage.map((entry) => entry.parents));
 
 ### clearTelemetryBuffer
 
@@ -70,6 +72,25 @@ Parameters:
 
 Returns: Nothing. The host buffer is replaced with an empty array.
 
+### getCachedDiversityStats
+
+```ts
+getCachedDiversityStats(
+  host: TelemetryAccessorHost,
+): DiversityStats | undefined
+```
+
+Read cached diversity statistics.
+
+This accessor does not compute diversity on demand. Its job is only to expose
+the last cached snapshot so callers can distinguish between "no diversity has
+been computed yet" and "diversity was computed and here is the result."
+
+Parameters:
+- `host` - - Telemetry host exposing an optional cached diversity snapshot.
+
+Returns: Cached diversity statistics when available, otherwise `undefined`.
+
 ### getObjectiveEventsSnapshot
 
 ```ts
@@ -94,75 +115,54 @@ Example:
 const events = getObjectiveEventsSnapshot(neat);
 console.table(events);
 
-### buildLineageSnapshot
+### getPerformanceStatsSnapshot
 
 ```ts
-buildLineageSnapshot(
-  population: { _id?: number | undefined; _parents?: number[] | undefined; }[],
-  limit: number,
-): { id: number; parents: number[]; }[]
+getPerformanceStatsSnapshot(
+  host: TelemetryAccessorHost,
+): { lastEvalMs: number | undefined; lastEvolveMs: number | undefined; }
 ```
 
-Snapshot lineage metadata for the first `limit` genomes.
+Snapshot performance timings for evaluation and evolution steps.
 
-The accessor deliberately returns only `{ id, parents }` pairs. That keeps
-lineage snapshots lightweight enough for telemetry entries, tests, and quick
-debugging while still exposing the key teaching signal: which genomes share
-ancestry and how recent offspring connect back to parents.
+These timings are intentionally coarse. They are useful for telemetry reads,
+simple dashboards, and regression tests that need to know which phase was
+recently expensive, but they are not meant to replace a profiler trace.
 
 Parameters:
-- `population` - - Population slice containing optional runtime lineage metadata.
-- `limit` - - Maximum number of genomes to sample from the front of the population.
+- `host` - - Telemetry host storing the last evaluation and evolution durations.
 
-Returns: Compact lineage entries with genome ids and parent ids.
+Returns: Object containing the most recent evaluation and evolution timings.
 
 Example:
 
-const lineage = buildLineageSnapshot(neat.population, 5);
-console.log(lineage.map((entry) => entry.parents));
-
-### getCachedDiversityStats
-
-```ts
-getCachedDiversityStats(
-  host: TelemetryAccessorHost,
-): DiversityStats | undefined
-```
-
-Read cached diversity statistics.
-
-This accessor does not compute diversity on demand. Its job is only to expose
-the last cached snapshot so callers can distinguish between "no diversity has
-been computed yet" and "diversity was computed and here is the result."
-
-Parameters:
-- `host` - - Telemetry host exposing an optional cached diversity snapshot.
-
-Returns: Cached diversity statistics when available, otherwise `undefined`.
+const timings = getPerformanceStatsSnapshot(neat);
+console.log(timings.lastEvalMs, timings.lastEvolveMs);
 
-### getPerformanceStatsSnapshot
+### getTelemetryBuffer
 
 ```ts
-getPerformanceStatsSnapshot(
+getTelemetryBuffer(
   host: TelemetryAccessorHost,
-): { lastEvalMs: number | undefined; lastEvolveMs: number | undefined; }
+): TelemetryEntry[]
 ```
 
-Snapshot performance timings for evaluation and evolution steps.
+Return the telemetry buffer, defaulting to an empty array when missing.
 
-These timings are intentionally coarse. They are useful for telemetry reads,
-simple dashboards, and regression tests that need to know which phase was
-recently expensive, but they are not meant to replace a profiler trace.
+This is the lowest-level read for recent telemetry history. It gives callers
+a stable way to inspect the current in-memory buffer without forcing every
+consumer to reimplement null checks.
 
 Parameters:
-- `host` - - Telemetry host storing the last evaluation and evolution durations.
+- `host` - - Telemetry host that may or may not have initialized its buffer.
 
-Returns: Object containing the most recent evaluation and evolution timings.
+Returns: Telemetry entries recorded so far, or an empty array when telemetry
+has not been started yet.
 
 Example:
 
-const timings = getPerformanceStatsSnapshot(neat);
-console.log(timings.lastEvalMs, timings.lastEvolveMs);
+const recentEntries = getTelemetryBuffer(neat).slice(-3);
+console.log(recentEntries.length);
 
 ### LINEAGE_SNAPSHOT_DEFAULT_LIMIT