# `Continuum.Observer`
[🔗](https://github.com/Yyeger/Continuum/blob/main/lib/continuum/observer.ex#L1)

Data and action helpers for the optional Continuum Observer.

The Observer is mounted from a host Phoenix router with
`Continuum.Observer.Router.continuum_observer/2`. Continuum does not start an
Observer supervisor and does not provide authentication; mount it only inside
an authenticated admin scope.

Query helpers in this module are Phoenix-independent and operate on the
configured Continuum instance repo. Event payloads are decoded with
`:erlang.binary_to_term/1` because Continuum stores its own trusted journal
data as `bytea`; the Observer is not a boundary for untrusted database writes.

# `run_state`

```elixir
@type run_state() :: :running | :suspended | :completed | :failed | :cancelled
```

# `cancel_run`

```elixir
@spec cancel_run(
  binary(),
  keyword()
) :: :ok | {:error, term()}
```

Cancels a run through the public Continuum API using the Observer instance.

# `decode_signal_payload`

```elixir
@spec decode_signal_payload(binary()) :: {:ok, term()} | {:error, term()}
```

Decodes a JSON payload from the Observer signal form.

# `get_run`

```elixir
@spec get_run(
  binary(),
  keyword()
) :: {:ok, map()} | {:error, :not_found | term()}
```

Loads one run for the Observer detail view.

# `list_events`

```elixir
@spec list_events(
  binary(),
  keyword()
) :: {:ok, [map()]} | {:error, term()}
```

Lists decoded journal events for a run ordered by sequence.

# `list_runs`

```elixir
@spec list_runs(keyword()) :: {:ok, map()} | {:error, term()}
```

Lists runs for the Observer index.

Options:

  * `:instance` - Continuum instance name or struct. Defaults to `Continuum`.
  * `:state` - atom/string run state filter.
  * `:workflow` - workflow module substring filter.
  * `:search` - run id or workflow substring filter.
  * `:page` - 1-based page number.
  * `:per_page` - page size, capped at 100.

# `pretty`

```elixir
@spec pretty(term()) :: binary()
```

Pretty prints an event payload for display.

# `run_topic`

```elixir
@spec run_topic(binary()) :: binary()
```

Returns the per-run topic used by run detail pages.

# `runs_topic`

```elixir
@spec runs_topic() :: binary()
```

Returns the low-fidelity per-instance runs topic used by the Observer index.

# `send_signal`

```elixir
@spec send_signal(binary(), atom() | binary(), term(), keyword()) ::
  :ok | {:error, term()}
```

Sends a signal through the public Continuum API using the Observer instance.

# `subscribe_run`

```elixir
@spec subscribe_run(
  binary(),
  keyword()
) :: :ok | {:error, term()}
```

Subscribes the caller to full-fidelity updates for a single run.

# `subscribe_runs`

```elixir
@spec subscribe_runs(keyword()) :: :ok | {:error, term()}
```

Subscribes the caller to coarse run-index updates for an instance.

# `successor_run_id`

```elixir
@spec successor_run_id(
  binary(),
  keyword()
) :: binary() | nil
```

Returns the run id that this run continued into via `continue_as_new`, or nil.

---

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