feat(runner): add error handling foundation

Introduce the foundation slice (P0-1, P0-2, P0-6) of the error handling
overhaul described in error_handling_design.md.

- Add `ColouredFlow.Runner.Errors` facade for centralised error
  classification: `tier/1`, `error_code/1`, `lifecycle?/1`, and
  `to_persisted_reason/1`.
- Add a stable `error_code` field to existing public exceptions
  (`NonLiveWorkitem`, `InvalidWorkitemTransition`, `UnboundActionOutput`,
  `UnsufficientTokensToConsume`, `ColourSetMismatch`, `InvalidResult`).
- Add four new public exceptions for the caller-facing error surface:
  `EnactmentNotRunning`, `EnactmentTimeout`, `EnactmentCallFailed`,
  `StoragePersistenceFailed`.
- Add caller-safe wrapper `WorkitemTransition.call_enactment/3` that
  normalises the full `GenServer.call/3` `:exit` surface (`:noproc`,
  `:timeout`, `:shutdown`, `:normal`, `:nodedown`, `:killed`,
  `:calling_self`, catch-all) into typed exceptions returned via
  `{:error, exception}`.
- Update `Enactment.Supervisor.terminate_enactment/2` to use the same
  wrapper; return type changes from `:ok` to `:ok | {:error, Exception.t()}`.
- Add `Registry.whereis/1` helper for explicit pid lookup.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: fahchen

error_handling_design.md

@@ -8,6 +8,7 @@ defmodule ColouredFlow.Definition.ColourSet.ColourSetMismatch do
   typed_structor definer: :defexception, enforce: true do
     field :colour_set, ColouredFlow.Definition.ColourSet.t()
     field :value, term()
+    field :error_code, atom(), default: :colour_set_mismatch
   end
 
   @impl Exception

lib/coloured_flow/definition/colour_set/colour_set_mismatch.ex

@@ -12,6 +12,7 @@ defmodule ColouredFlow.Expression.InvalidResult do
     field :expression, Expression.t()
 
     field :message, String.t()
+    field :error_code, atom(), default: :expression_invalid_result
   end
 
   @impl Exception

lib/coloured_flow/expression/invalid_result.ex

@@ -14,4 +14,16 @@ defmodule ColouredFlow.Runner.Enactment.Registry do
   def via_name({:enactment, id}) do
     {:via, Registry, {__MODULE__, {:enactment, id}}}
   end
+
+  @doc """
+  Look up the pid registered under the given key, returning `{:ok, pid}` or
+  `:error` if no process is registered.
+  """
+  @spec whereis({:enactment, Storage.enactment_id()}) :: {:ok, pid()} | :error
+  def whereis({:enactment, id}) do
+    case Registry.lookup(__MODULE__, {:enactment, id}) do
+      [{pid, _value}] -> {:ok, pid}
+      [] -> :error
+    end
+  end
 end

lib/coloured_flow/runner/enactment/registry.ex

@@ -6,7 +6,7 @@ defmodule ColouredFlow.Runner.Enactment.Supervisor do
   use DynamicSupervisor
 
   alias ColouredFlow.Runner.Enactment
-  alias ColouredFlow.Runner.Enactment.Registry
+  alias ColouredFlow.Runner.Enactment.WorkitemTransition
   alias ColouredFlow.Runner.Storage
 
   @typep enactment_id() :: Storage.enactment_id()
@@ -35,11 +35,16 @@ defmodule ColouredFlow.Runner.Enactment.Supervisor do
 
   @doc """
   Terminate an enactment forcibly.
+
+  Returns `:ok` on success, or `{:error, exception}` when the target enactment is
+  not running, the call times out, or the call exits abnormally.
   """
-  @spec terminate_enactment(enactment_id(), options :: [message: String.t()]) :: :ok
+  @spec terminate_enactment(enactment_id(), options :: [message: String.t()]) ::
+          :ok | {:error, Exception.t()}
   def terminate_enactment(enactment_id, options \\ []) do
-    enactment = Registry.via_name({:enactment, enactment_id})
-
-    GenServer.call(enactment, {:terminate, options})
+    case WorkitemTransition.call_enactment(enactment_id, {:terminate, options}) do
+      :ok -> :ok
+      {:error, _exception} = error -> error
+    end
   end
 end

lib/coloured_flow/runner/enactment/supervisor.ex

