macula_neuroevolution

# Changelog

All notable changes to macula-neuroevolution will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

## [Unreleased]

### Planned
- Wire L0 TWEANN evolution into neuroevolution_server
- Integration tests for cross-silo communication

---

## [0.18.2] - 2025-12-23

### Summary
**Complete SVG Documentation** - All ASCII diagrams replaced with SVG files for hex.pm rendering.

### Added
- 26 new SVG diagrams covering all guides:
  - `evolution-lifecycle.svg`, `selection-breeding.svg`, `steady-state-flow.svg`, `island-topology.svg`, `novelty-search.svg`, `map-elites-grid.svg` (evolution-strategies.md)
  - `liquid-conglomerate-full.svg`, `hierarchy-levels.svg`, `adaptive-hyperparameters.svg`, `training-dashboard.svg`, `distributed-mesh.svg` (liquid-conglomerate.md)
  - `game-ai-architecture.svg`, `robot-architecture.svg`, `trading-architecture.svg`, `edge-ai-mesh.svg` (inference-scenarios.md)
  - `swarm-architecture.svg`, `swarm-mesh.svg`, `distributed-training.svg` (swarm-robotics.md)
  - `species-population.svg`, `species-hierarchy.svg` (topology-evolution.md)
  - `lineage_cqrs_architecture.svg` (lineage-tracking.md)
  - `self_play_first_gen.svg`, `self_play_archive_selection.svg` (self-play.md)
  - `neat_gene_alignment.svg` (topology-evolution.md)
  - `architecture-overview.svg` (overview.md)
  - `individual-structure.svg` (getting-started.md)
  - `liquid-conglomerate-v2.svg` (meta-controller.md)

### Changed
- Updated all guide files to reference SVG diagrams instead of ASCII art
- Total assets: 37 SVG files

---

## [0.18.1] - 2025-12-23

### Summary
**Documentation Fix** - Replace ASCII diagrams with SVG, fix EDoc generation errors.

### Fixed
- EDoc errors from `@doc` tags on record definitions and `-callback` declarations
- ASCII diagrams causing backtick parse errors in hex.pm docs

### Added
- `assets/lc_silo_chain.svg` - Hierarchical L0/L1/L2 LTC TWEANN architecture
- `assets/distributed_evaluation.svg` - Distributed batch evaluation diagram

---

## [0.18.0] - 2025-12-23

### Summary
**Lineage Tracking Release** - Complete genealogy tracking infrastructure with CQRS-compliant behaviour, event records, and comprehensive documentation.

### Added

#### Lineage Event System (CQRS Architecture)
- **neuroevolution_lineage_events.erl** - Behaviour with required and optional callbacks

**Required Callbacks (Event Store)**:
- `init/1` - Initialize event store backend
- `persist_event/2` - Persist single event to appropriate stream
- `persist_batch/2` - Batch persist for efficiency
- `read_stream/3` - Read raw events from a stream
- `subscribe/3` - Subscribe to stream events (for projections)
- `unsubscribe/3` - Unsubscribe from stream

**Optional Callbacks (Queries via Projections)**:
- `get_breeding_tree/3` - Build ancestry tree up to N generations
- `get_fitness_trajectory/2` - Get fitness over time
- `get_mutation_history/2` - Get all mutations for an individual
- `get_knowledge_transfers/2` - Get mentor/student events
- `get_by_causation/2` - Find events by causation ID

**CQRS Design**: Required callbacks handle event store operations. Optional callbacks provide query capabilities and should be implemented using internal projections (read models), not by scanning events directly.

