fix: malformed listener is silently ignored; doc/comment cleanup

Round-6 follow-ups:

- `Listener.safe_invoke/3` gains a final catch-all clause that returns `:ok`
  instead of raising `FunctionClauseError` when the runner state is
  configured with a value that is neither `nil`, a bare atom, nor a
  `{module, extras}` tuple. This honours the module's documented promise
  that "the runner never lets a misbehaving listener stop or destabilise
  an enactment". A dispatch-test case asserts a string listener is silently
  ignored without crashing the enactment.
- `lib/coloured_flow/dsl/spec.md`:
  - Narrow the "requires `:storage`" sentence to `setup_flow!/0` and
    `insert_enactment!/{1,2}`; `start_enactment/{1,2}` works without
    storage as long as the caller supplies an enactment id.
  - Soften the compile-error claim — only duplicate-name and
    missing-colour-set violations are remapped to the originating macro
    callsite; other validator errors fall back to the `defmodule`
    callsite.
- `lib/coloured_flow/dsl/builder.ex` comment for `compile_transition_action/2`
  now references the actual generated arity (`__action_for__/5`).
- `lib/coloured_flow/dsl/function.ex` moduledoc renamed to `function/1`
  and `function/2` to match the actual macro arities.

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

Author: fahchen

lib/coloured_flow/dsl/builder.ex

@@ -391,7 +391,7 @@ defmodule ColouredFlow.DSL.Builder do
   defp resolve_step(:unknown, descr, _colour_sets), do: descr
 
   # Compile a single transition's `action do ... end` body into a
-  # `__action_for__/4` clause. The body has access to:
+  # `__action_for__/5` clause. The body has access to:
   #
   #   * `ctx`      — `ColouredFlow.Runner.Enactment.Listener.ctx()`
   #   * `workitem` — the just-completed `%Workitem{}`

lib/coloured_flow/dsl/function.ex

@@ -1,6 +1,6 @@
 defmodule ColouredFlow.DSL.Function do
   @moduledoc """
-  `function/2` and `function/3` macros. See `ColouredFlow.DSL` for context.
+  `function/1` and `function/2` macros. See `ColouredFlow.DSL` for context.
   """
 
   alias ColouredFlow.DSL.ExpressionHelper

lib/coloured_flow/dsl/spec.md

@@ -99,9 +99,12 @@ configuration, pass `listener: {__MODULE__, extras}` as an option — the
 positional argument and exposed inside DSL blocks as the magic binding
 `extras`.
 
-These functions only work when the host module passes `:storage` to
-`use ColouredFlow.DSL` (e.g. `storage: ColouredFlow.Runner.Storage.InMemory`).
-Without it, calling them raises a clear `ArgumentError`.
+`setup_flow!/0` and `insert_enactment!/{1,2}` only work when the host
+module passes `:storage` to `use ColouredFlow.DSL` (e.g.
+`storage: ColouredFlow.Runner.Storage.InMemory`); without it, calling
+them raises an `ArgumentError`. `start_enactment/{1,2}` is independent
+of `:storage` — it only needs an enactment id (or a handle returned by
+`insert_enactment!/{1,2}`) and the supervisor.
 
 ## Per-workflow options
 
@@ -357,5 +360,7 @@ populates `action.outputs` from arc/guard analysis), and runs
   - function names are unique and result descrs are fully resolved,
   - termination criteria reference only `markings`.
 
-Any failure raises a `CompileError` pointing to the offending macro
-call.
+Any failure raises a `CompileError`. Duplicate-name and missing-colour-set
+violations point back to the originating declaration via
+`{file, line}` metadata captured at macro expansion; other validator
+errors fall back to the `defmodule` callsite.

lib/coloured_flow/runner/enactment/listener.ex

@@ -132,6 +132,11 @@ defmodule ColouredFlow.Runner.Enactment.Listener do
     do_invoke(module, callback, args ++ [nil])
   end
 
+  # Malformed listener value (PID, string, mis-shaped tuple, …). The runner
+  # promises a misbehaving listener never destabilises the enactment, so
+  # silently drop the call rather than letting `FunctionClauseError` bubble.
+  def safe_invoke(_other, _callback, _args), do: :ok
+
   defp do_invoke(module, callback, full_args) do
     if function_exported?(module, callback, length(full_args)) do
       try do

test/coloured_flow/runner/enactment/listener_dispatch_test.exs

@@ -95,6 +95,24 @@ defmodule ColouredFlow.Runner.Enactment.ListenerDispatchTest do
     end
   end
 
+  describe "malformed listener" do
+    setup :setup_flow
+    setup :setup_enactment
+
+    @tag initial_markings: []
+    test "non-atom non-tuple value is silently ignored", %{enactment: enactment} do
+      pid =
+        start_supervised!(
+          {ColouredFlow.Runner.Enactment, enactment_id: enactment.id, listener: "garbage"},
+          id: enactment.id
+        )
+
+      [wi] = get_enactment_workitems(pid)
+      assert wi.state == :enabled
+      refute_received {:on_enactment_start, _, _}
+    end
+  end
+
   describe "lifecycle dispatch ({module, extras} listener)" do
     setup :setup_flow
     setup :setup_enactment