@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -42,28 +42,6 @@ A useful reading order is:
 
 ## neat/telemetry/recorder/telemetry.recorder.ts
 
-### createTelemetryEntryBase
-
-```ts
-createTelemetryEntryBase(
-  generationIndex: number,
-  bestScore: number,
-  speciesCount: number,
-): TelemetryEntry
-```
-
-Create a strict baseline telemetry entry with required fields populated.
-
-This helper centralizes defaults so downstream telemetry producers can
-extend the entry while keeping the strict `TelemetryEntry` contract.
-
-Parameters:
-- `generationIndex` - Generation index for the telemetry snapshot.
-- `bestScore` - Best fitness value observed in the generation.
-- `speciesCount` - Number of extant species.
-
-Returns: A strict telemetry entry with required fields populated.
-
 ### applyTelemetrySelect
 
 ```ts
@@ -92,33 +70,42 @@ neat._telemetrySelect = new Set(['diversity']);
 applyTelemetrySelect.call(neat, entry);
 ```
 
-### structuralEntropy
+### buildTelemetryEntry
 
 ```ts
-structuralEntropy(
-  graph: { [key: string]: unknown; nodes: { geneId: number; }[]; connections: { from: { geneId: number; }; to: { geneId: number; }; enabled: boolean; }[]; },
-): number
+buildTelemetryEntry(
+  fittest: Record<string, unknown>,
+): TelemetryEntry
 ```
 
-Lightweight proxy for structural entropy based on degree-distribution.
+Build a comprehensive telemetry entry for the current generation.
 
-This function computes an approximate entropy of a graph topology by
-counting node degrees and computing the entropy of the degree histogram.
-The result is cached on the graph object for the current generation in
-`_entropyVal` to avoid repeated expensive recomputation.
+This is the recorder's main orchestration surface. It gathers one coherent
+explanation of the current generation by combining immediate state
+(`generation`, `best`, `species`) with whichever optional evidence blocks the
+controller has enabled: diversity, lineage, objective activity, Pareto-front
+summaries, complexity growth, RNG state, and performance timing.
+
+This function intentionally mirrors the legacy in-loop telemetry construction
+to preserve behavior relied upon by tests and consumers.
 
 Parameters:
-- `graph` - - A genome-like object with `nodes` and `connections` arrays.
+- `fittest` - - The currently fittest genome (used to report `best` score).
 
-Returns: A non-negative number approximating structural entropy.
+Returns: A TelemetryEntry object suitable for recording/streaming.
 
 Example:
 
 ```ts
-const H = structuralEntropy.call(neat, genome);
-console.log(`Structure entropy: ${H.toFixed(3)}`);
+// build a telemetry snapshot for the current generation
+const snapshot = neat.buildTelemetryEntry(neat.population[0]);
+neat.recordTelemetryEntry(snapshot);
 ```
 
+The function has two internal paths:
+- multi-objective mode adds Pareto-front and hypervolume-oriented signals
+- mono-objective mode keeps the payload smaller while preserving the same core fields
+
 ### computeDiversityStats
 
 ```ts
@@ -145,6 +132,28 @@ neat.computeDiversityStats();
 console.log(neat._diversityStats.meanCompat);
 ```
 
+### createTelemetryEntryBase
+
+```ts
+createTelemetryEntryBase(
+  generationIndex: number,
+  bestScore: number,
+  speciesCount: number,
+): TelemetryEntry
+```
+
+Create a strict baseline telemetry entry with required fields populated.
+
+This helper centralizes defaults so downstream telemetry producers can
+extend the entry while keeping the strict `TelemetryEntry` contract.
+
+Parameters:
+- `generationIndex` - Generation index for the telemetry snapshot.
+- `bestScore` - Best fitness value observed in the generation.
+- `speciesCount` - Number of extant species.
+
+Returns: A strict telemetry entry with required fields populated.
+
 ### recordTelemetryEntry
 
 ```ts
@@ -178,42 +187,33 @@ Example:
 neat.recordTelemetryEntry({ gen: neat.generation, best: neat.population[0].score });
 ```
 
-### buildTelemetryEntry
+### structuralEntropy
 
 ```ts
-buildTelemetryEntry(
-  fittest: Record<string, unknown>,
-): TelemetryEntry
+structuralEntropy(
+  graph: { [key: string]: unknown; nodes: { geneId: number; }[]; connections: { from: { geneId: number; }; to: { geneId: number; }; enabled: boolean; }[]; },
+): number
 ```
 
