@reicek/neataptic-ts 0.1.24 → 0.1.26

package/src/neat/compat/README.md

@@ -88,49 +88,6 @@ if (distance < neat.options.compatibilityThreshold) {
 
 ## neat/compat/compat.ts
 
-### _fallbackInnov
-
-```ts
-_fallbackInnov(
-  connection: ConnectionLike,
-): number
-```
-
-Generate a deterministic fallback innovation id for a connection when the
-connection does not provide an explicit innovation number.
-
-Innovation numbers are the canonical alignment key because they let NEAT
-distinguish matching genes from disjoint or excess ones across topology
-changes. This fallback only exists for the boundary cases where a connection
-arrives without that explicit identifier. In that case the helper derives a
-stable directional id from the connection endpoints so the comparison can
-still proceed instead of silently dropping structure from the distance read.
-
-Interpret the fallback as a bridge, not as a replacement for properly tracked
-innovations. It keeps compatibility useful for legacy, test, or partially
-normalized genomes, but explicit innovation numbers remain the source of
-truth whenever they are available. A fallback match should therefore be read
-as "these connections occupy the same directed slot" rather than "these two
-genes are proven to share the same historical innovation event."
-
-Parameters:
-- `this` - - NEAT context kept for symmetry with the other compatibility helpers.
-- `connection` - - Connection object expected to contain `from.index` and `to.index`.
-
-Returns: Numeric innovation id derived from the directional endpoint pair.
-
-Example:
-
-```ts
-const fallbackInnovation = neat._fallbackInnov({
-  from: { index: 4 },
-  to: { index: 9 },
-  weight: 0.75,
-});
-
-// The same endpoint pair always resolves to the same synthetic id.
-```
-
 ### _compatibilityDistance
 
 ```ts
@@ -184,3 +141,46 @@ const speciesBoundaryDistance = neat._compatibilityDistance(genomeA, genomeB);
 const sameSpecies =
   speciesBoundaryDistance <= neat.options.compatibilityThreshold;
 ```
+
+### _fallbackInnov
+
+```ts
+_fallbackInnov(
+  connection: ConnectionLike,
+): number
+```
+
+Generate a deterministic fallback innovation id for a connection when the
+connection does not provide an explicit innovation number.
+
+Innovation numbers are the canonical alignment key because they let NEAT
+distinguish matching genes from disjoint or excess ones across topology
+changes. This fallback only exists for the boundary cases where a connection
+arrives without that explicit identifier. In that case the helper derives a
+stable directional id from the connection endpoints so the comparison can
+still proceed instead of silently dropping structure from the distance read.
+
+Interpret the fallback as a bridge, not as a replacement for properly tracked
+innovations. It keeps compatibility useful for legacy, test, or partially
+normalized genomes, but explicit innovation numbers remain the source of
+truth whenever they are available. A fallback match should therefore be read
+as "these connections occupy the same directed slot" rather than "these two
+genes are proven to share the same historical innovation event."
+
+Parameters:
+- `this` - - NEAT context kept for symmetry with the other compatibility helpers.
+- `connection` - - Connection object expected to contain `from.index` and `to.index`.
+
+Returns: Numeric innovation id derived from the directional endpoint pair.
+
+Example:
+
+```ts
+const fallbackInnovation = neat._fallbackInnov({
+  from: { index: 4 },
+  to: { index: 9 },
+  weight: 0.75,
+});
+
+// The same endpoint pair always resolves to the same synthetic id.
+```

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

@@ -36,6 +36,15 @@ Practical reading order:
 
 ## neat/compat/core/compat.types.ts
 
+### ComparisonMetrics
+
+Aggregated comparison metrics for compatibility calculations.
+
+`compareInnovationLists()` produces this structure so the final distance fold
+can stay separate from the merge walk that discovered the evidence. That
+split keeps the algorithm easier to explain: one pass classifies the gene
+relationship, a later pass applies the NEAT weighting policy.
+
 ### ConnectionLike
 
 Shape of a connection entry used during compatibility checks.
@@ -61,15 +70,6 @@ This keeps the boundary tightly focused on generation-scoped caches,
 compatibility coefficients, and the fallback innovation resolver instead of
 coupling the mechanics layer to the full `Neat` surface.
 
-### ComparisonMetrics
-
-Aggregated comparison metrics for compatibility calculations.
-
-`compareInnovationLists()` produces this structure so the final distance fold
-can stay separate from the merge walk that discovered the evidence. That
-split keeps the algorithm easier to explain: one pass classifies the gene
-relationship, a later pass applies the NEAT weighting policy.
-
 ## neat/compat/core/compat.core.ts
 
 Compatibility-distance mechanics used by NEAT speciation.
@@ -84,27 +84,6 @@ The helpers are deliberately small and ordered to match the real execution
 path: stabilize caches, normalize genomes, compare aligned innovations, then
 fold the discovered evidence into the NEAT distance formula.
 
-### ensureGenerationCache
-
-```ts
-ensureGenerationCache(
-  neatContext: NeatLikeForCompat,
-): void
-```
-
-Ensure generation-scoped compatibility caches exist.
-
-The compatibility layer keeps pairwise distance results only for the current
-generation because the population can mutate between generations. Once that
-happens, earlier distances are no longer trustworthy. This helper provides
-the safety boundary that drops stale cache state before later helpers assume
-a cache map exists.
-
-Parameters:
-- `neatContext` - - Current NEAT context holding generation and caches.
-
-Returns: Nothing. The helper resets caches when the generation changes.
-
 ### buildPairKey
 
 ```ts
@@ -126,6 +105,87 @@ Parameters:
 
 Returns: Stable cache key in the form `minId|maxId`.
 
+### compareInnovationLists
+
+```ts
+compareInnovationLists(
+  firstList: [number, number][],
+  secondList: [number, number][],
+): ComparisonMetrics
+```
+
+Compare two sorted innovation lists and derive compatibility metrics.
+
+This is the heart of the compatibility read. Because both lists are sorted,
+the helper can walk them once like a merge step: matching innovations count
+toward aligned genes, gaps inside the shared innovation range become disjoint
+genes, and the remaining tail genes become excess. Weight differences are
+only measured for matching genes because that is the only case where the two
+genomes clearly refer to the same structural gene.
+
+Parameters:
+- `firstList` - - Sorted innovation list for the first genome.
+- `secondList` - - Sorted innovation list for the second genome.
+
+Returns: Aggregated comparison metrics for distance computation.
+
+### computeCompatibilityDistance
+
+```ts
+computeCompatibilityDistance(
+  neatContext: NeatLikeForCompat,
+  metrics: ComparisonMetrics,
+): number
+```
+
+Compute the compatibility distance from precomputed metrics.
+
+This fold turns the raw comparison evidence into the familiar NEAT distance:
+excess structure penalty, disjoint structure penalty, and average matching
+weight drift. Structural counts are normalized by the larger genome size so
+larger topologies do not inflate distance merely because they contain more
+possible genes.
+
+Parameters:
+- `neatContext` - - NEAT context providing compatibility coefficients.
+- `metrics` - - Aggregated comparison metrics.
+
+Returns: Final compatibility distance for the genome pair.
+
+Example:
+
+```ts
+const distance = computeCompatibilityDistance(neat, {
+  firstGenomeSize: 12,
+  secondGenomeSize: 10,
+  matchingCount: 8,
+  disjointCount: 1,
+  excessCount: 2,
+  weightDifferenceSum: 0.9,
+});
+```
+
+### ensureGenerationCache
+
+```ts
+ensureGenerationCache(
+  neatContext: NeatLikeForCompat,
+): void
+```
+
+Ensure generation-scoped compatibility caches exist.
+
+The compatibility layer keeps pairwise distance results only for the current
+generation because the population can mutate between generations. Once that
+happens, earlier distances are no longer trustworthy. This helper provides
+the safety boundary that drops stale cache state before later helpers assume
+a cache map exists.
+
+Parameters:
+- `neatContext` - - Current NEAT context holding generation and caches.
+
+Returns: Nothing. The helper resets caches when the generation changes.
+
 ### getDistanceCacheMap
 
 ```ts
@@ -176,30 +236,6 @@ const innovationPairs = getSortedInnovationCache(neat, genome);
 // [[3, 0.12], [8, -0.7], [11, 0.44]]
 ```
 
-### compareInnovationLists
-
-```ts
-compareInnovationLists(
-  firstList: [number, number][],
-  secondList: [number, number][],
-): ComparisonMetrics
-```
-
-Compare two sorted innovation lists and derive compatibility metrics.
-
-This is the heart of the compatibility read. Because both lists are sorted,
-the helper can walk them once like a merge step: matching innovations count
-toward aligned genes, gaps inside the shared innovation range become disjoint
-genes, and the remaining tail genes become excess. Weight differences are
-only measured for matching genes because that is the only case where the two
-genomes clearly refer to the same structural gene.
-
-Parameters:
-- `firstList` - - Sorted innovation list for the first genome.
-- `secondList` - - Sorted innovation list for the second genome.
-
-Returns: Aggregated comparison metrics for distance computation.
-
 ### resolveMaxInnovation
 
 ```ts
@@ -219,39 +255,3 @@ Parameters:
 - `list` - - Sorted innovation list for a genome.
 
 Returns: Highest innovation id or `0` when the list is empty.
-
-### computeCompatibilityDistance
-
-```ts
-computeCompatibilityDistance(
-  neatContext: NeatLikeForCompat,
-  metrics: ComparisonMetrics,
-): number
-```
-
-Compute the compatibility distance from precomputed metrics.
-
-This fold turns the raw comparison evidence into the familiar NEAT distance:
-excess structure penalty, disjoint structure penalty, and average matching
-weight drift. Structural counts are normalized by the larger genome size so
-larger topologies do not inflate distance merely because they contain more
-possible genes.
-
-Parameters:
-- `neatContext` - - NEAT context providing compatibility coefficients.
-- `metrics` - - Aggregated comparison metrics.
-
-Returns: Final compatibility distance for the genome pair.
-
-Example:
-
-```ts
-const distance = computeCompatibilityDistance(neat, {
-  firstGenomeSize: 12,
-  secondGenomeSize: 10,
-  matchingCount: 8,
-  disjointCount: 1,
-  excessCount: 2,
-  weightDifferenceSum: 0.9,
-});
-```

package/src/neat/diversity/README.md

@@ -39,30 +39,24 @@ public read flow and the meaning of the resulting summary.
 
 ## neat/diversity/diversity.ts
 
-### structuralEntropy
+### buildEmptyDiversityStats
 
 ```ts
-structuralEntropy(
-  graph: default,
-): number
+buildEmptyDiversityStats(
+  populationSize: number,
+): DiversityStats
 ```
 
-Compute the Shannon-style entropy of a network's out-degree distribution.
-
-Structural entropy here is a lightweight topology fingerprint: it measures
-how evenly outgoing connections are distributed across nodes. It does not
-inspect weights or recurrent dynamics, so it works well as a cheap structural
-diversity signal.
+Build a zeroed diversity snapshot when no sampled metrics exist yet.
 
-Use this when you want to compare the shape of individual networks or add one
-more structural signal beside raw node and connection counts. Higher values
-generally mean connectivity is spread across more nodes instead of being
-concentrated into a few hubs.
+This helper gives controller facades and diagnostics a safe fallback object
+whose shape matches ordinary diversity output without pretending that real
+real sampling work has happened yet.
 
 Parameters:
-- `graph` - - Network to summarize structurally.
+- `populationSize` - - Population size to echo into the empty snapshot.
 
-Returns: Shannon-style entropy of the out-degree distribution.
+Returns: Diversity stats object with zeroed aggregates.
 
 ### computeDiversityStats
 
@@ -106,25 +100,6 @@ if (diversity) {
 }
 ```
 
-### buildEmptyDiversityStats
-
-```ts
-buildEmptyDiversityStats(
-  populationSize: number,
-): DiversityStats
-```
-
-Build a zeroed diversity snapshot when no sampled metrics exist yet.
-
-This helper gives controller facades and diagnostics a safe fallback object
-whose shape matches ordinary diversity output without pretending that real
-real sampling work has happened yet.
-
-Parameters:
-- `populationSize` - - Population size to echo into the empty snapshot.
-
-Returns: Diversity stats object with zeroed aggregates.
-
 ### DiversityStats
 
 Diversity statistics returned by sampled population analysis.
@@ -158,3 +133,28 @@ Lineage spread is useful for telemetry, but full all-pairs ancestry distance
 becomes expensive quickly. This cap keeps the lineage side of the report
 bounded while still surfacing whether ancestry depth is bunching up or
 staying distributed.
+
+### structuralEntropy
+
+```ts
+structuralEntropy(
+  graph: default,
+): number
+```
+
+Compute the Shannon-style entropy of a network's out-degree distribution.
+
+Structural entropy here is a lightweight topology fingerprint: it measures
+how evenly outgoing connections are distributed across nodes. It does not
+inspect weights or recurrent dynamics, so it works well as a cheap structural
+diversity signal.
+
+Use this when you want to compare the shape of individual networks or add one
+more structural signal beside raw node and connection counts. Higher values
+generally mean connectivity is spread across more nodes instead of being
+concentrated into a few hubs.
+
+Parameters:
+- `graph` - - Network to summarize structurally.
+
+Returns: Shannon-style entropy of the out-degree distribution.

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

@@ -17,30 +17,6 @@ Read the chapter in this order:
 
 ## neat/diversity/core/diversity.types.ts
 
-### NodeWithConnections
-
-Minimal node interface used by diversity computations.
-
-Diversity helpers only need each node's outgoing connection count to build a
-structural-entropy fingerprint, so this type keeps the reporting boundary
-narrower than the full runtime node model.
-
-### GenomeWithMetrics
-
-Minimal genome shape used by diversity computations.
-
-This projection is the per-genome input to the diversity report. It exposes
-exactly the data needed to answer four cheap read-side questions:
-
-- how large genomes are right now,
-- how uneven that structural size has become,
-- how far sampled ancestry depth has spread,
-- and how compatible each genome remains with sampled peers.
-
-Keeping the contract this small lets diagnostics and telemetry reuse the
-diversity helpers against genome-like snapshots rather than the full NEAT
-controller state.
-
 ### CompatComputer
 
 Minimal interface for computing compatibility distance between genomes.
@@ -67,6 +43,30 @@ In practice, telemetry consumers compare this object across generations to
 see whether mutation, speciation, and pruning are still producing meaningful
 variation without paying for exhaustive all-pairs analysis.
 
+### GenomeWithMetrics
+
+Minimal genome shape used by diversity computations.
+
+This projection is the per-genome input to the diversity report. It exposes
+exactly the data needed to answer four cheap read-side questions:
+
+- how large genomes are right now,
+- how uneven that structural size has become,
+- how far sampled ancestry depth has spread,
+- and how compatible each genome remains with sampled peers.
+
+Keeping the contract this small lets diagnostics and telemetry reuse the
+diversity helpers against genome-like snapshots rather than the full NEAT
+controller state.
+
+### NodeWithConnections
+
+Minimal node interface used by diversity computations.
+
+Diversity helpers only need each node's outgoing connection count to build a
+structural-entropy fingerprint, so this type keeps the reporting boundary
+narrower than the full runtime node model.
+
 ## neat/diversity/core/diversity.core.ts
 
 Diversity-statistics mechanics used by telemetry and diagnostics.
@@ -84,26 +84,6 @@ analysis, they sample the expensive comparisons and fold the results into a
 report that is accurate enough for telemetry trends, diagnostics, and
 generation-over-generation comparisons.
 
-### calculateStructuralEntropy
-
-```ts
-calculateStructuralEntropy(
-  graph: default,
-): number
-```
-
-Compute the Shannon-style entropy of a network's out-degree distribution.
-
-This is the chapter's shape metric. Two genomes can share similar node and
-connection counts while still distributing edges very differently, so the
-entropy read adds a lightweight topology fingerprint beside the raw size
-aggregates.
-
-Parameters:
-- `graph` - - Network instance to evaluate.
-
-Returns: Shannon-style entropy value.
-
 ### calculateDiversityStats
 
 ```ts
@@ -141,59 +121,25 @@ if (diversity) {
 }
 ```
 
-### MAX_LINEAGE_PAIR_SAMPLE
-
-Maximum lineage sample size for pairwise depth comparisons.
-
-Lineage spread is useful for telemetry, but full all-pairs ancestry distance
-becomes expensive quickly. This cap keeps the lineage side of the report
-bounded while still surfacing whether ancestry depth is bunching up or
-staying distributed.
-
-### MAX_COMPATIBILITY_SAMPLE
-
-Maximum population sample size for compatibility comparisons.
-
-Compatibility distance is the most obviously quadratic part of the diversity
-report. Sampling lets the controller estimate genetic separation cheaply
-enough to keep diversity reporting on the hot path for telemetry.
-
-### mean
-
-```ts
-mean(
-  values: number[],
-): number
-```
-
-Compute the arithmetic mean of a numeric array.
-
-The diversity report uses this helper for the direct summary columns such as
-average lineage depth, average node count, average connection count, and the
-mean entropy across genomes.
-
-Parameters:
-- `values` - - Values to average.
-
-Returns: Arithmetic mean, or `0` when the array is empty.
-
-### variance
+### calculateStructuralEntropy
 
 ```ts
-variance(
-  values: number[],
+calculateStructuralEntropy(
+  graph: default,
 ): number
 ```
 
-Compute the population variance of a numeric array.
+Compute the Shannon-style entropy of a network's out-degree distribution.
 
-Variance complements the raw averages by showing whether the population is
-staying structurally tight or spreading into a wider range of topology sizes.
+This is the chapter's shape metric. Two genomes can share similar node and
+connection counts while still distributing edges very differently, so the
+entropy read adds a lightweight topology fingerprint beside the raw size
+aggregates.
 
 Parameters:
-- `values` - - Values to evaluate.
+- `graph` - - Network instance to evaluate.
 
-Returns: Population variance, or `0` when the array is empty.
+Returns: Shannon-style entropy value.
 
 ### computeMeanAbsolutePairDistance
 
@@ -240,3 +186,57 @@ Parameters:
 - `sampleLimit` - - Maximum number of genomes to include.
 
 Returns: Mean compatibility distance across the sampled pairs.
+
+### MAX_COMPATIBILITY_SAMPLE
+
+Maximum population sample size for compatibility comparisons.
+
+Compatibility distance is the most obviously quadratic part of the diversity
+report. Sampling lets the controller estimate genetic separation cheaply
+enough to keep diversity reporting on the hot path for telemetry.
+
+### MAX_LINEAGE_PAIR_SAMPLE
+
+Maximum lineage sample size for pairwise depth comparisons.
+
+Lineage spread is useful for telemetry, but full all-pairs ancestry distance
+becomes expensive quickly. This cap keeps the lineage side of the report
+bounded while still surfacing whether ancestry depth is bunching up or
+staying distributed.
+
+### mean
+
+```ts
+mean(
+  values: number[],
+): number
+```
+
+Compute the arithmetic mean of a numeric array.
+
+The diversity report uses this helper for the direct summary columns such as
+average lineage depth, average node count, average connection count, and the
+mean entropy across genomes.
+
+Parameters:
+- `values` - - Values to average.
+
+Returns: Arithmetic mean, or `0` when the array is empty.
+
+### variance
+
+```ts
+variance(
+  values: number[],
+): number
+```
+
+Compute the population variance of a numeric array.
+
+Variance complements the raw averages by showing whether the population is
+staying structurally tight or spreading into a wider range of topology sizes.
+
+Parameters:
+- `values` - - Values to evaluate.
+
+Returns: Population variance, or `0` when the array is empty.