@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -43,207 +43,196 @@ test can inspect the recorded state without reaching into controller internals.
 
 ## neat/telemetry/facade/telemetry.facade.ts
 
-### getObjectiveKeys
+### clearParetoArchive
 
 ```ts
-getObjectiveKeys(
+clearParetoArchive(
   host: NeatTelemetryFacadeHost,
-): string[]
+): void
 ```
 
-Return just the registered objective keys in stable order.
+Clear the Pareto archive metadata stored on the host.
 
-This is the shortest inspection surface for tests and quick diagnostics that
-only need to confirm which objectives are active, not the full descriptor
-payload.
+Use this when multi-objective inspection should restart from a clean archive
+window, for example between experiments or before capturing a focused new
+frontier snapshot.
 
 Parameters:
-- `host` - - `Neat` instance exposing objective descriptors.
+- `host` - - `Neat` instance whose Pareto archive should be emptied.
 
-Returns: Ordered list of active objective keys.
+Returns: Nothing. The archive buffer is reset in place.
 
-### getTelemetry
+### clearTelemetry
 
 ```ts
-getTelemetry(
+clearTelemetry(
   host: NeatTelemetryFacadeHost,
-): TelemetryEntry[]
+): void
 ```
 
-Return the in-memory telemetry buffer.
+Clear cached telemetry entries.
 
-This is the fastest way to inspect the recent rhythm of a run: score trends,
-diversity changes, objective snapshots, and timing evidence exactly as they
-were recorded generation by generation.
+Use this when you want a fresh observation window without restarting the run.
+It is especially useful in notebooks, UI sessions, or targeted experiments
+where older telemetry would otherwise drown out the next few generations.
 
 Parameters:
-- `host` - - `Neat` instance storing generation telemetry snapshots.
-
-Returns: Telemetry entries captured so far, or an empty array when telemetry
-is not initialized.
-
-Example:
+- `host` - - `Neat` instance whose telemetry buffer should be reset.
 
-const telemetryWindow = getTelemetry(neat).slice(-5);
-console.table(telemetryWindow.map((entry) => ({
-  generation: entry.generation,
-  bestScore: entry.bestScore,
-  species: entry.species,
-})));
+Returns: Nothing. The helper mutates the host buffer in place.
 
-### exportTelemetryJSONL
+### clearTelemetryObjectives
 
 ```ts
-exportTelemetryJSONL(
+clearTelemetryObjectives(
   host: NeatTelemetryFacadeHost,
-): string
+): void
 ```
 
-Export telemetry as JSON Lines so logs can stream into files or post-processors.
+Remove all registered custom objectives so only the default objective path remains.
 
-JSONL is the most automation-friendly telemetry surface: one entry per line,
-easy to append to a file, easy to pipe into scripts, and stable enough for
-notebook or CLI post-processing.
+Read this as the reset companion to {@link registerTelemetryObjective}. It is
+useful when one inspection session temporarily added custom objectives and the
+caller wants to return the controller to its simpler baseline objective view.
 
 Parameters:
-- `host` - - `Neat` instance whose telemetry buffer should be serialized.
+- `host` - - `Neat` instance whose objective registry should be cleared.
 
-Returns: JSONL payload with one telemetry object per line.
+Returns: Nothing. The helper mutates the objective registry in place.
 
-### exportTelemetryCSV
+### exportParetoFrontJSONL
 
 ```ts
-exportTelemetryCSV(
+exportParetoFrontJSONL(
   host: NeatTelemetryFacadeHost,
-  maxEntries: number,
+  maxEntries: number | undefined,
 ): string
 ```
 
-Export recent telemetry entries as CSV for quick spreadsheet inspection.
+Export recent Pareto archive entries as JSON Lines.
 
-Prefer this when the reader is a person scanning a table instead of a script
-parsing nested JSON. The helper intentionally focuses on a recent window so a
-long run can still produce a compact worksheet.
+Use this when the archive needs to leave the controller for offline analysis,
+regression fixtures, or notebook-driven frontier inspection. Compared with
+`getParetoArchive()`, the emphasis here is portability rather than immediate
+in-memory inspection.
 
 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:
