@reicek/neataptic-ts 0.1.25 → 0.1.26

package/src/neat/telemetry/facade/archive/README.md

@@ -30,60 +30,76 @@ flowchart TD
 
 ## neat/telemetry/facade/archive/telemetry.facade.archive.ts
 
-### getMultiObjectiveMetrics
+### clearParetoArchive
 
 ```ts
-getMultiObjectiveMetrics(
+clearParetoArchive(
   host: TelemetryFacadeArchiveHost,
-): { rank: number; crowding: number; score: number; nodes: number; connections: number; }[]
+): void
 ```
 
-Build compact multi-objective metrics for the current population snapshot.
+Clear the Pareto archive metadata stored on the host.
 
-This chapter keeps the highest-level Pareto inspection helpers together so a
-caller can move from per-genome rank summaries to reconstructed fronts and
-archived vectors without leaving the same conceptual boundary.
+Reach for this when a caller wants a fresh archive observation window
+without resetting the rest of the telemetry system.
 
 Parameters:
-- `host` - - `Neat` instance whose population should be summarized.
+- `host` - - `Neat` instance whose Pareto archive should be emptied.
 
-Returns: Rank, crowding, score, and size metrics per genome.
+Returns: Nothing. The archive buffer is reset in place.
+
+### exportParetoFrontJSONL
+
+```ts
+exportParetoFrontJSONL(
+  host: TelemetryFacadeArchiveHost,
+  maxEntries: number,
+): string
+```
+
+Export recent Pareto archive entries as JSON Lines.
+
+Prefer this when archive inspection is leaving the process boundary. JSONL is
+easy to append to files, load into notebooks, or post-process with simple
+scripts while preserving one archived snapshot per line.
+
+Parameters:
+- `host` - - `Neat` instance storing Pareto objective snapshots.
+- `maxEntries` - - Maximum number of entries to serialize.
+
+Returns: JSONL payload for recent Pareto archive entries.
 
 Example:
 
 ```ts
-const metrics = getMultiObjectiveMetrics(neat);
-console.table(metrics.slice(0, 5));
+const archiveJsonl = exportParetoFrontJSONL(neat, 100);
+console.log(archiveJsonl.split('\n').at(0));
 ```
 
-### getParetoFronts
+### getMultiObjectiveMetrics
 
 ```ts
-getParetoFronts(
+getMultiObjectiveMetrics(
   host: TelemetryFacadeArchiveHost,
-  maxFronts: number,
-): default[][]
+): { rank: number; crowding: number; score: number; nodes: number; connections: number; }[]
 ```
 
-Reconstruct Pareto fronts from current rank annotations.
+Build compact multi-objective metrics for the current population snapshot.
 
-Use this when you want the live frontier grouping itself rather than a flat
-metrics table. The helper rebuilds the front structure from the population's
-current multi-objective annotations, which makes it useful for dashboards,
-tests, or teaching material that needs to show how genomes separate into
-dominance layers.
+This chapter keeps the highest-level Pareto inspection helpers together so a
+caller can move from per-genome rank summaries to reconstructed fronts and
+archived vectors without leaving the same conceptual boundary.
 
 Parameters:
-- `host` - - `Neat` instance whose population should be partitioned.
-- `maxFronts` - - Maximum number of fronts to reconstruct.
+- `host` - - `Neat` instance whose population should be summarized.
 
-Returns: Pareto fronts ordered from best to worst.
+Returns: Rank, crowding, score, and size metrics per genome.
 
 Example:
 
 ```ts
-const fronts = getParetoFronts(neat, 3);
-console.log(fronts.map((front) => front.length));
+const metrics = getMultiObjectiveMetrics(neat);
+console.table(metrics.slice(0, 5));
 ```
 
 ### getParetoArchive
@@ -114,52 +130,36 @@ const recentArchive = getParetoArchive(neat, 25);
 console.log(recentArchive.length);
 ```
 
-### exportParetoFrontJSONL
+### getParetoFronts
 
 ```ts
-exportParetoFrontJSONL(
+getParetoFronts(
   host: TelemetryFacadeArchiveHost,
-  maxEntries: number,
-): string
+  maxFronts: number,
+): default[][]
 ```
 
-Export recent Pareto archive entries as JSON Lines.
+Reconstruct Pareto fronts from current rank annotations.
 
-Prefer this when archive inspection is leaving the process boundary. JSONL is
-easy to append to files, load into notebooks, or post-process with simple
-scripts while preserving one archived snapshot per line.
+Use this when you want the live frontier grouping itself rather than a flat
+metrics table. The helper rebuilds the front structure from the population's
+current multi-objective annotations, which makes it useful for dashboards,
+tests, or teaching material that needs to show how genomes separate into
+dominance layers.
 
 Parameters:
-- `host` - - `Neat` instance storing Pareto objective snapshots.
-- `maxEntries` - - Maximum number of entries to serialize.
+- `host` - - `Neat` instance whose population should be partitioned.
+- `maxFronts` - - Maximum number of fronts to reconstruct.
 
-Returns: JSONL payload for recent Pareto archive entries.
+Returns: Pareto fronts ordered from best to worst.
 
 Example:
 
 ```ts
