@spec apply_signal(
  Squidie.Runtime.Signal.t(),
  keyword()
) ::
  {:ok, Squidie.ReadModel.Inspection.Snapshot.t()}
  | {:error, Squidie.Config.config_error() | term()}

Applies a Squidie-native runtime command signal.

Use the named helpers such as start/3, cancel/2, resume/3, approve/3, reject/3, and replay/2 for ordinary application calls. Use apply_signal/2 when an agent, router, webhook, scheduler, or Jido interop boundary has already normalized a request into a Squidie.Runtime.Signal envelope.

The envelope API applies the same runtime commands for starts, cron starts, replays, cancellation, and manual decisions while preserving signal metadata, occurrence time, and idempotency keys in the journal command history.

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

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

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

Requests cancellation for an eligible workflow run.

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

Loads Squidie configuration from the application environment with optional runtime overrides.

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

Loads Squidie configuration and raises if required keys are missing.

@spec execute_next(keyword()) :: Squidie.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, Squidie.ReadModel.Explanation.Diagnostic.t()}
  | {:error,
     :not_found
     | :invalid_run_id
     | read_option_error()
     | Squidie.Config.config_error()
     | Squidie.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, Squidie.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found
     | :invalid_run_id
     | read_option_error()
     | Squidie.Config.config_error()
     | Squidie.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, Squidie.Runs.GraphInspection.t()}
  | {:error,
     :not_found
     | :invalid_run_id
     | read_option_error()
     | Squidie.Config.config_error()
     | Squidie.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(
  [Squidie.ReadModel.Listing.list_filter()],
  keyword()
) ::
  {:ok, [Squidie.ReadModel.Listing.Summary.t()]}
  | {:error,
     Squidie.Config.config_error() | Squidie.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 preview_dynamic_work(String.t(), map() | keyword(), keyword()) ::
  {:ok, Squidie.Runs.DynamicWorkPreview.t()}
  | {:error,
     :not_found
     | Squidie.Config.config_error()
     | read_option_error()
     | Squidie.Runtime.Journal.DynamicWork.dynamic_work_error()
     | term()}

Validates bounded dynamic work and returns the graph it would produce.

This is the read-only companion to record_dynamic_work/3. It applies the same validation and normalization rules, but does not append a journal fact. Use it for UI previews, visual editor validation, and host-side dry runs before recording dynamic work durably. Pass :action_registry to require every dynamic node action key to be host-allowlisted before previewing.

@spec record_dynamic_work(String.t(), map() | keyword(), keyword()) ::
  {:ok, Squidie.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found
     | Squidie.Config.config_error()
     | read_option_error()
     | Squidie.Runtime.Journal.DynamicWork.dynamic_work_error()
     | term()}

Records bounded dynamic work for one workflow run.

This API records inspection-only dynamic structure. It does not make dynamic nodes executable, schedule dispatch attempts, or alter terminal-state decisions. Use it when host code or a runtime step has already made a bounded fanout or planning decision and dashboards need durable, validated metadata about that decision.

The attribute payload must include:

• :dynamic_key - a stable non-empty string for this dynamic work group.
• :origin - a map with :runnable_key, :step, and positive :attempt matching a planned runnable in the active run.
• :nodes - one or more dynamic node maps with unique non-empty :id values that do not collide with declared workflow steps or previously recorded dynamic nodes.

Optional :edges, :metadata, :reason, and :status values are normalized and redacted like other journal metadata. Pass :action_registry to require every dynamic node action key to be host-allowlisted before recording. Exact duplicate records are idempotent while the run remains active. Terminal runs, stale workflow definitions, invalid origins, node collisions, unknown options, and write conflicts return structured {:error, reason} tuples.

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

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

@spec replay(
  Ecto.UUID.t(),
  keyword()
) ::
  {:ok, Squidie.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found
     | :invalid_run_id
     | Squidie.Config.config_error()
     | Squidie.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 resume(Ecto.UUID.t()) ::
  {:ok, Squidie.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found | :invalid_run_id | Squidie.Config.config_error() | term()}

Resumes a run that is intentionally paused for manual intervention.

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

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

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

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

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

@spec schedule_dynamic_work(String.t(), map() | keyword(), keyword()) ::
  {:ok, Squidie.ReadModel.Inspection.Snapshot.t()}
  | {:error,
     :not_found
     | Squidie.Config.config_error()
     | read_option_error()
     | Squidie.Runtime.Journal.DynamicWork.dynamic_work_error()
     | term()}

Records bounded dynamic work and schedules each dynamic node as executable work.

This is the executable counterpart to record_dynamic_work/3. The dynamic work fact and the planned runnable intents are appended to the run thread in one optimistic write, then missing dispatch attempts are scheduled from that durable plan. Pass :action_registry; every dynamic node must include an approved :action key and may include an :input map for the scheduled attempt.

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

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

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

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

Starts a new workflow run through the workflow's default trigger with runtime overrides, or through a named trigger without runtime overrides.

@spec start(module(), atom(), map(), keyword()) ::
  {:ok, Squidie.ReadModel.Inspection.Snapshot.t()}
  | {:error, Squidie.Config.config_error()}
  | {:error, {:invalid_option, atom()}}
  | {:error, start_option_error()}
  | {:error, Squidie.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 start_child_run(Squidie.Step.Context.t(), module(), map(), keyword()) ::
  {:ok, Squidie.ReadModel.Inspection.Snapshot.t()}
  | {:error, Squidie.Config.config_error()}
  | {:error, {:invalid_option, atom() | term()}}
  | {:error, Squidie.Runtime.Journal.ChildStarter.start_error()}

Starts a child workflow run from a native step context.

Child starts are deterministic for the parent run, parent step, child workflow, child trigger, and required :child_key. Duplicate calls with the same key return the existing child run and do not duplicate parent lineage.

@spec start_spec(Squidie.Workflow.Spec.t() | map(), map(), keyword()) ::
  {:ok, Squidie.ReadModel.Inspection.Snapshot.t()}
  | {:error, Squidie.Config.config_error()}
  | {:error, start_option_error()}
  | {:error, Squidie.Runtime.Journal.Starter.start_error()}
  | {:error, {:dispatch_failed, term()}}

Starts a runtime-authored workflow spec through its default trigger.

Runtime-authored specs should be validated with a host-owned action registry before activation. Passing :action_registry lets Squidie resolve stable action keys to approved executable modules at the start boundary.

@spec start_spec(Squidie.Workflow.Spec.t() | map(), atom(), map(), keyword()) ::
  {:ok, Squidie.ReadModel.Inspection.Snapshot.t()}
  | {:error, Squidie.Config.config_error()}
  | {:error, start_option_error()}
  | {:error, Squidie.Runtime.Journal.Starter.start_error()}
  | {:error, {:dispatch_failed, term()}}

Starts a runtime-authored workflow spec through a named trigger.