+- `host` - - `Neat` instance storing Pareto objective snapshots.
+- `maxEntries` - - Maximum number of entries to serialize.
 
-const csv = exportTelemetryCSV(neat, 100);
-console.log(csv.split('\n').slice(0, 3).join('\n'));
+Returns: JSONL payload for recent Pareto archive entries.
 
-### clearTelemetry
+### exportSpeciesHistoryCSV
 
 ```ts
-clearTelemetry(
+exportSpeciesHistoryCSV(
   host: NeatTelemetryFacadeHost,
-): void
+  maxEntries: number,
+): string
 ```
 
-Clear cached telemetry entries.
+Export species history as CSV rows.
 
-Use this when you want a fresh observation window without restarting the run.
-It is especially useful in notebooks, UI sessions, or targeted experiments
-where older telemetry would otherwise drown out the next few generations.
+Prefer this when the reader is a person first and a program second. CSV is
+the quickest path from species history into spreadsheets, ad-hoc inspection,
+or lightweight experiment notes.
 
 Parameters:
-- `host` - - `Neat` instance whose telemetry buffer should be reset.
+- `host` - - `Neat` instance whose species history should be exported.
+- `maxEntries` - - Maximum number of recent history entries to include.
 
-Returns: Nothing. The helper mutates the host buffer in place.
+Returns: CSV payload for offline species analysis.
 
-### getObjectives
+### exportSpeciesHistoryJSONL
 
 ```ts
-getObjectives(
+exportSpeciesHistoryJSONL(
   host: NeatTelemetryFacadeHost,
-): { key: string; direction: "max" | "min"; }[]
+  maxEntries: number,
+): string
 ```
 
-Return a compact view of active objective descriptors.
+Export species history as JSON Lines.
 
-The full objective descriptor includes accessors and internal metadata. This
-read model trims that down to the pieces most useful in UI surfaces and
-debugging output: the key and whether the objective is minimized or
-maximized.
+Prefer this when the next consumer is a script, notebook, or append-friendly
+file sink. JSONL keeps each generation independently parseable while still
+preserving the richer row structure that CSV flattens away.
 
 Parameters:
-- `host` - - `Neat` instance exposing objective descriptors.
-
-Returns: Compact objective summaries in evaluation order.
-
-Example:
+- `host` - - `Neat` instance whose species history should be serialized.
+- `maxEntries` - - Maximum number of recent history entries to include.
 
-const objectives = getObjectives(neat);
-console.table(objectives);
+Returns: JSONL payload describing recent species history snapshots.
 
-### registerTelemetryObjective
+### exportTelemetryCSV
 
 ```ts
-registerTelemetryObjective(
+exportTelemetryCSV(
   host: NeatTelemetryFacadeHost,
-  key: string,
-  direction: "max" | "min",
-  accessor: (genome: default) => number,
-): void
+  maxEntries: number,
+): string
 ```
 
-Register or replace a custom objective.
+Export recent telemetry entries as CSV for quick spreadsheet inspection.
 
-This is the facade's write-side escape hatch for objective inspection flows.
-Use it when a dashboard, script, or experiment wants the telemetry and
-archive surfaces to start tracking a new tradeoff dimension without dropping
-into the lower-level objective modules first.
+Prefer this when the reader is a person scanning a table instead of a script
+parsing nested JSON. The helper intentionally focuses on a recent window so a
+long run can still produce a compact worksheet.
 
 Parameters:
-- `host` - - `Neat` instance whose multi-objective registry should change.
-- `key` - - Unique objective key.
-- `direction` - - Whether lower or higher values are considered better.
-- `accessor` - - Function that reads the objective value from a genome.
+- `host` - - `Neat` instance whose telemetry buffer should be exported.
+- `maxEntries` - - Maximum number of recent entries to include.
 
-Returns: Nothing. The objective registry on `host` is updated in place.
+Returns: CSV string containing the requested telemetry window.
 