-const archiveJsonl = exportParetoFrontJSONL(neat, 100);
-console.log(archiveJsonl.split('\n').at(0));
-```
-
-### clearParetoArchive
-
-```ts
-clearParetoArchive(
-  host: TelemetryFacadeArchiveHost,
-): void
+const fronts = getParetoFronts(neat, 3);
+console.log(fronts.map((front) => front.length));
 ```
 
-Clear the Pareto archive metadata stored on the host.
-
-Reach for this when a caller wants a fresh archive observation window
-without resetting the rest of the telemetry system.
-
-Parameters:
-- `host` - - `Neat` instance whose Pareto archive should be emptied.
-
-Returns: Nothing. The archive buffer is reset in place.
-
 ### TelemetryFacadeArchiveHost
 
 Narrow telemetry-facade host surface required by the archive chapter.

package/src/neat/telemetry/facade/buffer/README.md

@@ -29,31 +29,50 @@ flowchart TD
 
 ## neat/telemetry/facade/buffer/telemetry.facade.buffer.ts
 
-### getTelemetry
+### clearTelemetry
 
 ```ts
-getTelemetry(
+clearTelemetry(
   host: TelemetryFacadeBufferHost,
-): TelemetryEntry[]
+): void
 ```
 
-Return the in-memory telemetry buffer.
+Clear cached telemetry entries.
 
-This chapter groups the lowest-level telemetry reads with the export helpers
-so callers can treat "inspect the buffer" and "serialize the buffer" as one
-concept cluster inside the broader telemetry facade.
+Reach for this when you want a fresh telemetry observation window between
+experiment phases without rebuilding the rest of the controller.
 
 Parameters:
-- `host` - - `Neat` instance storing generation telemetry snapshots.
+- `host` - - `Neat` instance whose telemetry buffer should be reset.
 
-Returns: Telemetry entries captured so far, or an empty array when telemetry
-is not initialized.
+Returns: Nothing. The helper mutates the host buffer in place.
+
+### exportTelemetryCSV
+
+```ts
+exportTelemetryCSV(
+  host: TelemetryFacadeBufferHost,
+  maxEntries: number,
+): string
+```
+
+Export recent telemetry entries as CSV for quick spreadsheet inspection.
+
+Use this when the consumer is a person first. CSV makes it easy to open a
+recent telemetry window in a spreadsheet or quick table view without having
+to parse nested JSON structures.
+
+Parameters:
+- `host` - - `Neat` instance whose telemetry buffer should be exported.
+- `maxEntries` - - Maximum number of recent entries to include.
+
+Returns: CSV string containing the requested telemetry window.
 
 Example:
 
 ```ts
-const recentTelemetry = getTelemetry(neat);
-console.log(recentTelemetry.at(-1)?.gen);
+const csv = exportTelemetryCSV(neat, 100);
+console.log(csv.split('\n').slice(0, 3).join('\n'));
 ```
 
 ### exportTelemetryJSONL
@@ -82,52 +101,33 @@ const jsonl = exportTelemetryJSONL(neat);
 console.log(jsonl.split('\n').at(0));
 ```
 
-### exportTelemetryCSV
+### getTelemetry
 
 ```ts
-exportTelemetryCSV(
+getTelemetry(
   host: TelemetryFacadeBufferHost,
-  maxEntries: number,
-): string
+): TelemetryEntry[]
 ```
 
-Export recent telemetry entries as CSV for quick spreadsheet inspection.
+Return the in-memory telemetry buffer.
 
-Use this when the consumer is a person first. CSV makes it easy to open a
-recent telemetry window in a spreadsheet or quick table view without having
-to parse nested JSON structures.
+This chapter groups the lowest-level telemetry reads with the export helpers
+so callers can treat "inspect the buffer" and "serialize the buffer" as one
+concept cluster inside the broader telemetry facade.
 
 Parameters:
-- `host` - - `Neat` instance whose telemetry buffer should be exported.
-- `maxEntries` - - Maximum number of recent entries to include.
+- `host` - - `Neat` instance storing generation telemetry snapshots.
 
-Returns: CSV string containing the requested telemetry window.
+Returns: Telemetry entries captured so far, or an empty array when telemetry
+is not initialized.
 
 Example:
 
 ```ts
-const csv = exportTelemetryCSV(neat, 100);
-console.log(csv.split('\n').slice(0, 3).join('\n'));
-```
-
-### clearTelemetry
-
-```ts
-clearTelemetry(
-  host: TelemetryFacadeBufferHost,
-): void
+const recentTelemetry = getTelemetry(neat);
+console.log(recentTelemetry.at(-1)?.gen);
 ```
 
