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

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

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

Decodes a JSON payload from the Observer signal form.

@spec get_run(
  binary(),
  keyword()
) :: {:ok, Continuum.Run.t()} | {:error, :not_found | term()}

Loads one run for the Observer detail view.

@spec health(keyword()) :: {:ok, map()} | {:error, term()}

Builds the operational health report shown by the Observer health panel.

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

Lists bounded activity task state and last-heartbeat progress for a run.

Heartbeat details pass through the same configurable Observer redactor as event payloads.

@spec list_events(
  binary(),
  keyword()
) :: {:ok, Continuum.Page.t(map())} | {:error, term()}

Lists a bounded keyset page of decoded journal events ordered by sequence.

Pass :after_seq to continue from a previous page, :limit (capped at 100), :max_payload_bytes to reject oversized encoded payloads before decoding, and :redactor as a unary function or module that exports redact/1. The configured :observer_redactor application setting is used when :redactor is omitted.

@spec list_runs(keyword()) ::
  {:ok, Continuum.Page.t(Continuum.Run.t())} | {: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.

@spec pretty(
  term(),
  keyword()
) :: binary()

Pretty prints an event payload for display with a hard byte cap.

@spec repair_health(atom() | binary(), binary(), keyword()) ::
  {:ok, map()} | {:error, term()}

Plans or executes a fenced operational repair from the Observer.

Repairs remain dry-run by default; pass execute: true after presenting an explicit confirmation to the operator.

@spec replay_report(
  binary(),
  keyword()
) :: {:ok, map()} | {:error, term()}

Produces a read-only replay report with bounded work for the Observer.

Runs in an isolated worker and applies the configured Observer redactor to reported results and diagnostics. Defaults: 2 seconds, 2,000 events, 8 MiB combined encoded snapshot/history, and 64 KiB per input/result/event payload. Options :timeout_ms, :max_events, :max_history_bytes, and :max_payload_bytes may raise these up to 5 seconds, 10,000 events, 16 MiB, and 1 MiB respectively. Oversized data is refused before transferring it from PostgreSQL. A heap limit also bounds decoded data in the worker.

Accepts the instance, snapshot, against-module, and redactor options from Continuum.Replay.of_run/2. This helper provides no independent authorization; call it behind the same host authorization as the run detail view.

@spec run_topic(binary()) :: binary()

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

@spec runs_topic() :: binary()

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

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

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

@spec signal_contracts(
  binary(),
  keyword()
) :: {:ok, Continuum.SignalContract.contracts()} | {:error, term()}

Returns the signal contracts declared by the run's workflow version.

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

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

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

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

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

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