@spec approve_run(Ecto.UUID.t(), map(), keyword()) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found | :invalid_run_id | SquidMesh.Config.config_error() | term()}

Approves a paused approval step and resumes the run through its success path.

By default, this resolves an inspectable journal approval boundary and persists the decision as journal facts. Pass journal_storage: only when overriding the inferred Ecto storage boundary.

@spec cancel_run(
  Ecto.UUID.t(),
  keyword()
) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found
     | :invalid_run_id
     | SquidMesh.Config.config_error()
     | SquidMesh.Runtime.Journal.Cancellation.cancel_error()}

Requests cancellation for an eligible workflow run.

@spec config(keyword()) ::
  {:ok, SquidMesh.Config.t()} | {:error, SquidMesh.Config.config_error()}

Loads Squid Mesh configuration from the application environment with optional runtime overrides.

@spec config!(keyword()) :: SquidMesh.Config.t()

Loads Squid Mesh configuration and raises if required keys are missing.

@spec execute_next(keyword()) :: SquidMesh.Runtime.Journal.Executor.execute_result()

Executes the next visible workflow attempt through the selected runtime.

The default journal runtime claims one visible Jido journal-backed attempt, runs its declared step, and appends durable attempt completion or failure facts. Pass journal_storage: only when overriding the inferred Ecto storage boundary.

@spec explain_run(
  String.t(),
  keyword()
) ::
  {:ok, SquidMesh.ReadModel.Explanation.Diagnostic.t()}
  | {:error,
     :not_found
     | :invalid_run_id
     | read_option_error()
     | SquidMesh.Config.config_error()
     | SquidMesh.ReadModel.Explanation.explanation_error()}

Explains the current runtime state of one workflow run.

The result is structured diagnostic data for host apps, CLIs, and dashboards. Use inspect_run/2 for the factual run snapshot and explain_run/2 when an operator-facing surface needs the reason, evidence, and valid next actions for the run's current state.

The selected read model comes from host configuration unless overridden. The read model derives diagnostics from durable journal projections.

@spec inspect_run(
  String.t(),
  keyword()
) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found
     | :invalid_run_id
     | read_option_error()
     | SquidMesh.Config.config_error()
     | SquidMesh.ReadModel.Inspection.snapshot_error()}

Fetches one workflow run by id.

The selected read model comes from host configuration unless overridden. The read model rebuilds a projection-backed snapshot from durable journal entries.

@spec inspect_run_graph(
  String.t(),
  keyword()
) ::
  {:ok, SquidMesh.Runs.GraphInspection.t()}
  | {:error,
     :not_found
     | :invalid_run_id
     | read_option_error()
     | SquidMesh.Config.config_error()
     | SquidMesh.ReadModel.Inspection.snapshot_error()}

Fetches one workflow run as graph-oriented inspection data.

The graph projection preserves inspect_run/2 as the factual run snapshot and derives nodes and edges from that same durable state. The selected read model comes from host configuration unless overridden.

@spec list_runs(
  [SquidMesh.ReadModel.Listing.list_filter()],
  keyword()
) ::
  {:ok, [SquidMesh.ReadModel.Listing.Summary.t()]}
  | {:error,
     SquidMesh.Config.config_error() | SquidMesh.ReadModel.Listing.list_error()}

Lists workflow runs with optional filters.

Journal-backed runtime calls return redacted listing summaries. Use inspect_run/2 or inspect_run_graph/2 with a run id when callers need detailed runtime state for one run.

@spec reject_run(Ecto.UUID.t(), map(), keyword()) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found | :invalid_run_id | SquidMesh.Config.config_error() | term()}

Rejects a paused approval step and resumes the run through its rejection path.

By default, this resolves an inspectable journal approval boundary and persists the decision as journal facts. Pass journal_storage: only when overriding the inferred Ecto storage boundary.

@spec replay_run(
  Ecto.UUID.t(),
  keyword()
) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found
     | :invalid_run_id
     | SquidMesh.Config.config_error()
     | SquidMesh.Runtime.Journal.Replay.replay_error()}
  | {:error, {:dispatch_failed, term()}}

Creates a new run from a prior run and links it to the original run.

Replays are blocked by default once the source run completed an irreversible or non-compensatable step. Pass allow_irreversible: true only after an operator has reviewed the side effect and accepted re-execution.

@spec start_run(module(), map()) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error, SquidMesh.Config.config_error()}
  | {:error, start_option_error()}
  | {:error, SquidMesh.Runtime.Journal.Starter.start_error()}
  | {:error, {:dispatch_failed, term()}}

Starts a new workflow run with the given payload through the workflow's default trigger.

The Jido journal runtime returns a projection-backed SquidMesh.ReadModel.Inspection.Snapshot.

@spec start_run(module(), map(), keyword()) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error, SquidMesh.Config.config_error()}
  | {:error, {:invalid_option, atom()}}
  | {:error, start_option_error()}
  | {:error, SquidMesh.Runtime.Journal.Starter.start_error()}
  | {:error, {:dispatch_failed, term()}}

@spec start_run(module(), atom(), map()) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error, SquidMesh.Config.config_error()}
  | {:error, start_option_error()}
  | {:error, SquidMesh.Runtime.Journal.Starter.start_error()}
  | {:error, {:dispatch_failed, term()}}

Starts a new workflow run through a named trigger with the given payload.

@spec start_run(module(), atom(), map(), keyword()) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error, SquidMesh.Config.config_error()}
  | {:error, {:invalid_option, atom()}}
  | {:error, start_option_error()}
  | {:error, SquidMesh.Runtime.Journal.Starter.start_error()}
  | {:error, {:dispatch_failed, term()}}

Starts a named trigger while applying runtime configuration overrides.

Overrides are intended for host-app test and integration boundaries. Runtime context injection is kept out of this public API so scheduled starts and other internal callers can keep their idempotency metadata isolated.

The Jido journal runtime is the default and infers Ecto-backed journal storage from the configured repo. Pass journal_storage: only when a host, test, or integration boundary needs a non-default storage adapter. Journal execution supports normal action steps, immediate built-in :log steps, built-in :wait steps in transition and dependency workflows, and manual :pause or :approval boundaries.

@spec unblock_run(Ecto.UUID.t()) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found | :invalid_run_id | SquidMesh.Config.config_error() | term()}

Resumes a run that is intentionally paused for manual intervention.

This arity uses the configured runtime. By default, it resolves an inspectable journal pause boundary using the inferred Ecto journal storage.

@spec unblock_run(
  Ecto.UUID.t(),
  keyword()
) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found | :invalid_run_id | SquidMesh.Config.config_error() | term()}

@spec unblock_run(Ecto.UUID.t(), map()) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found | :invalid_run_id | SquidMesh.Config.config_error() | term()}

Resumes a paused run with either configuration overrides or manual action attributes.

Pass a keyword list to override runtime configuration, or a map to provide manual action attributes. Attribute maps are validated against the paused step's manual action contract before the runtime appends resume events or dispatches successor work.

@spec unblock_run(Ecto.UUID.t(), map(), keyword()) ::
  {:ok, SquidMesh.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found | :invalid_run_id | SquidMesh.Config.config_error() | term()}

Resumes a paused run with manual action attributes and configuration overrides.

By default, this resolves an inspectable journal pause boundary and persists the manual action attributes in journal resolution metadata. Pass journal_storage: only when overriding the inferred Ecto storage boundary.