Compile-time crossover safety, sensible defaults, framework-owned age lifecycle

- Add SupportsGeneCrossover/SupportsPointCrossover marker traits; UniqueGenotype
  + incompatible crossover is now a compile error instead of runtime panic
- Remove has_crossover_indexes/has_crossover_points runtime checks from builder
- Default target_population_size from 0 to 100
- Move increment_age from crossover implementations to evolve loop
- Update AGENTS.md: remove solved gotchas (1,5,7,9), renumber remaining

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: basvanwesting

AGENTS.md

@@ -3,7 +3,7 @@
 This file helps AI coding agents use this library correctly. It covers decision
 guidance, API reference, gotchas, and copy-paste templates.
 
-**Read the Gotchas section before writing code.** Gotchas 1, 2, 3, and 7 cause
+**Read the Gotchas section before writing code.** Gotchas 1, 2, and 5 cause
 compilation or runtime failures that are hard to debug after the fact.
 
 ## Quick Start
@@ -84,17 +84,18 @@ When implementing `calculate_for_chromosome`, access genes via `chromosome.genes
 | `BinaryGenotype` | All | `CrossoverUniform` or `CrossoverSinglePoint` |
 | `ListGenotype<T>` | All | `CrossoverUniform` |
 | `MultiListGenotype<T>` | All | `CrossoverUniform` |
-| `UniqueGenotype<T>` | `CrossoverClone`, `CrossoverRejuvenate` ONLY | `CrossoverClone` |
-| `MultiUniqueGenotype<T>` | Point-based + `CrossoverClone`, `CrossoverRejuvenate` (NO gene-based) | `CrossoverSinglePoint` |
+| `UniqueGenotype<T>` | `CrossoverClone`, `CrossoverRejuvenate` ONLY (others are compile errors) | `CrossoverClone` |
+| `MultiUniqueGenotype<T>` | Point-based + `CrossoverClone`, `CrossoverRejuvenate` (gene-based are compile errors) | `CrossoverSinglePoint` |
 | `RangeGenotype<T>` | All | `CrossoverMultiPoint` |
 | `MultiRangeGenotype<T>` | All | `CrossoverSingleGene` |
 
-**WARNING**: `UniqueGenotype` will cause a **runtime panic** with gene-based or
-point-based crossovers. Use `CrossoverClone` (clones parents, relies on mutation
-for diversity) or `CrossoverRejuvenate` (like Clone but optimized for less memory copying).
-`MultiUniqueGenotype` supports point-based crossovers (`CrossoverSinglePoint`,
-`CrossoverMultiPoint`) but panics on gene-based ones (`CrossoverUniform`,
-`CrossoverSingleGene`, `CrossoverMultiGene`).
+**Compile-time safety**: `UniqueGenotype` does not implement `SupportsGeneCrossover`
+or `SupportsPointCrossover`, so incompatible crossovers are **compile errors**.
+Use `CrossoverClone` (clones parents, relies on mutation for diversity) or
+`CrossoverRejuvenate` (like Clone but optimized for less memory copying).
+`MultiUniqueGenotype` implements `SupportsPointCrossover` only, so gene-based
+crossovers (`CrossoverUniform`, `CrossoverSingleGene`, `CrossoverMultiGene`) are
+compile errors.
 
 ### Which Select?
 
@@ -250,7 +251,7 @@ ExtensionMassDeduplication::new(
 Required:
 - `.with_genotype(genotype)` — the search space
 - `.with_fitness(fitness)` — the evaluation function
-- `.with_target_population_size(n)` — number of chromosomes (**defaults to 0, always set this**)
+- `.with_target_population_size(n)` — number of chromosomes (defaults to 100)
 - `.with_select(select)` — parent selection strategy
 - `.with_crossover(crossover)` — how parents combine
 - `.with_mutate(mutate)` — how offspring are varied
@@ -348,22 +349,20 @@ let (best, _all_runs) = Evolve::builder()
 HillClimb also supports `.call_repeatedly(n)` and `.call_par_repeatedly(n)`.
 
 Both `.call()` and `.build()` return `Result<_, TryFromEvolveBuilderError>`.
-Builder validation catches: missing required fields, incompatible genotype +
-crossover combinations, and missing ending conditions. The error message includes
-an actionable fix suggestion.
+Builder validation catches: missing required fields and missing ending conditions.
+Incompatible genotype + crossover combinations are caught at compile time via
+trait bounds (`SupportsGeneCrossover`, `SupportsPointCrossover`). The error
+message includes an actionable fix suggestion.
 
 ### Common mistakes
 
 ```rust
