@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -52,445 +52,484 @@ they reveal about the search?"
 
 ## neat/telemetry/metrics/telemetry.metrics.ts
 
-### getCachedEntropy
+### applyComplexityStatsMonoObjective
 
 ```ts
-getCachedEntropy(
-  generation: number | undefined,
-  entropyGraph: Record<string, unknown>,
-): number | undefined
+applyComplexityStatsMonoObjective(
+  telemetryContext: { _lastMeanNodes?: number | undefined; _lastMeanConns?: number | undefined; },
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  populationSnapshot: GenomeDetailed[],
+  entry: TelemetryEntryRecord,
+): void
 ```
 
-Read a cached entropy value if it exists and belongs to the current
-generation.
+Attach complexity stats for mono-objective mode.
 
 Parameters:
-- `generation` - - Current generation number.
-- `entropyGraph` - - Genome-like graph object.
-
-Returns: Cached entropy number, or undefined when not available.
+- `telemetryContext` - - Neat-like context with population state.
+- `telemetryOptions` - - Options controlling complexity telemetry.
+- `entry` - - Telemetry entry to update.
 
-### computeDegreeCounts
+### applyComplexityStatsMultiObjective
 
 ```ts
-computeDegreeCounts(
-  entropyGraph: { nodes: { geneId: number; }[]; connections: { from: { geneId: number; }; to: { geneId: number; }; enabled: boolean; }[]; },
-): Record<number, number>
+applyComplexityStatsMultiObjective(
+  telemetryContext: { _lastMeanNodes?: number | undefined; _lastMeanConns?: number | undefined; },
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  population: GenomeDetailed[],
+  entry: TelemetryEntryRecord,
+): void
 ```
 
-Compute per-node degree counts for enabled connections.
+Attach complexity stats for multi-objective mode.
 
 Parameters:
-- `entropyGraph` - - Genome-like graph object.
-
-Returns: Map geneId -> degree count.
+- `telemetryContext` - - Neat-like context with population state.
+- `telemetryOptions` - - Options controlling complexity telemetry.
+- `population` - - Population snapshot.
+- `entry` - - Telemetry entry to update.
 
-### buildDegreeHistogram
+### applyFastModeDefaults
 
 ```ts
-buildDegreeHistogram(
-  counts: Record<number, number>,
-): Record<number, number>
+applyFastModeDefaults(
+  telemetryContext: { _fastModeTuned?: boolean | undefined; },
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+): void
 ```
 
-Build a histogram of degree frequencies from a degree-count table.
+Apply fast-mode tuning to diversity sampling and novelty defaults.
 
 Parameters:
-- `counts` - - Map geneId -> degree count.
-
-Returns: Map degree -> number of nodes with that degree.
+- `telemetryContext` - - Context object storing fast-mode tuning flag.
+- `telemetryOptions` - - Options with diversity and novelty settings.
 
-### computeEntropyFromHistogram
+### applyHypervolumeTelemetry
 
 ```ts
-computeEntropyFromHistogram(
-  histogram: Record<number, number>,
-  totalNodes: number,
-): number
+applyHypervolumeTelemetry(
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  hyperVolumeProxy: number,
+  entry: TelemetryEntryRecord,
+): void
 ```
 
-Compute entropy from a degree-frequency histogram.
+Attach hypervolume scalar when requested.
 
 Parameters:
-- `histogram` - - Map degree -> number of nodes.
-- `totalNodes` - - Total node count used to normalize into probabilities.
-
-Returns: Entropy value (non-negative).
+- `telemetryOptions` - - Options controlling telemetry fields.
+- `hyperVolumeProxy` - - Hypervolume proxy value.
+- `entry` - - Telemetry entry to update.
 
-### setCachedEntropy
+### applyLineageStatsMonoObjective
 
 ```ts
-setCachedEntropy(
-  generation: number | undefined,
-  entropyGraph: Record<string, unknown>,
-  entropyValue: number,
+applyLineageStatsMonoObjective(
+  telemetryContext: { _lineageEnabled?: boolean | undefined; _getRNG?: (() => () => number) | undefined; _lastMeanDepth?: number | undefined; _prevInbreedingCount?: number | undefined; },
+  populationSnapshot: GenomeDetailed[],
+  entry: TelemetryEntryRecord,
 ): void
 ```
 
-Cache an entropy value for the current generation on the graph object.
+Apply lineage stats for mono-objective mode using sampled ancestors.
 
 Parameters:
-- `generation` - - Current generation number.
-- `entropyGraph` - - Genome-like graph object.
-- `entropyValue` - - Entropy value to cache.
+- `telemetryContext` - - Neat-like context with lineage settings.
+- `population` - - Population snapshot.
+- `entry` - - Telemetry entry to update.
 
-### getTelemetryCoreSnapshot
+### applyLineageStatsMultiObjective
 
 ```ts
-getTelemetryCoreSnapshot(
-  sourceEntry: Record<string, unknown>,
-  fields: TelemetryCoreFields,
-): Partial<Record<string, unknown>>
+applyLineageStatsMultiObjective(
+  telemetryContext: { _lineageEnabled?: boolean | undefined; _getRNG?: (() => () => number) | undefined; _lastMeanDepth?: number | undefined; _prevInbreedingCount?: number | undefined; },
+  population: GenomeDetailed[],
+  entry: TelemetryEntryRecord,
+): void
 ```
 
-Build a snapshot of the core telemetry fields present on the entry; does
-not mutate the source entry.
+Apply lineage stats for multi-objective mode using ancestor uniqueness.
 
 Parameters:
-- `sourceEntry` - - Source telemetry object.
-- `fields` - - Core telemetry field keys to preserve.
-
-Returns: Shallow snapshot of core fields that exist on the entry.
+- `telemetryContext` - - Neat-like context with lineage settings.
+- `population` - - Population snapshot.
+- `entry` - - Telemetry entry to update.
 
-### stripUnselectedTelemetryKeys
+### applyObjectiveAges
 
 ```ts
-stripUnselectedTelemetryKeys(
-  sourceEntry: Record<string, unknown>,
-  selection: Set<string>,
-  fields: TelemetryCoreFields,
-): Record<string, unknown>
+applyObjectiveAges(
+  telemetryContext: { _objectiveAges?: Map<string, number> | undefined; },
+  entry: TelemetryEntryRecord,
+): void
 ```
 
-Remove non-core keys that are not whitelisted by the selection set.
-Mutates the provided entry in-place for efficiency.
+Apply objective age snapshots to the entry.
 
 Parameters:
-- `sourceEntry` - - Telemetry entry being filtered.
-- `selection` - - Whitelist of additional telemetry keys.
-- `fields` - - Core telemetry field keys that must be preserved.
-
-Returns: The same entry reference after filtering.
+- `telemetryContext` - - Neat-like context with objective ages.
+- `entry` - - Telemetry entry to update.
 
-### mergeTelemetryCoreFields
+### applyObjectiveEvents
 
 ```ts
-mergeTelemetryCoreFields(
-  sourceEntry: Record<string, unknown>,
-  coreSnapshot: Partial<Record<string, unknown>>,
-): Record<string, unknown>
+applyObjectiveEvents(
+  telemetryContext: { _pendingObjectiveAdds?: string[] | undefined; _pendingObjectiveRemoves?: string[] | undefined; _objectiveEvents?: ObjectiveEvent[] | undefined; },
+  entry: TelemetryEntryRecord,
+  generation: number,
+): void
 ```
 
-Re-attach core fields to the filtered entry.
-Mutates the entry so the caller keeps the original reference.
+Apply and flush objective lifecycle events.
 
 Parameters:
-- `sourceEntry` - - Filtered telemetry entry to update.
-- `coreSnapshot` - - Snapshot of core fields to ensure presence.
+- `telemetryContext` - - Neat-like context holding objective events.
+- `entry` - - Telemetry entry to update.
+- `generation` - - Generation index for event records.
 
-Returns: The same entry reference with core fields restored.
+### applyObjectiveImportance
 
