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
- Docker compose for multi-node mesh testing
- Integration tests with 3-node mesh cluster

---

## [0.23.2] - 2025-12-24

### Fixed
- Fix broken documentation link in behavioral-events.md

---

## [0.23.1] - 2025-12-24

### Added
- **guides/behavioral-events.md** - Comprehensive user guide for 93 behavioral events
  - Event emission and subscription examples
  - Complete event catalog by silo
  - Event metadata structure
  - Best practices for event handling

---

## [0.23.0] - 2025-12-24

### Summary
**Macula Mesh Distribution & Behavioral Events** - Add distributed fitness evaluation across macula mesh nodes and comprehensive per-silo behavioral event infrastructure.

### Added

#### Mesh Distribution (Phase 1)
- **mesh_sup.erl** - Supervisor for mesh distribution components
- **evaluator_pool_registry.erl** - Track remote evaluator capacity with load balancing
- **macula_mesh.erl** - Macula integration facade (conditional compilation)
- **distributed_evaluator.erl** - RPC-based evaluation dispatch with retry
- **mesh_tests.erl** - 19 unit tests for mesh components
- `evaluation_mode = mesh` option in neuro_config
- `mesh_config` field for realm and preferences
- `rebar3 as mesh compile` for macula-enabled builds

#### Behavioral Events (93 events across 11 silos)
- **lc_events_common.hrl** - Shared macros and record definitions
- **neuroevolution_behavioral_events.erl** - Event emission/subscription API
- Per-silo event modules: temporal (9), economic (10), morphological (9), competitive (10), social (9), cultural (9), developmental (9), regulatory (9), ecological (9), communication (6), distribution (4)
- Event emission with `emit_*` functions and `to_map/1` conversion

#### Mesh Features
- Load balancing based on capacity, latency, and error rate
- Automatic retry on evaluation failure
- Local preference (configurable, default 30%)
- Graceful fallback when macula not compiled in
- EMA-based latency tracking for evaluator selection

### Tests
- 437 tests total (19 new mesh tests, behavioral event tests)

---

## [0.19.0] - 2025-12-23

### Summary
**Complete 13-Silo Liquid Conglomerate Architecture** - Full implementation of all 13 specialized silos with shared infrastructure, cross-silo signaling, and comprehensive unit tests.

### Added

#### Infrastructure Modules
- **lc_silo_behavior.erl** - Common behaviour with `get_silo_type/0` and `get_time_constant/0` callbacks
- **lc_ets_utils.erl** - Shared ETS utilities (CRUD, time-based operations, aggregations)
- **include/lc_silos.hrl** - Common silo records and type definitions
- **include/lc_signals.hrl** - Signal type definitions for cross-silo communication

#### Phase 2: High-Value Silos
- **temporal_silo.erl** - Episode timing, learning rates, convergence tracking (τ=10)
- **economic_silo.erl** - Compute budgets, energy economics, Gini coefficient (τ=20)
- **morphological_silo.erl** - Network complexity, pruning, efficiency metrics (τ=30)

#### Phase 3: Competition Silos
- **competitive_silo.erl** - Elo ratings, opponent archive, matchmaking (τ=15)
- **social_silo.erl** - Reputation, coalitions, social networks (τ=25)

#### Phase 4: Learning Silos
- **cultural_silo.erl** - Innovations, traditions, meme spread (τ=35)
- **developmental_silo.erl** - Ontogeny, plasticity, critical periods (τ=40)
- **regulatory_silo.erl** - Gene expression, module activation, epigenetics (τ=45)

#### Phase 5: Environment Silos
- **ecological_silo.erl** - Niches, resource pools, environmental stress (τ=50)
- **communication_silo.erl** - Vocabulary, messaging, coordination (τ=55)

#### Phase 6: Distribution Silo
- **distribution_silo.erl** - Islands, migration, load balancing (τ=60)

#### Cross-Silo Signal Routing
- Updated **lc_cross_silo.erl** with ~60+ signal types for all 13 silos
- Signal validation, decay, and batch emission support
- Updated **lc_supervisor.erl** with extension silo support

#### Unit Tests (340 silo tests)
- **lc_silo_behavior_tests.erl** - Behaviour contract tests
- **lc_ets_utils_tests.erl** - ETS utility tests
- **lc_cross_silo_tests.erl** - Signal routing tests
- **temporal_silo_tests.erl** - 24 tests
- **economic_silo_tests.erl** - 20 tests
- **morphological_silo_tests.erl** - 14 tests
- **competitive_silo_tests.erl** - 26 tests
- **social_silo_tests.erl** - 22 tests
- **cultural_silo_tests.erl** - 26 tests
- **developmental_silo_tests.erl** - 22 tests
- **regulatory_silo_tests.erl** - 20 tests
- **ecological_silo_tests.erl** - 24 tests
- **communication_silo_tests.erl** - 22 tests
- **distribution_silo_tests.erl** - 24 tests

#### Documentation
- 14 new silo guides in `guides/silos/`:
  - lc-overview.md, task-silo.md, resource-silo.md, distribution-silo.md
  - temporal-silo.md, economic-silo.md, morphological-silo.md
  - competitive-silo.md, social-silo.md, cultural-silo.md
  - ecological-silo.md, developmental-silo.md, regulatory-silo.md
  - communication-silo.md
- SVG diagrams for silo architecture

### Architecture

Each silo implements the `lc_silo_behavior` with:
- **gen_server** for state management
- **ETS tables** for persistent collections via `lc_ets_utils`
- **L0 Sensors** (normalized 0.0-1.0) for state observation
- **L0 Actuators** with configurable bounds
- **Cross-silo signals** via `lc_cross_silo` router
- **Time constants** (τ) for multi-timescale adaptation

### Test Results
- 726 tests passing (340 silo tests + 386 other tests)
- 4 tests skipped (pre-existing self_play_tests for unimplemented modules)
- Dialyzer: 192 pre-existing warnings (unrelated to silos)

---

## [0.18.4] - 2025-12-23

### Fixed
- Minor bug fixes

---

## [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.19.0...HEAD
[0.19.0]: https://github.com/macula-io/macula-neuroevolution/compare/v0.18.4...v0.19.0
[0.18.4]: https://github.com/macula-io/macula-neuroevolution/compare/v0.18.2...v0.18.4
[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