@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -52,101 +52,94 @@ flowchart LR
 
 ## neat/telemetry/exports/telemetry.exports.ts
 
-### exportTelemetryJSONL
+### buildSpeciesHistoryCsv
 
 ```ts
-exportTelemetryJSONL(): string
+buildSpeciesHistoryCsv(
+  recentHistory: SpeciesHistoryEntry[],
+  headers: string[],
+): string
 ```
 
-Serialize telemetry as JSON Lines for stream-friendly log exports.
-
-JSONL keeps the export path almost lossless: each telemetry entry is emitted
-as one JSON object on one line, which makes the format easy to append to a
-file, stream through command-line tools, or reload in notebook code without
-flattening nested structures first.
+Build the full CSV string for species history entries.
 
-Parameters:
-- `this` - - Neat instance exposing the internal telemetry buffer.
+Species history exports are row-expanded: each generation snapshot can produce
+multiple rows, one for each species stat recorded inside that generation. The
+helper therefore writes a single shared header line and then flattens the
+nested history structure into one CSV row per species snapshot.
 
-Returns: JSONL payload with one telemetry object per line.
+The important teaching point is that species history is not a one-row-per-
+generation export. A generation can contain several contemporaneous species,
+so the serializer preserves that multiplicity instead of forcing species data
+into one over-packed cell.
 
-Example:
+Parameters:
+- `recentHistory` - - History entries to export.
+- `headers` - - Ordered headers for the export window.
 
-```ts
-const jsonl = exportTelemetryJSONL.call(neat);
-console.log(jsonl.split('\n').length);
-```
+Returns: Complete CSV payload.
 
-### exportTelemetryCSV
+### buildTelemetryHeaders
 
 ```ts
-exportTelemetryCSV(
-  maxEntries: number,
-): string
+buildTelemetryHeaders(
+  info: TelemetryHeaderInfo,
+): string[]
 ```
 
-Export recent telemetry entries to a CSV string.
-
-This is the human-scanning export path. Instead of preserving the exact
-object graph like JSONL does, it discovers a stable column set across the
-sampled window and then flattens grouped metrics into prefixed columns.
+Build the ordered header list for telemetry CSV output.
 
-Flattening rules:
-- nested `complexity`, `perf`, `lineage`, and selected `diversity` fields
-  become `group.key` columns,
-- optional arrays and maps are serialized as JSON cells only when present in
-  the sampled window,
-- the most recent `maxEntries` records are exported to keep output bounded.
+Once discovery is complete, this helper turns the collected key sets into the
+final column order. Group prefixes such as `complexity.` and `perf.` preserve
+meaning after flattening so spreadsheet readers can still tell which runtime
+family a value came from.
 
-Use this path when the reader question is comparative rather than archival:
-you want to sort, filter, chart, or diff recent runtime behavior in a tool
-that understands rows and columns better than nested objects.
+The output order is intentionally grouped rather than purely alphabetical. It
+keeps top-level run facts first, then nested metric families, then sparse
+optional payload columns that behave more like attachments.
 
 Parameters:
-- `this` - - Neat instance exposing the internal telemetry buffer.
-- `maxEntries` - - Maximum number of recent telemetry rows to include.
+- `info` - - Collected header discovery state.
 
-Returns: CSV string containing headers plus one row per exported entry.
+Returns: Ordered header names used for serialization.
 
-Example:
+### collectTelemetryHeaderInfo
 
 ```ts
-const csv = exportTelemetryCSV.call(neat, 50);
-console.log(csv.split('\n')[0]);
+collectTelemetryHeaderInfo(
+  entries: TelemetryEntry[],
+): TelemetryHeaderInfo
 ```
 
-### exportSpeciesHistoryCSV
+Collect header metadata from the sampled telemetry entries.
 
-```ts
-exportSpeciesHistoryCSV(
-  maxEntries: number,
-): string
-```
+This is the discovery pass that makes CSV exports deterministic. Instead of
+assuming every telemetry entry has the same shape, the helper scans the
+window first and records which base fields, grouped metrics, and optional
+columns actually appear anywhere in the sample.
 
-Export species history snapshots to CSV.
+Conceptually, this is where an irregular event stream becomes a table plan.
+The rest of the CSV path is simpler because this helper commits to one export
+shape before row serialization starts.
 
-The exporter preserves runtime-added species stat fields by discovering the
-union of keys across the requested history window. When history has not been
-recorded yet but live species data exists, the helper synthesizes a minimal
-snapshot so early-run CSV exports remain deterministic.
+Parameters:
+- `entries` - - Telemetry entries included in the export window.
 
