workspace.txt

Create an agent team to discuss the @AGENTS.md from different angles: one
teammate for architectural understanding, one teammate for docs, one teammate
representing the AI clients user. Discuss the good and the bad, and what seems
inconsistent, missing or could be improved. Also explicitly discuss where the
application architecture can be improved as seen from a AI client user
perspective.


why is dedup 30% faster, the iterator is unsorted, so dedup does almost nothing.

            rng.sample_iter(self.gene_index_sampler)
                .take(number_of_crossovers)
                .dedup()
                .for_each(|index| {
                    std::mem::swap(&mut father.genes[index], &mut mother.genes[index]);
                });

I don't feel comfortable adding dedup because it works as the underlying reason is non-transparant and can change

⏺ From the team discussion, two proposals involved API/breaking changes:

  Gotcha #7: Make target_population_size require explicit setting
  - Proposal: Change the field from usize (defaulting to 0) to Option<usize> (defaulting to None), forcing users to call .with_target_population_size().
  - Rejected: Breaking API change for marginal benefit — the builder already catches 0 with a clear error message.

  Gotcha #9: Automate increment_age() in the Evolve loop
  - Proposal: Move state.population.increment_age() out of individual Crossover implementations and into the Evolve strategy loop (before crossover.call()), so custom crossover impls don't need to remember it.
  - Rejected: Would double-increment age for existing custom crossover implementations that already call it — a silent behavioral break.

  Both were ruled out as "not worth the breaking change" given the existing validation/documentation already handles them adequately.

## TODO

## MAYBE
* Apply precision (to f32/f64) during hashing in order to converge and hit
  staleness when nearing the required precision level (maybe per scale?)
* Crossover calls reset_metadata, but sometimes the parens are equal and
  sometimes when they are not the difference isn't crossed over. In both
  conditions, you create a child equal to an existing parent. This leads to a
  cache hit when calculating the fitness again. That is confusing. Extensions
  can mutate chromosomes which calls reset_metadata (fitness is reset). Now
  crossover follows and clones parents without a fitness, into new children
  without fitness, this will lead to a cache miss and a cache hit when
  calculating the fitness
* Consider dropping .with_genes_hashing() and always set to true, because it is
  needed for proper GA functionality regardless the overhead
* Consider dropping .with_chromosome_recycling() and always set to false
  (stripping the recycling completely), because it is complicated and risky for
  custom Crossover implementations and maybe framework overhead simply doesn't
  matter as much with regards to Fitness overhead
* Target cardinality range for Mutate Dynamic to avoid constant switching (noisy in reporting events)
* Add scaling helper function
* Add simulated annealing strategy
* Add Roulette selection with and without duplicates (with fitness ordering)
* Add OrderOne crossover for UniqueGenotype?
  * Order Crossover (OX): Simple and works well for many permutation problems.
  * Partially Mapped Crossover (PMX): Preserves more of the parent's structure but is slightly more complex.
  * Cycle Crossover (CX): Ensures all genes come from one parent, useful for strict preservation of order.
  * Edge Crossover (EX): Preserves adjacency relationships, suitable for Traveling Salesman Problem or similar.
* Add WholeArithmetic crossover for RangeGenotype?
* Add CountTrueWithWork instead of CountTrueWithSleep for better benchmarks?
* StrategyBuilder, with_par_fitness_threshold, with_permutate_threshold?
* Add target fitness score to Permutate? Seems illogical, but would be symmetrical. Don't know yet
* Add negative selection-rate to encode in-place crossover? But do keep the old
  extend with best-parents with the pre v0.20 selection-rate behaviour which was crucial for evolve_nqueens