v0.3.1 - Architectural Alignment

Overview

Version: 0.3.1 Phase: Foundation Duration: 1 week Focus: Align genotype and constructor with DXNN2 architecture patterns

Motivation

The v0.3.0 implementation created working neural network processes but diverged from DXNN2's core architecture:

• Used ETS instead of Mnesia (no persistence)
• Used maps instead of records (lost type safety, incompatible with genome_mutator)
• Inline topology building instead of morphology module (not extensible)
• No integration with genome_mutator for linking (can't reuse for mutations)

This release corrects these deviations to ensure compatibility with DXNN2's evolution engine.

Objectives

1. Mnesia Integration: Switch from ETS to Mnesia for genotype storage
2. Record-Based Data: Use records from records.hrl for all genotype elements
3. Morphology Module: Create morphology.erl for sensor/actuator specifications
4. Genome Mutator Integration: Use genome_mutator:link_FromElementToElement for linking
5. Constructor Update: Synchronous linking compatible with Mnesia/records

Deliverables

1. genotype.erl Refactoring

Replace current ETS/maps implementation with Mnesia/records:

%% Current (v0.3.0)
Agent = #{
    id => AgentId,
    type => agent,
    cortex_id => CortexId,
    ...
},
ets:insert(?GENOTYPE_DB, {AgentId, Agent}).

%% Target (v0.3.1)
Agent = #agent{
    id = AgentId,
    encoding_type = neural,
    cx_id = CortexId,
    specie_id = SpecieId,
    constraint = Constraint,
    ...
},
mnesia:write(Agent).

Functions to implement:

• init_db/0 - Create Mnesia schema and tables
• construct_Agent/3 - Match DXNN2 signature (Specie_Id, Agent_Id, SpecCon)
• construct_Cortex/6 - Match DXNN2 signature
• construct_SeedNN/6 - Initial neuron layer construction
• construct_Neuron/6 - Individual neuron construction
• read/1, write/1, dirty_read/1 - Mnesia wrappers
• clone_Agent/1 - Deep copy with new IDs
• delete_Agent/1 - Remove agent and all components

2. morphology.erl Module

Create morphology module for sensor/actuator specifications:

-module(morphology).
-export([
    get_InitSensors/1,
    get_InitActuators/1
]).

%% XOR morphology (for testing)
get_InitSensors(xor_mimic) ->
    [#sensor{name=xor_GetInput, vl=2, scape={private, xor_sim}}];

get_InitActuators(xor_mimic) ->
    [#actuator{name=xor_SendOutput, vl=1, scape={private, xor_sim}}].

%% Default morphology
get_InitSensors(default) ->
    [#sensor{name=rng, vl=2}];

get_InitActuators(default) ->
    [#actuator{name=pts, vl=1}].

3. genome_mutator Integration

Use genome_mutator for element linking instead of inline code:

%% Current (v0.3.0) - inline linking
connect_layers(SensorIds, NeuronLayers, ActuatorIds) ->
    %% ... inline weight creation and ID updates

%% Target (v0.3.1) - use genome_mutator
link_Neuron(Generation, From_Ids, N_Id, To_Ids) ->
    [genome_mutator:link_FromElementToElement(Generation, From_Id, N_Id)
     || From_Id <- From_Ids],
    [genome_mutator:link_FromElementToElement(Generation, N_Id, To_Id)
     || To_Id <- To_Ids].

4. constructor.erl Update

Update constructor to work with Mnesia/records:

%% Read from Mnesia instead of ETS
Agent = genotype:dirty_read({agent, AgentId}),
Cortex = genotype:dirty_read({cortex, Agent#agent.cx_id}),

%% Use spawn_CerebralUnits pattern from DXNN2
spawn_CerebralUnits(IdsNPIds, sensor, SIds),
spawn_CerebralUnits(IdsNPIds, neuron, NIds),
spawn_CerebralUnits(IdsNPIds, actuator, AIds),

%% Synchronous linking (send state to waiting processes)
link_Sensors(SIds, IdsNPIds),
link_Neurons(NIds, IdsNPIds),
link_Actuators(AIds, IdsNPIds).

5. Mnesia Schema

Tables to create:

Implementation Plan

Day 1-2: Mnesia Setup and genotype.erl Core

1. Add Mnesia schema initialization
2. Implement basic read/write/delete with Mnesia
3. Implement construct_Agent/3 with constraints
4. Implement construct_Cortex/6

Day 3: morphology.erl and Neuron Construction

1. Create morphology.erl with xor_mimic and default
2. Implement construct_SeedNN/6
3. Implement construct_Neuron/6

Day 4: genome_mutator Integration

1. Port or create genome_mutator:link_FromElementToElement
2. Update genotype to use link_Neuron pattern
3. Implement clone_Agent/1 with genome_mutator

Day 5: constructor.erl Update

1. Update constructor to use Mnesia reads
2. Implement spawn_CerebralUnits pattern
3. Implement synchronous linking functions
4. Update tests

Day 6-7: Testing and Documentation

1. Update all genotype_tests to use Mnesia
2. Update constructor_tests
3. Add integration test for full network cycle
4. Update module documentation
5. Run dialyzer and fix warnings

Testing Requirements

Unit Tests

• Mnesia operations (read, write, dirty_read, delete)
• Agent construction with different morphologies
• Neuron linking with genome_mutator
• Clone operations

Integration Tests

• Full agent construction -> phenotype spawn -> evaluation cycle
• Agent cloning preserves topology
• Mnesia persistence across restarts

Dependencies

External

• Mnesia (OTP)
• Records from records.hrl (or types.hrl)

Internal (may need to port from DXNN2)

• genome_mutator:link_FromElementToElement/3
• genome_mutator:link_FromElementToElement/4 (with Generation)

Quality Gates

• [ ] All existing tests pass (214 tests)
• [ ] New Mnesia tests pass
• [ ] Integration test for full cycle passes
• [ ] Dialyzer clean
• [ ] genotype API matches DXNN2 signatures
• [ ] Records used instead of maps
• [ ] No process dictionary usage

Risks and Mitigations

Success Criteria

1. genotype:construct_Agent(SpecieId, AgentId, Constraint) works
2. Agent stored in Mnesia with proper records
3. Constructor spawns phenotype from Mnesia-stored genotype
4. Network completes evaluation cycle
5. Agent clone creates independent copy
6. All tests pass, dialyzer clean

References

• DXNN2 genotype.erl
• DXNN2 exoself.erl
• DXNN2 records.hrl
• DXNN2 genome_mutator.erl

Document Version: 1.0 Created: November 2025 Author: Macula-TWEANN Development Team