-Clear cached telemetry entries.
-
-Reach for this when you want a fresh telemetry observation window between
-experiment phases without rebuilding the rest of the controller.
-
-Parameters:
-- `host` - - `Neat` instance whose telemetry buffer should be reset.
-
-Returns: Nothing. The helper mutates the host buffer in place.
-
 ### TelemetryFacadeBufferHost
 
 Narrow telemetry-facade host surface required by the buffer/export chapter.

package/src/neat/telemetry/facade/lineage/README.md

@@ -58,14 +58,14 @@ const lineageSnapshot = getLineageSnapshot(neat);
 console.log(lineageSnapshot.at(-1)?.parents);
 ```
 
-### TelemetryLineageSnapshotEntry
+### LINEAGE_SNAPSHOT_DEFAULT_LIMIT
 
-Compact lineage entry exposed by the telemetry facade.
+Default limit for lineage snapshots to avoid large payloads.
 
-This read model stays intentionally small so inspection helpers can show
-immediate ancestry without exporting full genealogy trees.
-It is meant to answer "who were this genome's parents?" quickly, not to
-preserve every lineage annotation the deeper lineage subsystem may track.
+The lineage view is meant for inspection, tests, and compact summaries, not
+for exporting the full ancestry of every genome in a large population. This
+default keeps snapshots small enough to log or render quickly while still
+showing inheritance patterns near the front of the population.
 
 ### TelemetryFacadeLineageHost
 
@@ -77,11 +77,11 @@ That narrowness is deliberate: the telemetry facade only needs enough data
 to build a compact current snapshot, not the broader history and policy
 state owned by the full lineage subsystem.
 
-### LINEAGE_SNAPSHOT_DEFAULT_LIMIT
+### TelemetryLineageSnapshotEntry
 
-Default limit for lineage snapshots to avoid large payloads.
+Compact lineage entry exposed by the telemetry facade.
 
-The lineage view is meant for inspection, tests, and compact summaries, not
-for exporting the full ancestry of every genome in a large population. This
-default keeps snapshots small enough to log or render quickly while still
-showing inheritance patterns near the front of the population.
+This read model stays intentionally small so inspection helpers can show
+immediate ancestry without exporting full genealogy trees.
+It is meant to answer "who were this genome's parents?" quickly, not to
+preserve every lineage annotation the deeper lineage subsystem may track.

package/src/neat/telemetry/facade/objectives/README.md

@@ -28,6 +28,50 @@ flowchart TD
 
 ## neat/telemetry/facade/objectives/telemetry.facade.objectives.ts
 
+### clearTelemetryObjectives
+
+```ts
+clearTelemetryObjectives(
+  host: TelemetryFacadeObjectivesHost,
+): void
+```
+
+Remove all registered custom objectives so only the default objective path remains.
+
+Reach for this when an experiment wants to reset the objective surface to its
+baseline state without rebuilding the whole controller.
+
+Parameters:
+- `host` - - `Neat` instance whose objective registry should be cleared.
+
+Returns: Nothing. The helper mutates the objective registry in place.
+
+### getObjectiveEvents
+
+```ts
+getObjectiveEvents(
+  host: TelemetryFacadeObjectivesHost,
+): { gen: number; type: "add" | "remove"; key: string; }[]
+```
+
+Snapshot recent objective add/remove events for telemetry consumers.
+
+This is the historical companion to {@link getObjectives}. The descriptor
+summary tells you what is active now; the event log tells you how the active
+set changed across recent generations.
+
+Parameters:
+- `host` - - `Neat` instance storing objective lifecycle events.
+
+Returns: Shallow copy of the recorded objective events.
+
+Example:
+
+```ts
+const recentEvents = getObjectiveEvents(neat);
+console.log(recentEvents.at(-1));
+```
+
 ### getObjectiveKeys
 
 ```ts
@@ -104,50 +148,6 @@ Parameters:
 
 Returns: Nothing. The objective registry on `host` is updated in place.
 