-### safelyApplyTelemetrySelect
+```ts
+applyObjectiveImportance(
+  telemetryContext: { _lastObjImportance?: ObjImportance | undefined; },
+  entry: TelemetryEntryRecord,
+): void
+```
+
+Apply the most recent objective importance snapshot.
+
+Parameters:
+- `telemetryContext` - - Neat-like context with objective importance.
+- `entry` - - Telemetry entry to update.
+
+### applyObjectivesSnapshot
 
 ```ts
-safelyApplyTelemetrySelect(
-  telemetryContext: TContext,
-  telemetryEntry: TelemetryEntry,
-  applyTelemetrySelectFn: (this: TContext, entry: Record<string, unknown>) => Record<string, unknown>,
+applyObjectivesSnapshot(
+  telemetryContext: { _getObjectives?: (() => { key: string; }[]) | undefined; },
+  entry: TelemetryEntryRecord,
 ): void
 ```
 
-Apply telemetry selection while swallowing selection errors.
+Apply objectives list snapshot (keys only).
 
 Parameters:
-- `telemetryContext` - - Neat-like context with telemetry selection.
-- `telemetryEntry` - - Entry to filter in place.
-- `applyTelemetrySelectFn` - - Selection helper to invoke.
+- `telemetryContext` - - Neat-like context with objective provider.
+- `entry` - - Telemetry entry to update.
 
-### applyFastModeDefaults
+### applyPerformanceStats
 
 ```ts
-applyFastModeDefaults(
-  telemetryContext: { _fastModeTuned?: boolean | undefined; },
+applyPerformanceStats(
+  telemetryContext: { _lastEvalDuration?: number | undefined; _lastEvolveDuration?: number | undefined; },
   telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  entry: TelemetryEntryRecord,
 ): void
 ```
 
-Apply fast-mode tuning to diversity sampling and novelty defaults.
+Attach performance stats when configured.
 
 Parameters:
-- `telemetryContext` - - Context object storing fast-mode tuning flag.
-- `telemetryOptions` - - Options with diversity and novelty settings.
+- `telemetryContext` - - Neat-like context with performance data.
+- `telemetryOptions` - - Options controlling performance telemetry.
+- `entry` - - Telemetry entry to update.
 
-### computeCompatibilityStats
+### applyRngState
 
 ```ts
-computeCompatibilityStats(
-  genomes: TelemetryGenome[],
-  size: number,
-  pairSampleCount: number,
-  rngFactoryFn: () => () => number,
-  compatibilityDistance: ((a: TelemetryGenome, b: TelemetryGenome) => number) | undefined,
-): { meanCompat: number; varCompat: number; }
+applyRngState(
+  telemetryContext: { _rngState?: unknown; },
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  entry: TelemetryEntryRecord,
+): void
 ```
 
-Compute pairwise compatibility statistics via sampling.
+Attach RNG state when configured.
 
 Parameters:
-- `genomes` - - Population snapshot.
-- `size` - - Population size.
-- `pairSampleCount` - - Number of pairs to sample.
-- `rngFactoryFn` - - RNG factory returning a uniform random function.
-- `compatibilityDistance` - - Optional compatibility distance function.
+- `telemetryContext` - - Neat-like context with RNG state.
+- `telemetryOptions` - - Options controlling RNG telemetry.
+- `entry` - - Telemetry entry to update.
 
-Returns: Mean and variance of sampled compatibilities.
+### applySpeciesAllocation
 
-### computeEntropyStats
+```ts
+applySpeciesAllocation(
+  telemetryContext: { _lastOffspringAlloc?: SpeciesAlloc[] | undefined; },
+  entry: TelemetryEntryRecord,
+): void
+```
+
+Apply per-species offspring allocation snapshot.
+
+Parameters:
+- `telemetryContext` - - Neat-like context with allocation snapshot.
+- `entry` - - Telemetry entry to update.
+
+### buildComplexityEntry
 
 ```ts
-computeEntropyStats(
-  genomes: TelemetryGenome[],
-  structuralEntropyFn: (genome: TelemetryGenome) => number,
-): { meanEntropy: number; varEntropy: number; }
+buildComplexityEntry(
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  meanCounts: { meanNodes: number; meanConns: number; },
+  maxCounts: { maxNodes: number; maxConns: number; },
+  meanEnabledRatio: number,
+  growthValues: { growthNodes: number; growthConns: number; },
+): { meanNodes: number; meanConns: number; maxNodes: number; maxConns: number; meanEnabledRatio: number; growthNodes: number; growthConns: number; budgetMaxNodes: number; budgetMaxConns: number; }
 ```
 
-Compute structural entropy mean and variance across the population.
+Build the complexity entry payload for multi-objective mode.
 
 Parameters:
-- `genomes` - - Population snapshot.
-- `structuralEntropyFn` - - Function to compute entropy for a genome.
+- `telemetryOptions` - - Options controlling complexity telemetry.
+- `meanCounts` - - Mean node/connection counts.
+- `maxCounts` - - Max node/connection counts.
+- `meanEnabledRatio` - - Mean enabled ratio.
+- `growthValues` - - Growth deltas.
 
-Returns: Mean and variance of entropy values.
+Returns: Complexity entry payload.
 
-### computeGraphletEntropy
+### buildDegreeHistogram
 
 ```ts
-computeGraphletEntropy(
-  genomes: TelemetryGenome[],
-  size: number,
-  graphletSampleCount: number,
-  rngFactoryFn: () => () => number,
-): number
+buildDegreeHistogram(
+  counts: Record<number, number>,
+): Record<number, number>
 ```
 
-Sample graphlet motifs and compute entropy over their edge counts.
+Build a histogram of degree frequencies from a degree-count table.
 
 Parameters:
-- `genomes` - - Population snapshot.
-- `size` - - Population size.
-- `graphletSampleCount` - - Number of graphlets to sample.
-- `rngFactoryFn` - - RNG factory returning a uniform random function.
+- `counts` - - Map geneId -> degree count.
 
-Returns: Graphlet entropy value.
+Returns: Map degree -> number of nodes with that degree.
 
-### pickDistinctIndices
+### buildLineageContext
 
 ```ts
-pickDistinctIndices(
-  upperBound: number,
-  count: number,
-  rng: () => number,
-): number[]
+buildLineageContext(
+  context: { _getRNG?: (() => () => number) | undefined; },
+  populationSnapshot: GenomeDetailed[],
+): NeatLineageContext
 ```
 
-Pick a fixed number of distinct random indices.
+Build a lineage helper context for ancestor operations.
 
 Parameters:
-- `upperBound` - - Exclusive upper bound for random indices.
-- `count` - - Number of distinct indices to pick.
-- `rng` - - RNG function returning values in [0,1).
+- `context` - - Neat-like context with RNG helpers.
+- `populationSnapshot` - - Population snapshot.
 
-Returns: Array of distinct indices.
+Returns: Lineage helper context.
 
-### countEnabledEdges
+### buildLineageEntry
 
 ```ts
-countEnabledEdges(
-  genome: TelemetryGenome,
-  selectedNodes: NodeLike[],
-): number
+buildLineageEntry(
+  context: { _prevInbreedingCount?: number | undefined; },
+  bestGenomeSnapshot: GenomeDetailed,
+  meanDepthValue: number,
+  ancestorUniquenessScore: number,
+): { parents: number[]; depthBest: number; meanDepth: number; inbreeding: number; ancestorUniq: number; }
 ```
 
-Count enabled edges between the selected nodes in a genome.
+Build the lineage entry payload.
 
 Parameters:
-- `genome` - - Genome with connections to inspect.
-- `selectedNodes` - - Nodes forming the graphlet sample.
+- `context` - - Neat-like context with lineage info.
+- `bestGenomeSnapshot` - - Best genome snapshot.
+- `meanDepthValue` - - Mean lineage depth.
+- `ancestorUniquenessScore` - - Ancestor uniqueness score.
 
-Returns: Edge count capped at 3.
+Returns: Lineage entry payload.
 
-### computeOperatorStatsSnapshot
+### collectDepths
 
 ```ts
-computeOperatorStatsSnapshot(
-  operatorStats: OperatorStatsMap | undefined,
-): { op: string; succ: number; att: number; }[]
+collectDepths(
+  populationSnapshot: GenomeDetailed[],
+): number[]
 ```
 
-Snapshot operator statistics into a telemetry-friendly array.
+Collect depth values for the current population.
 
 Parameters:
-- `operatorStats` - - Operator stats map (opName -> success/attempts).
+- `populationSnapshot` - - Population snapshot.
 