-### clearTelemetryObjectives
+Example:
+
+const csv = exportTelemetryCSV(neat, 100);
+console.log(csv.split('\n').slice(0, 3).join('\n'));
+
+### exportTelemetryJSONL
 
 ```ts
-clearTelemetryObjectives(
+exportTelemetryJSONL(
   host: NeatTelemetryFacadeHost,
-): void
+): string
 ```
 
-Remove all registered custom objectives so only the default objective path remains.
+Export telemetry as JSON Lines so logs can stream into files or post-processors.
 
-Read this as the reset companion to {@link registerTelemetryObjective}. It is
-useful when one inspection session temporarily added custom objectives and the
-caller wants to return the controller to its simpler baseline objective view.
+JSONL is the most automation-friendly telemetry surface: one entry per line,
+easy to append to a file, easy to pipe into scripts, and stable enough for
+notebook or CLI post-processing.
 
 Parameters:
-- `host` - - `Neat` instance whose objective registry should be cleared.
+- `host` - - `Neat` instance whose telemetry buffer should be serialized.
 
-Returns: Nothing. The helper mutates the objective registry in place.
+Returns: JSONL payload with one telemetry object per line.
 
-### getObjectiveEvents
+### getDiversityStats
 
 ```ts
-getObjectiveEvents(
+getDiversityStats(
   host: NeatTelemetryFacadeHost,
-): { gen: number; type: "add" | "remove"; key: string; }[]
+): DiversityStats
 ```
 
-Snapshot recent objective add/remove events for telemetry consumers.
+Return cached diversity metrics, computing a fallback snapshot when needed.
 
-This gives read-side tooling a lightweight history of objective churn without
-forcing it to replay the full controller lifecycle. Use it when the question
-is "when did the objective set change?" rather than "what are the active
-objectives right now?"
+This keeps the public facade resilient: callers can always ask for diversity
+stats even before a full metrics pass has run.
+The resulting snapshot is especially useful when you need to judge whether a
+run is still exploring many structural alternatives or converging too hard.
 
 Parameters:
-- `host` - - `Neat` instance storing objective lifecycle events.
+- `host` - - `Neat` instance exposing cached diversity state.
 
-Returns: Shallow copy of the recorded objective events.
+Returns: Diversity metrics for the current population.
+
+Example:
+
+const diversity = getDiversityStats(neat);
+console.log(diversity.structuralEntropy, diversity.uniqueStructures);
 
 ### getLineageSnapshot
 
@@ -270,136 +259,110 @@ Parameters:
 
 Returns: Array of `{ id, parents }` lineage entries.
 
-### exportSpeciesHistoryCSV
+### getMultiObjectiveMetrics
 
 ```ts
-exportSpeciesHistoryCSV(
+getMultiObjectiveMetrics(
   host: NeatTelemetryFacadeHost,
-  maxEntries: number,
-): string
+): { rank: number; crowding: number; score: number; nodes: number; connections: number; }[]
 ```
 
-Export species history as CSV rows.
+Build compact multi-objective metrics for the current population snapshot.
 
-Prefer this when the reader is a person first and a program second. CSV is
-the quickest path from species history into spreadsheets, ad-hoc inspection,
-or lightweight experiment notes.
+This helper is meant for inspection surfaces that need the shape of the
+current Pareto landscape without pulling every genome field into view.
+
+Read it as the facade's tradeoff-summary helper: enough information to see
+rank layers, crowding pressure, and rough structural size, but not so much
+detail that dashboards or quick diagnostics have to unpack whole genomes.
 
 Parameters:
-- `host` - - `Neat` instance whose species history should be exported.
-- `maxEntries` - - Maximum number of recent history entries to include.
+- `host` - - `Neat` instance whose population should be summarized.
 
-Returns: CSV payload for offline species analysis.
+Returns: Rank, crowding, score, and size metrics per genome.
 