@@ -2,32 +2,39 @@ defmodule ColouredFlow.Runner.Enactment.WorkitemTransition do
   @moduledoc """
   Workitem transition functions, which are dispatched to the corresponding
   enactment gen_server.
+
+  All public functions in this module funnel `GenServer.call/3` through a
+  caller-safe wrapper that translates the full `:exit` surface (`:noproc`,
+  `:timeout`, `:nodedown`, `:shutdown`, `:normal`, `:killed`, ...) into typed
+  exceptions returned via `{:error, exception}`. Callers therefore never have to
+  handle raw process-exit signals.
   """
 
   alias ColouredFlow.Enactment.Occurrence
 
   alias ColouredFlow.Runner.Enactment.Registry
   alias ColouredFlow.Runner.Enactment.Workitem
+  alias ColouredFlow.Runner.Exceptions
   alias ColouredFlow.Runner.Storage
 
   @typep enactment_id() :: Storage.enactment_id()
   @typep workitem_id() :: Workitem.id()
 
+  @call_timeout 5_000
+
   @spec start_workitem(enactment_id(), workitem_id()) ::
           {:ok, Workitem.t(:started)} | {:error, Exception.t()}
   def start_workitem(enactment_id, workitem_id) do
     case start_workitems(enactment_id, [workitem_id]) do
       {:ok, [workitem]} -> {:ok, workitem}
-      {:error, exception} -> {:error, exception}
+      {:error, _exception} = error -> error
     end
   end
 
   @spec start_workitems(enactment_id(), [workitem_id()]) ::
           {:ok, [Workitem.t(:started)]} | {:error, Exception.t()}
   def start_workitems(enactment_id, workitem_ids) when is_list(workitem_ids) do
-    enactment = via_name(enactment_id)
-
-    GenServer.call(enactment, {:start_workitems, workitem_ids})
+    call_enactment(enactment_id, {:start_workitems, workitem_ids})
   end
 
   @spec complete_workitem(
@@ -37,7 +44,7 @@ defmodule ColouredFlow.Runner.Enactment.WorkitemTransition do
   def complete_workitem(enactment_id, {workitem_id, outputs}) do
     case complete_workitems(enactment_id, [{workitem_id, outputs}]) do
       {:ok, [workitem]} -> {:ok, workitem}
-      {:error, exception} -> {:error, exception}
+      {:error, _exception} = error -> error
     end
   end
 
@@ -46,12 +53,73 @@ defmodule ColouredFlow.Runner.Enactment.WorkitemTransition do
           Enumerable.t({workitem_id(), Occurrence.free_binding()})
         ) :: {:ok, [Workitem.t(:completed)]} | {:error, Exception.t()}
   def complete_workitems(enactment_id, workitem_id_and_outputs_list) do
-    enactment = via_name(enactment_id)
-
-    GenServer.call(enactment, {:complete_workitems, workitem_id_and_outputs_list})
+    call_enactment(enactment_id, {:complete_workitems, workitem_id_and_outputs_list})
   end
 
-  defp via_name(enactment_id) do
-    Registry.via_name({:enactment, enactment_id})
+  @doc """
+  Caller-safe wrapper around `GenServer.call/3` against an enactment's via name.
+
+  Returns the GenServer reply unchanged on success (`{:ok, _}` or `{:error, _}`),
+  or normalises any `:exit` from a missing/dying/timing-out process into a typed
+  exception returned via `{:error, exception}`. The full exit surface is
+  enumerated below; unknown exit reasons fall through to `EnactmentCallFailed`.
+  """
+  # credo:disable-for-lines:2 JetCredo.Checks.ExplicitAnyType
+  @spec call_enactment(enactment_id(), term(), timeout()) ::
+          term() | {:error, Exception.t()}
+  def call_enactment(enactment_id, message, timeout \\ @call_timeout) do
+    case Registry.whereis({:enactment, enactment_id}) do
+      :error ->
+        {:error,
+         Exceptions.EnactmentNotRunning.exception(
+           enactment_id: enactment_id,
+           reason: :not_started
+         )}
+
+      {:ok, pid} ->
+        try do
+          GenServer.call(pid, message, timeout)
+        catch
+          :exit, {:noproc, _info} ->
+            {:error,
+             Exceptions.EnactmentNotRunning.exception(
+               enactment_id: enactment_id,
+               reason: :not_started
+             )}
+
+          :exit, {:timeout, _info} ->
+            {:error,
+             Exceptions.EnactmentTimeout.exception(
+               enactment_id: enactment_id,
+               timeout: timeout
+             )}
+
+          :exit, {:shutdown, _info} ->
+            {:error,
+             Exceptions.EnactmentNotRunning.exception(
+               enactment_id: enactment_id,
+               reason: :shutting_down
+             )}
+
+          :exit, {:normal, _info} ->
+            {:error,
+             Exceptions.EnactmentNotRunning.exception(
+               enactment_id: enactment_id,
+               reason: :stopped_during_call
+             )}
+
+          :exit, {:calling_self, _info} = reason ->
+            # Programming error — surface it.
+            exit(reason)
+
+          :exit, reason ->
+            # Catch-all: :killed, {:nodedown, _}, or any other crash mid-call.
+            {:error,
+             Exceptions.EnactmentCallFailed.exception(
+               enactment_id: enactment_id,
+               reason: reason
+             )}
+        end
+    end
   end
 end