-### clearTelemetryObjectives
-
-```ts
-clearTelemetryObjectives(
-  host: TelemetryFacadeObjectivesHost,
-): void
-```
-
-Remove all registered custom objectives so only the default objective path remains.
-
-Reach for this when an experiment wants to reset the objective surface to its
-baseline state without rebuilding the whole controller.
-
-Parameters:
-- `host` - - `Neat` instance whose objective registry should be cleared.
-
-Returns: Nothing. The helper mutates the objective registry in place.
-
-### getObjectiveEvents
-
-```ts
-getObjectiveEvents(
-  host: TelemetryFacadeObjectivesHost,
-): { gen: number; type: "add" | "remove"; key: string; }[]
-```
-
-Snapshot recent objective add/remove events for telemetry consumers.
-
-This is the historical companion to {@link getObjectives}. The descriptor
-summary tells you what is active now; the event log tells you how the active
-set changed across recent generations.
-
-Parameters:
-- `host` - - `Neat` instance storing objective lifecycle events.
-
-Returns: Shallow copy of the recorded objective events.
-
-Example:
-
-```ts
-const recentEvents = getObjectiveEvents(neat);
-console.log(recentEvents.at(-1));
-```
-
 ### TelemetryFacadeObjectivesHost
 
 Narrow telemetry-facade host surface required by the objectives chapter.

package/src/neat/telemetry/facade/runtime/README.md

@@ -26,32 +26,6 @@ flowchart TD
 
 ## neat/telemetry/facade/runtime/telemetry.facade.runtime.ts
 
-### getPerformanceStats
-
-```ts
-getPerformanceStats(
-  host: TelemetryFacadeRuntimeHost,
-): { lastEvalMs: number | undefined; lastEvolveMs: number | undefined; }
-```
-
-Return coarse timing metrics for the last evaluation and evolution passes.
-
-Keeping this beside the diversity snapshot helper makes the runtime chapter a
-compact place to inspect the latest controller-health signals without mixing
-them with lineage, species, or archive reads.
-
-Parameters:
-- `host` - - `Neat` instance tracking performance timings.
-
-Returns: Snapshot of the last evaluation and evolution durations.
-
-Example:
-
-```ts
-const performance = getPerformanceStats(neat);
-console.log(performance.lastEvalMs, performance.lastEvolveMs);
-```
-
 ### getDiversityStats
 
 ```ts
@@ -83,6 +57,32 @@ const diversity = getDiversityStats(neat);
 console.log(diversity.population, diversity.meanCompat);
 ```
 
+### getPerformanceStats
+
+```ts
+getPerformanceStats(
+  host: TelemetryFacadeRuntimeHost,
+): { lastEvalMs: number | undefined; lastEvolveMs: number | undefined; }
+```
+
+Return coarse timing metrics for the last evaluation and evolution passes.
+
+Keeping this beside the diversity snapshot helper makes the runtime chapter a
+compact place to inspect the latest controller-health signals without mixing
+them with lineage, species, or archive reads.
+
+Parameters:
+- `host` - - `Neat` instance tracking performance timings.
+
+Returns: Snapshot of the last evaluation and evolution durations.
+
+Example:
+
+```ts
+const performance = getPerformanceStats(neat);
+console.log(performance.lastEvalMs, performance.lastEvolveMs);
+```
+
 ### TelemetryFacadeRuntimeHost
 
 Narrow telemetry-facade host surface required by the runtime-metrics chapter.

package/src/neat/telemetry/facade/species/README.md

@@ -91,33 +91,6 @@ const jsonl = exportSpeciesHistoryJSONL(neat, 50);
 console.log(jsonl.split('\n').at(0));
 ```
 
-### getSpeciesStats
-
-```ts
-getSpeciesStats(
-  host: TelemetryFacadeSpeciesHost,
-): { id: number; size: number; bestScore: number; lastImproved: number; }[]
-```
-
-Return a concise summary for each current species.
-
-This is the "what does the roster look like right now?" read path.
-Reach for it when you want dashboard-friendly state such as current species
-sizes, best scores, and recent improvement markers without paying for the
-heavier historical buffer.
-
-Parameters:
-- `host` - - `Neat` instance whose live species registry should be summarized.
-
-Returns: Array of current species summaries.
-
-Example:
-
-```ts
-const speciesStats = getSpeciesStats(neat);
-console.table(speciesStats);
-```
-
 ### getSpeciesHistory
 
 ```ts
@@ -149,6 +122,33 @@ const speciesHistory = getSpeciesHistory(neat);
 console.log(speciesHistory.at(-1));
 ```
 
+### getSpeciesStats
+
+```ts
+getSpeciesStats(
+  host: TelemetryFacadeSpeciesHost,
+): { id: number; size: number; bestScore: number; lastImproved: number; }[]
+```
+
+Return a concise summary for each current species.
+
+This is the "what does the roster look like right now?" read path.
+Reach for it when you want dashboard-friendly state such as current species
+sizes, best scores, and recent improvement markers without paying for the
+heavier historical buffer.
+
+Parameters:
+- `host` - - `Neat` instance whose live species registry should be summarized.
+
+Returns: Array of current species summaries.
+
+Example:
+
+```ts
+const speciesStats = getSpeciesStats(neat);
+console.table(speciesStats);
+```
+
 ### TelemetryFacadeSpeciesHost
 
 Narrow telemetry-facade host surface required by the species chapter.