# `Alloy.Events`
[🔗](https://github.com/alloy-ex/alloy/blob/v0.12.4/lib/alloy/events.ex#L1)

Event envelope construction and runtime opts normalization.

Builds v1 event envelopes, manages sequence counters, and derives
correlation IDs. Used by `Alloy.Agent.Turn` to wrap raw provider and
tool events into the versioned envelope shape exposed to `:on_event`
callbacks on `Alloy.run/2` and `Alloy.stream/3`.

The v1 envelope is part of the protocol surface — anything `Turn`
emits is something downstream consumers can rely on. `:telemetry`
events fired alongside the envelope are the lower-level analogue.

# `build_correlation_id`

```elixir
@spec build_correlation_id(Alloy.Agent.State.t()) :: binary()
```

Derive a correlation ID from the agent state's context.

Precedence: `context[:request_id]` > `context[:correlation_id]` >
generated from `agent_id`.

# `emit`

```elixir
@spec emit(keyword(), non_neg_integer(), term()) :: :ok
```

Emit an event envelope.

Builds a v1 envelope from the raw event, calls the `on_event` callback,
and fires a `:telemetry` event.

# `normalize_opts`

```elixir
@spec normalize_opts(
  Alloy.Agent.State.t(),
  keyword()
) :: keyword()
```

Normalize runtime opts for event emission.

Ensures `:on_event`, `:event_seq_ref`, and `:event_correlation_id`
are present in the opts keyword list.

---

*Consult [api-reference.md](api-reference.md) for complete listing*