@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -35,6 +35,22 @@ flowchart TD
 
 ## neat/lineage/core/lineage.types.ts
 
+### AncestorQueueEntry
+
+Queue entry used during breadth-first ancestor traversal.
+
+Each entry records which ancestor id is being explored, how deep that
+ancestor sits relative to the original genome, and an optional cached genome
+reference so later traversal steps can enqueue that ancestor's parents.
+
+### GenomeIndexPair
+
+Index pair representing one sampled genome comparison.
+
+The lineage uniqueness metric does not compare every possible pair in large
+populations. Instead it samples a bounded set of pairs, then asks how much
+recent ancestry overlaps inside each comparison.
+
 ### GenomeLike
 
 Minimal genome shape used by lineage helpers.
@@ -62,22 +78,6 @@ The population supplies the ancestry graph to inspect. The RNG provider keeps
 sampled uniqueness deterministic so the same run can replay the same sampled
 comparisons during tests or exported-state debugging.
 
-### GenomeIndexPair
-
-Index pair representing one sampled genome comparison.
-
-The lineage uniqueness metric does not compare every possible pair in large
-populations. Instead it samples a bounded set of pairs, then asks how much
-recent ancestry overlaps inside each comparison.
-
-### AncestorQueueEntry
-
-Queue entry used during breadth-first ancestor traversal.
-
-Each entry records which ancestor id is being explored, how deep that
-ancestor sits relative to the original genome, and an optional cached genome
-reference so later traversal steps can enqueue that ancestor's parents.
-
 ## neat/lineage/core/lineage.core.ts
 
 Lineage-analysis mechanics used by NEAT ancestry helpers.
@@ -119,46 +119,24 @@ flowchart TD
   compare --> mean[Mean ancestor uniqueness]:::accent
 ```
 
-### normalizeParentIds
-
-```ts
-normalizeParentIds(
-  value: GenomeLike,
-): number[]
-```
-
-Normalize the parent ID list for a genome.
-
-This helper is the first seam in the pipeline: it turns "maybe has lineage
-metadata" into a guaranteed array shape so the traversal code never needs to
-branch on missing parent storage.
-
-Parameters:
-- `value` - - Genome to read parents from.
-
-Returns: Parent ID list, or an empty array when absent.
-
-### createInitialQueue
+### calculateMaxSamplePairs
 
 ```ts
-createInitialQueue(
-  parentIds: number[],
-  population: GenomeLike[],
-): AncestorQueueEntry[]
+calculateMaxSamplePairs(
+  size: number,
+): number
 ```
 
-Create the initial breadth-first queue from direct parent IDs.
+Compute the upper bound on sampled genome pairs.
 
-This queue is the bridge between stored lineage metadata and the traversal
-loop. Depth starts at the direct-parent layer because lineage uniqueness is a
-recent-family metric first; later queue expansion can then walk outward while
-still respecting the bounded depth window.
+The uniqueness metric is intentionally sampled rather than exhaustive. This
+helper keeps that budget honest by capping the requested sample count to both
+the true combinatorial maximum and the chapter's global runtime limit.
 
 Parameters:
-- `parentIds` - - Direct parent IDs to seed the queue.
-- `population` - - Current population for ID lookups.
+- `size` - - Population size.
 
-Returns: Queue entries at depth 1.
+Returns: Sample cap respecting both the combinatorial count and the global limit.
 
 ### collectAncestorIds
 
@@ -186,6 +164,71 @@ Parameters:
 
 Returns: Unique ancestor IDs encountered within the depth window.
 
+### computeAverageDistance
+
+```ts
+computeAverageDistance(
+  distances: number[],
+): number
+```
+
+Compute the mean ancestor distance across sampled pairs.
+
+This is the final fold from many local comparisons into one controller-facing
+scalar. Rounding is intentional: the value is meant to be a stable telemetry
+and adaptive-policy signal rather than a high-precision scientific output.
+
+Parameters:
+- `distances` - - Pairwise Jaccard distances.
+
+Returns: Mean distance rounded to the configured decimal precision.
+
+### computePairDistances
+
+```ts
+computePairDistances(
+  pairs: GenomeIndexPair[],
+  population: GenomeLike[],
+  buildAncestorSet: (genome: GenomeLike) => Set<number>,
+): number[]
+```
+
+Compute Jaccard distances for sampled genome pairs.
+
+This stage turns sampled pair indices into actual lineage evidence. Each pair
+is resolved to two genomes, each genome is expanded into a shallow ancestor
+set, and those sets are compared using Jaccard distance so the final metric
+reflects overlap rather than raw ancestor counts.
+
+Parameters:
+- `pairs` - - Sampled index pairs.
+- `population` - - Current population.
+- `buildAncestorSet` - - Helper that builds ancestor sets for genomes.
+
+Returns: Jaccard distances for valid pairs.
+
+### createInitialQueue
+
+```ts
+createInitialQueue(
+  parentIds: number[],
+  population: GenomeLike[],
+): AncestorQueueEntry[]
+```
+
+Create the initial breadth-first queue from direct parent IDs.
+
+This queue is the bridge between stored lineage metadata and the traversal
+loop. Depth starts at the direct-parent layer because lineage uniqueness is a
+recent-family metric first; later queue expansion can then walk outward while
+still respecting the bounded depth window.
+
+Parameters:
+- `parentIds` - - Direct parent IDs to seed the queue.
+- `population` - - Current population for ID lookups.
+
+Returns: Queue entries at depth 1.
+
 ### hasMinimumPopulation
 
 ```ts
