# `SquidMesh.Workflow.Definition` [🔗](https://github.com/ccarvalho-eng/squid_mesh/blob/main/lib/squid_mesh/workflow/definition.ex#L1) Runtime-facing representation of a compiled workflow definition. `SquidMesh.Workflow` builds the declarative DSL at compile time. This module loads the compiled definition and applies the runtime operations needed for run creation, payload resolution, and persistence serialization. # `built_in_step_kind` ```elixir @type built_in_step_kind() :: :wait | :log | :pause | :approval ``` # `dependency_progress` ```elixir @type dependency_progress() :: :complete | {:dispatch, [atom()]} | {:wait, [atom()]} | {:error, {:no_runnable_step, [atom()]}} ``` # `dependency_step_status` ```elixir @type dependency_step_status() :: :pending | :running | :completed | :failed ``` # `inspect_step` ```elixir @type inspect_step() :: %{ step: atom(), depends_on: [atom()], status: inspect_step_status() } ``` # `inspect_step_status` ```elixir @type inspect_step_status() :: dependency_step_status() | :waiting ``` # `load_error` ```elixir @type load_error() :: {:invalid_workflow, module() | String.t()} ``` # `payload_error_details` ```elixir @type payload_error_details() :: %{ optional(:missing_fields) => [atom()], optional(:unknown_fields) => [atom() | String.t()], optional(:invalid_types) => %{optional(atom()) => atom()} } ``` # `payload_field` ```elixir @type payload_field() :: %{name: atom(), type: atom(), opts: keyword()} ``` # `retry` ```elixir @type retry() :: %{step: atom(), opts: keyword()} ``` # `step` ```elixir @type step() :: %{ name: atom(), module: module() | built_in_step_kind(), opts: keyword() } ``` # `step_input_mapping` ```elixir @type step_input_mapping() :: [atom()] ``` # `step_output_mapping` ```elixir @type step_output_mapping() :: atom() ``` # `t` ```elixir @type t() :: %{ triggers: [trigger()], payload: [payload_field()], steps: [step()], transitions: [transition()], retries: [retry()], entry_steps: [atom()], initial_step: atom(), entry_step: atom() | nil } ``` # `transition` ```elixir @type transition() :: %{from: atom(), on: transition_outcome(), to: atom()} ``` # `transition_outcome` ```elixir @type transition_outcome() :: :ok | :error ``` # `transition_target` ```elixir @type transition_target() :: atom() | :complete ``` # `trigger` ```elixir @type trigger() :: %{ name: atom(), type: trigger_type(), config: map(), payload: [payload_field()] } ``` # `trigger_error` ```elixir @type trigger_error() :: {:invalid_trigger, atom() | String.t()} ``` # `trigger_type` ```elixir @type trigger_type() :: :manual | :cron ``` # `apply_output_mapping` ```elixir @spec apply_output_mapping(t(), atom(), map()) :: {:ok, map()} | {:error, {:unknown_step, atom()}} ``` Applies the declared output mapping for one step result. # `approval_transition_targets` ```elixir @spec approval_transition_targets(t(), atom()) :: {:ok, %{ok: transition_target(), error: transition_target()}} | {:error, {:unknown_transition, atom(), atom()}} ``` Resolves the success and rejection targets for an approval step. # `default_trigger` ```elixir @spec default_trigger(t()) :: atom() ``` Returns the default trigger for the workflow definition. # `dependency_mode?` ```elixir @spec dependency_mode?(t()) :: boolean() ``` Returns true when the workflow uses dependency-based step progression. # `dependency_progress` ```elixir @spec dependency_progress( t(), %{optional(atom() | String.t()) => dependency_step_status() | String.t()} ) :: dependency_progress() ``` Resolves dependency-mode progress from persisted per-step state. Ready steps are scheduled breadth-first by dependency phase so newly unlocked descendants do not bypass incomplete root or sibling steps. # `deserialize_payload` ```elixir @spec deserialize_payload(t() | nil, map()) :: map() ``` Deserializes persisted payload keys back to declared workflow field names. # `deserialize_step` ```elixir @spec deserialize_step(t(), String.t() | nil) :: atom() | String.t() | nil ``` Deserializes a persisted step name back to the declared workflow step. # `deserialize_trigger` ```elixir @spec deserialize_trigger(t() | nil, String.t() | nil) :: atom() | String.t() | nil ``` Deserializes a persisted trigger name back to the declared workflow trigger. # `entry_step` ```elixir @spec entry_step(t()) :: atom() | nil ``` Returns the workflow entry step. # `entry_steps` ```elixir @spec entry_steps(t()) :: [atom()] ``` Returns the workflow entry steps in semantic execution order. # `initial_step` ```elixir @spec initial_step(t()) :: atom() ``` Returns the first step scheduled when a run starts. # `inspect_steps` ```elixir @spec inspect_steps( t(), %{ optional(atom() | String.t()) => dependency_step_status() | inspect_step_status() } ) :: [inspect_step()] ``` Builds the public per-step inspection view from declared steps and persisted step statuses. # `load` ```elixir @spec load(module()) :: {:ok, t()} | {:error, load_error()} ``` Loads a compiled workflow definition from a workflow module. # `load_serialized` ```elixir @spec load_serialized(String.t()) :: {:ok, module(), t()} | {:error, load_error()} ``` Loads a workflow definition from its persisted module name. # `next_step_after_success` ```elixir @spec next_step_after_success(t(), atom(), [atom() | String.t()]) :: {:ok, transition_target()} | {:error, {:no_runnable_step, [atom()]}} ``` Resolves the next step after a successful execution. # `resolve_payload` ```elixir @spec resolve_payload(t(), map()) :: {:ok, map()} | {:error, {:invalid_payload, payload_error_details()}} ``` Resolves payload defaults and validates the final payload for a new run. # `resolve_trigger` ```elixir @spec resolve_trigger(t(), atom()) :: {:ok, atom()} | {:error, trigger_error()} ``` Resolves one named trigger from the workflow definition. # `serialize_step` ```elixir @spec serialize_step(atom() | String.t() | nil) :: String.t() | nil ``` Serializes a step identifier for persistence. # `serialize_trigger` ```elixir @spec serialize_trigger(atom() | String.t() | nil) :: String.t() | nil ``` Serializes a trigger identifier for persistence. # `serialize_workflow` ```elixir @spec serialize_workflow(module()) :: String.t() ``` Serializes a workflow module name for persistence. # `step` ```elixir @spec step(t(), atom()) :: {:ok, step()} | {:error, {:unknown_step, atom()}} ``` Fetches one declared workflow step by name. # `step_input_mapping` ```elixir @spec step_input_mapping(t(), atom()) :: {:ok, step_input_mapping() | nil} | {:error, {:unknown_step, atom()}} ``` Returns the explicit input mapping for one declared step, if any. # `step_output_mapping` ```elixir @spec step_output_mapping(t(), atom()) :: {:ok, step_output_mapping() | nil} | {:error, {:unknown_step, atom()}} ``` Returns the explicit output mapping key for one declared step, if any. # `transition_target` ```elixir @spec transition_target(t(), atom(), transition_outcome()) :: {:ok, transition_target()} | {:error, {:unknown_transition, atom(), atom()}} ``` Resolves the transition target for a step outcome. # `validate_payload` ```elixir @spec validate_payload(t(), map()) :: :ok | {:error, {:invalid_payload, payload_error_details()}} ``` Validates a payload map against the workflow payload contract. --- *Consult [api-reference.md](api-reference.md) for complete listing*