test(runner): cover Errors facade and call_enactment exit surface

Add P0-7 caller-safety tests and Runner.Errors facade unit tests.

While writing the tests, fix the call_enactment/3 exit-reason
unwrapping: GenServer.call/3 wraps the callee's exit reason as
{reason, {GenServer, :call, _info}} before re-exiting in the caller, so
the previous flat catch patterns missed reasons like {:shutdown, term}
and recorded the wrapped tuple as the EnactmentCallFailed reason.
Extract a small classify_exit/3 helper that unwraps once and dispatches
by the underlying reason.

Tests cover:
- start_workitem / complete_workitem / Enactment.Supervisor.terminate_enactment
  against a never-started enactment_id (-> EnactmentNotRunning :not_started).
- call_enactment/3 against stub processes that exit :normal,
  {:shutdown, _}, an arbitrary atom, or simply stall past the timeout.
- Registry.whereis/1 lookup and miss paths.

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

Author: fahchen

lib/coloured_flow/runner/enactment/workitem_transition.ex

@@ -80,46 +80,74 @@ defmodule ColouredFlow.Runner.Enactment.WorkitemTransition do
         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
-             )}
+            classify_exit(unwrap_call_reason(reason), enactment_id, timeout)
         end
     end
   end
+
+  # `GenServer.call/3` wraps the callee's exit reason as
+  # `{reason, {GenServer, :call, [pid, message, timeout]}}` before re-exiting in
+  # the caller. Unwrap so we can classify by the underlying reason alone.
+  # credo:disable-for-next-line JetCredo.Checks.ExplicitAnyType
+  @spec unwrap_call_reason(term()) :: term()
+  defp unwrap_call_reason({reason, {GenServer, :call, _info}}), do: reason
+  defp unwrap_call_reason(reason), do: reason
+
+  # credo:disable-for-next-line JetCredo.Checks.ExplicitAnyType
+  @spec classify_exit(term(), enactment_id(), timeout()) ::
+          {:error, Exception.t()} | no_return()
+  defp classify_exit(:noproc, enactment_id, _timeout) do
+    {:error,
+     Exceptions.EnactmentNotRunning.exception(
+       enactment_id: enactment_id,
+       reason: :not_started
+     )}
+  end
+
+  defp classify_exit(:timeout, enactment_id, timeout) do
+    {:error,
+     Exceptions.EnactmentTimeout.exception(
+       enactment_id: enactment_id,
+       timeout: timeout
+     )}
+  end
+
+  defp classify_exit(:normal, enactment_id, _timeout) do
+    {:error,
+     Exceptions.EnactmentNotRunning.exception(
+       enactment_id: enactment_id,
+       reason: :stopped_during_call
+     )}
+  end
+
+  defp classify_exit(:shutdown, enactment_id, _timeout) do
+    {:error,
+     Exceptions.EnactmentNotRunning.exception(
+       enactment_id: enactment_id,
+       reason: :shutting_down
+     )}
+  end
+
+  defp classify_exit({:shutdown, _shutdown_reason}, enactment_id, _timeout) do
+    {:error,
+     Exceptions.EnactmentNotRunning.exception(
+       enactment_id: enactment_id,
+       reason: :shutting_down
+     )}
+  end
+
+  defp classify_exit(:calling_self, _enactment_id, _timeout) do
+    # Programming error — surface it instead of swallowing.
+    exit(:calling_self)
+  end
+
+  defp classify_exit(reason, enactment_id, _timeout) do
+    # Catch-all: `:killed`, `{:nodedown, node}`, or any other crash reason.
+    {:error,
+     Exceptions.EnactmentCallFailed.exception(
+       enactment_id: enactment_id,
+       reason: reason
+     )}
+  end
 end

test/coloured_flow/runner/enactment/workitem_transition_test.exs