@@ -205,24 +248,24 @@ Parameters:
 
 Returns: `true` when at least two genomes exist.
 
-### calculateMaxSamplePairs
+### normalizeParentIds
 
 ```ts
-calculateMaxSamplePairs(
-  size: number,
-): number
+normalizeParentIds(
+  value: GenomeLike,
+): number[]
 ```
 
-Compute the upper bound on sampled genome pairs.
+Normalize the parent ID list for a genome.
 
-The uniqueness metric is intentionally sampled rather than exhaustive. This
-helper keeps that budget honest by capping the requested sample count to both
-the true combinatorial maximum and the chapter's global runtime limit.
+This helper is the first seam in the pipeline: it turns "maybe has lineage
+metadata" into a guaranteed array shape so the traversal code never needs to
+branch on missing parent storage.
 
 Parameters:
-- `size` - - Population size.
+- `value` - - Genome to read parents from.
 
-Returns: Sample cap respecting both the combinatorial count and the global limit.
+Returns: Parent ID list, or an empty array when absent.
 
 ### sampleGenomePairs
 
@@ -247,46 +290,3 @@ Parameters:
 - `rngFactory` - - RNG provider used to obtain a random function.
 
 Returns: Array of sampled index pairs.
-
-### computePairDistances
-
-```ts
-computePairDistances(
-  pairs: GenomeIndexPair[],
-  population: GenomeLike[],
-  buildAncestorSet: (genome: GenomeLike) => Set<number>,
-): number[]
-```
-
-Compute Jaccard distances for sampled genome pairs.
-
-This stage turns sampled pair indices into actual lineage evidence. Each pair
-is resolved to two genomes, each genome is expanded into a shallow ancestor
-set, and those sets are compared using Jaccard distance so the final metric
-reflects overlap rather than raw ancestor counts.
-
-Parameters:
-- `pairs` - - Sampled index pairs.
-- `population` - - Current population.
-- `buildAncestorSet` - - Helper that builds ancestor sets for genomes.
-
-Returns: Jaccard distances for valid pairs.
-
-### computeAverageDistance
-
-```ts
-computeAverageDistance(
-  distances: number[],
-): number
-```
-
-Compute the mean ancestor distance across sampled pairs.
-
-This is the final fold from many local comparisons into one controller-facing
-scalar. Rounding is intentional: the value is meant to be a stable telemetry
-and adaptive-policy signal rather than a high-precision scientific output.
-
-Parameters:
-- `distances` - - Pairwise Jaccard distances.
-
-Returns: Mean distance rounded to the configured decimal precision.

package/src/neat/multiobjective/category/README.md

@@ -33,38 +33,33 @@ flowchart TD
 
 ## neat/multiobjective/category/multiobjective.category.ts
 