-### exportSpeciesHistoryJSONL
+### getNoveltyArchiveSize
 
 ```ts
-exportSpeciesHistoryJSONL(
+getNoveltyArchiveSize(
   host: NeatTelemetryFacadeHost,
-  maxEntries: number,
-): string
+): number
 ```
 
-Export species history as JSON Lines.
+Return the current novelty archive size.
 
-Prefer this when the next consumer is a script, notebook, or append-friendly
-file sink. JSONL keeps each generation independently parseable while still
-preserving the richer row structure that CSV flattens away.
+This is the smallest novelty-health read in the facade. Use it when you do
+not need descriptor payloads, only a quick sense of whether novelty search is
+still collecting distinct behaviors or has gone quiet.
 
 Parameters:
-- `host` - - `Neat` instance whose species history should be serialized.
-- `maxEntries` - - Maximum number of recent history entries to include.
+- `host` - - `Neat` instance tracking novelty behavior descriptors.
 
-Returns: JSONL payload describing recent species history snapshots.
+Returns: Number of archived novelty descriptors.
 
-### getSpeciesStats
+### getObjectiveEvents
 
 ```ts
-getSpeciesStats(
+getObjectiveEvents(
   host: NeatTelemetryFacadeHost,
-): { id: number; size: number; bestScore: number; lastImproved: number; }[]
+): { gen: number; type: "add" | "remove"; key: string; }[]
 ```
 
-Return a concise summary for each current species.
+Snapshot recent objective add/remove events for telemetry consumers.
 
-This is the fastest species-level diagnostic when you want to see whether the
-population is still split across several improving families or collapsing
-toward one dominant cluster.
+This gives read-side tooling a lightweight history of objective churn without
+forcing it to replay the full controller lifecycle. Use it when the question
+is "when did the objective set change?" rather than "what are the active
+objectives right now?"
 
 Parameters:
-- `host` - - `Neat` instance whose live species registry should be summarized.
-
-Returns: Array of current species summaries.
-
-Example:
+- `host` - - `Neat` instance storing objective lifecycle events.
 
-const speciesSummary = getSpeciesStats(neat);
-console.table(speciesSummary);
+Returns: Shallow copy of the recorded objective events.
 
-### getSpeciesHistory
+### getObjectiveKeys
 
 ```ts
-getSpeciesHistory(
+getObjectiveKeys(
   host: NeatTelemetryFacadeHost,
-): SpeciesHistoryEntry[]
+): string[]
 ```
 
-Return recorded species history, lazily backfilling extended metrics when enabled.
+Return just the registered objective keys in stable order.
 
-Use this when you need the story across generations rather than the current
-snapshot. It is the better surface for plots, regressions, and post-run
-analysis of stagnation or speciation churn.
+This is the shortest inspection surface for tests and quick diagnostics that
+only need to confirm which objectives are active, not the full descriptor
+payload.
 
 Parameters:
-- `host` - - `Neat` instance storing species history snapshots.
-
-Returns: Historical species entries for each recorded generation.
-
-Example:
+- `host` - - `Neat` instance exposing objective descriptors.
 
-const historyWindow = getSpeciesHistory(neat).slice(-10);
-console.log(historyWindow.length);
+Returns: Ordered list of active objective keys.
 
-### getNoveltyArchiveSize
+### getObjectives
 
 ```ts
-getNoveltyArchiveSize(
+getObjectives(
   host: NeatTelemetryFacadeHost,
-): number
+): { key: string; direction: "max" | "min"; }[]
 ```
 
-Return the current novelty archive size.
+Return a compact view of active objective descriptors.
 
-This is the smallest novelty-health read in the facade. Use it when you do
-not need descriptor payloads, only a quick sense of whether novelty search is
-still collecting distinct behaviors or has gone quiet.
+The full objective descriptor includes accessors and internal metadata. This
+read model trims that down to the pieces most useful in UI surfaces and
+debugging output: the key and whether the objective is minimized or
+maximized.
 
 Parameters:
