neuroevolution_lineage_events behaviour (faber_neuroevolution v1.2.4)

View Source

Behaviour definition for neuroevolution lineage event persistence.

This behaviour defines the minimal API for lineage tracking. Implementations MUST be non-blocking to avoid impacting evolution performance.

Callbacks

init/1 - Initialize backend persist_event/2 - Fire-and-forget single event persist_batch/2 - Fire-and-forget batch of events read_stream/3 - Read events (for recovery/replay) subscribe/3 - Subscribe to stream (for projections) unsubscribe/3 - Unsubscribe from stream

Performance Requirements

Lineage tracking must NEVER block the evolution loop:

- persist_event/persist_batch should return immediately - Use async I/O internally (spawn, cast, buffering) - Acceptable to lose events under extreme load - read_stream may block (only used for recovery)

Stream Design

Events are organized into streams based on entity type:

- individual-{id} : Birth, death, fitness, mutations - species-{id} : Speciation, lineage events - population-{id} : Generation, capacity events - coalition-{id} : Coalition lifecycle

Summary

Types

direction/0

-type direction() :: forward | backward.

event/0

-type event() :: map().

position/0

-type position() :: non_neg_integer().

read_opts/0

-type read_opts() :: #{from => position(), limit => pos_integer(), direction => direction()}.

stream_id/0

-type stream_id() :: binary().

Callbacks

init/1

-callback init(Config :: map()) -> {ok, State :: term()} | {error, Reason :: term()}.

persist_batch/2

-callback persist_batch(Events :: [event()], State :: term()) -> ok.

persist_event/2

-callback persist_event(Event :: event(), State :: term()) -> ok.

read_stream/3

-callback read_stream(StreamId :: stream_id(), Opts :: read_opts(), State :: term()) ->
                         {ok, Events :: [event()]} | {error, Reason :: term()}.

subscribe/3

-callback subscribe(StreamId :: stream_id(), Pid :: pid(), State :: term()) ->
                       ok | {error, Reason :: term()}.

unsubscribe/3

-callback unsubscribe(StreamId :: stream_id(), Pid :: pid(), State :: term()) ->
                         ok | {error, Reason :: term()}.