-Build a comprehensive telemetry entry for the current generation.
-
-This is the recorder's main orchestration surface. It gathers one coherent
-explanation of the current generation by combining immediate state
-(`generation`, `best`, `species`) with whichever optional evidence blocks the
-controller has enabled: diversity, lineage, objective activity, Pareto-front
-summaries, complexity growth, RNG state, and performance timing.
+Lightweight proxy for structural entropy based on degree-distribution.
 
-This function intentionally mirrors the legacy in-loop telemetry construction
-to preserve behavior relied upon by tests and consumers.
+This function computes an approximate entropy of a graph topology by
+counting node degrees and computing the entropy of the degree histogram.
+The result is cached on the graph object for the current generation in
+`_entropyVal` to avoid repeated expensive recomputation.
 
 Parameters:
-- `fittest` - - The currently fittest genome (used to report `best` score).
+- `graph` - - A genome-like object with `nodes` and `connections` arrays.
 
-Returns: A TelemetryEntry object suitable for recording/streaming.
+Returns: A non-negative number approximating structural entropy.
 
 Example:
 
 ```ts
-// build a telemetry snapshot for the current generation
-const snapshot = neat.buildTelemetryEntry(neat.population[0]);
-neat.recordTelemetryEntry(snapshot);
+const H = structuralEntropy.call(neat, genome);
+console.log(`Structure entropy: ${H.toFixed(3)}`);
 ```
 
-The function has two internal paths:
-- multi-objective mode adds Pareto-front and hypervolume-oriented signals
-- mono-objective mode keeps the payload smaller while preserving the same core fields
-
 ### TelemetryContext
 
 Context view used within telemetry helpers to access optional internal

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

@@ -18,14 +18,29 @@ are narrow enough to stay telemetry-local.
 
 ## neat/telemetry/types/telemetry.types.ts
 
-### TelemetryGenome
+### OperatorStatsMap
 
-Minimal genome shape used by telemetry helpers.
+Operator stats map shape for telemetry extraction.
 
-Telemetry code rarely needs the entire `Network` surface. Most helpers only
-care about structural size and a few optional lineage hints, so this type
-captures the smallest genome contract needed for diversity, complexity, and
-lineage-oriented telemetry work.
+Adaptive mutation telemetry records success and attempt counts per operator.
+This map type names that contract so extraction helpers can stay specific
+about what they read without depending on a broader controller class.
+
+### TelemetryBufferContext
+
+Minimal telemetry buffer context shape.
+
+Runtime helpers only need a host that can expose or receive the in-memory
+telemetry buffer. This tiny shape keeps those helpers reusable and easy to
+test.
+
+### TelemetryCoreFields
+
+Core telemetry field keys used by selection helpers.
+
+Some telemetry fields remain mandatory even when callers request a narrower
+export or inspection surface. This alias documents that those core keys are
+treated as a fixed protected set rather than arbitrary strings.
 
 ### TelemetryDiversityOptions
 
@@ -36,14 +51,6 @@ to the fields that matter for diversity-oriented telemetry decisions: whether
 diversity metrics are enabled, how aggressively to sample in fast mode, and
 which novelty-search defaults should influence telemetry output.
 
-### TelemetryStreamOptions
-
-Minimal telemetry stream options for streaming helpers.
-
-The runtime layer only needs to know whether streaming is enabled and which
-callback should receive each entry. This keeps the callback contract explicit
-without forcing runtime helpers to depend on the entire controller option bag.
-
 ### TelemetryEntryRecord
 
 Telemetry entry shape used for constructing snapshots.
@@ -52,21 +59,14 @@ Builders often need the strongly typed `TelemetryEntry` model plus temporary
 access to additional dynamic fields while a snapshot is being assembled or
 filtered. This alias keeps that construction-phase flexibility localized.
 
-### OperatorStatsMap
-
-Operator stats map shape for telemetry extraction.
-
-Adaptive mutation telemetry records success and attempt counts per operator.
-This map type names that contract so extraction helpers can stay specific
-about what they read without depending on a broader controller class.
-
-### TelemetryBufferContext
+### TelemetryGenome
 
-Minimal telemetry buffer context shape.
+Minimal genome shape used by telemetry helpers.
 
-Runtime helpers only need a host that can expose or receive the in-memory
-telemetry buffer. This tiny shape keeps those helpers reusable and easy to
-test.
+Telemetry code rarely needs the entire `Network` surface. Most helpers only
+care about structural size and a few optional lineage hints, so this type
+captures the smallest genome contract needed for diversity, complexity, and
+lineage-oriented telemetry work.
 
 ### TelemetrySelectContext
 