-Returns: Operator stats snapshot array.
+Returns: Array of depth values (defaults to 0).
 
-### readOperatorStats
+### collectPopulationCounts
 
 ```ts
-readOperatorStats(
-  operatorStats: OperatorStatsMap | undefined,
-): { name: string; success: number; attempts: number; }[]
+collectPopulationCounts(
+  populationSnapshot: GenomeDetailed[],
+): { nodeCounts: number[]; connectionCounts: number[]; }
 ```
 
-Convert operator stats map into the public accessor shape.
+Collect node and connection counts for the population.
 
 Parameters:
-- `operatorStats` - - Operator stats map stored on the host.
+- `populationSnapshot` - - Population snapshot.
 
-Returns: Public operator summaries for dashboards and tests.
+Returns: Node and connection counts arrays.
 
-### computeHyperVolumeProxy
+### computeAncestorUniquenessSampled
 
 ```ts
-computeHyperVolumeProxy(
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  population: GenomeDetailed[],
+computeAncestorUniquenessSampled(
+  context: { _getRNG?: (() => () => number) | undefined; },
+  populationSnapshot: GenomeDetailed[],
 ): number
 ```
 
-Compute a hypervolume-like proxy for the Pareto front.
+Compute ancestor uniqueness using sampled Jaccard distance.
 
 Parameters:
-- `telemetryOptions` - - Options controlling complexity metric.
-- `population` - - Population snapshot.
+- `context` - - Neat-like context with RNG helpers.
+- `populationSnapshot` - - Population snapshot.
 
-Returns: Hypervolume proxy value.
+Returns: Rounded ancestor uniqueness score.
 
-### computeParetoFrontSizes
+### computeAndStoreGrowthValues
 
 ```ts
-computeParetoFrontSizes(
-  population: GenomeDetailed[],
-): number[]
+computeAndStoreGrowthValues(
+  context: { _lastMeanNodes?: number | undefined; _lastMeanConns?: number | undefined; },
+  meanCounts: { meanNodes: number; meanConns: number; },
+): { growthNodes: number; growthConns: number; }
 ```
 
-Compute sizes of early Pareto fronts.
+Compute growth values and store the latest means on the context.
 
 Parameters:
-- `population` - - Population snapshot.
+- `context` - - Neat-like context with previous mean values.
+- `meanCounts` - - Current mean node/connection counts.
 
-Returns: Array of front sizes (rank 0..4).
+Returns: Growth values for nodes and connections.
 
-### applyObjectiveImportance
+### computeCompatibilityStats
 
 ```ts
-applyObjectiveImportance(
-  telemetryContext: { _lastObjImportance?: ObjImportance | undefined; },
-  entry: TelemetryEntryRecord,
-): void
+computeCompatibilityStats(
+  genomes: TelemetryGenome[],
+  size: number,
+  pairSampleCount: number,
+  rngFactoryFn: () => () => number,
+  compatibilityDistance: ((a: TelemetryGenome, b: TelemetryGenome) => number) | undefined,
+): { meanCompat: number; varCompat: number; }
 ```
 
-Apply the most recent objective importance snapshot.
+Compute pairwise compatibility statistics via sampling.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with objective importance.
-- `entry` - - Telemetry entry to update.
+- `genomes` - - Population snapshot.
+- `size` - - Population size.
+- `pairSampleCount` - - Number of pairs to sample.
+- `rngFactoryFn` - - RNG factory returning a uniform random function.
+- `compatibilityDistance` - - Optional compatibility distance function.
 
-### applyObjectiveAges
+Returns: Mean and variance of sampled compatibilities.
+
+### computeDegreeCounts
 
 ```ts
-applyObjectiveAges(
-  telemetryContext: { _objectiveAges?: Map<string, number> | undefined; },
-  entry: TelemetryEntryRecord,
-): void
+computeDegreeCounts(
+  entropyGraph: { nodes: { geneId: number; }[]; connections: { from: { geneId: number; }; to: { geneId: number; }; enabled: boolean; }[]; },
+): Record<number, number>
 ```
 
-Apply objective age snapshots to the entry.
+Compute per-node degree counts for enabled connections.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with objective ages.
-- `entry` - - Telemetry entry to update.
+- `entropyGraph` - - Genome-like graph object.
 
-### applyObjectiveEvents
+Returns: Map geneId -> degree count.
+
+### computeEnabledRatios
 
 ```ts
-applyObjectiveEvents(
-  telemetryContext: { _pendingObjectiveAdds?: string[] | undefined; _pendingObjectiveRemoves?: string[] | undefined; _objectiveEvents?: ObjectiveEvent[] | undefined; },
-  entry: TelemetryEntryRecord,
-  generation: number,
-): void
+computeEnabledRatios(
+  populationSnapshot: GenomeDetailed[],
+): number[]
 ```
 
-Apply and flush objective lifecycle events.
+Compute enabled ratios per genome.
 
 Parameters:
-- `telemetryContext` - - Neat-like context holding objective events.
-- `entry` - - Telemetry entry to update.
-- `generation` - - Generation index for event records.
+- `populationSnapshot` - - Population snapshot.
 
-### applySpeciesAllocation
+Returns: Array of enabled ratios.
+
+### computeEntropyFromHistogram
 
 ```ts
-applySpeciesAllocation(
-  telemetryContext: { _lastOffspringAlloc?: SpeciesAlloc[] | undefined; },
-  entry: TelemetryEntryRecord,
-): void
+computeEntropyFromHistogram(
+  histogram: Record<number, number>,
+  totalNodes: number,
+): number
 ```
 
-Apply per-species offspring allocation snapshot.
+Compute entropy from a degree-frequency histogram.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with allocation snapshot.
-- `entry` - - Telemetry entry to update.
+- `histogram` - - Map degree -> number of nodes.
+- `totalNodes` - - Total node count used to normalize into probabilities.
 
-### applyObjectivesSnapshot
+Returns: Entropy value (non-negative).
+
+### computeEntropyStats
 
 ```ts
-applyObjectivesSnapshot(
-  telemetryContext: { _getObjectives?: (() => { key: string; }[]) | undefined; },
-  entry: TelemetryEntryRecord,
-): void
+computeEntropyStats(
+  genomes: TelemetryGenome[],
+  structuralEntropyFn: (genome: TelemetryGenome) => number,
+): { meanEntropy: number; varEntropy: number; }
 ```
 
-Apply objectives list snapshot (keys only).
+Compute structural entropy mean and variance across the population.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with objective provider.
-- `entry` - - Telemetry entry to update.
+- `genomes` - - Population snapshot.
+- `structuralEntropyFn` - - Function to compute entropy for a genome.
 
-### applyHypervolumeTelemetry
+Returns: Mean and variance of entropy values.
+
+### computeGraphletEntropy
 
 ```ts
-applyHypervolumeTelemetry(
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  hyperVolumeProxy: number,
-  entry: TelemetryEntryRecord,
-): void
+computeGraphletEntropy(
+  genomes: TelemetryGenome[],
+  size: number,
+  graphletSampleCount: number,
+  rngFactoryFn: () => () => number,
+): number
 ```
 
-Attach hypervolume scalar when requested.
+Sample graphlet motifs and compute entropy over their edge counts.
 
 Parameters:
-- `telemetryOptions` - - Options controlling telemetry fields.
-- `hyperVolumeProxy` - - Hypervolume proxy value.
-- `entry` - - Telemetry entry to update.
+- `genomes` - - Population snapshot.
+- `size` - - Population size.
+- `graphletSampleCount` - - Number of graphlets to sample.
+- `rngFactoryFn` - - RNG factory returning a uniform random function.
 
-### applyRngState
+Returns: Graphlet entropy value.
+
+### computeHyperVolumeProxy
 
 ```ts
-applyRngState(
-  telemetryContext: { _rngState?: unknown; },
+computeHyperVolumeProxy(
   telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  entry: TelemetryEntryRecord,
-): void
+  population: GenomeDetailed[],
+): number
 ```
 
-Attach RNG state when configured.
+Compute a hypervolume-like proxy for the Pareto front.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with RNG state.
-- `telemetryOptions` - - Options controlling RNG telemetry.
-- `entry` - - Telemetry entry to update.
+- `telemetryOptions` - - Options controlling complexity metric.
+- `population` - - Population snapshot.
+
+Returns: Hypervolume proxy value.
 
 ### computeLineageStats
 