-This is the most timeline-oriented export in the chapter. Instead of one row
-per telemetry entry, it expands each generation snapshot into one row per
-species so a reader can inspect turnover, stagnation, and size changes with
-ordinary tabular tools.
+Returns: Flattened header discovery state.
 
-Parameters:
-- `this` - - Neat instance exposing species history and optional live species.
-- `maxEntries` - - Maximum number of recent history snapshots to include.
+### DEFAULT_SPECIES_BEST_SCORE
 
-Returns: CSV payload describing one species row per generation snapshot.
+Default fallback best score when a synthesized history row lacks a score.
 
-Example:
+This preserves a numeric best-score column even when the runtime only has a
+minimally reconstructed species snapshot.
 
-```ts
-const csv = exportSpeciesHistoryCSV.call(neat, 25);
-console.log(csv.split('\n').slice(0, 2).join('\n'));
-```
+### DEFAULT_SPECIES_HISTORY_GENERATION
+
+Default fallback generation used when backfilling an early species snapshot.
+
+The synthetic row still prefers the controller's live generation when it is
+available. This constant is the final floor for partially initialized hosts.
 
 ### DEFAULT_SPECIES_HISTORY_MAX_ENTRIES
 
@@ -167,6 +160,14 @@ Default fallback species id when a synthesized history row lacks an id.
 This only appears in the synthetic early-history path where live species
 exist but a formal history snapshot has not been archived yet.
 
+### DEFAULT_SPECIES_LAST_IMPROVED
+
+Default fallback last-improved generation when a synthesized row lacks one.
+
+A neutral default keeps the CSV shape deterministic without pretending the
+exporter knows more improvement history than the controller has actually
+recorded.
+
 ### DEFAULT_SPECIES_SIZE
 
 Default fallback species size when a synthesized history row lacks a size.
@@ -175,84 +176,101 @@ The exporter prefers an explicit neutral size over leaving the cell absent so
 spreadsheets and notebooks can still treat the backfilled row as a stable
 member of the same column contract.
 
-### DEFAULT_SPECIES_BEST_SCORE
-
-Default fallback best score when a synthesized history row lacks a score.
-
-This preserves a numeric best-score column even when the runtime only has a
-minimally reconstructed species snapshot.
-
-### DEFAULT_SPECIES_LAST_IMPROVED
+### exportSpeciesHistoryCSV
 
-Default fallback last-improved generation when a synthesized row lacks one.
+```ts
+exportSpeciesHistoryCSV(
+  maxEntries: number,
+): string
+```
 
-A neutral default keeps the CSV shape deterministic without pretending the
-exporter knows more improvement history than the controller has actually
-recorded.
+Export species history snapshots to CSV.
 
-### DEFAULT_SPECIES_HISTORY_GENERATION
+The exporter preserves runtime-added species stat fields by discovering the
+union of keys across the requested history window. When history has not been
+recorded yet but live species data exists, the helper synthesizes a minimal
+snapshot so early-run CSV exports remain deterministic.
 
-Default fallback generation used when backfilling an early species snapshot.
+This is the most timeline-oriented export in the chapter. Instead of one row
+per telemetry entry, it expands each generation snapshot into one row per
+species so a reader can inspect turnover, stagnation, and size changes with
+ordinary tabular tools.
 
-The synthetic row still prefers the controller's live generation when it is
-available. This constant is the final floor for partially initialized hosts.
+Parameters:
+- `this` - - Neat instance exposing species history and optional live species.
+- `maxEntries` - - Maximum number of recent history snapshots to include.
 
-### TelemetryHeaderInfo
+Returns: CSV payload describing one species row per generation snapshot.
 
-Shape describing collected telemetry header discovery info.
+Example:
 
-Think of this as the temporary export blueprint for one CSV window. Before a
-telemetry entry can be flattened into cells, the exporter needs to know which
-top-level fields exist, which nested metric groups need prefixed columns, and
-which optional arrays or maps appeared anywhere in the sampled window.
+```ts
+const csv = exportSpeciesHistoryCSV.call(neat, 25);
+console.log(csv.split('\n').slice(0, 2).join('\n'));
+```
 
-### collectTelemetryHeaderInfo
+### exportTelemetryCSV
 
 ```ts
-collectTelemetryHeaderInfo(
-  entries: TelemetryEntry[],
-): TelemetryHeaderInfo
+exportTelemetryCSV(
+  maxEntries: number,
+): string
 ```
 
-Collect header metadata from the sampled telemetry entries.
+Export recent telemetry entries to a CSV string.
 
