Byzanteam
diff --git a/‎lib/coloured_flow/dsl.ex‎
Lines changed: 20 additions & 1 deletion b/‎lib/coloured_flow/dsl.ex‎
Lines changed: 20 additions & 1 deletion
diff --git a/‎lib/coloured_flow/dsl/builder.ex‎
Lines changed: 180 additions & 0 deletions b/‎lib/coloured_flow/dsl/builder.ex‎
Lines changed: 180 additions & 0 deletions
diff --git a/‎lib/coloured_flow/dsl/function.ex‎
Lines changed: 1 addition & 1 deletion b/‎lib/coloured_flow/dsl/function.ex‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎lib/coloured_flow/dsl/lifecycle.ex‎
Lines changed: 99 additions & 0 deletions b/‎lib/coloured_flow/dsl/lifecycle.ex‎
Lines changed: 99 additions & 0 deletions
@@ -8,7 +8,9 @@ defmodule ColouredFlow.DSL do
   alias ColouredFlow.Definition.Variable
 
   @doc false
-  defmacro __using__(_opts) do
+  defmacro __using__(opts) do
+    task_supervisor = Keyword.get(opts, :task_supervisor)
+
     quote do
       import ColouredFlow.DSL,
         only: [
@@ -52,6 +54,13 @@ defmodule ColouredFlow.DSL do
           on_markings: 1
         ]
 
+      import ColouredFlow.DSL.Lifecycle,
+        only: [
+          on_enactment_start: 1,
+          on_enactment_terminate: 1,
+          on_enactment_exception: 1
+        ]
+
       import ColouredFlow.MultiSet, only: [sigil_MS: 2, multi_set_coefficient: 2]
 
       Module.register_attribute(__MODULE__, :cf_colour_sets, accumulate: true)
@@ -65,6 +74,7 @@ defmodule ColouredFlow.DSL do
       Module.register_attribute(__MODULE__, :cf_termination_criteria, accumulate: true)
       Module.register_attribute(__MODULE__, :cf_name, accumulate: false)
       Module.register_attribute(__MODULE__, :cf_version, accumulate: false)
+      Module.register_attribute(__MODULE__, :cf_task_supervisor, accumulate: false)
 
       # Per-declaration metadata: accumulates `{name, file, line}` triples so
       # `Builder` can map validator-driven errors back to the offending callsite.
@@ -75,6 +85,15 @@ defmodule ColouredFlow.DSL do
       Module.register_attribute(__MODULE__, :cf_places_meta, accumulate: true)
       Module.register_attribute(__MODULE__, :cf_transitions_meta, accumulate: true)
 
+      # Per-transition action body AST collected by `transition do ... end` —
+      # each entry is `{transition_name, body_ast, free_vars}`.
+      Module.register_attribute(__MODULE__, :cf_transition_actions, accumulate: true)
+
+      # Enactment-level lifecycle hook bodies (`{kind, body_ast}`).
+      Module.register_attribute(__MODULE__, :cf_lifecycle_hooks, accumulate: true)
+
+      @cf_task_supervisor unquote(task_supervisor)
+
       @before_compile ColouredFlow.DSL.Builder
     end
   end
 
@@ -16,6 +16,7 @@ defmodule ColouredFlow.DSL.Builder do
   alias ColouredFlow.Validators.Exceptions.UniqueNameViolationError
 
   @doc false
+  # credo:disable-for-next-line Credo.Check.Refactor.CyclomaticComplexity
   defmacro __before_compile__(env) do
     cpnet = build_cpnet(env.module)
     cpnet = resolve_function_results(cpnet)
@@ -30,8 +31,19 @@ defmodule ColouredFlow.DSL.Builder do
       {:ok, validated} ->
         name = Module.get_attribute(env.module, :cf_name)
         version = Module.get_attribute(env.module, :cf_version)
+        task_supervisor = Module.get_attribute(env.module, :cf_task_supervisor)
+        transition_actions = source_order_meta(env.module, :cf_transition_actions)
+        lifecycle_hooks = source_order_meta(env.module, :cf_lifecycle_hooks)
+
+        action_clauses =
+          Enum.map(transition_actions, &compile_transition_action(&1, task_supervisor))
+
+        lifecycle_clauses =
+          Enum.map(lifecycle_hooks, &compile_lifecycle_hook(&1, task_supervisor))
 
         quote do
+          @behaviour ColouredFlow.Runner.Enactment.LifecycleHooks
+
           @doc """
           The `%ColouredFlow.Definition.ColouredPetriNet{}` materialised from the DSL
           declarations in this module.
@@ -54,6 +66,63 @@ defmodule ColouredFlow.DSL.Builder do
           def __cpn__(:name), do: unquote(name)
           def __cpn__(:version), do: unquote(version)
           def __cpn__(:initial_markings), do: unquote(Macro.escape(initial_markings))
+
+          @doc """
+          Insert an enactment row using `ColouredFlow.Runner.Storage.insert_enactment/1`.
+          The `flow_id` and `initial_markings` keys are filled in by this helper; pass
+          extra keys via `options` to merge into the storage params (e.g., `:id`).
+
+          Not idempotent — every invocation inserts a fresh row. Callers needing dedup
+          must enforce it at application level.
+
+          The caller is responsible for inserting the underlying `Schemas.Flow` row (or
+          `InMemory` flow record) — this helper does *not* set up the flow.
+          """
+          @spec insert_enactment(binary(), [Marking.t()], keyword()) ::
+                  {:ok, ColouredFlow.Runner.Storage.Schemas.Enactment.t()}
+          def insert_enactment(
+                flow_id,
+                initial_markings \\ __cpn__(:initial_markings),
+                options \\ []
+              )
+              when is_binary(flow_id) and is_list(initial_markings) and is_list(options) do
+            ColouredFlow.Runner.Storage.insert_enactment(
+              Map.merge(
+                %{flow_id: flow_id, initial_markings: initial_markings},
+                Map.new(options)
+              )
+            )
+          end
+
+          @doc """
+          Start the enactment under `ColouredFlow.Runner.Enactment.Supervisor`, binding
+          this module as the per-instance `ColouredFlow.Runner.Enactment.LifecycleHooks`
+          unless the caller overrides it via `opts[:lifecycle_hooks]`.
+
+          The override accepts the same shape as the runtime hooks field — a bare module,
+          a `{module, keyword}` tuple (so callbacks receive per-instance options as the
+          second argument), or `nil` to disable hooks entirely for this enactment.
+          """
+          @spec start_enactment(binary(), keyword()) :: DynamicSupervisor.on_start_child()
+          def start_enactment(enactment_id, opts \\ [])
+              when is_binary(enactment_id) and is_list(opts) do
+            opts = Keyword.put_new(opts, :lifecycle_hooks, __MODULE__)
+            ColouredFlow.Runner.Enactment.Supervisor.start_enactment(enactment_id, opts)
+          end
+
+          # credo:disable-for-next-line JetCredo.Checks.ExplicitAnyType
+          @spec __action_for__(String.t(), map(), keyword()) :: any()
+          unquote_splicing(action_clauses)
+          defp __action_for__(_transition, _event, _options), do: :ok
+
+          @doc false
+          @impl ColouredFlow.Runner.Enactment.LifecycleHooks
+          def on_workitem_completed(event, options) do
+            __action_for__(event.workitem.binding_element.transition, event, options)
+            :ok
+          end
+
+          unquote_splicing(lifecycle_clauses)
         end
 
       {:error, exception} ->
@@ -307,4 +376,115 @@ defmodule ColouredFlow.DSL.Builder do
   end
 
   defp resolve_step(:unknown, descr, _colour_sets), do: descr
+
+  # Compile a single transition's `action do ... end` body into a
+  # `__action_for__/3` clause. The body has access to:
+  #
+  #   * `event`   — `LifecycleHooks.workitem_completed_event()` map carrying
+  #     `:enactment_id`, `:markings`, `:workitem`, `:occurrence`, `:binding`.
+  #   * `options` — keyword list registered alongside the hook module.
+  #   * each CPN variable bound by the transition's incoming arcs (`:s`,
+  #     `:x`, …) — plucked from `event.binding`. Body-local pattern-match
+  #     names are NOT injected, so writing `pid = options[:pid]` (or any
+  #     local) inside `action do ... end` is safe.
+  #
+  # The wrapper unpacks `event.binding` via `Keyword.fetch!/2` for each
+  # transition-bound var (using a `_`-prefixed alias when the body does not
+  # reference the var, to suppress unused-variable warnings) and runs the
+  # body inside a `Task.Supervisor.start_child/2` call (or unsupervised
+  # `Task.start/1` when no `:task_supervisor` was provided to
+  # `use ColouredFlow.DSL`) so the runner never blocks on user side effects.
+  defp compile_transition_action(
+         {transition_name, body, incoming_vars},
+         task_supervisor
+       ) do
+    # `incoming_vars` is the ground-truth set of CPN variables this
+    # transition's incoming arcs bind — we always fetch each one from
+    # `event.binding` and immediately discard the binding via `_ = var`
+    # so a body that only references a subset of the bound vars does
+    # not trip `--warnings-as-errors`. Body-local pattern-match names
+    # (`pid = options[:pid]`, etc.) are NOT in this list and are never
+    # touched.
+    var_assignments =
+      Enum.flat_map(incoming_vars, fn var ->
+        var_ast = Macro.var(var, nil)
+
+        [
+          quote do
+            unquote(var_ast) = Keyword.fetch!(var!(event).binding, unquote(var))
+          end,
+          quote do
+            # Discard expression so a body that doesn't reference the var
+            # doesn't trip `--warnings-as-errors`. The underscore prefix
+            # satisfies the project's unused-variable naming convention.
+            _used = unquote(var_ast)
+          end
+        ]
+      end)
+
+    task_call = wrap_in_task(body, task_supervisor)
+
+    quote do
+      defp __action_for__(unquote(transition_name), var!(event), var!(options)) do
+        _event = var!(event)
+        _options = var!(options)
+        unquote_splicing(var_assignments)
+        unquote(task_call)
+      end
+    end
+  end
+
+  defp compile_lifecycle_hook({:on_enactment_start, body}, task_supervisor) do
+    task_call = wrap_in_task(body, task_supervisor)
+
+    quote do
+      @impl ColouredFlow.Runner.Enactment.LifecycleHooks
+      def on_enactment_start(var!(event), var!(options)) do
+        _event = var!(event)
+        _options = var!(options)
+        unquote(task_call)
+        :ok
+      end
+    end
+  end
+
+  defp compile_lifecycle_hook({:on_enactment_terminate, body}, task_supervisor) do
+    task_call = wrap_in_task(body, task_supervisor)
+
+    quote do
+      @impl ColouredFlow.Runner.Enactment.LifecycleHooks
+      def on_enactment_terminate(var!(event), var!(options)) do
+        _event = var!(event)
+        _options = var!(options)
+        unquote(task_call)
+        :ok
+      end
+    end
+  end
+
+  defp compile_lifecycle_hook({:on_enactment_exception, body}, task_supervisor) do
+    task_call = wrap_in_task(body, task_supervisor)
+
+    quote do
+      @impl ColouredFlow.Runner.Enactment.LifecycleHooks
+      def on_enactment_exception(var!(event), var!(options)) do
+        _event = var!(event)
+        _options = var!(options)
+        unquote(task_call)
+        :ok
+      end
+    end
+  end
+
+  defp wrap_in_task(body, nil) do
+    quote do
+      Task.start(fn -> unquote(body) end)
+    end
+  end
+
+  defp wrap_in_task(body, task_supervisor) do
+    quote do
+      Task.Supervisor.start_child(unquote(task_supervisor), fn -> unquote(body) end)
+    end
+  end
 end
@@ -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
 
@@ -0,0 +1,99 @@
+defmodule ColouredFlow.DSL.Lifecycle do
+  @moduledoc """
+  `on_enactment_start/1`, `on_enactment_terminate/1`, and
+  `on_enactment_exception/1` macros.
+
+  Each macro registers a clause that the workflow module's
+  `ColouredFlow.Runner.Enactment.LifecycleHooks` callback will execute. Bodies are
+  wrapped in a task by `ColouredFlow.DSL.Builder` (using the `:task_supervisor`
+  option passed to `use ColouredFlow.DSL`, falling back to an unsupervised
+  `Task.start/1`) so the runner never blocks on user-defined side effects.
+
+  Each hook may appear at most once per workflow. A second declaration raises a
+  `CompileError` pointing to the offending macro call.
+
+  Inside every hook body, the magic bindings `event` and `options` are available.
+  `event` is the typed event map documented on each
+  `ColouredFlow.Runner.Enactment.LifecycleHooks` callback (e.g.,
+  `event.enactment_id`, `event.markings`, `event.reason`); `options` is the
+  keyword list registered alongside the hook module via the `{module, options}`
+  tuple form (or `[]` when registered as a bare module).
+  """
+
+  @doc """
+  Runs once when the enactment GenServer finishes booting (after snapshot recovery
+  and initial calibration). Inside the body, `event.enactment_id` and
+  `event.markings` are available.
+
+  ## Examples
+
+      on_enactment_start do
+        Logger.info("enactment started: " <> event.enactment_id)
+      end
+  """
+  defmacro on_enactment_start(do: body) do
+    push_hook!(:on_enactment_start, body, __CALLER__)
+  end
+
+  @doc """
+  Runs when the enactment terminates normally. Inside the body, `event.reason` is
+  one of `:implicit`, `:explicit`, `:force`.
+
+  ## Examples
+
+      on_enactment_terminate do
+        Logger.info("done: " <> inspect(event.reason))
+      end
+  """
+  defmacro on_enactment_terminate(do: body) do
+    push_hook!(:on_enactment_terminate, body, __CALLER__)
+  end
+
+  @doc """
+  Runs when the runner records an exception against the enactment. Inside the
+  body, `event.reason` carries the failure mode (e.g., `:abnormal_exit`,
+  `:snapshot_corrupt`, `:invalid_termination_criteria`,
+  `:crash_threshold_exceeded`, `:terminated`, `:already_in_exception`).
+
+  ## Examples
+
+      on_enactment_exception do
+        Logger.error("workflow blew up: " <> inspect(event.reason))
+      end
+  """
+  defmacro on_enactment_exception(do: body) do
+    push_hook!(:on_enactment_exception, body, __CALLER__)
+  end
+
+  defp push_hook!(kind, body, caller) do
+    file = caller.file
+    line = caller.line
+    escaped_body = Macro.escape(body)
+
+    quote do
+      ColouredFlow.DSL.Lifecycle.__push_hook__!(
+        __MODULE__,
+        unquote(kind),
+        unquote(escaped_body),
+        unquote(file),
+        unquote(line)
+      )
+    end
+  end
+
+  @doc false
+  @spec __push_hook__!(module(), atom(), Macro.t(), String.t(), non_neg_integer()) :: :ok
+  def __push_hook__!(module, kind, body, file, line) do
+    existing = Module.get_attribute(module, :cf_lifecycle_hooks) || []
+
+    if Enum.any?(existing, fn {existing_kind, _body} -> existing_kind == kind end) do
+      raise CompileError,
+        description: "#{kind} already declared in this workflow",
+        file: file,
+        line: line
+    end
+
+    Module.put_attribute(module, :cf_lifecycle_hooks, {kind, body})
+    :ok
+  end
+end