#### Event Record Definitions (lineage_events.hrl)
- **Birth Events**: offspring_born, pioneer_spawned, clone_produced, immigrant_arrived
- **Death Events**: individual_culled, lifespan_expired, individual_perished
- **Lifecycle Events**: individual_matured, fertility_waned
- **Fitness Events**: fitness_evaluated, fitness_improved, fitness_declined, champion_crowned
- **Mutation Events**: mutation_applied, neuron_added, neuron_removed, connection_added, connection_removed, weight_perturbed
- **Species Events**: lineage_diverged, species_emerged, lineage_ended, lineage_merged
- **Knowledge Transfer Events**: knowledge_transferred, skill_imitated, behavior_cloned, weights_grafted, structure_seeded, mentor_assigned, mentorship_concluded
- **Epigenetic Events**: mark_acquired, mark_inherited, mark_decayed
- **Coalition Events**: coalition_formed, coalition_dissolved, coalition_joined
- **Population Events**: generation_completed, population_initialized, population_terminated, stagnation_detected, breakthrough_achieved, carrying_capacity_reached, catastrophe_occurred

#### Unit Tests
- **test/neuroevolution_lineage_events_tests.erl** - 23 tests for behaviour contract
  - 17 tests for required callbacks (event store operations)
  - 6 tests for optional callbacks (query operations)
- **test/mock_lineage_backend.erl** - In-memory mock implementation (implements all callbacks)

#### Documentation
- **guides/lineage-tracking.md** - CQRS architecture guide with usage examples
- **assets/lineage_architecture.svg** - Architecture overview diagram

### Stream Design
Events are routed to streams by entity type:
- `individual-{id}` - Birth, death, fitness, mutations, knowledge transfer
- `species-{id}` - Speciation, lineage divergence/merge
- `population-{id}` - Generation, capacity, catastrophe
- `coalition-{id}` - Coalition lifecycle

### Architecture Notes
- **Required Callbacks**: Event store operations (persist, read, subscribe)
- **Optional Callbacks**: Query operations (implemented via projections internally)
- **Mock Backend**: Implements all callbacks (scans events directly for queries)
- **Production Backend**: Should use projections for optional callbacks

### Test Results
- 419 tests passing (23 new lineage tests)
- 4 tests skipped (self_play_tests - pre-existing missing opponent_archive module)
- Dialyzer clean

---

## [0.13.0] - 2025-12-11

### Summary
**Liquid Conglomerate v2 Release** - Complete hierarchical meta-learning architecture with 3 specialized silos (Resource, Task, Distribution), L1/L2 controllers, and cross-silo communication.

### Added

#### LC v2 Architecture
- **lc_supervisor.erl** - Supervises all LC v2 child processes
- **lc_cross_silo.erl** - Signal routing between silos with validation and decay
- **lc_reward.erl** - Cooperative reward computation for all silos
- **lc_l1_controller.erl** - Generic L1 hyperparameter tuning
- **lc_l2_controller.erl** - Strategic meta-tuning with slow exploration

#### Silo Morphologies (TWEANN Sensor/Actuator Definitions)
- **resource_l0_morphology.erl** - Resource silo (13 sensors, 8 actuators)
- **task_l0_morphology.erl** - Task silo (16 sensors, 12 actuators)
- **distribution_l0_morphology.erl** - Distribution silo (14 sensors, 10 actuators)

#### Sensor & Actuator Implementations
- **resource_l0_sensors.erl** - System metrics collection
- **resource_l0_actuators.erl** - Resource control application
- **task_l0_sensors.erl** - Evolution statistics collection
- **task_l0_actuators.erl** - Evolution parameter application
- **distribution_l0_sensors.erl** - Network metrics collection
- **distribution_l0_actuators.erl** - Distribution control application

#### Unit Tests (108 new tests)
- **test/lc_morphology_tests.erl** - 43 tests for morphology modules
- **test/lc_reward_tests.erl** - 34 tests for reward computation
- **test/lc_l1_controller_tests.erl** - 15 tests for L1 controller
- **test/lc_l2_controller_tests.erl** - 16 tests for L2 controller

#### Documentation
- **guides/cooperative-silos.md** - Cross-silo communication guide
- **guides/assets/lc_architecture.svg** - Architecture overview diagram
- **guides/assets/lc_hierarchical_learning.svg** - Hierarchical learning diagram
- **guides/assets/lc_cross_silo_signals.svg** - Signal routing diagram
- **guides/assets/lc_silo_tweann_io.svg** - L0 TWEANN sensors/actuators diagram
- **guides/assets/lc_silo_interactions.svg** - Detailed cross-silo interaction flow diagram
- **guides/assets/lc_feedback_loop.svg** - Feedback loop between Resource and Task silos
- Updated **guides/meta-controller.md** with implementation roadmap