-This is the discovery pass that makes CSV exports deterministic. Instead of
-assuming every telemetry entry has the same shape, the helper scans the
-window first and records which base fields, grouped metrics, and optional
-columns actually appear anywhere in the sample.
+This is the human-scanning export path. Instead of preserving the exact
+object graph like JSONL does, it discovers a stable column set across the
+sampled window and then flattens grouped metrics into prefixed columns.
 
-Conceptually, this is where an irregular event stream becomes a table plan.
-The rest of the CSV path is simpler because this helper commits to one export
-shape before row serialization starts.
+Flattening rules:
+- nested `complexity`, `perf`, `lineage`, and selected `diversity` fields
+  become `group.key` columns,
+- optional arrays and maps are serialized as JSON cells only when present in
+  the sampled window,
+- the most recent `maxEntries` records are exported to keep output bounded.
+
+Use this path when the reader question is comparative rather than archival:
+you want to sort, filter, chart, or diff recent runtime behavior in a tool
+that understands rows and columns better than nested objects.
 
 Parameters:
-- `entries` - - Telemetry entries included in the export window.
+- `this` - - Neat instance exposing the internal telemetry buffer.
+- `maxEntries` - - Maximum number of recent telemetry rows to include.
 
-Returns: Flattened header discovery state.
+Returns: CSV string containing headers plus one row per exported entry.
 
-### buildTelemetryHeaders
+Example:
 
 ```ts
-buildTelemetryHeaders(
-  info: TelemetryHeaderInfo,
-): string[]
+const csv = exportTelemetryCSV.call(neat, 50);
+console.log(csv.split('\n')[0]);
 ```
 
-Build the ordered header list for telemetry CSV output.
+### exportTelemetryJSONL
 
-Once discovery is complete, this helper turns the collected key sets into the
-final column order. Group prefixes such as `complexity.` and `perf.` preserve
-meaning after flattening so spreadsheet readers can still tell which runtime
-family a value came from.
+```ts
+exportTelemetryJSONL(): string
+```
 
-The output order is intentionally grouped rather than purely alphabetical. It
-keeps top-level run facts first, then nested metric families, then sparse
-optional payload columns that behave more like attachments.
+Serialize telemetry as JSON Lines for stream-friendly log exports.
+
+JSONL keeps the export path almost lossless: each telemetry entry is emitted
+as one JSON object on one line, which makes the format easy to append to a
+file, stream through command-line tools, or reload in notebook code without
+flattening nested structures first.
 
 Parameters:
-- `info` - - Collected header discovery state.
+- `this` - - Neat instance exposing the internal telemetry buffer.
 
-Returns: Ordered header names used for serialization.
+Returns: JSONL payload with one telemetry object per line.
+
+Example:
+
+```ts
+const jsonl = exportTelemetryJSONL.call(neat);
+console.log(jsonl.split('\n').length);
+```
 
 ### serializeTelemetryEntry
 
@@ -281,32 +299,14 @@ Parameters:
 
 Returns: CSV row string.
 
-### buildSpeciesHistoryCsv
-
-```ts
-buildSpeciesHistoryCsv(
-  recentHistory: SpeciesHistoryEntry[],
-  headers: string[],
-): string
-```
-
-Build the full CSV string for species history entries.
-
-Species history exports are row-expanded: each generation snapshot can produce
-multiple rows, one for each species stat recorded inside that generation. The
-helper therefore writes a single shared header line and then flattens the
-nested history structure into one CSV row per species snapshot.
-
-The important teaching point is that species history is not a one-row-per-
-generation export. A generation can contain several contemporaneous species,
-so the serializer preserves that multiplicity instead of forcing species data
-into one over-packed cell.
+### TelemetryHeaderInfo
 
-Parameters:
-- `recentHistory` - - History entries to export.
-- `headers` - - Ordered headers for the export window.
+Shape describing collected telemetry header discovery info.
 
-Returns: Complete CSV payload.
+Think of this as the temporary export blueprint for one CSV window. Before a
+telemetry entry can be flattened into cells, the exporter needs to know which
+top-level fields exist, which nested metric groups need prefixed columns, and
+which optional arrays or maps appeared anywhere in the sampled window.
 
 ## neat/telemetry/exports/telemetry.exports.utils.ts
 
@@ -324,6 +324,39 @@ functions first answer the low-level questions: which columns exist in this
 window, which optional structures actually appeared, which species-history
 fields must be backfilled, and how should one value become one safe CSV cell.
 
