SquidMesh.Workflow (squid_mesh v0.1.0-beta.3)

Declarative workflow contract for Squid Mesh workflow modules.

Example

defmodule Billing.InvoiceReminder do
  use SquidMesh.Workflow

  workflow do
    trigger :invoice_delivery do
      manual()

      payload do
        field :account_id, :string
        field :invoice_id, :string
      end
    end

    step :load_invoice, Billing.Steps.LoadInvoice
    step :send_email, Billing.Steps.SendReminderEmail, retry: [max_attempts: 3]

    transition :load_invoice, on: :ok, to: :send_email
  end
end

The contract defined here captures workflow structure. Validation and runtime execution behavior are added in subsequent slices.

Summary

Functions

__before_compile__(env)

Validates the collected workflow declarations and emits runtime accessors.

__push_current_trigger_definition__(module, definition)

Adds one trigger definition to the workflow module currently being compiled.

__push_current_trigger_payload_field__(module, field)

Adds one payload field to the trigger currently being compiled.

__resolve_runtime_definition__(definition)

Resolves late-bound runtime metadata for generated workflow definitions.

__using__(opts)

Injects the workflow DSL and compile-time collectors into a workflow module.

cron(expression, opts \\ [])

Declares a cron-based trigger.

field(name, type, opts \\ [])

Declares one payload field inside a trigger payload block.

manual()

Declares a manual trigger.

payload(list)

Declares the payload contract for the current trigger.

to_spec(workflow)

Converts a compiled workflow module into Squid Mesh's normalized workflow spec.

transition(from, opts)

Declares a transition from one step outcome to the next step.

trigger(name, list)

Declares a named workflow trigger.

validate_spec(spec)

Validates a normalized workflow spec without resolving workflow or step modules.

Functions

__before_compile__(env)

(macro)

@spec __before_compile__(Macro.Env.t()) :: Macro.t()

Validates the collected workflow declarations and emits runtime accessors.

__push_current_trigger_definition__(module, definition)

@spec __push_current_trigger_definition__(module(), map()) :: :ok

Adds one trigger definition to the workflow module currently being compiled.

__push_current_trigger_payload_field__(module, field)

@spec __push_current_trigger_payload_field__(module(), map()) :: :ok

Adds one payload field to the trigger currently being compiled.

__resolve_runtime_definition__(definition)

@spec __resolve_runtime_definition__(map()) :: map()

Resolves late-bound runtime metadata for generated workflow definitions.

Workflow modules store a compile-time definition, but step modules may expose Squid Mesh step metadata that should be read when the workflow definition is consumed. This keeps generated workflow modules small while preserving the runtime contract used by dispatch and inspection.

using(opts)

(macro)

@spec __using__(keyword()) :: Macro.t()

Injects the workflow DSL and compile-time collectors into a workflow module.

cron(expression, opts \\ [])

(macro)

Declares a cron-based trigger.

Pass idempotency: :return_existing_run when duplicate deliveries should return the first run, or idempotency: :skip_duplicate when duplicates should be reported as skipped. Idempotent cron triggers require either a scheduler-provided :signal_id or an :intended_window with both bounds so the runtime can derive a stable idempotency key.

field(name, type, opts \\ [])

(macro)

Declares one payload field inside a trigger payload block.

manual()

(macro)

Declares a manual trigger.

payload(list)

(macro)

Declares the payload contract for the current trigger.

to_spec(workflow)

@spec to_spec(module()) ::
  {:ok, SquidMesh.Workflow.Spec.t()}
  | {:error, SquidMesh.Workflow.Definition.load_error()}

Converts a compiled workflow module into Squid Mesh's normalized workflow spec.

transition(from, opts)

(macro)

Declares a transition from one step outcome to the next step.

trigger(name, list)

(macro)

Declares a named workflow trigger.

validate_spec(spec)

@spec validate_spec(SquidMesh.Workflow.Spec.t() | map() | term()) ::
  :ok | {:error, {:invalid_workflow_spec, [map()]}}

Validates a normalized workflow spec without resolving workflow or step modules.

This validates the structural contract used by Squid Mesh planner state. It does not prove that arbitrary module atoms are owned by the host application or executable as runtime-authored workflow code.