Behavioral Events Guide

This guide explains how to use the behavioral event system in macula-neuroevolution. Events capture domain-specific actions using evolutionary biology terminology, enabling event sourcing, auditing, and inter-component communication.

Design Principles

Behavioral, Not CRUD

Events describe what happened in domain language:

Past Tense

Events are immutable facts that already happened:

Quick Start

Emitting Events

%% Include the event definitions
-include_lib("macula_neuroevolution/include/lc_temporal_events.hrl").

%% Emit an episode completion event
lc_temporal_events:emit_episode_completed(
    IndividualId,
    EpisodeNumber,
    DurationMs,
    success,      % outcome
    0.15,         % fitness_delta
    1000          % steps_taken
).

Subscribing to Events

%% Subscribe to temporal events
neuroevolution_behavioral_events:subscribe(temporal, self()),

%% Handle events in your process
handle_info({lc_event, temporal, #episode_completed{} = Event}, State) ->
    Duration = Event#episode_completed.duration_ms,
    %% Process the event...
    {noreply, State}.

Querying Event History

%% Get recent events for a silo
Events = neuroevolution_behavioral_events:get_events(temporal, #{
    since => erlang:system_time(millisecond) - 60000,  % Last minute
    limit => 100
}).

Event Categories by Silo

Temporal Silo (9 events)

Episode and timing management.

%% Example: Episode completion
#episode_completed{
    meta = #lc_event_meta{...},
    individual_id = <<"ind_123">>,
    episode_number = 42,
    duration_ms = 1500,
    outcome = success,           % success | failure | timeout | early_termination
    fitness_delta = 0.05,
    steps_taken = 1000
}

Economic Silo (10 events)

Resource allocation and budgeting.

Morphological Silo (9 events)

Network structure changes.

Competitive Silo (10 events)

Adversarial dynamics.

Social Silo (9 events)

Cooperation and reputation.

Cultural Silo (9 events)

Innovation and tradition.

Developmental Silo (9 events)

Ontogeny and plasticity.

Regulatory Silo (9 events)

Gene expression control.

Ecological Silo (9 events)

Environmental dynamics.

Communication Silo (6 events)

Signaling and coordination.

Distribution Silo (4 events)

Population structure.

Event Metadata

All events include standard metadata:

-record(lc_event_meta, {
    event_id :: binary(),           % Unique event identifier
    timestamp :: integer(),         % Unix milliseconds
    realm :: binary(),              % Multi-tenancy realm
    population_id :: binary(),      % Population context
    generation :: non_neg_integer(),% Generation number
    source_silo :: atom()           % Emitting silo type
}).

Event Storage

Events can be stored for replay and analysis:

%% Configure event storage
neuroevolution_behavioral_events:configure(#{
    storage => ets,              % ets | dets | custom
    max_events => 100000,        % Ring buffer size
    persistence => false         % Write to disk
}).

Integration with Silos

Each silo's event module provides typed emission functions:

%% Temporal silo
lc_temporal_events:emit_episode_started(IndId, EpisodeNum, ExpectedDuration, Gen).
lc_temporal_events:emit_learning_rate_adapted(PopId, OldRate, NewRate, Reason, Gen).

%% Economic silo
lc_economic_events:emit_budget_allocated(IndId, Amount, Source, Gen).
lc_economic_events:emit_trade_executed(FromId, ToId, ResourceType, Amount, Gen).

%% Competitive silo
lc_competitive_events:emit_match_played(Player1, Player2, Result, EloDelta, Gen).
lc_competitive_events:emit_champion_crowned(IndId, Fitness, PreviousChampion, Gen).

Best Practices

1. Subscribe Early: Set up subscriptions before evolution starts
2. Handle Async: Events may arrive out of order
3. Batch Processing: Process events in batches for efficiency
4. Selective Subscription: Only subscribe to events you need
5. Idempotent Handlers: Design handlers to handle duplicates

See Also

• Liquid Conglomerate Overview
• Cross-Silo Communication