-### processMultiObjective
+### adaptDominanceEpsilon
 
 ```ts
-processMultiObjective(
+adaptDominanceEpsilon(
   internal: NeatControllerForEvolution,
-  config: { paretoArchiveMax: number; targetFrontMin: number; targetFrontUpperRatio: number; targetFrontLowerRatio: number; defaultEpsilonAdjust: number; defaultEpsilonMin: number; defaultEpsilonMax: number; defaultEpsilonCooldown: number; pruneWindowDefault: number; pruneRangeEpsDefault: number; },
+  paretoFronts: GenomeWithMetadata[][],
+  config: { targetFrontMin: number; targetFrontUpperRatio: number; targetFrontLowerRatio: number; defaultEpsilonAdjust: number; defaultEpsilonMin: number; defaultEpsilonMax: number; defaultEpsilonCooldown: number; },
 ): void
 ```
 
-Apply the multi-objective evolution policy for the current generation.
-
-This is the bridge between the generic Pareto-ranking helpers and the larger
-evolve loop. It runs the ranking pass, reorders the live population by
-`(rank, crowding)`, snapshots the best fronts for telemetry, optionally
-adjusts dominance epsilon to keep the frontier size useful, and prunes
-objectives that have gone flat for long enough to stop influencing search.
+Adapt dominance epsilon based on Pareto front size.
 
-Conceptually, this helper owns the post-ranking reaction layer:
-1. compute fresh fronts and crowding evidence,
-2. convert that evidence into stable population order,
-3. persist compact history for later reads,
-4. tune or prune long-lived multi-objective policy state.
+This is the controller's feedback loop for keeping the leading front in a
+useful size band. If too many genomes land on the first front, epsilon grows
+so future dominance becomes stricter. If too few survive, epsilon shrinks so
+the controller relaxes back toward a broader competitive set.
 
-The function updates the controller in place because evolve needs the new
-ordering, archive state, and adaptive settings immediately for the rest of
-the generation loop.
+The cooldown gate matters because the frontier can oscillate from one
+generation to the next. Waiting a few generations between adjustments keeps
+the threshold from chattering.
 
 Parameters:
 - `internal` - - NEAT controller instance.
-- `config` - - Multi-objective tuning constants.
+- `paretoFronts` - - Non-dominated fronts.
+- `config` - - Epsilon tuning constants.
 
-Returns: Nothing. The controller is updated in place.
+Returns: void.
 
 ### computeCrowdingDistances
 
@@ -97,27 +92,64 @@ Parameters:
 
 Returns: crowding distances aligned with population order.
 
-### sortPopulationByPareto
+### processMultiObjective
 
 ```ts
-sortPopulationByPareto(
+processMultiObjective(
   internal: NeatControllerForEvolution,
-  populationSnapshot: GenomeWithMetadata[],
-  crowdingDistances: number[],
+  config: { paretoArchiveMax: number; targetFrontMin: number; targetFrontUpperRatio: number; targetFrontLowerRatio: number; defaultEpsilonAdjust: number; defaultEpsilonMin: number; defaultEpsilonMax: number; defaultEpsilonCooldown: number; pruneWindowDefault: number; pruneRangeEpsDefault: number; },
 ): void
 ```
 
-Sort population by Pareto rank and crowding distance.
+Apply the multi-objective evolution policy for the current generation.
 
-The ordering rule is lexicographic: lower `_moRank` wins first, then higher
-crowding distance wins within the same front. This keeps the live population
-aligned with NSGA-II style selection pressure while preserving one stable
-index map from the pre-sort snapshot to the later crowding write-back.
+This is the bridge between the generic Pareto-ranking helpers and the larger
+evolve loop. It runs the ranking pass, reorders the live population by
+`(rank, crowding)`, snapshots the best fronts for telemetry, optionally
+adjusts dominance epsilon to keep the frontier size useful, and prunes
+objectives that have gone flat for long enough to stop influencing search.
+
+Conceptually, this helper owns the post-ranking reaction layer:
+1. compute fresh fronts and crowding evidence,
+2. convert that evidence into stable population order,
+3. persist compact history for later reads,
+4. tune or prune long-lived multi-objective policy state.
+
+The function updates the controller in place because evolve needs the new
+ordering, archive state, and adaptive settings immediately for the rest of
+the generation loop.
 
 Parameters:
 - `internal` - - NEAT controller instance.