+### buildSpeciesHistoryStats
+
+```ts
+buildSpeciesHistoryStats(
+  speciesList: SpeciesHistoryStat[],
+  defaultSpeciesId: number,
+  defaultSpeciesSize: number,
+  defaultBestScore: number,
+  defaultLastImproved: number,
+): SpeciesHistoryStat[]
+```
+
+Normalize raw species records into exportable history stats.
+
+Runtime species objects can arrive with slightly different shapes depending
+on when they were recorded or which legacy path produced them. This helper
+converts those permissive records into one compact export-ready model with
+explicit fallbacks for id, size, score, and last-improved generation.
+
+Parameters:
+- `speciesList` - - Raw species records to normalize.
+- `defaultSpeciesId` - - Default species id when missing.
+- `defaultSpeciesSize` - - Default species size when missing.
+- `defaultBestScore` - - Default best score when missing.
+- `defaultLastImproved` - - Default last improved when missing.
+
+Returns: Normalized stats for CSV export.
+
+Example:
+
+const stats = buildSpeciesHistoryStats(neat._species ?? [], -1, 0, 0, 0);
+console.log(stats.length);
+
 ### collectBaseKeys
 
 ```ts
@@ -347,47 +380,47 @@ Parameters:
 
 Returns: void. Mutates `state.baseKeys`.
 
-### collectGroupedMetricKeys
+### collectDiversityLineageMetrics
 
 ```ts