-// WRONG: UniqueGenotype + CrossoverUniform = RUNTIME PANIC
+// WRONG: UniqueGenotype + CrossoverUniform = COMPILE ERROR
 // FIX:   Use CrossoverClone or CrossoverRejuvenate
 
 // WRONG: No ending condition = COMPILE/BUILD ERROR
 // FIX:   Add .with_max_stale_generations(1000)
 
-// WRONG: target_population_size not set (defaults to 0) = SILENT FAILURE
-// FIX:   Add .with_target_population_size(100)
-
 // WRONG: Fitness returns f64 = TYPE ERROR
 // FIX:   Return Some((score / precision) as FitnessValue)
 
@@ -721,13 +720,10 @@ Combine with `max_stale_generations` to trigger phase transitions automatically
 
 ## Gotchas
 
-1. **UniqueGenotype + standard crossover = runtime panic.** Use `CrossoverClone`. MultiUniqueGenotype supports point-based but not gene-based crossovers.
-2. **FitnessValue is isize.** Scale floats manually: `(score / precision) as FitnessValue`.
-3. **Ending condition required.** Evolve/HillClimb need at least one of: `target_fitness_score`, `max_stale_generations`, `max_generations`.
-4. **Fitness struct must be `Clone + Debug`.**
-5. **RangeGenotype requires a type parameter.** Use turbofish: `RangeGenotype::<f64>::builder()`, `RangeGenotype::<i32>::builder()`.
-6. **Permutate + RangeGenotype** requires `MutationType::Step`, `StepScaled`, or `Discrete`.
-7. **`target_population_size` defaults to 0.** Always set it for Evolve.
-8. **Custom Crossover/Mutate/Extension must call `chromosome.reset_metadata(genotype.genes_hashing)`** after modifying genes directly.
-9. **Custom Crossover must call `state.population.increment_age()`** on existing chromosomes.
-10. **For deterministic tests:** use `.with_rng_seed_from_u64(0)`. Exact results may change between library versions, but deterministic within a version.
+1. **FitnessValue is isize.** Scale floats manually: `(score / precision) as FitnessValue`.
+2. **Ending condition required.** Evolve/HillClimb need at least one of: `target_fitness_score`, `max_stale_generations`, `max_generations`.
+3. **Fitness struct must be `Clone + Debug`.**
+4. **Permutate + RangeGenotype** requires `MutationType::Step`, `StepScaled`, or `Discrete`.
+5. **`target_population_size` defaults to 100.** Override with `.with_target_population_size(n)` if needed.
+6. **Custom Crossover/Mutate/Extension must call `chromosome.reset_metadata(genotype.genes_hashing)`** after modifying genes directly.
+7. **For deterministic tests:** use `.with_rng_seed_from_u64(0)`. Exact results may change between library versions, but deterministic within a version.

src/crossover.rs

@@ -14,9 +14,10 @@
 //! High values converge faster, but risk losing good solutions. Low values have poor exploration
 //! and risk of premature convergence
 //!
-//! As crossover adds offspring (with age zero) it is also the responsibility of the crossover to
-//! increment the age of the parents. This is done because the definition of "offspring" is "age
-//! zero". So this should be done in-sync and is therefore not a generational loop concern of Evolve.
+//! Age tracking: the evolve loop increments the age of all chromosomes immediately before calling
+//! crossover. Crossover then adds offspring (with age zero) to the population. These two steps are
+//! logically coupled — offspring are "age zero" relative to their parents' incremented age — but
+//! the framework owns the increment so custom crossover implementations cannot forget it.
 //!
 //! Normally the crossover adds children to the population, thus increasing the population_size
 //! above the target_population_size. Selection will reduce this again in the next generation.
@@ -83,8 +84,7 @@ pub type CrossoverAllele<C> = <<C as Crossover>::Genotype as Genotype>::Allele;
 ///         let selected_population_size =
 ///             (existing_population_size as f32 * self.selection_rate).ceil() as usize;
 ///
-///         // Important!!! Increment age, as the old offspring now become parents
-///         state.population.increment_age();
+///         // Note: increment_age is handled by the evolve loop immediately before this call
 ///         // Important!!! Append offspring as recycled clones from parents (will reset age and crossover later)
 ///         // Use population's methods for safe chromosome recycling
 ///         state.population.extend_from_within(selected_population_size);
