# `Mobus.Stepwise.History`
[🔗](https://github.com/fosferon/mobus_stepwise/blob/main/lib/mobus/stepwise/history.ex#L1)

Structured access to runtime history and trace data.

The engine maintains two audit trails in the runtime:

  * `:history` — state transition log (`from`, `to`, `event`, `at`)
  * `:trace` — fine-grained execution trace (actions, steps, breakpoints)

These helpers provide stable read access and controlled append
without depending on internal list structure.

# `append`

```elixir
@spec append(map(), map()) :: map()
```

Appends a custom event to the history.

# `append_trace`

```elixir
@spec append_trace(map(), map()) :: map()
```

Appends a custom entry to the trace.

# `events`

```elixir
@spec events(map()) :: [map()]
```

Returns the full history list from the runtime.

# `events_by`

```elixir
@spec events_by(map(), atom() | String.t()) :: [map()]
```

Returns history entries filtered by event name.

# `last_event`

```elixir
@spec last_event(map()) :: map() | nil
```

Returns the last history entry, or `nil`.

# `trace`

```elixir
@spec trace(map()) :: [map()]
```

Returns the full trace list from the runtime.

# `trace_by_kind`

```elixir
@spec trace_by_kind(map(), atom() | String.t()) :: [map()]
```

Returns trace entries filtered by kind.

# `transition_count`

```elixir
@spec transition_count(map()) :: non_neg_integer()
```

Returns the number of state transitions recorded.

---

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