### Changed
- Updated implementation roadmap (Phases 3-6 complete)
- Enhanced LC v2 documentation with cooperative reward signals

### Theoretical Foundation
- Multi-timescale separation: Distribution (τ=1), Resource (τ=5), Task (τ=50)
- Hierarchical control: L0 (safety), L1 (feedback), L2 (feedforward)
- Graceful degradation: L2 failure → L1 fallback → L0 safety

### Test Results
- 326 tests passing (108 new LC v2 tests)
- Dialyzer clean
- All documentation links validated

---

## [0.12.1] - 2025-12-07

### Summary
**Safety & Dependency Update** - MAP-Elites grid validation and macula-tweann 0.13.0 compatibility.

### Changed
- **rebar.config**: Updated macula_tweann dependency from ~> 0.12.0 to ~> 0.13.0

### Fixed
- **map_elites_strategy.erl**: Added grid size validation to prevent unbounded memory growth
  - Maximum 10,000 cells enforced (e.g., 10 bins × 4 dimensions, or 100 bins × 2 dimensions)
  - Descriptive error with hint when configuration exceeds limit
  - Prevents potential OOM from high-dimensional behavior spaces

### Test Results
- 218 tests passing
- Dialyzer: 35 pre-existing warnings (unrelated to this release)

---

## [0.12.0] - 2025-12-01

### Summary
**Evolution Strategies & Meta-Learning Release** - Multiple evolution strategies with LTC meta-controller.

### Added

#### Evolution Strategies
- **generational_strategy.erl** - Classic generational GA
- **steady_state_strategy.erl** - Continuous replacement with age tracking
- **novelty_strategy.erl** - Novelty search with behavior archive
- **map_elites_strategy.erl** - Quality-Diversity algorithm with behavior grid
- **island_strategy.erl** - Island model with migration topology

#### Meta-Learning
- **meta_controller.erl** - LTC-based hyperparameter controller
- **meta_trainer.erl** - Advantage estimation and gradient computation
- **meta_reward.erl** - Multi-component reward calculation

#### Core Infrastructure
- **neuroevolution_server.erl** - Main gen_server for training orchestration
- **neuroevolution_events.erl** - Event system for training notifications
- **neuroevolution_selection.erl** - Selection operators (tournament, roulette, top-N)
- **neuroevolution_genetic.erl** - Crossover and mutation operators
- **neuroevolution_speciation.erl** - NEAT-style speciation support
- **neuroevolution_stats.erl** - Population statistics

#### Documentation
- Comprehensive guides for all features
- Architecture overview with diagrams
- LTC meta-controller explanation
- Liquid Conglomerate vision document

---

## [0.11.0] - 2025-11-15

### Summary
Initial public release with core neuroevolution functionality.

### Added
- Basic population management
- Parallel fitness evaluation
- Weight mutation and crossover
- Event callback system
- Integration with macula_tweann

---

[Unreleased]: https://github.com/macula-io/macula-neuroevolution/compare/v0.18.2...HEAD
[0.18.2]: https://github.com/macula-io/macula-neuroevolution/compare/v0.18.1...v0.18.2
[0.18.1]: https://github.com/macula-io/macula-neuroevolution/compare/v0.18.0...v0.18.1
[0.18.0]: https://github.com/macula-io/macula-neuroevolution/compare/v0.17.0...v0.18.0
[0.13.0]: https://github.com/macula-io/macula-neuroevolution/compare/v0.12.1...v0.13.0
[0.12.1]: https://github.com/macula-io/macula-neuroevolution/compare/v0.12.0...v0.12.1
[0.12.0]: https://github.com/macula-io/macula-neuroevolution/compare/v0.11.0...v0.12.0
[0.11.0]: https://github.com/macula-io/macula-neuroevolution/releases/tag/v0.11.0