@@ -515,71 +554,35 @@ Parameters:
 
 Returns: Lineage mean depth and pairwise distance.
 
-### applyLineageStatsMultiObjective
-
-```ts
-applyLineageStatsMultiObjective(
-  telemetryContext: { _lineageEnabled?: boolean | undefined; _getRNG?: (() => () => number) | undefined; _lastMeanDepth?: number | undefined; _prevInbreedingCount?: number | undefined; },
-  population: GenomeDetailed[],
-  entry: TelemetryEntryRecord,
-): void
-```
-
-Apply lineage stats for multi-objective mode using ancestor uniqueness.
-
-Parameters:
-- `telemetryContext` - - Neat-like context with lineage settings.
-- `population` - - Population snapshot.
-- `entry` - - Telemetry entry to update.
-
-### applyLineageStatsMonoObjective
-
-```ts
-applyLineageStatsMonoObjective(
-  telemetryContext: { _lineageEnabled?: boolean | undefined; _getRNG?: (() => () => number) | undefined; _lastMeanDepth?: number | undefined; _prevInbreedingCount?: number | undefined; },
-  populationSnapshot: GenomeDetailed[],
-  entry: TelemetryEntryRecord,
-): void
-```
-
-Apply lineage stats for mono-objective mode using sampled ancestors.
-
-Parameters:
-- `telemetryContext` - - Neat-like context with lineage settings.
-- `population` - - Population snapshot.
-- `entry` - - Telemetry entry to update.
-
-### isLineageEligible
+### computeMaxCounts
 
 ```ts
-isLineageEligible(
-  context: { _lineageEnabled?: boolean | undefined; },
-  populationSnapshot: GenomeDetailed[],
-): boolean
+computeMaxCounts(
+  counts: { nodeCounts: number[]; connectionCounts: number[]; },
+): { maxNodes: number; maxConns: number; }
 ```
 
-Check whether lineage metrics should be computed.
+Compute max node and connection counts.
 
 Parameters:
-- `context` - - Neat-like context with lineage flag.
-- `populationSnapshot` - - Population snapshot to validate.
+- `counts` - - Node and connection counts arrays.
 
-Returns: True when lineage stats should be computed.
+Returns: Max node and connection counts.
 
-### collectDepths
+### computeMeanCounts
 
 ```ts
-collectDepths(
-  populationSnapshot: GenomeDetailed[],
-): number[]
+computeMeanCounts(
+  counts: { nodeCounts: number[]; connectionCounts: number[]; },
+): { meanNodes: number; meanConns: number; }
 ```
 
-Collect depth values for the current population.
+Compute mean node and connection counts.
 
 Parameters:
-- `populationSnapshot` - - Population snapshot.
+- `counts` - - Node and connection counts arrays.
 
-Returns: Array of depth values (defaults to 0).
+Returns: Mean node and connection counts.
 
 ### computeMeanDepth
 
@@ -596,39 +599,35 @@ Parameters:
 
 Returns: Mean depth value.
 
-### computeAncestorUniquenessSampled
+### computeMeanEnabledRatio
 
 ```ts
-computeAncestorUniquenessSampled(
-  context: { _getRNG?: (() => () => number) | undefined; },
-  populationSnapshot: GenomeDetailed[],
+computeMeanEnabledRatio(
+  enabledRatios: number[],
 ): number
 ```
 
-Compute ancestor uniqueness using sampled Jaccard distance.
+Compute mean of enabled ratios.
 
 Parameters:
-- `context` - - Neat-like context with RNG helpers.
-- `populationSnapshot` - - Population snapshot.
+- `enabledRatios` - - Enabled ratios per genome.
 
-Returns: Rounded ancestor uniqueness score.
+Returns: Mean enabled ratio.
 
-### pickDistinctPairIndices
+### computeOperatorStatsSnapshot
 
 ```ts
-pickDistinctPairIndices(
-  context: { _getRNG?: (() => () => number) | undefined; },
-  populationSize: number,
-): { firstIndex: number; secondIndex: number; }
+computeOperatorStatsSnapshot(
+  operatorStats: OperatorStatsMap | undefined,
+): { op: string; succ: number; att: number; }[]
 ```
 
-Pick two distinct indices using the context RNG.
+Snapshot operator statistics into a telemetry-friendly array.
 
 Parameters:
-- `context` - - Neat-like context with RNG factory.
-- `populationSize` - - Population size for index bounds.
+- `operatorStats` - - Operator stats map (opName -> success/attempts).
 
-Returns: Pair of distinct indices.
+Returns: Operator stats snapshot array.
 
 ### computePairJaccardDistance
 
@@ -651,22 +650,20 @@ Parameters:
 
 Returns: Jaccard distance or undefined when both sets are empty.
 
-### buildLineageContext
-
-```ts
-buildLineageContext(
-  context: { _getRNG?: (() => () => number) | undefined; },
-  populationSnapshot: GenomeDetailed[],
-): NeatLineageContext
+### computeParetoFrontSizes
+
+```ts
+computeParetoFrontSizes(
+  population: GenomeDetailed[],
+): number[]
 ```
 
-Build a lineage helper context for ancestor operations.
+Compute sizes of early Pareto fronts.
 
 Parameters:
-- `context` - - Neat-like context with RNG helpers.
-- `populationSnapshot` - - Population snapshot.
+- `population` - - Population snapshot.
 
-Returns: Lineage helper context.
+Returns: Array of front sizes (rank 0..4).
 
 ### countAncestorIntersection
 
@@ -685,195 +682,198 @@ Parameters:
 
 Returns: Intersection count.
 
-### buildLineageEntry
+### countEnabledEdges
 
 ```ts
-buildLineageEntry(
-  context: { _prevInbreedingCount?: number | undefined; },
-  bestGenomeSnapshot: GenomeDetailed,
-  meanDepthValue: number,
-  ancestorUniquenessScore: number,
-): { parents: number[]; depthBest: number; meanDepth: number; inbreeding: number; ancestorUniq: number; }
+countEnabledEdges(
+  genome: TelemetryGenome,
+  selectedNodes: NodeLike[],
+): number
 ```
 
-Build the lineage entry payload.
+Count enabled edges between the selected nodes in a genome.
 
 Parameters:
-- `context` - - Neat-like context with lineage info.
-- `bestGenomeSnapshot` - - Best genome snapshot.
-- `meanDepthValue` - - Mean lineage depth.
-- `ancestorUniquenessScore` - - Ancestor uniqueness score.
+- `genome` - - Genome with connections to inspect.
+- `selectedNodes` - - Nodes forming the graphlet sample.
 
-Returns: Lineage entry payload.
+Returns: Edge count capped at 3.
 
-### collectPopulationCounts
+### getCachedEntropy
 
 ```ts
-collectPopulationCounts(
-  populationSnapshot: GenomeDetailed[],
-): { nodeCounts: number[]; connectionCounts: number[]; }
+getCachedEntropy(
+  generation: number | undefined,
+  entropyGraph: Record<string, unknown>,
+): number | undefined
 ```
 
-Collect node and connection counts for the population.
+Read a cached entropy value if it exists and belongs to the current
+generation.
 
 Parameters:
-- `populationSnapshot` - - Population snapshot.
+- `generation` - - Current generation number.
+- `entropyGraph` - - Genome-like graph object.
 
-Returns: Node and connection counts arrays.
+Returns: Cached entropy number, or undefined when not available.
 
-### computeMeanCounts
+### getTelemetryCoreSnapshot
 
 ```ts
-computeMeanCounts(
-  counts: { nodeCounts: number[]; connectionCounts: number[]; },
-): { meanNodes: number; meanConns: number; }
+getTelemetryCoreSnapshot(
+  sourceEntry: Record<string, unknown>,
+  fields: TelemetryCoreFields,
+): Partial<Record<string, unknown>>
 ```
 
-Compute mean node and connection counts.
+Build a snapshot of the core telemetry fields present on the entry; does
+not mutate the source entry.
 
 Parameters:
-- `counts` - - Node and connection counts arrays.
+- `sourceEntry` - - Source telemetry object.
+- `fields` - - Core telemetry field keys to preserve.
 
-Returns: Mean node and connection counts.
+Returns: Shallow snapshot of core fields that exist on the entry.
 
-### computeMaxCounts
+### isLineageEligible
 
 ```ts
