LemonCore.Event (lemon_core v0.1.0)

View Source

Canonical event envelope used on the Bus and in persisted streams.

Fields

  • :type - Event type as an atom (e.g., :run_started, :delta, :completed)
  • :ts_ms - Timestamp in milliseconds (monotonic wallclock)
  • :payload - Event-specific data
  • :meta - Optional metadata (should include run_id, session_key, origin where applicable)

Examples

iex> LemonCore.Event.new(:run_started, %{engine: "lemon"})
%LemonCore.Event{type: :run_started, ts_ms: 1234567890, payload: %{engine: "lemon"}, meta: nil}

iex> LemonCore.Event.new(:delta, %{text: "Hello"}, %{run_id: "abc", seq: 1})
%LemonCore.Event{type: :delta, ts_ms: 1234567890, payload: %{text: "Hello"}, meta: %{run_id: "abc", seq: 1}}

Summary

Types

engine_reasoning_attrs()
t()

Functions

engine_action(payload, meta)

Builds a validated engine action event for run-status surfaces.

engine_reasoning(attrs)

Builds a validated reasoning engine-action event for operator/status surfaces.

new(type, payload, meta \\ nil)

Creates a new event with the current timestamp.

new_with_ts(type, ts_ms, payload, meta \\ nil)

Creates a new event with a specific timestamp.

now_ms()

Returns the current time in milliseconds.

Types

engine_reasoning_attrs()

@type engine_reasoning_attrs() :: %{
  :run_id => String.t(),
  :session_key => String.t(),
  :text => String.t(),
  optional(:source) => String.t(),
  optional(:phase) => String.t() | atom(),
  optional(:visibility) => atom() | String.t(),
  optional(:engine) => String.t(),
  optional(:action_id) => String.t(),
  optional(:parent_run_id) => String.t(),
  optional(:agent_id) => String.t(),
  optional(:task_id) => String.t()
}

t()

@type t() :: %LemonCore.Event{
  meta: map() | nil,
  payload: term(),
  ts_ms: non_neg_integer(),
  type: atom()
}

Functions

engine_action(payload, meta)

@spec engine_action(map(), map()) :: t()

Builds a validated engine action event for run-status surfaces.

engine_reasoning(attrs)

@spec engine_reasoning(engine_reasoning_attrs() | map()) :: t()

Builds a validated reasoning engine-action event for operator/status surfaces.

new(type, payload, meta \\ nil)

@spec new(type :: atom(), payload :: term(), meta :: map() | nil) :: t()

Creates a new event with the current timestamp.

Parameters

  • type - The event type atom
  • payload - Event-specific payload data
  • meta - Optional metadata map (default: nil)

Examples

iex> event = LemonCore.Event.new(:run_started, %{engine: "lemon"})
iex> event.type
:run_started

new_with_ts(type, ts_ms, payload, meta \\ nil)

@spec new_with_ts(
  type :: atom(),
  ts_ms :: non_neg_integer(),
  payload :: term(),
  meta :: map() | nil
) :: t()

Creates a new event with a specific timestamp.

now_ms()

@spec now_ms() :: non_neg_integer()

Returns the current time in milliseconds.