lib/coloured_flow/runner/enactment/workitem_transition.ex

@@ -0,0 +1,84 @@
+defmodule ColouredFlow.Runner.Errors do
+  @moduledoc """
+  Central error classification helpers for `ColouredFlow.Runner`.
+
+  Pattern-matches on known exception modules and returns their tier, stable error
+  code, and persisted reason mapping. New exception modules in the runner must be
+  registered here.
+
+  ## Tiers
+
+  | Tier | Description                                                                                           |
+  | ---- | ----------------------------------------------------------------------------------------------------- |
+  | `1`  | Caller-visible operational errors. Returned from public API; enactment process state unchanged.       |
+  | `2`  | Enactment-fatal errors. Persisted to `enactments.state = :exception`; gracefully stops the GenServer. |
+  | `3`  | Transient infrastructure errors. Let it crash; supervisor restarts.                                   |
+  | `4`  | Programmer errors. Should be caught by validators or compile-time checks.                             |
+
+  See `error_handling_design.md` at the repository root for the full
+  specification.
+  """
+
+  alias ColouredFlow.Definition.ColourSet.ColourSetMismatch
+  alias ColouredFlow.Expression.InvalidResult
+  alias ColouredFlow.Runner.Exception, as: PersistedException
+  alias ColouredFlow.Runner.Exceptions
+
+  @doc """
+  Returns the tier (1–4) of the given exception when surfaced through the runner.
+
+  Tier classification is best-effort static — the same exception type may belong
+  to different tiers depending on call site. Callers that need precise tiering
+  should track it at the originating site rather than rely solely on this
+  function.
+  """
+  @spec tier(Exception.t()) :: 1 | 2 | 3 | 4
+  def tier(%Exceptions.NonLiveWorkitem{}), do: 1
+  def tier(%Exceptions.InvalidWorkitemTransition{}), do: 1
+  def tier(%Exceptions.UnsufficientTokensToConsume{}), do: 1
+  def tier(%Exceptions.UnboundActionOutput{}), do: 1
+  def tier(%Exceptions.EnactmentNotRunning{}), do: 1
+  def tier(%Exceptions.EnactmentTimeout{}), do: 1
+  def tier(%Exceptions.EnactmentCallFailed{}), do: 1
+  def tier(%Exceptions.StoragePersistenceFailed{}), do: 1
+  def tier(%ColourSetMismatch{}), do: 1
+  def tier(%InvalidResult{}), do: 1
+  def tier(_other), do: 3
+
+  @doc """
+  Returns the stable error code atom for the exception.
+
+  For exceptions defined in this codebase the code is stored on the struct as the
+  `:error_code` field. For foreign exceptions (e.g. `ArithmeticError`,
+  `RuntimeError`) the function returns `:unknown` — callers should treat foreign
+  exceptions as Tier 3 transient or Tier 4 programmer errors.
+  """
+  @spec error_code(Exception.t()) :: atom()
+  def error_code(%{error_code: code}) when is_atom(code), do: code
+  def error_code(_other), do: :unknown
+
+  @doc """
+  Returns `true` if the exception, when raised inside an enactment, should trigger
+  a lifecycle `:exception` event (i.e. a persisted state transition to
+  `:exception`).
+
+  An exception is lifecycle-relevant when it has a corresponding persisted reason
+  (see `to_persisted_reason/1`). Equivalent to `tier(exception) == 2` once Tier 2
+  exception modules are registered, but the persisted-reason dispatch is the
+  authoritative check.
+  """
+  @spec lifecycle?(Exception.t()) :: boolean()
+  def lifecycle?(exception), do: not is_nil(to_persisted_reason(exception))
+
+  @doc """
+  Maps an exception to a persisted fatal reason atom, if one applies.
+
+  The persisted reason is the value stored in `enactment_logs.exception.reason`
+  (`Ecto.Enum` constrained to `ColouredFlow.Runner.Exception.__reasons__/0`).
+  Returns `nil` for exceptions that should not produce a persisted enactment
+  exception state.
+  """
+  @spec to_persisted_reason(Exception.t()) :: PersistedException.reason() | nil
+  def to_persisted_reason(%InvalidResult{}), do: :termination_criteria_evaluation
+  def to_persisted_reason(_other), do: nil
+end