@@ -76,10 +76,10 @@ Selection helpers narrow telemetry entries to a configured subset of fields.
 This context type names the single host capability they need: an optional set
 of selected telemetry keys.
 
-### TelemetryCoreFields
+### TelemetryStreamOptions
 
-Core telemetry field keys used by selection helpers.
+Minimal telemetry stream options for streaming helpers.
 
-Some telemetry fields remain mandatory even when callers request a narrower
-export or inspection surface. This alias documents that those core keys are
-treated as a fixed protected set rather than arbitrary strings.
+The runtime layer only needs to know whether streaming is enabled and which
+callback should receive each entry. This keeps the callback contract explicit
+without forcing runtime helpers to depend on the entire controller option bag.

package/src/neat/topology-intent/README.md

@@ -66,46 +66,61 @@ promoteGenomeToFeedForwardIntentWhenEligible(genome, shouldPromote);
 
 ## neat/topology-intent/neat.topology-intent.ts
 
-### usesFeedForwardMutationPolicy
+### isGenomeEligibleForFeedForwardIntentPromotion
 
 ```ts
-usesFeedForwardMutationPolicy(
-  mutationConfig: unknown,
+isGenomeEligibleForFeedForwardIntentPromotion(
+  genome: TopologyIntentGenome,
 ): boolean
 ```
 
-Determine whether the configured mutation policy communicates feed-forward intent.
+Check whether a genome can safely adopt feed-forward topology intent.
 
-Accepts the canonical mutation pool reference, the legacy single-item array
-wrapper, or a flattened pool that exactly matches the canonical feed-forward
-operator order. The comparison stays strict on purpose so the controller does
-not silently reinterpret custom mutation pools as feed-forward mode.
+Eligibility is intentionally conservative: the graph must already be free of
+gates and self-connections, and every normal connection must follow the
+current node ordering. This keeps the helper focused on preserving an
+already-feed-forward structure instead of rewriting arbitrary graphs into a
+different interpretation.
 
-In practice this helper answers the policy question only. It does not inspect
-a concrete genome, and it does not attempt runtime promotion by itself.
-That separation is important because a caller may request feed-forward
-mutation semantics while still holding seed genomes whose current graphs are
-recurrent, gated, or otherwise not yet eligible for the stricter runtime
-contract.
+The helper therefore answers a structural-preservation question, not a graph
+repair question. A `false` result does not mean the genome is invalid. It
+means only that this bridge should not relabel it as feed-forward yet.
 
-Treat this as the chapter's public signal decoder. It translates several
-legacy and canonical configuration shapes into one yes-or-no answer that the
-rest of the controller can reuse consistently.
+This distinction is the chapter's core invariant. The helper is intentionally
+willing to say "not yet" to valid genomes, because false positives would be
+worse than conservative misses at this boundary.
 
 Parameters:
-- `mutationConfig` - Configured mutation option.
+- `genome` - Genome candidate.
 
-Returns: True when the option expresses canonical feed-forward intent.
+Returns: True when the genome can safely adopt feed-forward intent.
 
-Example:
+### matchesCanonicalFeedForwardPool
 
 ```ts
-const shouldPromote = usesFeedForwardMutationPolicy(neat.options.mutation);
-if (!shouldPromote) {
-  console.log('keep unconstrained topology intent');
-}
+matchesCanonicalFeedForwardPool(
+  configuredPool: TopologyIntentMutationMethod[],
+  canonicalPool: TopologyIntentMutationMethod[],
+): boolean
 ```
 
+Check whether a configured mutation pool matches the canonical FFW pool.
+
+This helper exists so callers can recognize the feed-forward mutation policy
+even after options have been flattened, copied, or wrapped by legacy code.
+The comparison deliberately stays order-sensitive because the canonical pool
+is treated as one explicit public signal rather than as a fuzzy set of
+approximately similar operators.
+That strictness is a feature: it keeps the topology-intent story predictable
+for readers and users instead of letting near-matches silently acquire a
+stronger runtime meaning than they asked for.
+
+Parameters:
+- `configuredPool` - Mutation pool configured on the NEAT instance.
+- `canonicalPool` - Canonical feed-forward mutation pool.
+
+Returns: True when both pools align by operator name and order.
+
 ### promoteGenomeToFeedForwardIntentWhenEligible
 
 ```ts
@@ -145,17 +160,6 @@ const shouldPromote = usesFeedForwardMutationPolicy(neat.options.mutation);
 promoteGenomeToFeedForwardIntentWhenEligible(candidateGenome, shouldPromote);
 ```
 
