# `SquidMesh.Runtime.StateMachine`
[🔗](https://github.com/ccarvalho-eng/squid_mesh/blob/main/lib/squid_mesh/runtime/state_machine.ex#L1)

Explicit run lifecycle state machine for the Squid Mesh runtime.

The runtime coordinator and the later Jido-backed executor should consume
this module as the single source of truth for valid run-state transitions.
It defines the workflow run lifecycle without mixing in step execution or
persistence concerns.

# `state`

```elixir
@type state() :: SquidMesh.Run.status()
```

# `transition_error`

```elixir
@type transition_error() ::
  {:unknown_state, atom()}
  | {:invalid_transition, from_state :: state(), to_state :: state()}
```

# `allowed_transitions`

```elixir
@spec allowed_transitions(state()) ::
  {:ok, [state()]} | {:error, {:unknown_state, atom()}}
```

Returns the states that may be reached directly from the current state.

# `can_transition?`

```elixir
@spec can_transition?(state(), state()) :: boolean()
```

Reports whether a transition is valid.

# `schedule_next_step?`

```elixir
@spec schedule_next_step?(state()) :: boolean()
```

Reports whether the runtime may schedule another step while the run is in
the given state.

# `states`

```elixir
@spec states() :: [state()]
```

Returns all valid run states.

# `terminal?`

```elixir
@spec terminal?(state()) :: boolean()
```

Reports whether a state is terminal.

# `transition`

```elixir
@spec transition(state(), state()) :: {:ok, state()} | {:error, transition_error()}
```

Validates a requested state transition.

---

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