Protocol defining how workflow nodes execute within a workflow context.

The Invokable protocol is the runtime heart of Runic. It defines how each node type (Step, Condition, Rule, Accumulator, etc.) executes within the context of a workflow, enabling extension of Runic's runtime with nodes that have different execution properties and evaluation semantics.

Three-Phase Execution Model

All workflow execution uses a three-phase model that enables parallel execution and external scheduler integration:

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   PREPARE   │ ───► │   EXECUTE   │ ───► │    APPLY    │
│  (Phase 1)  │      │  (Phase 2)  │      │  (Phase 3)  │
└─────────────┘      └─────────────┘      └─────────────┘
      │                    │                    │
      ▼                    ▼                    ▼
 Extract context      Run work fn         Reduce results
 from workflow        in isolation         into workflow
 → %Runnable{}        (parallelizable)     (sequential)

1. Prepare (prepare/3) - Extract minimal context from workflow into a %Runnable{} struct
2. Execute (execute/2) - Run the node's work function in isolation (can be parallelized)
3. Apply - Events on the Runnable are folded back into the workflow via apply_event/2

This separation enables:

• Parallel execution of independent nodes (Phase 2 has no workflow access)
• External scheduler integration via prepare_for_dispatch/1 and apply_runnable/2
• Distributed execution by dispatching Runnables to remote workers (events are serializable)
• Separation of concerns between pure computation and stateful workflow updates

Protocol Functions

Return Types

• prepare/3 returns:

  • {:ok, %Runnable{}} - Ready for execution
  • {:skip, (Workflow.t() -> Workflow.t())} - Skip with reducer function
  • {:defer, (Workflow.t() -> Workflow.t())} - Defer with reducer function

• execute/2 returns a %Runnable{} with:

  • status: :completed - With result and events populated
  • status: :failed - With error populated
  • status: :skipped - With events for skip handling

Built-in Implementations

Runic provides Invokable implementations for all core node types:

External Scheduler Integration

The three-phase model enables integration with custom schedulers:

# Phase 1: Prepare runnables for dispatch
workflow = Workflow.plan_eagerly(workflow, input)
{workflow, runnables} = Workflow.prepare_for_dispatch(workflow)

# Phase 2: Execute (dispatch to worker pool, external service, etc.)
executed = Task.async_stream(runnables, fn runnable ->
  Runic.Workflow.Invokable.execute(runnable.node, runnable)
end, timeout: :infinity)

# Phase 3: Apply results back to workflow
workflow = Enum.reduce(executed, workflow, fn {:ok, runnable}, wrk ->
  Workflow.apply_runnable(wrk, runnable)
end)

Implementing Custom Invokable

To create a custom node type, implement the protocol:

defmodule MyApp.CustomNode do
  defstruct [:hash, :name, :work]
end

defimpl Runic.Workflow.Invokable, for: MyApp.CustomNode do
  alias Runic.Workflow
  alias Runic.Workflow.{Fact, Runnable, CausalContext}
  alias Runic.Workflow.Events.{FactProduced, ActivationConsumed}

  def match_or_execute(_node), do: :execute

  def invoke(%MyApp.CustomNode{} = node, workflow, fact) do
    result = node.work.(fact.value)
    result_fact = Fact.new(value: result, ancestry: {node.hash, fact.hash})

    workflow
    |> Workflow.log_fact(result_fact)
    |> Workflow.draw_connection(node, result_fact, :produced)
    |> Workflow.mark_runnable_as_ran(node, fact)
    |> Workflow.prepare_next_runnables(node, result_fact)
  end

  def prepare(%MyApp.CustomNode{} = node, workflow, fact) do
    context = CausalContext.new(
      node_hash: node.hash,
      input_fact: fact,
      ancestry_depth: Workflow.ancestry_depth(workflow, fact)
    )

    {:ok, Runnable.new(node, fact, context)}
  end

  def execute(%MyApp.CustomNode{} = node, %Runnable{input_fact: fact, context: ctx} = runnable) do
    result = node.work.(fact.value)
    result_fact = Fact.new(value: result, ancestry: {node.hash, fact.hash})

    events = [
      %FactProduced{
        hash: result_fact.hash,
        value: result_fact.value,
        ancestry: result_fact.ancestry,
        producer_label: :produced,
        weight: ctx.ancestry_depth + 1
      },
      %ActivationConsumed{
        fact_hash: fact.hash,
        node_hash: node.hash,
        from_label: :runnable
      }
    ]

    Runnable.complete(runnable, result_fact, events)
  end
end

See the Protocols Guide for more details and examples.