@@ -151,17 +151,6 @@ pub trait Crossover: Clone + Send + Sync + std::fmt::Debug {
     ) {
         // state.update_population_cardinality(genotype, config);
     }
-
-    /// to guard against invalid Crossover strategies which break the internal consistency
-    /// of the genes, unique genotypes can't simply exchange genes without gene duplication issues
-    fn require_crossover_indexes(&self) -> bool {
-        false
-    }
-    /// to guard against invalid Crossover strategies which break the internal consistency
-    /// of the genes, unique genotypes can't simply exchange genes without gene duplication issues
-    fn require_crossover_points(&self) -> bool {
-        false
-    }
 }
 
 #[derive(Clone, Debug)]

src/crossover/clone.rs

@@ -29,7 +29,6 @@ impl<G: EvolveGenotype> Crossover for Clone<G> {
         let selected_population_size =
             (existing_population_size as f32 * self.selection_rate).ceil() as usize;
 
-        state.population.increment_age();
         state
             .population
             .extend_from_within(selected_population_size);

src/crossover/multi_gene.rs

@@ -1,5 +1,5 @@
 use super::Crossover;
-use crate::genotype::EvolveGenotype;
+use crate::genotype::{EvolveGenotype, SupportsGeneCrossover};
 use crate::strategy::evolve::{EvolveConfig, EvolveState};
 use crate::strategy::{StrategyAction, StrategyReporter, StrategyState};
 use itertools::Itertools;
@@ -16,15 +16,15 @@ use std::time::Instant;
 /// [MultiUniqueGenotype](crate::genotype::MultiUniqueGenotype) as it would not preserve the gene
 /// uniqueness in the children.
 #[derive(Clone, Debug)]
-pub struct MultiGene<G: EvolveGenotype> {
+pub struct MultiGene<G: EvolveGenotype + SupportsGeneCrossover> {
     _phantom: PhantomData<G>,
     pub selection_rate: f32,
     pub crossover_rate: f32,
     pub crossover_sampler: Bernoulli,
     pub number_of_crossovers: usize,
     pub allow_duplicates: bool,
 }
-impl<G: EvolveGenotype> Crossover for MultiGene<G> {
+impl<G: EvolveGenotype + SupportsGeneCrossover> Crossover for MultiGene<G> {
     type Genotype = G;
 
     fn call<R: Rng, SR: StrategyReporter<Genotype = G>>(
@@ -39,7 +39,6 @@ impl<G: EvolveGenotype> Crossover for MultiGene<G> {
         let existing_population_size = state.population.chromosomes.len();
         let selected_population_size =
             (existing_population_size as f32 * self.selection_rate).ceil() as usize;
-        state.population.increment_age();
         state
             .population
             .extend_from_within(selected_population_size);
@@ -69,12 +68,9 @@ impl<G: EvolveGenotype> Crossover for MultiGene<G> {
         }
         state.add_duration(StrategyAction::Crossover, now.elapsed());
     }
-    fn require_crossover_indexes(&self) -> bool {
-        true
-    }
 }
 
-impl<G: EvolveGenotype> MultiGene<G> {
+impl<G: EvolveGenotype + SupportsGeneCrossover> MultiGene<G> {
     /// Create a new MultiGene crossover strategy.
     /// * `selection_rate` - fraction of parents selected for reproduction (0.5-0.8 typical)
     /// * `crossover_rate` - probability parent pair crosses over vs cloning (0.5-0.9 typical)

src/crossover/multi_point.rs

@@ -1,5 +1,5 @@
 use super::Crossover;
-use crate::genotype::EvolveGenotype;
+use crate::genotype::{EvolveGenotype, SupportsPointCrossover};
 use crate::strategy::evolve::{EvolveConfig, EvolveState};
 use crate::strategy::{StrategyAction, StrategyReporter, StrategyState};
 use itertools::Itertools;
@@ -16,15 +16,15 @@ use std::time::Instant;
 /// Not allowed for [UniqueGenotype](crate::genotype::UniqueGenotype) as it would not preserve the gene uniqueness in the children.
 /// Allowed for [MultiUniqueGenotype](crate::genotype::MultiUniqueGenotype) as there are valid crossover points between each new set
 #[derive(Clone, Debug)]
-pub struct MultiPoint<G: EvolveGenotype> {
+pub struct MultiPoint<G: EvolveGenotype + SupportsPointCrossover> {
     _phantom: PhantomData<G>,
     pub selection_rate: f32,
     pub crossover_rate: f32,
     pub crossover_sampler: Bernoulli,
     pub number_of_crossovers: usize,
     pub allow_duplicates: bool,
 }
-impl<G: EvolveGenotype> Crossover for MultiPoint<G> {
+impl<G: EvolveGenotype + SupportsPointCrossover> Crossover for MultiPoint<G> {
     type Genotype = G;
 
     fn call<R: Rng, SR: StrategyReporter<Genotype = G>>(
@@ -39,7 +39,6 @@ impl<G: EvolveGenotype> Crossover for MultiPoint<G> {
         let existing_population_size = state.population.chromosomes.len();
         let selected_population_size =
             (existing_population_size as f32 * self.selection_rate).ceil() as usize;
-        state.population.increment_age();
         state
             .population
             .extend_from_within(selected_population_size);
@@ -69,12 +68,9 @@ impl<G: EvolveGenotype> Crossover for MultiPoint<G> {
         }
         state.add_duration(StrategyAction::Crossover, now.elapsed());
     }
-    fn require_crossover_points(&self) -> bool {
-        true
-    }
 }
 
-impl<G: EvolveGenotype> MultiPoint<G> {
+impl<G: EvolveGenotype + SupportsPointCrossover> MultiPoint<G> {
     /// Create a new MultiPoint crossover strategy.
     /// * `selection_rate` - fraction of parents selected for reproduction (0.5-0.8 typical)
     /// * `crossover_rate` - probability parent pair crosses over vs cloning (0.5-0.9 typical)

src/crossover/rejuvenate.rs

@@ -33,7 +33,6 @@ impl<G: EvolveGenotype> Crossover for Rejuvenate<G> {
         let dropped_population_size = (existing_population_size - selected_population_size).max(0);
 
         state.population.truncate(selected_population_size);
-        state.population.increment_age();
         state.population.extend_from_within(dropped_population_size);
 
         state

src/crossover/single_gene.rs

@@ -1,5 +1,5 @@
 use super::Crossover;
-use crate::genotype::EvolveGenotype;
+use crate::genotype::{EvolveGenotype, SupportsGeneCrossover};
 use crate::strategy::evolve::{EvolveConfig, EvolveState};
 use crate::strategy::{StrategyAction, StrategyReporter, StrategyState};
 use itertools::Itertools;
@@ -15,13 +15,13 @@ use std::time::Instant;
 /// [MultiUniqueGenotype](crate::genotype::MultiUniqueGenotype) as it would not preserve the gene
 /// uniqueness in the children.
 #[derive(Clone, Debug)]
-pub struct SingleGene<G: EvolveGenotype> {
+pub struct SingleGene<G: EvolveGenotype + SupportsGeneCrossover> {
     _phantom: PhantomData<G>,
     pub selection_rate: f32,
     pub crossover_rate: f32,
     pub crossover_sampler: Bernoulli,
 }
-impl<G: EvolveGenotype> Crossover for SingleGene<G> {
+impl<G: EvolveGenotype + SupportsGeneCrossover> Crossover for SingleGene<G> {
     type Genotype = G;
 
     fn call<R: Rng, SR: StrategyReporter<Genotype = G>>(
@@ -36,7 +36,6 @@ impl<G: EvolveGenotype> Crossover for SingleGene<G> {
         let existing_population_size = state.population.chromosomes.len();
         let selected_population_size =
             (existing_population_size as f32 * self.selection_rate).ceil() as usize;
-        state.population.increment_age();
         state
             .population
             .extend_from_within(selected_population_size);
@@ -61,12 +60,9 @@ impl<G: EvolveGenotype> Crossover for SingleGene<G> {
 
         state.add_duration(StrategyAction::Crossover, now.elapsed());
     }
-    fn require_crossover_indexes(&self) -> bool {
-        true
-    }
 }
 
-impl<G: EvolveGenotype> SingleGene<G> {
+impl<G: EvolveGenotype + SupportsGeneCrossover> SingleGene<G> {
     /// Create a new SingleGene crossover strategy.
     /// * `selection_rate` - fraction of parents selected for reproduction (0.5-0.8 typical)
     /// * `crossover_rate` - probability parent pair crosses over vs cloning (0.5-0.9 typical)

src/crossover/single_point.rs

@@ -1,5 +1,5 @@
 use super::Crossover;
-use crate::genotype::EvolveGenotype;
+use crate::genotype::{EvolveGenotype, SupportsPointCrossover};
 use crate::strategy::evolve::{EvolveConfig, EvolveState};
 use crate::strategy::{StrategyAction, StrategyReporter, StrategyState};
 use itertools::Itertools;
@@ -14,13 +14,13 @@ use std::time::Instant;
 /// Not allowed for [UniqueGenotype](crate::genotype::UniqueGenotype) as it would not preserve the gene uniqueness in the children.
 /// Allowed for [MultiUniqueGenotype](crate::genotype::MultiUniqueGenotype) as there are valid crossover points between each new set
 #[derive(Clone, Debug)]
-pub struct SinglePoint<G: EvolveGenotype> {
+pub struct SinglePoint<G: EvolveGenotype + SupportsPointCrossover> {
     _phantom: PhantomData<G>,
     pub selection_rate: f32,
     pub crossover_rate: f32,
     pub crossover_sampler: Bernoulli,
 }
-impl<G: EvolveGenotype> Crossover for SinglePoint<G> {
+impl<G: EvolveGenotype + SupportsPointCrossover> Crossover for SinglePoint<G> {
     type Genotype = G;
 
     fn call<R: Rng, SR: StrategyReporter<Genotype = G>>(
@@ -35,7 +35,6 @@ impl<G: EvolveGenotype> Crossover for SinglePoint<G> {
         let existing_population_size = state.population.chromosomes.len();
         let selected_population_size =
             (existing_population_size as f32 * self.selection_rate).ceil() as usize;
-        state.population.increment_age();
         state
             .population
             .extend_from_within(selected_population_size);
@@ -60,12 +59,9 @@ impl<G: EvolveGenotype> Crossover for SinglePoint<G> {
 
         state.add_duration(StrategyAction::Crossover, now.elapsed());
     }
-    fn require_crossover_points(&self) -> bool {
-        true
-    }
 }
 
-impl<G: EvolveGenotype> SinglePoint<G> {
+impl<G: EvolveGenotype + SupportsPointCrossover> SinglePoint<G> {
     /// Create a new SinglePoint crossover strategy.
     /// * `selection_rate` - fraction of parents selected for reproduction (0.5-0.8 typical)
     /// * `crossover_rate` - probability parent pair crosses over vs cloning (0.5-0.9 typical)

src/crossover/uniform.rs

@@ -1,5 +1,5 @@
 use super::Crossover;
-use crate::genotype::EvolveGenotype;
+use crate::genotype::{EvolveGenotype, SupportsGeneCrossover};
 use crate::strategy::evolve::{EvolveConfig, EvolveState};
 use crate::strategy::{StrategyAction, StrategyReporter, StrategyState};
 use itertools::Itertools;
@@ -15,14 +15,14 @@ use std::time::Instant;
 /// [MultiUniqueGenotype](crate::genotype::MultiUniqueGenotype) as it would not preserve the gene
 /// uniqueness in the children.
 #[derive(Clone, Debug)]
-pub struct Uniform<G: EvolveGenotype> {
+pub struct Uniform<G: EvolveGenotype + SupportsGeneCrossover> {
     _phantom: PhantomData<G>,
     pub selection_rate: f32,
     pub crossover_rate: f32,
     pub crossover_sampler: Bernoulli,
 }
 
-impl<G: EvolveGenotype> Crossover for Uniform<G> {
+impl<G: EvolveGenotype + SupportsGeneCrossover> Crossover for Uniform<G> {
     type Genotype = G;
 
     fn call<R: Rng, SR: StrategyReporter<Genotype = G>>(
@@ -38,7 +38,6 @@ impl<G: EvolveGenotype> Crossover for Uniform<G> {
         let existing_population_size = state.population.chromosomes.len();
         let selected_population_size =
             (existing_population_size as f32 * self.selection_rate).ceil() as usize;
-        state.population.increment_age();
         state
             .population
             .extend_from_within(selected_population_size);
@@ -69,12 +68,9 @@ impl<G: EvolveGenotype> Crossover for Uniform<G> {
 
         state.add_duration(StrategyAction::Crossover, now.elapsed());
     }
-    fn require_crossover_indexes(&self) -> bool {
-        true
-    }
 }
 
-impl<G: EvolveGenotype> Uniform<G> {
+impl<G: EvolveGenotype + SupportsGeneCrossover> Uniform<G> {
     /// Create a new Uniform crossover strategy.
     /// * `selection_rate` - fraction of parents selected for reproduction (0.5-0.8 typical)
     /// * `crossover_rate` - probability parent pair crosses over vs cloning (0.5-0.9 typical)