lib/coloured_flow/runner/errors.ex

@@ -0,0 +1,34 @@
+defmodule ColouredFlow.Runner.Exceptions.EnactmentCallFailed do
+  @moduledoc """
+  Raised when a public Runner API call to an enactment fails with an exit reason
+  that does not map to a more specific exception (`EnactmentNotRunning` or
+  `EnactmentTimeout`). Carries the original exit reason for postmortem use.
+
+  Common cases include the called process being killed (`:killed`), the remote
+  node going down (`{:nodedown, node}`), or any other unhandled `GenServer.call`
+  exit pattern.
+  """
+
+  use TypedStructor
+
+  alias ColouredFlow.Runner.Storage
+
+  typed_structor definer: :defexception, enforce: true do
+    field :enactment_id, Storage.enactment_id()
+    field :reason, term()
+    field :error_code, atom(), default: :enactment_call_failed
+  end
+
+  # credo:disable-for-next-line JetCredo.Checks.ExplicitAnyType
+  @impl Exception
+  def exception(arguments) do
+    struct!(__MODULE__, arguments)
+  end
+
+  @impl Exception
+  def message(%__MODULE__{} = exception) do
+    """
+    The call to enactment #{exception.enactment_id} failed with reason: #{inspect(exception.reason)}.
+    """
+  end
+end

lib/coloured_flow/runner/exceptions/enactment_call_failed.ex

@@ -0,0 +1,32 @@
+defmodule ColouredFlow.Runner.Exceptions.EnactmentNotRunning do
+  @moduledoc """
+  Raised when a public Runner API call targets an enactment that is not currently
+  running. Possible causes include the enactment never having been started, the
+  enactment having terminated, having transitioned to `:exception`, or being in
+  the middle of a graceful shutdown when the call arrived.
+  """
+
+  use TypedStructor
+
+  alias ColouredFlow.Runner.Storage
+
+  @type reason() :: :not_started | :shutting_down | :stopped_during_call | :unknown
+
+  typed_structor definer: :defexception, enforce: true do
+    field :enactment_id, Storage.enactment_id()
+    field :reason, reason(), default: :unknown
+    field :error_code, atom(), default: :enactment_not_running
+  end
+
+  @impl Exception
+  def exception(arguments) do
+    struct!(__MODULE__, arguments)
+  end
+
+  @impl Exception
+  def message(%__MODULE__{} = exception) do
+    """
+    The enactment with ID #{exception.enactment_id} is not running (#{exception.reason}).
+    """
+  end
+end

lib/coloured_flow/runner/exceptions/enactment_not_running.ex

@@ -0,0 +1,29 @@
+defmodule ColouredFlow.Runner.Exceptions.EnactmentTimeout do
+  @moduledoc """
+  Raised when a public Runner API call to an enactment exceeds the configured call
+  timeout. The enactment process may still be alive and may eventually complete
+  the requested operation; the caller has merely stopped waiting.
+  """
+
+  use TypedStructor
+
+  alias ColouredFlow.Runner.Storage
+
+  typed_structor definer: :defexception, enforce: true do
+    field :enactment_id, Storage.enactment_id()
+    field :timeout, non_neg_integer() | :infinity
+    field :error_code, atom(), default: :enactment_timeout
+  end
+
+  @impl Exception
+  def exception(arguments) do
+    struct!(__MODULE__, arguments)
+  end
+
+  @impl Exception
+  def message(%__MODULE__{} = exception) do
+    """
+    The call to enactment #{exception.enactment_id} timed out after #{exception.timeout}ms.
+    """
+  end
+end