# `Rheo.Event.Lineage`
[🔗](https://github.com/thanos/rheo/blob/v1.0.0/lib/rheo/event/lineage.ex#L1)

Standard metadata keys for event lineage and provenance.

These live in `Rheo.Event.metadata` (string keys after persistence), not as
top-level Event fields.

| Key | Meaning |
|---|---|
| `correlation_id` | Shared id across a saga / request |
| `causation_id` | Id of the event or command that caused this one |
| `producer` | Producing service or component |
| `schema` | Payload schema name |
| `schema_version` | Schema version (string or number) |

## Example

    iex> meta = Rheo.Event.Lineage.put(%{},
    ...>   correlation_id: "req-1",
    ...>   producer: "pricing",
    ...>   schema: "curve_update",
    ...>   schema_version: 1
    ...> )
    iex> Rheo.Event.Lineage.get(meta, :correlation_id)
    "req-1"

# `get`

```elixir
@spec get(Rheo.Event.t() | map(), atom()) :: term() | nil
```

Reads a lineage field from an event or metadata map.

Accepts atom or string keys on the source map.

## Examples

    iex> Rheo.Event.Lineage.get(%{"correlation_id" => "c1"}, :correlation_id)
    "c1"

    iex> event = %Rheo.Event{
    ...>   id: "e1",
    ...>   stream: "s",
    ...>   partition: 0,
    ...>   sequence: 1,
    ...>   timestamp: ~U[2026-01-15 12:00:00.000Z],
    ...>   payload: %{},
    ...>   metadata: %{producer: "api"}
    ...> }
    iex> Rheo.Event.Lineage.get(event, :producer)
    "api"

    iex> Rheo.Event.Lineage.get(%{}, :schema)
    nil

# `keys`

```elixir
@spec keys() :: [atom()]
```

Returns the list of standardized lineage metadata keys.

## Examples

    iex> :correlation_id in Rheo.Event.Lineage.keys()
    true

# `put`

```elixir
@spec put(map(), keyword()) :: map()
```

Builds a metadata map from lineage options.

Unknown keys are ignored. Values are kept as-is; backends stringify atom keys
on append.

## Arguments

  * `metadata` — existing map to merge into (default `%{}`)
  * `opts` — keyword list; only keys in `keys/0` are copied

## Examples

    iex> Rheo.Event.Lineage.put(correlation_id: "abc", ignored: true)
    %{correlation_id: "abc"}

    iex> Rheo.Event.Lineage.put(%{"x" => 1}, producer: "risk")
    %{"x" => 1, producer: "risk"}

---

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