-collectGroupedMetricKeys(
+collectDiversityLineageMetrics(
   entry: TelemetryEntry,
   state: TelemetryHeaderCollectionState,
 ): void
 ```
 
-Collect nested metric keys for grouped telemetry fields.
+Collect curated diversity lineage metrics for stable CSV exports.
 
-Grouped telemetry objects such as `complexity`, `perf`, and `lineage` become
-prefixed CSV columns. This helper discovers those nested keys without mixing
-them into the base top-level header set.
+Diversity objects can contain more information than the CSV surface needs.
+This helper intentionally exports only the lineage-related diversity metrics
+that are useful and stable enough to deserve fixed columns.
 
 Parameters:
 - `entry` - - Telemetry entry to inspect.
 - `state` - - Mutable header collection state.
 
-Returns: void. Mutates complexity/perf/lineage key sets.
+Returns: void. Mutates diversity lineage key set.
 
-### collectDiversityLineageMetrics
+### collectGroupedMetricKeys
 
 ```ts
-collectDiversityLineageMetrics(
+collectGroupedMetricKeys(
   entry: TelemetryEntry,
   state: TelemetryHeaderCollectionState,
 ): void
 ```
 
-Collect curated diversity lineage metrics for stable CSV exports.
+Collect nested metric keys for grouped telemetry fields.
 
-Diversity objects can contain more information than the CSV surface needs.
-This helper intentionally exports only the lineage-related diversity metrics
-that are useful and stable enough to deserve fixed columns.
+Grouped telemetry objects such as `complexity`, `perf`, and `lineage` become
+prefixed CSV columns. This helper discovers those nested keys without mixing
+them into the base top-level header set.
 
 Parameters:
 - `entry` - - Telemetry entry to inspect.
 - `state` - - Mutable header collection state.
 
-Returns: void. Mutates diversity lineage key set.
+Returns: void. Mutates complexity/perf/lineage key sets.
 
 ### collectOptionalColumnPresence
 
@@ -411,24 +444,26 @@ Parameters:
 
 Returns: void. Mutates optional-column flags.
 
-### ensureSpeciesHistoryArray
+### collectSpeciesHistoryHeaders
 
 ```ts
-ensureSpeciesHistoryArray(
-  neatInstance: NeatLike & { _speciesHistory?: SpeciesHistoryEntry[] | undefined; },
-): SpeciesHistoryEntry[]
+collectSpeciesHistoryHeaders(
+  history: SpeciesHistoryEntry[],
+  generationHeader: string,
+): string[]
 ```
 
-Ensure the species history array exists on the Neat instance.
+Collect ordered header keys for species history CSV export.
 
-This helper gives the CSV path one stable backing array to work with, even in
-early or partially initialized controller states. It keeps later export code
-focused on serialization instead of defensive host checks.
+Species history rows can grow new fields over time. This helper scans the
+selected history window and builds the union of all encountered stat keys so
+every emitted row follows one shared, predictable column order.
 
 Parameters:
-- `neatInstance` - - Neat instance holding species history.
+- `history` - - Recent species history entries.
+- `generationHeader` - - Header label for generation column.
 
-Returns: Species history backing array (ensured on instance).
+Returns: Ordered header list for CSV output.
 
 ### ensureMinimalSpeciesSnapshot
 
@@ -467,85 +502,24 @@ Example:
 const history = ensureSpeciesHistoryArray(neat);
 ensureMinimalSpeciesSnapshot(neat, history, 0, -1, 0, 0, 0);
 
-### collectSpeciesHistoryHeaders
-
-```ts
-collectSpeciesHistoryHeaders(
-  history: SpeciesHistoryEntry[],
-  generationHeader: string,
-): string[]
-```
-
-Collect ordered header keys for species history CSV export.
-
-Species history rows can grow new fields over time. This helper scans the
-selected history window and builds the union of all encountered stat keys so
-every emitted row follows one shared, predictable column order.
-
-Parameters:
-- `history` - - Recent species history entries.
-- `generationHeader` - - Header label for generation column.
-
-Returns: Ordered header list for CSV output.
-
-### buildSpeciesHistoryStats
-
-```ts
-buildSpeciesHistoryStats(
-  speciesList: SpeciesHistoryStat[],
-  defaultSpeciesId: number,
-  defaultSpeciesSize: number,
-  defaultBestScore: number,
-  defaultLastImproved: number,
-): SpeciesHistoryStat[]
-```
-
-Normalize raw species records into exportable history stats.
-
-Runtime species objects can arrive with slightly different shapes depending
-on when they were recorded or which legacy path produced them. This helper
-converts those permissive records into one compact export-ready model with
-explicit fallbacks for id, size, score, and last-improved generation.
-
-Parameters:
-- `speciesList` - - Raw species records to normalize.
-- `defaultSpeciesId` - - Default species id when missing.
-- `defaultSpeciesSize` - - Default species size when missing.
-- `defaultBestScore` - - Default best score when missing.
-- `defaultLastImproved` - - Default last improved when missing.
-
-Returns: Normalized stats for CSV export.
-
-Example:
-
-const stats = buildSpeciesHistoryStats(neat._species ?? [], -1, 0, 0, 0);
-console.log(stats.length);
-
-### serializeSpeciesHistoryRow
+### ensureSpeciesHistoryArray
 
 ```ts
-serializeSpeciesHistoryRow(
-  historyEntry: SpeciesHistoryEntry,
-  speciesStat: SpeciesHistoryStat,
-  orderedHeaders: string[],
-  generationHeader: string,
-): string
+ensureSpeciesHistoryArray(
+  neatInstance: NeatLike & { _speciesHistory?: SpeciesHistoryEntry[] | undefined; },
+): SpeciesHistoryEntry[]
 ```
 
-Serialize one species history row using the provided headers.
+Ensure the species history array exists on the Neat instance.
 
-Species history CSV output is built row by row from one generation snapshot
-plus one species stat record. This helper guarantees that each row follows
-the same previously collected header order, even when some species records
-omit optional fields.
+This helper gives the CSV path one stable backing array to work with, even in
+early or partially initialized controller states. It keeps later export code
+focused on serialization instead of defensive host checks.
 
 Parameters:
-- `historyEntry` - - A single generation snapshot.
-- `speciesStat` - - A single species stat record for that generation.
-- `orderedHeaders` - - Ordered header list for stable CSV.
-- `generationHeader` - - Column header name for generation.
+- `neatInstance` - - Neat instance holding species history.
 
-Returns: CSV row string matching the provided header order.
+Returns: Species history backing array (ensured on instance).
 
 ### resolveSpeciesHistoryCellValue
 
@@ -591,6 +565,32 @@ Parameters:
 
 Returns: JSON string or empty string when JSON.stringify returns undefined.
 
+### serializeSpeciesHistoryRow
+
+```ts
+serializeSpeciesHistoryRow(
+  historyEntry: SpeciesHistoryEntry,
+  speciesStat: SpeciesHistoryStat,
+  orderedHeaders: string[],
+  generationHeader: string,
+): string
+```
+
+Serialize one species history row using the provided headers.
+
+Species history CSV output is built row by row from one generation snapshot
+plus one species stat record. This helper guarantees that each row follows
+the same previously collected header order, even when some species records
+omit optional fields.
+
+Parameters:
+- `historyEntry` - - A single generation snapshot.
+- `speciesStat` - - A single species stat record for that generation.
+- `orderedHeaders` - - Ordered header list for stable CSV.
+- `generationHeader` - - Column header name for generation.
+
+Returns: CSV row string matching the provided header order.
+
 ### TelemetryHeaderCollectionState
 
 Mutable state container used while collecting telemetry header metadata.