-- `populationSnapshot` - - Current population reference.
-- `crowdingDistances` - - Crowding distances aligned with population order.
+- `config` - - Multi-objective tuning constants.
+
+Returns: Nothing. The controller is updated in place.
+
+### pruneInactiveObjectives
+
+```ts
+pruneInactiveObjectives(
+  internal: NeatControllerForEvolution,
+  config: { pruneWindowDefault: number; pruneRangeEpsDefault: number; },
+): void
+```
+
+Prune objectives that have collapsed ranges over a window.
+
+This helper removes objectives that are no longer contributing meaningful
+discrimination across the current population. An objective is considered
+structurally inactive when its observed range stays below the configured
+epsilon for enough consecutive generations.
+
+The pruning pass is intentionally conservative:
+- protected objectives such as `fitness` and `complexity` are never removed,
+- stale counters must persist for a full window before removal,
+- objective-cache invalidation happens only after an actual removal so later
+  reads rebuild the descriptor list from the surviving objective set.
+
+Parameters:
+- `internal` - - NEAT controller instance.
+- `config` - - Pruning constants.
 
 Returns: void.
 
@@ -151,58 +183,26 @@ Parameters:
 
 Returns: void.
 
-### adaptDominanceEpsilon
-
-```ts
-adaptDominanceEpsilon(
-  internal: NeatControllerForEvolution,
-  paretoFronts: GenomeWithMetadata[][],
-  config: { targetFrontMin: number; targetFrontUpperRatio: number; targetFrontLowerRatio: number; defaultEpsilonAdjust: number; defaultEpsilonMin: number; defaultEpsilonMax: number; defaultEpsilonCooldown: number; },
-): void
-```
-
-Adapt dominance epsilon based on Pareto front size.
-
-This is the controller's feedback loop for keeping the leading front in a
-useful size band. If too many genomes land on the first front, epsilon grows
-so future dominance becomes stricter. If too few survive, epsilon shrinks so
-the controller relaxes back toward a broader competitive set.
-
-The cooldown gate matters because the frontier can oscillate from one
-generation to the next. Waiting a few generations between adjustments keeps
-the threshold from chattering.
-
-Parameters:
-- `internal` - - NEAT controller instance.
-- `paretoFronts` - - Non-dominated fronts.
-- `config` - - Epsilon tuning constants.
-
-Returns: void.
-
-### pruneInactiveObjectives
+### sortPopulationByPareto
 
 ```ts
-pruneInactiveObjectives(
+sortPopulationByPareto(
   internal: NeatControllerForEvolution,
-  config: { pruneWindowDefault: number; pruneRangeEpsDefault: number; },
+  populationSnapshot: GenomeWithMetadata[],
+  crowdingDistances: number[],
 ): void
 ```
 
-Prune objectives that have collapsed ranges over a window.
-
-This helper removes objectives that are no longer contributing meaningful
-discrimination across the current population. An objective is considered
-structurally inactive when its observed range stays below the configured
-epsilon for enough consecutive generations.
+Sort population by Pareto rank and crowding distance.
 
-The pruning pass is intentionally conservative:
-- protected objectives such as `fitness` and `complexity` are never removed,
-- stale counters must persist for a full window before removal,
-- objective-cache invalidation happens only after an actual removal so later
-  reads rebuild the descriptor list from the surviving objective set.
+The ordering rule is lexicographic: lower `_moRank` wins first, then higher
+crowding distance wins within the same front. This keeps the live population
+aligned with NSGA-II style selection pressure while preserving one stable
+index map from the pre-sort snapshot to the later crowding write-back.
 
 Parameters:
 - `internal` - - NEAT controller instance.
-- `config` - - Pruning constants.
+- `populationSnapshot` - - Current population reference.
+- `crowdingDistances` - - Crowding distances aligned with population order.
 
 Returns: void.