-- `host` - - `Neat` instance tracking novelty behavior descriptors.
-
-Returns: Number of archived novelty descriptors.
-
-### getMultiObjectiveMetrics
-
-```ts
-getMultiObjectiveMetrics(
-  host: NeatTelemetryFacadeHost,
-): { rank: number; crowding: number; score: number; nodes: number; connections: number; }[]
-```
-
-Build compact multi-objective metrics for the current population snapshot.
-
-This helper is meant for inspection surfaces that need the shape of the
-current Pareto landscape without pulling every genome field into view.
+- `host` - - `Neat` instance exposing objective descriptors.
 
-Read it as the facade's tradeoff-summary helper: enough information to see
-rank layers, crowding pressure, and rough structural size, but not so much
-detail that dashboards or quick diagnostics have to unpack whole genomes.
+Returns: Compact objective summaries in evaluation order.
 
-Parameters:
-- `host` - - `Neat` instance whose population should be summarized.
+Example:
 
-Returns: Rank, crowding, score, and size metrics per genome.
+const objectives = getObjectives(neat);
+console.table(objectives);
 
 ### getOperatorStats
 
@@ -420,27 +383,6 @@ Parameters:
 
 Returns: Operator summaries suitable for dashboards and debugging.
 
-### getParetoFronts
-
-```ts
-getParetoFronts(
-  host: NeatTelemetryFacadeHost,
-  maxFronts: number | undefined,
-): default[][]
-```
-
-Reconstruct Pareto fronts from current rank annotations.
-
-Use this when the question is structural rather than historical: which fronts
-exist right now, and how many genomes are sitting on each layer of the
-current tradeoff surface?
-
-Parameters:
-- `host` - - `Neat` instance whose population should be partitioned.
-- `maxFronts` - - Maximum number of fronts to reconstruct.
-
-Returns: Pareto fronts ordered from best to worst.
-
 ### getParetoArchive
 
 ```ts
@@ -463,27 +405,26 @@ Parameters:
 
 Returns: Slice of the recent Pareto archive.
 
-### exportParetoFrontJSONL
+### getParetoFronts
 
 ```ts
-exportParetoFrontJSONL(
+getParetoFronts(
   host: NeatTelemetryFacadeHost,
-  maxEntries: number | undefined,
-): string
+  maxFronts: number | undefined,
+): default[][]
 ```
 
-Export recent Pareto archive entries as JSON Lines.
+Reconstruct Pareto fronts from current rank annotations.
 
-Use this when the archive needs to leave the controller for offline analysis,
-regression fixtures, or notebook-driven frontier inspection. Compared with
-`getParetoArchive()`, the emphasis here is portability rather than immediate
-in-memory inspection.
+Use this when the question is structural rather than historical: which fronts
+exist right now, and how many genomes are sitting on each layer of the
+current tradeoff surface?
 
 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.
 
 ### getPerformanceStats
 
@@ -508,67 +449,82 @@ Example:
 const timing = getPerformanceStats(neat);
 console.log(timing.lastEvalMs, timing.lastEvolveMs);
 
-### getDiversityStats
+### getSpeciesHistory
 
 ```ts
-getDiversityStats(
+getSpeciesHistory(
   host: NeatTelemetryFacadeHost,
-): DiversityStats
+): SpeciesHistoryEntry[]
 ```
 
-Return cached diversity metrics, computing a fallback snapshot when needed.
+Return recorded species history, lazily backfilling extended metrics when enabled.
 
-This keeps the public facade resilient: callers can always ask for diversity
-stats even before a full metrics pass has run.
-The resulting snapshot is especially useful when you need to judge whether a
-run is still exploring many structural alternatives or converging too hard.
+Use this when you need the story across generations rather than the current
+snapshot. It is the better surface for plots, regressions, and post-run
+analysis of stagnation or speciation churn.
 
 Parameters:
-- `host` - - `Neat` instance exposing cached diversity state.
+- `host` - - `Neat` instance storing species history snapshots.
 
-Returns: Diversity metrics for the current population.
+Returns: Historical species entries for each recorded generation.
 
 Example:
 
-const diversity = getDiversityStats(neat);
-console.log(diversity.structuralEntropy, diversity.uniqueStructures);
+const historyWindow = getSpeciesHistory(neat).slice(-10);
+console.log(historyWindow.length);
 
-### resetNoveltyArchive
+### getSpeciesStats
 
 ```ts
