@spec apply_output_mapping(t(), atom(), map()) ::
  {:ok, map()} | {:error, {:unknown_step, atom()}}

Applies the declared output mapping for one step result.

@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.

@spec default_trigger(t()) :: atom()

Returns the default trigger for the workflow definition.

@spec dependency_mode?(t()) :: boolean()

Returns true when the workflow uses dependency-based step progression.

@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.

@spec deserialize_payload(t() | nil, map()) :: map()

Deserializes persisted payload keys back to declared workflow field names.

@spec deserialize_step(t(), String.t() | nil) :: atom() | String.t() | nil

Deserializes a persisted step name back to the declared workflow step.

@spec deserialize_trigger(t() | nil, String.t() | nil) :: atom() | String.t() | nil

Deserializes a persisted trigger name back to the declared workflow trigger.

@spec entry_step(t()) :: atom() | nil

Returns the workflow entry step.

@spec entry_steps(t()) :: [atom()]

Returns the workflow entry steps in semantic execution order.

@spec failure_recovery(t(), atom()) ::
  {:ok, failure_recovery() | nil}
  | {:error, {:unknown_transition, atom(), atom()}}

Returns the explicit failure recovery route for a step when one was declared.

@spec initial_step(t()) :: atom()

Returns the first step scheduled when a run starts.

@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.

@spec load(module()) :: {:ok, t()} | {:error, load_error()}

Loads a compiled workflow definition from a workflow module.

@spec load_serialized(String.t()) :: {:ok, module(), t()} | {:error, load_error()}

Loads a workflow definition from its persisted module name.

@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.

@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.

@spec resolve_trigger(t(), atom()) :: {:ok, atom()} | {:error, trigger_error()}

Resolves one named trigger from the workflow definition.

@spec serialize_step(atom() | String.t() | nil) :: String.t() | nil

Serializes a step identifier for persistence.

@spec serialize_trigger(atom() | String.t() | nil) :: String.t() | nil

Serializes a trigger identifier for persistence.

@spec serialize_workflow(module()) :: String.t()

Serializes a workflow module name for persistence.

@spec step(t(), atom()) :: {:ok, step()} | {:error, {:unknown_step, atom()}}

Fetches one declared workflow step by name.

@spec step_compensation_callback(t(), atom()) ::
  {:ok, module() | nil} | {:error, {:unknown_step, atom()}}

Returns the compensation callback for one declared step, if any.

A callback means the step's completed side effect is reversible by a host application action. The runtime uses it only during saga rollback after a downstream terminal failure, never as a same-step fallback.

@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.

@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.

@spec step_recovery_policy(t(), atom()) ::
  {:ok, recovery_policy()} | {:error, {:unknown_step, atom()}}

Returns the recovery policy for one declared step.

Irreversible steps are always treated as non-compensatable. Steps marked compensatable: false keep their reversibility marker but still require explicit operator review before replay.

@spec step_transaction_boundary(t(), atom()) ::
  {:ok, step_transaction_boundary() | nil} | {:error, {:unknown_step, atom()}}

Returns the local transaction boundary for one declared step, if any.

:repo wraps only the host action execution in the configured Ecto repo transaction. Squid Mesh persists attempt, step, and run progression in its normal durable phase after the action returns.

@spec transition(t(), atom(), transition_outcome()) ::
  {:ok, transition()} | {:error, {:unknown_transition, atom(), atom()}}

Resolves the full transition metadata for one step outcome.

@spec transition_target(t(), atom(), transition_outcome()) ::
  {:ok, transition_target()} | {:error, {:unknown_transition, atom(), atom()}}

Resolves the transition target for a step outcome.

@spec trigger(t(), atom()) :: {:ok, trigger()} | {:error, trigger_error()}

Fetches one declared workflow trigger by name.

@spec unsafe_replay_steps(t(), [
  atom() | String.t() | {atom() | String.t(), map() | nil}
]) :: [map()]

Returns completed steps whose recovery policy makes replay unsafe by default.

@spec validate_payload(t(), map()) ::
  :ok | {:error, {:invalid_payload, payload_error_details()}}

Validates a payload map against the workflow payload contract.