# `Squidie.ReadModel.Explanation`
[🔗](https://github.com/dark-trench/squidie/blob/main/lib/squidie/read_model/explanation.ex#L1)

Projection-backed explanation for the journal-backed runtime.

`Squidie.ReadModel.Inspection` answers what durable journal
projections currently show. This module answers why that state matters to an
operator by deriving a deterministic reason, high-signal details, and the
runtime boundary that would make progress.

Explanations are read-only. They do not schedule missing dispatches, apply
completed results, recover expired claims, or mutate checkpoints.

# `explanation_error`

```elixir
@type explanation_error() ::
  Squidie.ReadModel.Inspection.snapshot_error()
  | {:invalid_option, {:run_id, :invalid}}
```

# `explanation_option`

```elixir
@type explanation_option() :: Squidie.ReadModel.Inspection.snapshot_option()
```

# `storage_config`

```elixir
@type storage_config() :: Squidie.ReadModel.Inspection.storage_config()
```

# `explain`

```elixir
@spec explain(storage_config(), String.t(), [explanation_option()]) ::
  {:ok, Squidie.ReadModel.Explanation.Diagnostic.t()}
  | {:error, explanation_error()}
```

Builds a projection-backed explanation for one workflow run.

Options are the same as `Squidie.ReadModel.Inspection.snapshot/3`.
Missing runs and invalid options return the same structured errors as the
underlying snapshot call.

# `from_snapshot`

```elixir
@spec from_snapshot(Squidie.ReadModel.Inspection.Snapshot.t()) ::
  Squidie.ReadModel.Explanation.Diagnostic.t()
```

Derives an explanation from an existing projection-backed snapshot.

This is useful when a caller already has a snapshot and wants a stable
diagnostic view without re-reading storage.

---

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