-resetNoveltyArchive(
+getSpeciesStats(
   host: NeatTelemetryFacadeHost,
-): void
+): { id: number; size: number; bestScore: number; lastImproved: number; }[]
 ```
 
-Clear the novelty archive.
+Return a concise summary for each current species.
 
-This is useful when a caller wants to restart the novelty observation window
-without also resetting the rest of telemetry or the broader controller state.
+This is the fastest species-level diagnostic when you want to see whether the
+population is still split across several improving families or collapsing
+toward one dominant cluster.
 
 Parameters:
-- `host` - - `Neat` instance whose novelty archive should be reset.
+- `host` - - `Neat` instance whose live species registry should be summarized.
 
-Returns: Nothing. The archive is mutated in place.
+Returns: Array of current species summaries.
 
-### clearParetoArchive
+Example:
+
+const speciesSummary = getSpeciesStats(neat);
+console.table(speciesSummary);
+
+### getTelemetry
 
 ```ts
-clearParetoArchive(
+getTelemetry(
   host: NeatTelemetryFacadeHost,
-): void
+): TelemetryEntry[]
 ```
 
-Clear the Pareto archive metadata stored on the host.
+Return the in-memory telemetry buffer.
 
-Use this when multi-objective inspection should restart from a clean archive
-window, for example between experiments or before capturing a focused new
-frontier snapshot.
+This is the fastest way to inspect the recent rhythm of a run: score trends,
+diversity changes, objective snapshots, and timing evidence exactly as they
+were recorded generation by generation.
 
 Parameters:
-- `host` - - `Neat` instance whose Pareto archive should be emptied.
+- `host` - - `Neat` instance storing generation telemetry snapshots.
 
-Returns: Nothing. The archive buffer is reset in place.
+Returns: Telemetry entries captured so far, or an empty array when telemetry
+is not initialized.
+
+Example:
+
+const telemetryWindow = getTelemetry(neat).slice(-5);
+console.table(telemetryWindow.map((entry) => ({
+  generation: entry.generation,
+  bestScore: entry.bestScore,
+  species: entry.species,
+})));
 
 ### NeatTelemetryFacadeHost
 
@@ -580,3 +536,47 @@ read-heavy diagnostics and export helpers into one focused module without
 exposing the entire controller implementation. The host shape keeps the
 contract small: population snapshots, telemetry caches, objective accessors,
 and archive buffers.
+
+### registerTelemetryObjective
+
+```ts
+registerTelemetryObjective(
+  host: NeatTelemetryFacadeHost,
+  key: string,
+  direction: "max" | "min",
+  accessor: (genome: default) => number,
+): void
+```
+
+Register or replace a custom objective.
+
+This is the facade's write-side escape hatch for objective inspection flows.
+Use it when a dashboard, script, or experiment wants the telemetry and
+archive surfaces to start tracking a new tradeoff dimension without dropping
+into the lower-level objective modules first.
+
+Parameters:
+- `host` - - `Neat` instance whose multi-objective registry should change.
+- `key` - - Unique objective key.
+- `direction` - - Whether lower or higher values are considered better.
+- `accessor` - - Function that reads the objective value from a genome.
+
+Returns: Nothing. The objective registry on `host` is updated in place.
+
+### resetNoveltyArchive
+
+```ts
+resetNoveltyArchive(
+  host: NeatTelemetryFacadeHost,
+): void
+```
+
+Clear the novelty archive.
+
+This is useful when a caller wants to restart the novelty observation window
+without also resetting the rest of telemetry or the broader controller state.
+
+Parameters:
+- `host` - - `Neat` instance whose novelty archive should be reset.
+
+Returns: Nothing. The archive is mutated in place.