[CodeByBryant]

Summary

Second of five Phase 4 PRs, implementing the design merged in #97 (ADR 0006). Everything needed to build, mutate, recombine, validate and compare genomes, with none of it wired into the World yet. There is no new simulated behavior and no hash change; the existing golden hashes are untouched and the determinism suite passes against them.

• @evo/contracts: Genome and its gene groups; GENE_DEFINITIONS (the fixed canonical gene order, 23 genes); GeneRange, GeneticsConfig, LearningInheritanceMode, LineageRecord.
• @evo/config: WorldConfig.genetics (mutation scales, blend alpha, brain architecture, founder learning baseline, learning inheritance, per-gene overrides), organisms.hue, DEFAULT_GENE_RANGES, full validation with tests. Shared check helpers moved unchanged into checks.ts.
• simulation/src/genetics/ (pure functions, no World integration):
  • table-driven mutation with a different operator per kind (gaussian, point, bit-flip, circular wrap, correlated trait-shift, relative learning-rate, sparse brain-weight);
  • recombination: blend crossover for continuous genes, uniform pick for int/bool, shortest-arc blend for circular genes, and per-block segment crossover for brain weights so both parents' brains contribute;
  • validateGenome / repairGenome, genomeDistance, inheritedBrainWeights (all three learning-inheritance modes), founder creation.
  • Operators work on gene vectors over a spec table, so integer, boolean, circular and correlated genes are tested with synthetic tables (the production table has none of the first two).

One behavior-preserving change outside the new code

reproduction.energyCost / offspringEnergy are replaced by offspringInvestment / overheadFraction (per ADR 0006). The defaults (12.5 and 0.6) give exactly Phase 3's 20 paid and 25 to the child (verified exactly in floating point), and ReproductionSystem is the only simulation code touched. The determinism suite passes against the unchanged goldens, which is the proof that nothing moved.

Design refinements made while implementing (ADR 0006 / genetics docs updated in this PR)

• Life-stage ordering is enforced by the operators, not by disjoint ranges. A gene declared orderedAfter another has its lower bound raised above it in mutation, recombination and repair, so maturityAge < senescenceAge < maxAge holds for any ranges. The ADR originally required non-overlapping ranges, which would have rejected ordinary baseline overrides (for example small ages in tests).
• Default gene ranges widen to include a changed founder baseline, so overriding organisms.* / reproduction.* never needs a matching range override. An edge set explicitly in genetics.genes is never moved, and validation rejects a baseline outside it.
• learningRate mutates multiplicatively (a Gaussian fraction of its value) because the engine has no deterministic exp for log-space mutation.
• Affordability guard (implemented when genes go live): reproduction requires energy >= max(minEnergy, cost), so paying can never drive energy negative regardless of gene combination.

Test plan

• pnpm format:check clean in a fresh clone
• pnpm check green in a fresh clone: 7 contracts, 55 config (up from 29), 326 simulation (up from 212, 114 new genetics tests)
• pnpm build green (all 8 packages/apps)
• pnpm test:determinism: 17/17 against the unchanged goldens
• Negative check: Object.keys, **, Math.exp, Math.random and for...in inside genetics/ all fail the determinism lint (temporary violations, reverted)

Next: PR 3 makes organisms carry genomes (behavior-preserving, with an equivalence gate against Phase 3's pinned scenarios).

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota.