SquidMesh.Workflow.Definition (squid_mesh v0.1.0-alpha.3)

Copy Markdown View Source

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.

Summary

Types

built_in_step_kind()
dependency_progress()
dependency_step_status()
inspect_step()
inspect_step_status()
load_error()
payload_error_details()
payload_field()
retry()
step()
step_input_mapping()
step_output_mapping()
t()
transition()
transition_outcome()
transition_target()
trigger()
trigger_error()
trigger_type()

Functions

apply_output_mapping(definition, step_name, output)

Applies the declared output mapping for one step result.

approval_transition_targets(definition, step_name)

Resolves the success and rejection targets for an approval step.

default_trigger(definition)

Returns the default trigger for the workflow definition.

dependency_mode?(definition)

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

dependency_progress(definition, step_statuses)

Resolves dependency-mode progress from persisted per-step state.

deserialize_payload(definition, payload)

Deserializes persisted payload keys back to declared workflow field names.

deserialize_step(definition, step_name)

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

deserialize_trigger(definition, trigger_name)

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

entry_step(definition)

Returns the workflow entry step.

entry_steps(definition)

Returns the workflow entry steps in semantic execution order.

initial_step(definition)

Returns the first step scheduled when a run starts.

inspect_steps(definition, step_statuses \\ %{})

Builds the public per-step inspection view from declared steps and persisted step statuses.

load(workflow)

Loads a compiled workflow definition from a workflow module.

load_serialized(workflow_name)

Loads a workflow definition from its persisted module name.

next_step_after_success(definition, from_step, completed_steps)

Resolves the next step after a successful execution.

resolve_payload(definition, payload)

Resolves payload defaults and validates the final payload for a new run.

resolve_trigger(definition, trigger_name)

Resolves one named trigger from the workflow definition.

serialize_step(step)

Serializes a step identifier for persistence.

serialize_trigger(trigger)

Serializes a trigger identifier for persistence.

serialize_workflow(workflow)

Serializes a workflow module name for persistence.

step(definition, step_name)

Fetches one declared workflow step by name.

step_input_mapping(definition, step_name)

Returns the explicit input mapping for one declared step, if any.

step_output_mapping(definition, step_name)

Returns the explicit output mapping key for one declared step, if any.

transition_target(definition, from_step, outcome)

Resolves the transition target for a step outcome.

validate_payload(definition, payload)

Validates a payload map against the workflow payload contract.

Types

built_in_step_kind()

@type built_in_step_kind() :: :wait | :log | :pause | :approval

dependency_progress()

@type dependency_progress() ::
  :complete
  | {:dispatch, [atom()]}
  | {:wait, [atom()]}
  | {:error, {:no_runnable_step, [atom()]}}

dependency_step_status()

@type dependency_step_status() :: :pending | :running | :completed | :failed

inspect_step()

@type inspect_step() :: %{
  step: atom(),
  depends_on: [atom()],
  status: inspect_step_status()
}

inspect_step_status()

@type inspect_step_status() :: dependency_step_status() | :waiting

load_error()

@type load_error() :: {:invalid_workflow, module() | String.t()}

payload_error_details()

@type payload_error_details() :: %{
  optional(:missing_fields) => [atom()],
  optional(:unknown_fields) => [atom() | String.t()],
  optional(:invalid_types) => %{optional(atom()) => atom()}
}

payload_field()

@type payload_field() :: %{name: atom(), type: atom(), opts: keyword()}

retry()

@type retry() :: %{step: atom(), opts: keyword()}

step()

@type step() :: %{
  name: atom(),
  module: module() | built_in_step_kind(),
  opts: keyword()
}

step_input_mapping()

@type step_input_mapping() :: [atom()]

step_output_mapping()

@type step_output_mapping() :: atom()

t()

@type t() :: %{
  triggers: [trigger()],
  payload: [payload_field()],
  steps: [step()],
  transitions: [transition()],
  retries: [retry()],
  entry_steps: [atom()],
  initial_step: atom(),
  entry_step: atom() | nil
}

transition()

@type transition() :: %{from: atom(), on: transition_outcome(), to: atom()}

transition_outcome()

@type transition_outcome() :: :ok | :error

transition_target()

@type transition_target() :: atom() | :complete

trigger()

@type trigger() :: %{
  name: atom(),
  type: trigger_type(),
  config: map(),
  payload: [payload_field()]
}

trigger_error()

@type trigger_error() :: {:invalid_trigger, atom() | String.t()}

trigger_type()

@type trigger_type() :: :manual | :cron

Functions

apply_output_mapping(definition, step_name, output)

@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(definition, step_name)

@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(definition)

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

Returns the default trigger for the workflow definition.

dependency_mode?(definition)

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

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

dependency_progress(definition, step_statuses)

@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(definition, payload)

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

Deserializes persisted payload keys back to declared workflow field names.

deserialize_step(definition, step_name)

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

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

deserialize_trigger(definition, trigger_name)

@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(definition)

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

Returns the workflow entry step.

entry_steps(definition)

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

Returns the workflow entry steps in semantic execution order.

initial_step(definition)

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

Returns the first step scheduled when a run starts.

inspect_steps(definition, step_statuses \\ %{})

@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(workflow)

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

Loads a compiled workflow definition from a workflow module.

load_serialized(workflow_name)

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

Loads a workflow definition from its persisted module name.

next_step_after_success(definition, from_step, completed_steps)

@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(definition, payload)

@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(definition, trigger_name)

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

Resolves one named trigger from the workflow definition.

serialize_step(step)

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

Serializes a step identifier for persistence.

serialize_trigger(trigger)

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

Serializes a trigger identifier for persistence.

serialize_workflow(workflow)

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

Serializes a workflow module name for persistence.

step(definition, step_name)

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

Fetches one declared workflow step by name.

step_input_mapping(definition, step_name)

@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(definition, step_name)

@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(definition, from_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.

validate_payload(definition, payload)

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

Validates a payload map against the workflow payload contract.