-computeMaxCounts(
-  counts: { nodeCounts: number[]; connectionCounts: number[]; },
-): { maxNodes: number; maxConns: number; }
+isLineageEligible(
+  context: { _lineageEnabled?: boolean | undefined; },
+  populationSnapshot: GenomeDetailed[],
+): boolean
 ```
 
-Compute max node and connection counts.
+Check whether lineage metrics should be computed.
 
 Parameters:
-- `counts` - - Node and connection counts arrays.
+- `context` - - Neat-like context with lineage flag.
+- `populationSnapshot` - - Population snapshot to validate.
 
-Returns: Max node and connection counts.
+Returns: True when lineage stats should be computed.
 
-### computeEnabledRatios
+### mergeTelemetryCoreFields
 
 ```ts
-computeEnabledRatios(
-  populationSnapshot: GenomeDetailed[],
-): number[]
+mergeTelemetryCoreFields(
+  sourceEntry: Record<string, unknown>,
+  coreSnapshot: Partial<Record<string, unknown>>,
+): Record<string, unknown>
 ```
 
-Compute enabled ratios per genome.
+Re-attach core fields to the filtered entry.
+Mutates the entry so the caller keeps the original reference.
 
 Parameters:
-- `populationSnapshot` - - Population snapshot.
+- `sourceEntry` - - Filtered telemetry entry to update.
+- `coreSnapshot` - - Snapshot of core fields to ensure presence.
 
-Returns: Array of enabled ratios.
+Returns: The same entry reference with core fields restored.
 
-### computeMeanEnabledRatio
+### pickDistinctIndices
 
 ```ts
-computeMeanEnabledRatio(
-  enabledRatios: number[],
-): number
+pickDistinctIndices(
+  upperBound: number,
+  count: number,
+  rng: () => number,
+): number[]
 ```
 
-Compute mean of enabled ratios.
+Pick a fixed number of distinct random indices.
 
 Parameters:
-- `enabledRatios` - - Enabled ratios per genome.
+- `upperBound` - - Exclusive upper bound for random indices.
+- `count` - - Number of distinct indices to pick.
+- `rng` - - RNG function returning values in [0,1).
 
-Returns: Mean enabled ratio.
+Returns: Array of distinct indices.
 
-### computeAndStoreGrowthValues
+### pickDistinctPairIndices
 
 ```ts
-computeAndStoreGrowthValues(
-  context: { _lastMeanNodes?: number | undefined; _lastMeanConns?: number | undefined; },
-  meanCounts: { meanNodes: number; meanConns: number; },
-): { growthNodes: number; growthConns: number; }
+pickDistinctPairIndices(
+  context: { _getRNG?: (() => () => number) | undefined; },
+  populationSize: number,
+): { firstIndex: number; secondIndex: number; }
 ```
 
-Compute growth values and store the latest means on the context.
+Pick two distinct indices using the context RNG.
 
 Parameters:
-- `context` - - Neat-like context with previous mean values.
-- `meanCounts` - - Current mean node/connection counts.
+- `context` - - Neat-like context with RNG factory.
+- `populationSize` - - Population size for index bounds.
 
-Returns: Growth values for nodes and connections.
+Returns: Pair of distinct indices.
 
-### buildComplexityEntry
+### readOperatorStats
 
 ```ts
-buildComplexityEntry(
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  meanCounts: { meanNodes: number; meanConns: number; },
-  maxCounts: { maxNodes: number; maxConns: number; },
-  meanEnabledRatio: number,
-  growthValues: { growthNodes: number; growthConns: number; },
-): { meanNodes: number; meanConns: number; maxNodes: number; maxConns: number; meanEnabledRatio: number; growthNodes: number; growthConns: number; budgetMaxNodes: number; budgetMaxConns: number; }
+readOperatorStats(
+  operatorStats: OperatorStatsMap | undefined,
+): { name: string; success: number; attempts: number; }[]
 ```
 
-Build the complexity entry payload for multi-objective mode.
+Convert operator stats map into the public accessor shape.
 
 Parameters:
-- `telemetryOptions` - - Options controlling complexity telemetry.
-- `meanCounts` - - Mean node/connection counts.
-- `maxCounts` - - Max node/connection counts.
-- `meanEnabledRatio` - - Mean enabled ratio.
-- `growthValues` - - Growth deltas.
+- `operatorStats` - - Operator stats map stored on the host.
 
-Returns: Complexity entry payload.
+Returns: Public operator summaries for dashboards and tests.
 
-### applyComplexityStatsMultiObjective
+### safelyApplyTelemetrySelect
 
 ```ts
-applyComplexityStatsMultiObjective(
-  telemetryContext: { _lastMeanNodes?: number | undefined; _lastMeanConns?: number | undefined; },
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  population: GenomeDetailed[],
-  entry: TelemetryEntryRecord,
+safelyApplyTelemetrySelect(
+  telemetryContext: TContext,
+  telemetryEntry: TelemetryEntry,
+  applyTelemetrySelectFn: (this: TContext, entry: Record<string, unknown>) => Record<string, unknown>,
 ): void
 ```
 
-Attach complexity stats for multi-objective mode.
+Apply telemetry selection while swallowing selection errors.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with population state.
-- `telemetryOptions` - - Options controlling complexity telemetry.
-- `population` - - Population snapshot.
-- `entry` - - Telemetry entry to update.
+- `telemetryContext` - - Neat-like context with telemetry selection.
+- `telemetryEntry` - - Entry to filter in place.
+- `applyTelemetrySelectFn` - - Selection helper to invoke.
 
-### applyComplexityStatsMonoObjective
+### setCachedEntropy
 
 ```ts
-applyComplexityStatsMonoObjective(
-  telemetryContext: { _lastMeanNodes?: number | undefined; _lastMeanConns?: number | undefined; },
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  populationSnapshot: GenomeDetailed[],
-  entry: TelemetryEntryRecord,
+setCachedEntropy(
+  generation: number | undefined,
+  entropyGraph: Record<string, unknown>,
+  entropyValue: number,
 ): void
 ```
 
-Attach complexity stats for mono-objective mode.
+Cache an entropy value for the current generation on the graph object.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with population state.
-- `telemetryOptions` - - Options controlling complexity telemetry.
-- `entry` - - Telemetry entry to update.
+- `generation` - - Current generation number.
+- `entropyGraph` - - Genome-like graph object.
+- `entropyValue` - - Entropy value to cache.
 
-### applyPerformanceStats
+### stripUnselectedTelemetryKeys
 
 ```ts
-applyPerformanceStats(
-  telemetryContext: { _lastEvalDuration?: number | undefined; _lastEvolveDuration?: number | undefined; },
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  entry: TelemetryEntryRecord,
-): void
+stripUnselectedTelemetryKeys(
+  sourceEntry: Record<string, unknown>,
+  selection: Set<string>,
+  fields: TelemetryCoreFields,
+): Record<string, unknown>
 ```
 
-Attach performance stats when configured.
+Remove non-core keys that are not whitelisted by the selection set.
+Mutates the provided entry in-place for efficiency.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with performance data.
-- `telemetryOptions` - - Options controlling performance telemetry.
-- `entry` - - Telemetry entry to update.
+- `sourceEntry` - - Telemetry entry being filtered.
+- `selection` - - Whitelist of additional telemetry keys.
+- `fields` - - Core telemetry field keys that must be preserved.
+
+Returns: The same entry reference after filtering.
 
 ## neat/telemetry/metrics/telemetry.metrics.rng.ts
 
@@ -896,53 +896,35 @@ Parameters:
 
 ## neat/telemetry/metrics/telemetry.metrics.entropy.ts
 
-### getCachedEntropy
-
-```ts
-getCachedEntropy(
-  generation: number | undefined,
-  entropyGraph: Record<string, unknown>,
-): number | undefined
-```
-
-Read a cached entropy value if it exists and belongs to the current
-generation.
-
-Parameters:
-- `generation` - - Current generation number.
-- `entropyGraph` - - Genome-like graph object.
-
-Returns: Cached entropy number, or undefined when not available.
-
-### computeDegreeCounts
+### buildDegreeHistogram
 
 ```ts
-computeDegreeCounts(
-  entropyGraph: { nodes: { geneId: number; }[]; connections: { from: { geneId: number; }; to: { geneId: number; }; enabled: boolean; }[]; },
+buildDegreeHistogram(
+  counts: Record<number, number>,
 ): Record<number, number>
 ```
 
-Compute per-node degree counts for enabled connections.
+Build a histogram of degree frequencies from a degree-count table.
 
 Parameters:
-- `entropyGraph` - - Genome-like graph object.
+- `counts` - - Map geneId -> degree count.
 
-Returns: Map geneId -> degree count.
+Returns: Map degree -> number of nodes with that degree.
 
-### buildDegreeHistogram
+### computeDegreeCounts
 
 ```ts
-buildDegreeHistogram(
-  counts: Record<number, number>,
+computeDegreeCounts(
+  entropyGraph: { nodes: { geneId: number; }[]; connections: { from: { geneId: number; }; to: { geneId: number; }; enabled: boolean; }[]; },
 ): Record<number, number>
 ```
 
-Build a histogram of degree frequencies from a degree-count table.
+Compute per-node degree counts for enabled connections.
 
 Parameters:
-- `counts` - - Map geneId -> degree count.
+- `entropyGraph` - - Genome-like graph object.
 
-Returns: Map degree -> number of nodes with that degree.
+Returns: Map geneId -> degree count.
 
 ### computeEntropyFromHistogram
 
@@ -961,6 +943,24 @@ Parameters:
 
 Returns: Entropy value (non-negative).
 
+### getCachedEntropy
+
+```ts
+getCachedEntropy(
+  generation: number | undefined,
+  entropyGraph: Record<string, unknown>,
+): number | undefined
+```
+
+Read a cached entropy value if it exists and belongs to the current
+generation.
+
+Parameters:
+- `generation` - - Current generation number.
+- `entropyGraph` - - Genome-like graph object.
+
+Returns: Cached entropy number, or undefined when not available.
+
 ### setCachedEntropy
 
 ```ts
@@ -980,28 +980,22 @@ Parameters:
 
 ## neat/telemetry/metrics/telemetry.metrics.lineage.ts
 
-### computeLineageStats
+### applyLineageStatsMonoObjective
 
 ```ts
-computeLineageStats(
-  lineageEnabled: boolean,
-  genomes: TelemetryGenome[],
-  size: number,
-  pairSampleCount: number,
-  rngFactoryFn: () => () => number,
-): { lineageMeanDepth: number; lineageMeanPairDist: number; }
+applyLineageStatsMonoObjective(
+  telemetryContext: { _lineageEnabled?: boolean | undefined; _getRNG?: (() => () => number) | undefined; _lastMeanDepth?: number | undefined; _prevInbreedingCount?: number | undefined; },
+  populationSnapshot: GenomeDetailed[],
+  entry: TelemetryEntryRecord,
+): void
 ```
 
-Compute lineage depth and pairwise depth-distance statistics.
+Apply lineage stats for mono-objective mode using sampled ancestors.
 
 Parameters:
-- `lineageEnabled` - - Whether lineage metrics are enabled.
-- `genomes` - - Population snapshot.
-- `size` - - Population size.
-- `pairSampleCount` - - Number of pairs to sample.
-- `rngFactoryFn` - - RNG factory returning a uniform random function.
-
-Returns: Lineage mean depth and pairwise distance.
+- `telemetryContext` - - Neat-like context with lineage settings.
+- `population` - - Population snapshot.
+- `entry` - - Telemetry entry to update.
 
 ### applyLineageStatsMultiObjective
 
@@ -1020,39 +1014,43 @@ Parameters:
 - `population` - - Population snapshot.
 - `entry` - - Telemetry entry to update.
 
-### applyLineageStatsMonoObjective
+### buildLineageContext
 
 ```ts
-applyLineageStatsMonoObjective(
-  telemetryContext: { _lineageEnabled?: boolean | undefined; _getRNG?: (() => () => number) | undefined; _lastMeanDepth?: number | undefined; _prevInbreedingCount?: number | undefined; },
+buildLineageContext(
+  context: { _getRNG?: (() => () => number) | undefined; },
   populationSnapshot: GenomeDetailed[],
-  entry: TelemetryEntryRecord,
-): void
+): NeatLineageContext
 ```
 
-Apply lineage stats for mono-objective mode using sampled ancestors.
+Build a lineage helper context for ancestor operations.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with lineage settings.
-- `population` - - Population snapshot.
-- `entry` - - Telemetry entry to update.
+- `context` - - Neat-like context with RNG helpers.
+- `populationSnapshot` - - Population snapshot.
 
-### isLineageEligible
+Returns: Lineage helper context.
+
+### buildLineageEntry
 
 ```ts
-isLineageEligible(
-  context: { _lineageEnabled?: boolean | undefined; },
-  populationSnapshot: GenomeDetailed[],
-): boolean
+buildLineageEntry(
+  context: { _prevInbreedingCount?: number | undefined; },
+  bestGenomeSnapshot: GenomeDetailed,
+  meanDepthValue: number,
+  ancestorUniquenessScore: number,
+): { parents: number[]; depthBest: number; meanDepth: number; inbreeding: number; ancestorUniq: number; }
 ```
 
-Check whether lineage metrics should be computed.
+Build the lineage entry payload.
 
 Parameters:
-- `context` - - Neat-like context with lineage flag.
-- `populationSnapshot` - - Population snapshot to validate.
+- `context` - - Neat-like context with lineage info.
+- `bestGenomeSnapshot` - - Best genome snapshot.
+- `meanDepthValue` - - Mean lineage depth.
+- `ancestorUniquenessScore` - - Ancestor uniqueness score.
 
-Returns: True when lineage stats should be computed.
+Returns: Lineage entry payload.
 
 ### collectDepths
 
@@ -1069,21 +1067,6 @@ Parameters:
 
 Returns: Array of depth values (defaults to 0).
 
-### computeMeanDepth
-
-```ts
-computeMeanDepth(
-  depthValues: number[],
-): number
-```
-
-Compute the mean depth from a depth list.
-
-Parameters:
-- `depthValues` - - Depth values to average.
-
-Returns: Mean depth value.
-
 ### computeAncestorUniquenessSampled
 
 ```ts
@@ -1101,22 +1084,43 @@ Parameters:
 
 Returns: Rounded ancestor uniqueness score.
 
-### pickDistinctPairIndices
+### computeLineageStats
 
 ```ts
-pickDistinctPairIndices(
-  context: { _getRNG?: (() => () => number) | undefined; },
-  populationSize: number,
-): { firstIndex: number; secondIndex: number; }
+computeLineageStats(
+  lineageEnabled: boolean,
+  genomes: TelemetryGenome[],
+  size: number,
+  pairSampleCount: number,
+  rngFactoryFn: () => () => number,
+): { lineageMeanDepth: number; lineageMeanPairDist: number; }
 ```
 
-Pick two distinct indices using the context RNG.
+Compute lineage depth and pairwise depth-distance statistics.
 
 Parameters:
-- `context` - - Neat-like context with RNG factory.
-- `populationSize` - - Population size for index bounds.
+- `lineageEnabled` - - Whether lineage metrics are enabled.
+- `genomes` - - Population snapshot.
+- `size` - - Population size.
+- `pairSampleCount` - - Number of pairs to sample.
+- `rngFactoryFn` - - RNG factory returning a uniform random function.
 
-Returns: Pair of distinct indices.
+Returns: Lineage mean depth and pairwise distance.
+
+### computeMeanDepth
+
+```ts
+computeMeanDepth(
+  depthValues: number[],
+): number
+```
+
+Compute the mean depth from a depth list.
+
+Parameters:
+- `depthValues` - - Depth values to average.
+
+Returns: Mean depth value.
 
 ### computePairJaccardDistance
 
@@ -1139,23 +1143,6 @@ Parameters:
 
 Returns: Jaccard distance or undefined when both sets are empty.
 
-### buildLineageContext
-
-```ts
-buildLineageContext(
-  context: { _getRNG?: (() => () => number) | undefined; },
-  populationSnapshot: GenomeDetailed[],
-): NeatLineageContext
-```
-
-Build a lineage helper context for ancestor operations.
-
-Parameters:
-- `context` - - Neat-like context with RNG helpers.
-- `populationSnapshot` - - Population snapshot.
-
-Returns: Lineage helper context.
-
 ### countAncestorIntersection
 
 ```ts
@@ -1173,26 +1160,39 @@ Parameters:
 
 Returns: Intersection count.
 
-### buildLineageEntry
+### isLineageEligible
 
 ```ts
-buildLineageEntry(
-  context: { _prevInbreedingCount?: number | undefined; },
-  bestGenomeSnapshot: GenomeDetailed,
-  meanDepthValue: number,
-  ancestorUniquenessScore: number,
-): { parents: number[]; depthBest: number; meanDepth: number; inbreeding: number; ancestorUniq: number; }
+isLineageEligible(
+  context: { _lineageEnabled?: boolean | undefined; },
+  populationSnapshot: GenomeDetailed[],
+): boolean
 ```
 
-Build the lineage entry payload.
+Check whether lineage metrics should be computed.
 
 Parameters:
-- `context` - - Neat-like context with lineage info.
-- `bestGenomeSnapshot` - - Best genome snapshot.
-- `meanDepthValue` - - Mean lineage depth.
-- `ancestorUniquenessScore` - - Ancestor uniqueness score.
+- `context` - - Neat-like context with lineage flag.
+- `populationSnapshot` - - Population snapshot to validate.
 
-Returns: Lineage entry payload.
+Returns: True when lineage stats should be computed.
+
+### pickDistinctPairIndices
+
+```ts
+pickDistinctPairIndices(
+  context: { _getRNG?: (() => () => number) | undefined; },
+  populationSize: number,
+): { firstIndex: number; secondIndex: number; }
+```
+
+Pick two distinct indices using the context RNG.
+
+Parameters:
+- `context` - - Neat-like context with RNG factory.
+- `populationSize` - - Population size for index bounds.
+
+Returns: Pair of distinct indices.
 
 ## neat/telemetry/metrics/telemetry.metrics.operator.ts
 
@@ -1304,6 +1304,23 @@ Parameters:
 
 Returns: Graphlet entropy value.
 
+### countEnabledEdges
+
+```ts
+countEnabledEdges(
+  genome: TelemetryGenome,
+  selectedNodes: NodeLike[],
+): number
+```
+
+Count enabled edges between the selected nodes in a genome.
+
+Parameters:
+- `genome` - - Genome with connections to inspect.
+- `selectedNodes` - - Nodes forming the graphlet sample.
+
+Returns: Edge count capped at 3.
+
 ### pickDistinctIndices
 
 ```ts
@@ -1323,23 +1340,6 @@ Parameters:
 
 Returns: Array of distinct indices.
 
-### countEnabledEdges
-
-```ts
-countEnabledEdges(
-  genome: TelemetryGenome,
-  selectedNodes: NodeLike[],
-): number
-```
-
-Count enabled edges between the selected nodes in a genome.
-
-Parameters:
-- `genome` - - Genome with connections to inspect.
-- `selectedNodes` - - Nodes forming the graphlet sample.
-
-Returns: Edge count capped at 3.
-
 ## neat/telemetry/metrics/telemetry.metrics.selection.ts
 
 ### getTelemetryCoreSnapshot
@@ -1358,27 +1358,7 @@ Parameters:
 - `sourceEntry` - - Source telemetry object.
 - `fields` - - Core telemetry field keys to preserve.
 
-Returns: Shallow snapshot of core fields that exist on the entry.
-
-### stripUnselectedTelemetryKeys
-
-```ts
-stripUnselectedTelemetryKeys(
-  sourceEntry: Record<string, unknown>,
-  selection: Set<string>,
-  fields: TelemetryCoreFields,
-): Record<string, unknown>
-```
-
-Remove non-core keys that are not whitelisted by the selection set.
-Mutates the provided entry in-place for efficiency.
-
-Parameters:
-- `sourceEntry` - - Telemetry entry being filtered.
-- `selection` - - Whitelist of additional telemetry keys.
-- `fields` - - Core telemetry field keys that must be preserved.
-
-Returns: The same entry reference after filtering.
+Returns: Shallow snapshot of core fields that exist on the entry.
 
 ### mergeTelemetryCoreFields
 
@@ -1415,82 +1395,102 @@ Parameters:
 - `telemetryEntry` - - Entry to filter in place.
 - `applyTelemetrySelectFn` - - Selection helper to invoke.
 
-## neat/telemetry/metrics/telemetry.metrics.complexity.ts
-
-### collectPopulationCounts
+### stripUnselectedTelemetryKeys
 
 ```ts
-collectPopulationCounts(
-  populationSnapshot: GenomeDetailed[],
-): { nodeCounts: number[]; connectionCounts: number[]; }
+stripUnselectedTelemetryKeys(
+  sourceEntry: Record<string, unknown>,
+  selection: Set<string>,
+  fields: TelemetryCoreFields,
+): Record<string, unknown>
 ```
 
-Collect node and connection counts for the population.
+Remove non-core keys that are not whitelisted by the selection set.
+Mutates the provided entry in-place for efficiency.
 
 Parameters:
-- `populationSnapshot` - - Population snapshot.
+- `sourceEntry` - - Telemetry entry being filtered.
+- `selection` - - Whitelist of additional telemetry keys.
+- `fields` - - Core telemetry field keys that must be preserved.
 
-Returns: Node and connection counts arrays.
+Returns: The same entry reference after filtering.
 
-### computeMeanCounts
+## neat/telemetry/metrics/telemetry.metrics.complexity.ts
+
+### applyComplexityStatsMonoObjective
 
 ```ts
-computeMeanCounts(
-  counts: { nodeCounts: number[]; connectionCounts: number[]; },
-): { meanNodes: number; meanConns: number; }
+applyComplexityStatsMonoObjective(
+  telemetryContext: { _lastMeanNodes?: number | undefined; _lastMeanConns?: number | undefined; },
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  populationSnapshot: GenomeDetailed[],
+  entry: TelemetryEntryRecord,
+): void
 ```
 
-Compute mean node and connection counts.
+Attach complexity stats for mono-objective mode.
 
 Parameters:
-- `counts` - - Node and connection counts arrays.
-
-Returns: Mean node and connection counts.
+- `telemetryContext` - - Neat-like context with population state.
+- `telemetryOptions` - - Options controlling complexity telemetry.
+- `entry` - - Telemetry entry to update.
 
-### computeMaxCounts
+### applyComplexityStatsMultiObjective
 
 ```ts
-computeMaxCounts(
-  counts: { nodeCounts: number[]; connectionCounts: number[]; },
-): { maxNodes: number; maxConns: number; }
+applyComplexityStatsMultiObjective(
+  telemetryContext: { _lastMeanNodes?: number | undefined; _lastMeanConns?: number | undefined; },
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  population: GenomeDetailed[],
+  entry: TelemetryEntryRecord,
+): void
 ```
 
-Compute max node and connection counts.
+Attach complexity stats for multi-objective mode.
 
 Parameters:
-- `counts` - - Node and connection counts arrays.
-
-Returns: Max node and connection counts.
+- `telemetryContext` - - Neat-like context with population state.
+- `telemetryOptions` - - Options controlling complexity telemetry.
+- `population` - - Population snapshot.
+- `entry` - - Telemetry entry to update.
 
-### computeEnabledRatios
+### buildComplexityEntry
 
 ```ts
-computeEnabledRatios(
-  populationSnapshot: GenomeDetailed[],
-): number[]
+buildComplexityEntry(
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  meanCounts: { meanNodes: number; meanConns: number; },
+  maxCounts: { maxNodes: number; maxConns: number; },
+  meanEnabledRatio: number,
+  growthValues: { growthNodes: number; growthConns: number; },
+): { meanNodes: number; meanConns: number; maxNodes: number; maxConns: number; meanEnabledRatio: number; growthNodes: number; growthConns: number; budgetMaxNodes: number; budgetMaxConns: number; }
 ```
 
-Compute enabled ratios per genome.
+Build the complexity entry payload for multi-objective mode.
 
 Parameters:
-- `populationSnapshot` - - Population snapshot.
+- `telemetryOptions` - - Options controlling complexity telemetry.
+- `meanCounts` - - Mean node/connection counts.
+- `maxCounts` - - Max node/connection counts.
+- `meanEnabledRatio` - - Mean enabled ratio.
+- `growthValues` - - Growth deltas.
 
-Returns: Array of enabled ratios.
+Returns: Complexity entry payload.
 
-### computeMeanEnabledRatio
+### collectPopulationCounts
 
 ```ts
-computeMeanEnabledRatio(
-  enabledRatios: number[],
-): number
+collectPopulationCounts(
+  populationSnapshot: GenomeDetailed[],
+): { nodeCounts: number[]; connectionCounts: number[]; }
 ```
 
-Compute mean of enabled ratios.
+Collect node and connection counts for the population.
 
 Parameters:
-- `enabledRatios` - - Enabled ratios per genome.
+- `populationSnapshot` - - Population snapshot.
 
-Returns: Mean enabled ratio.
+Returns: Node and connection counts arrays.
 
 ### computeAndStoreGrowthValues
 
@@ -1509,113 +1509,83 @@ Parameters:
 
 Returns: Growth values for nodes and connections.
 
-### buildComplexityEntry
+### computeEnabledRatios
 
 ```ts
-buildComplexityEntry(
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  meanCounts: { meanNodes: number; meanConns: number; },
-  maxCounts: { maxNodes: number; maxConns: number; },
-  meanEnabledRatio: number,
-  growthValues: { growthNodes: number; growthConns: number; },
-): { meanNodes: number; meanConns: number; maxNodes: number; maxConns: number; meanEnabledRatio: number; growthNodes: number; growthConns: number; budgetMaxNodes: number; budgetMaxConns: number; }
+computeEnabledRatios(
+  populationSnapshot: GenomeDetailed[],
+): number[]
 ```
 
-Build the complexity entry payload for multi-objective mode.
+Compute enabled ratios per genome.
 
 Parameters:
-- `telemetryOptions` - - Options controlling complexity telemetry.
-- `meanCounts` - - Mean node/connection counts.
-- `maxCounts` - - Max node/connection counts.
-- `meanEnabledRatio` - - Mean enabled ratio.
-- `growthValues` - - Growth deltas.
+- `populationSnapshot` - - Population snapshot.
 
-Returns: Complexity entry payload.
+Returns: Array of enabled ratios.
 
-### applyComplexityStatsMultiObjective
+### computeMaxCounts
 
 ```ts
-applyComplexityStatsMultiObjective(
-  telemetryContext: { _lastMeanNodes?: number | undefined; _lastMeanConns?: number | undefined; },
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  population: GenomeDetailed[],
-  entry: TelemetryEntryRecord,
-): void
+computeMaxCounts(
+  counts: { nodeCounts: number[]; connectionCounts: number[]; },
+): { maxNodes: number; maxConns: number; }
 ```
 
-Attach complexity stats for multi-objective mode.
+Compute max node and connection counts.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with population state.
-- `telemetryOptions` - - Options controlling complexity telemetry.
-- `population` - - Population snapshot.
-- `entry` - - Telemetry entry to update.
+- `counts` - - Node and connection counts arrays.
 
-### applyComplexityStatsMonoObjective
+Returns: Max node and connection counts.
+
+### computeMeanCounts
 
 ```ts
-applyComplexityStatsMonoObjective(
-  telemetryContext: { _lastMeanNodes?: number | undefined; _lastMeanConns?: number | undefined; },
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  populationSnapshot: GenomeDetailed[],
-  entry: TelemetryEntryRecord,
-): void
+computeMeanCounts(
+  counts: { nodeCounts: number[]; connectionCounts: number[]; },
+): { meanNodes: number; meanConns: number; }
 ```
 
-Attach complexity stats for mono-objective mode.
+Compute mean node and connection counts.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with population state.
-- `telemetryOptions` - - Options controlling complexity telemetry.
-- `entry` - - Telemetry entry to update.
+- `counts` - - Node and connection counts arrays.
 
-## neat/telemetry/metrics/telemetry.metrics.objectives.ts
+Returns: Mean node and connection counts.
 
-### computeHyperVolumeProxy
+### computeMeanEnabledRatio
 
 ```ts
-computeHyperVolumeProxy(
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  population: GenomeDetailed[],
+computeMeanEnabledRatio(
+  enabledRatios: number[],
 ): number
 ```
 
-Compute a hypervolume-like proxy for the Pareto front.
+Compute mean of enabled ratios.
 
 Parameters:
-- `telemetryOptions` - - Options controlling complexity metric.
-- `population` - - Population snapshot.
-
-Returns: Hypervolume proxy value.
-
-### computeParetoFrontSizes
-
-```ts
-computeParetoFrontSizes(
-  population: GenomeDetailed[],
-): number[]
-```
-
-Compute sizes of early Pareto fronts.
+- `enabledRatios` - - Enabled ratios per genome.
 
-Parameters:
-- `population` - - Population snapshot.
+Returns: Mean enabled ratio.
 
-Returns: Array of front sizes (rank 0..4).
+## neat/telemetry/metrics/telemetry.metrics.objectives.ts
 
-### applyObjectiveImportance
+### applyHypervolumeTelemetry
 
 ```ts
-applyObjectiveImportance(
-  telemetryContext: { _lastObjImportance?: ObjImportance | undefined; },
+applyHypervolumeTelemetry(
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  hyperVolumeProxy: number,
   entry: TelemetryEntryRecord,
 ): void
 ```
 
-Apply the most recent objective importance snapshot.
+Attach hypervolume scalar when requested.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with objective importance.
+- `telemetryOptions` - - Options controlling telemetry fields.
+- `hyperVolumeProxy` - - Hypervolume proxy value.
 - `entry` - - Telemetry entry to update.
 
 ### applyObjectiveAges
@@ -1650,19 +1620,19 @@ Parameters:
 - `entry` - - Telemetry entry to update.
 - `generation` - - Generation index for event records.
 
-### applySpeciesAllocation
+### applyObjectiveImportance
 
 ```ts
-applySpeciesAllocation(
-  telemetryContext: { _lastOffspringAlloc?: SpeciesAlloc[] | undefined; },
+applyObjectiveImportance(
+  telemetryContext: { _lastObjImportance?: ObjImportance | undefined; },
   entry: TelemetryEntryRecord,
 ): void
 ```
 
-Apply per-species offspring allocation snapshot.
+Apply the most recent objective importance snapshot.
 
 Parameters:
-- `telemetryContext` - - Neat-like context with allocation snapshot.
+- `telemetryContext` - - Neat-like context with objective importance.
 - `entry` - - Telemetry entry to update.
 
 ### applyObjectivesSnapshot
@@ -1680,23 +1650,53 @@ Parameters:
 - `telemetryContext` - - Neat-like context with objective provider.
 - `entry` - - Telemetry entry to update.
 
-### applyHypervolumeTelemetry
+### applySpeciesAllocation
 
 ```ts
-applyHypervolumeTelemetry(
-  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
-  hyperVolumeProxy: number,
+applySpeciesAllocation(
+  telemetryContext: { _lastOffspringAlloc?: SpeciesAlloc[] | undefined; },
   entry: TelemetryEntryRecord,
 ): void
 ```
 
-Attach hypervolume scalar when requested.
+Apply per-species offspring allocation snapshot.
 
 Parameters:
-- `telemetryOptions` - - Options controlling telemetry fields.
-- `hyperVolumeProxy` - - Hypervolume proxy value.
+- `telemetryContext` - - Neat-like context with allocation snapshot.
 - `entry` - - Telemetry entry to update.
 
+### computeHyperVolumeProxy
+
+```ts
+computeHyperVolumeProxy(
+  telemetryOptions: NeatOptions & TelemetryDiversityOptions,
+  population: GenomeDetailed[],
+): number
+```
+
+Compute a hypervolume-like proxy for the Pareto front.
+
+Parameters:
+- `telemetryOptions` - - Options controlling complexity metric.
+- `population` - - Population snapshot.
+
+Returns: Hypervolume proxy value.
+
+### computeParetoFrontSizes
+
+```ts
+computeParetoFrontSizes(
+  population: GenomeDetailed[],
+): number[]
+```
+
+Compute sizes of early Pareto fronts.
+
+Parameters:
+- `population` - - Population snapshot.
+
+Returns: Array of front sizes (rank 0..4).
+
 ## neat/telemetry/metrics/telemetry.metrics.performance.ts
 
 ### applyPerformanceStats