@@ -0,0 +1,173 @@
+defmodule ColouredFlow.Runner.Enactment.WorkitemTransitionTest do
+  @moduledoc """
+  Tests for the caller-safe wrapper around `GenServer.call/3` in
+  `WorkitemTransition`. Covers the full `:exit` surface defined in
+  `error_handling_design.md`.
+  """
+
+  use ExUnit.Case, async: true
+
+  alias ColouredFlow.Runner.Enactment.Registry, as: EnactmentRegistry
+  alias ColouredFlow.Runner.Enactment.Supervisor, as: EnactmentSupervisor
+  alias ColouredFlow.Runner.Enactment.WorkitemTransition
+  alias ColouredFlow.Runner.Exceptions
+
+  describe "start_workitem/2 against a non-running enactment" do
+    test "returns EnactmentNotRunning when the enactment was never started" do
+      enactment_id = Ecto.UUID.generate()
+
+      assert {:error, %Exceptions.EnactmentNotRunning{} = ex} =
+               WorkitemTransition.start_workitem(enactment_id, Ecto.UUID.generate())
+
+      assert ex.enactment_id == enactment_id
+      assert ex.reason == :not_started
+      assert ex.error_code == :enactment_not_running
+    end
+  end
+
+  describe "complete_workitem/2 against a non-running enactment" do
+    test "returns EnactmentNotRunning when the enactment was never started" do
+      enactment_id = Ecto.UUID.generate()
+
+      assert {:error, %Exceptions.EnactmentNotRunning{} = ex} =
+               WorkitemTransition.complete_workitem(enactment_id, {Ecto.UUID.generate(), []})
+
+      assert ex.enactment_id == enactment_id
+      assert ex.reason == :not_started
+    end
+  end
+
+  describe "Enactment.Supervisor.terminate_enactment/2 against a non-running enactment" do
+    test "returns EnactmentNotRunning when the enactment was never started" do
+      enactment_id = Ecto.UUID.generate()
+
+      assert {:error, %Exceptions.EnactmentNotRunning{} = ex} =
+               EnactmentSupervisor.terminate_enactment(enactment_id)
+
+      assert ex.enactment_id == enactment_id
+      assert ex.reason == :not_started
+    end
+  end
+
+  describe "call_enactment/3 :exit surface coverage" do
+    test "EnactmentTimeout when the called process does not reply within the timeout" do
+      enactment_id = Ecto.UUID.generate()
+      {pid, ref} = spawn_registered_stub(enactment_id, fn -> :stall end)
+
+      try do
+        assert {:error, %Exceptions.EnactmentTimeout{} = ex} =
+                 WorkitemTransition.call_enactment(enactment_id, :anything, 50)
+
+        assert ex.enactment_id == enactment_id
+        assert ex.timeout == 50
+      after
+        send(pid, :stop)
+        await_down(pid, ref)
+      end
+    end
+
+    test "EnactmentNotRunning(:stopped_during_call) when called process exits :normal mid-call" do
+      enactment_id = Ecto.UUID.generate()
+      {_pid, ref} = spawn_registered_stub(enactment_id, fn -> {:exit_on_call, :normal} end)
+
+      assert {:error, %Exceptions.EnactmentNotRunning{} = ex} =
+               WorkitemTransition.call_enactment(enactment_id, :anything, 1_000)
+
+      assert ex.enactment_id == enactment_id
+      assert ex.reason == :stopped_during_call
+
+      await_down(:_pid, ref)
+    end
+
+    test "EnactmentNotRunning(:shutting_down) when called process exits {:shutdown, _} mid-call" do
+      enactment_id = Ecto.UUID.generate()
+
+      {_pid, ref} =
+        spawn_registered_stub(enactment_id, fn -> {:exit_on_call, {:shutdown, :test}} end)
+
+      assert {:error, %Exceptions.EnactmentNotRunning{} = ex} =
+               WorkitemTransition.call_enactment(enactment_id, :anything, 1_000)
+
+      assert ex.enactment_id == enactment_id
+      assert ex.reason == :shutting_down
+
+      await_down(:_pid, ref)
+    end
+
+    test "EnactmentCallFailed catch-all when called process exits with arbitrary reason" do
+      enactment_id = Ecto.UUID.generate()
+
+      {_pid, ref} =
+        spawn_registered_stub(enactment_id, fn -> {:exit_on_call, :custom_crash_reason} end)
+
+      assert {:error, %Exceptions.EnactmentCallFailed{} = ex} =
+               WorkitemTransition.call_enactment(enactment_id, :anything, 1_000)
+
+      assert ex.enactment_id == enactment_id
+      assert ex.reason == :custom_crash_reason
+      assert ex.error_code == :enactment_call_failed
+
+      await_down(:_pid, ref)
+    end
+  end
+
+  describe "Registry.whereis/1" do
+    test "returns :error when no process is registered for the key" do
+      assert :error == EnactmentRegistry.whereis({:enactment, Ecto.UUID.generate()})
+    end
+
+    test "returns {:ok, pid} when a process is registered" do
+      enactment_id = Ecto.UUID.generate()
+      {pid, ref} = spawn_registered_stub(enactment_id, fn -> :stall end)
+
+      try do
+        assert {:ok, ^pid} = EnactmentRegistry.whereis({:enactment, enactment_id})
+      after
+        send(pid, :stop)
+        await_down(pid, ref)
+      end
+    end
+  end
+
+  defp spawn_registered_stub(enactment_id, behaviour_fun) do
+    parent = self()
+
+    pid =
+      spawn(fn ->
+        {:ok, _owner} =
+          Registry.register(EnactmentRegistry, {:enactment, enactment_id}, nil)
+
+        send(parent, {:registered, self()})
+
+        case behaviour_fun.() do
+          :stall ->
+            receive do
+              :stop -> :ok
+            end
+
+          {:exit_on_call, exit_reason} ->
+            receive do
+              {:"$gen_call", _from, _msg} -> exit(exit_reason)
+            end
+        end
+      end)
+
+    ref = Process.monitor(pid)
+
+    receive do
+      {:registered, ^pid} -> :ok
+    after
+      500 -> raise "stub registration timed out"
+    end
+
+    {pid, ref}
+  end
+
+  defp await_down(_pid, ref) do
+    receive do
+      {:DOWN, ^ref, :process, _object, _reason} -> :ok
+    after
+      1_000 -> :ok
+    end
+  end
+end