-### TopologyIntentMutationMethod
-
-Minimal mutation descriptor used by topology-intent helpers.
-
-The bridge only needs one stable piece of information from a mutation entry:
-its public name. That keeps the topology-intent checks aligned with the
-canonical feed-forward pool without importing the full mutation subsystem.
-Keeping the contract this small also makes the chapter's main teaching point
-easier to see: topology intent recognition is a public-policy comparison, not
-a second mutation-engine implementation.
-
 ### TopologyIntentGenome
 
 Minimal genome surface required to promote feed-forward intent safely.
@@ -169,57 +173,53 @@ In other words, this contract captures just enough structure to answer the
 chapter's one real question: "would a feed-forward runtime label preserve the
 current graph's meaning, or would it over-promise?"
 
-### matchesCanonicalFeedForwardPool
-
-```ts
-matchesCanonicalFeedForwardPool(
-  configuredPool: TopologyIntentMutationMethod[],
-  canonicalPool: TopologyIntentMutationMethod[],
-): boolean
-```
-
-Check whether a configured mutation pool matches the canonical FFW pool.
-
-This helper exists so callers can recognize the feed-forward mutation policy
-even after options have been flattened, copied, or wrapped by legacy code.
-The comparison deliberately stays order-sensitive because the canonical pool
-is treated as one explicit public signal rather than as a fuzzy set of
-approximately similar operators.
-That strictness is a feature: it keeps the topology-intent story predictable
-for readers and users instead of letting near-matches silently acquire a
-stronger runtime meaning than they asked for.
+### TopologyIntentMutationMethod
 
-Parameters:
-- `configuredPool` - Mutation pool configured on the NEAT instance.
-- `canonicalPool` - Canonical feed-forward mutation pool.
+Minimal mutation descriptor used by topology-intent helpers.
 
-Returns: True when both pools align by operator name and order.
+The bridge only needs one stable piece of information from a mutation entry:
+its public name. That keeps the topology-intent checks aligned with the
+canonical feed-forward pool without importing the full mutation subsystem.
+Keeping the contract this small also makes the chapter's main teaching point
+easier to see: topology intent recognition is a public-policy comparison, not
+a second mutation-engine implementation.
 
-### isGenomeEligibleForFeedForwardIntentPromotion
+### usesFeedForwardMutationPolicy
 
 ```ts
-isGenomeEligibleForFeedForwardIntentPromotion(
-  genome: TopologyIntentGenome,
+usesFeedForwardMutationPolicy(
+  mutationConfig: unknown,
 ): boolean
 ```
 
-Check whether a genome can safely adopt feed-forward topology intent.
+Determine whether the configured mutation policy communicates feed-forward intent.
 
-Eligibility is intentionally conservative: the graph must already be free of
-gates and self-connections, and every normal connection must follow the
-current node ordering. This keeps the helper focused on preserving an
-already-feed-forward structure instead of rewriting arbitrary graphs into a
-different interpretation.
+Accepts the canonical mutation pool reference, the legacy single-item array
+wrapper, or a flattened pool that exactly matches the canonical feed-forward
+operator order. The comparison stays strict on purpose so the controller does
+not silently reinterpret custom mutation pools as feed-forward mode.
 
-The helper therefore answers a structural-preservation question, not a graph
-repair question. A `false` result does not mean the genome is invalid. It
-means only that this bridge should not relabel it as feed-forward yet.
+In practice this helper answers the policy question only. It does not inspect
+a concrete genome, and it does not attempt runtime promotion by itself.
+That separation is important because a caller may request feed-forward
+mutation semantics while still holding seed genomes whose current graphs are
+recurrent, gated, or otherwise not yet eligible for the stricter runtime
+contract.
 
-This distinction is the chapter's core invariant. The helper is intentionally
-willing to say "not yet" to valid genomes, because false positives would be
-worse than conservative misses at this boundary.
+Treat this as the chapter's public signal decoder. It translates several
+legacy and canonical configuration shapes into one yes-or-no answer that the
+rest of the controller can reuse consistently.
 
 Parameters:
-- `genome` - Genome candidate.
+- `mutationConfig` - Configured mutation option.
 
-Returns: True when the genome can safely adopt feed-forward intent.
+Returns: True when the option expresses canonical feed-forward intent.
+
+Example:
+
+```ts
+const shouldPromote = usesFeedForwardMutationPolicy(neat.options.mutation);
+if (!shouldPromote) {
+  console.log('keep unconstrained topology intent');
+}
+```