feat(dsl): initial_markings accessor, hygiene, caller line, shared decomposer (#87)

## Summary

Codex review followups for the DSL PR (#69332aa). Four small,
independent fixes:

- **`initial_markings/0` accessor** — the `initial_marking/2` macro
accumulated into `@cf_initial_markings`, but `Builder` never read it.
Now exposed as a zero-arity helper returning
`[%ColouredFlow.Enactment.Marking{}]` (Runner seed data; intentionally
separate from `cpnet/0`'s static definition).
- **Hygiene checks** — `guard`/`action`/`on_markings` previously
silently overwrote when called twice in the same scope. Now raise
`CompileError` pointing at the second declaration.
- **Caller line/file in errors** — `guard`, `action`, `on_markings`,
`transition`, `termination`, `function`, `input`, `output`, `place`,
`initial_marking` all capture `__CALLER__.{file,line}` and thread it
through their `__set_*__!` / `__open_*__!` / `__push_arc__` helpers, so
`CompileError`s point at the offending line, not the `defmodule` line.
- **Shared type decomposer** — `DSL.Function` no longer maintains its
own `decompose_type/1`; reuses `Notation.Colset.__decompose_type__/1`
(newly exposed under the `__name__/N` "internal but reusable"
convention). `Builder.resolve_descr/2` stays — it does the user-name →
primitive descr lookup, which is orthogonal to AST decomposition.

Plus minor cleanups along the way: replace `ArgumentError` raises in
macro bodies with `CompileError`+file/line, fix the `~MS[1, 2, 3]` typo
in `spec.md` and `place.ex` docs (the sigil is space-separated), drop a
dead `if scope.markings || true do` in termination close.

## Test plan

- [x] new tests for `initial_markings/0` (empty, single, multi-place
accumulation)
- [x] new tests for duplicate `guard` / `action` / `on_markings`
(compile via `Code.compile_string` and assert `error.line` matches the
second declaration)
- [x] existing function tests still pass after the shared-decomposer
refactor
- [x] `mix format --check-formatted`
- [x] `mix compile --warnings-as-errors`
- [x] `mix credo --strict` (0 issues)
- [x] `mix dialyzer` (baseline `Total errors: 6, Skipped: 6` unchanged)
- [x] `MIX_ENV=test mix test` (63 doctests, 410 tests, 0 failures)

Author: fahchen

lib/coloured_flow/dsl/arc.ex

@@ -23,7 +23,7 @@ defmodule ColouredFlow.DSL.Arc do
       end
   """
   defmacro input(place, expression_or_opts, opts_or_block \\ []) do
-    build_arc(place, expression_or_opts, opts_or_block, :p_to_t, "input")
+    build_arc(place, expression_or_opts, opts_or_block, :p_to_t, "input", __CALLER__)
   end
 
   @doc """
@@ -40,31 +40,37 @@ defmodule ColouredFlow.DSL.Arc do
       end
   """
   defmacro output(place, expression_or_opts, opts_or_block \\ []) do
-    build_arc(place, expression_or_opts, opts_or_block, :t_to_p, "output")
+    build_arc(place, expression_or_opts, opts_or_block, :t_to_p, "output", __CALLER__)
   end
 
   @spec build_arc(
           Macro.t(),
           Macro.t(),
           Macro.t(),
           Arc.orientation(),
-          String.t()
+          String.t(),
+          Macro.Env.t()
         ) :: Macro.t()
-  defp build_arc(place, arg2, arg3, orientation, label) do
-    place_value = unquote_atom!(place, "#{label} place")
-    {opts, expr_ast} = decompose_args(arg2, arg3, label)
+  defp build_arc(place, arg2, arg3, orientation, label, caller) do
+    place_value = unquote_atom!(place, "#{label} place", caller)
+    {opts, expr_ast} = decompose_args(arg2, arg3, label, caller)
 
     arc_label = Keyword.get(opts, :label)
     expression = ExpressionHelper.build_arc_expression!(orientation, expr_ast)
 
     quote do
-      ColouredFlow.DSL.Transition.__push_arc__(__MODULE__, %Arc{
-        label: unquote(arc_label),
-        orientation: unquote(orientation),
-        transition: nil,
-        place: unquote(Atom.to_string(place_value)),
-        expression: unquote(Macro.escape(expression))
-      })
+      ColouredFlow.DSL.Transition.__push_arc__(
+        __MODULE__,
+        %Arc{
+          label: unquote(arc_label),
+          orientation: unquote(orientation),
+          transition: nil,
+          place: unquote(Atom.to_string(place_value)),
+          expression: unquote(Macro.escape(expression))
+        },
+        unquote(caller.file),
+        unquote(caller.line)
+      )
     end
   end
 
@@ -75,10 +81,10 @@ defmodule ColouredFlow.DSL.Arc do
   #   - (place, expression, opts_keyword)            -- arg3 is keyword (no :do)
   #   - (place, opts_keyword, do: expression)        -- arg2 is keyword, arg3 has :do
   #   - (place, do: expression)                      -- arg2 is keyword with :do, arg3 == []
-  @spec decompose_args(Macro.t(), Macro.t(), String.t()) :: {keyword(), Macro.t()}
-  defp decompose_args(arg2, arg3, label)
+  @spec decompose_args(Macro.t(), Macro.t(), String.t(), Macro.Env.t()) :: {keyword(), Macro.t()}
+  defp decompose_args(arg2, arg3, label, caller)
 
-  defp decompose_args(arg2, [], _label) do
+  defp decompose_args(arg2, [], _label, _caller) do
     if keyword?(arg2) and Keyword.has_key?(arg2, :do) do
       {body, opts} = Keyword.pop!(arg2, :do)
       {opts, body}
@@ -87,7 +93,7 @@ defmodule ColouredFlow.DSL.Arc do
     end
   end
 
-  defp decompose_args(arg2, arg3, label) when is_list(arg3) do
+  defp decompose_args(arg2, arg3, label, caller) when is_list(arg3) do
     cond do
       Keyword.has_key?(arg3, :do) and keyword?(arg2) ->
         {body, opts_after_do} = Keyword.pop!(arg3, :do)
@@ -101,13 +107,18 @@ defmodule ColouredFlow.DSL.Arc do
         {arg3, arg2}
 
       true ->
-        raise ArgumentError, "Invalid `#{label}` arguments: #{inspect(arg3)}"
+        raise CompileError,
+          description: "Invalid `#{label}` arguments: #{inspect(arg3)}",
+          file: caller.file,
+          line: caller.line
     end
   end
 
-  defp decompose_args(arg2, arg3, label) do
-    raise ArgumentError,
-          "Invalid `#{label}` arguments: arg2=#{inspect(arg2)}, arg3=#{inspect(arg3)}"
+  defp decompose_args(arg2, arg3, label, caller) do
+    raise CompileError,
+      description: "Invalid `#{label}` arguments: arg2=#{inspect(arg2)}, arg3=#{inspect(arg3)}",
+      file: caller.file,
+      line: caller.line
   end
 
   defp keyword?(list) when is_list(list) do
@@ -120,10 +131,13 @@ defmodule ColouredFlow.DSL.Arc do
 
   defp keyword?(_other), do: false
 
-  @spec unquote_atom!(Macro.t(), String.t()) :: atom()
-  defp unquote_atom!(value, _label) when is_atom(value), do: value
+  @spec unquote_atom!(Macro.t(), String.t(), Macro.Env.t()) :: atom()
+  defp unquote_atom!(value, _label, _caller) when is_atom(value), do: value
 
-  defp unquote_atom!(value, label) do
-    raise ArgumentError, "Expected #{label} to be an atom, got: #{Macro.to_string(value)}"
+  defp unquote_atom!(value, label, caller) do
+    raise CompileError,
+      description: "Expected #{label} to be an atom, got: #{Macro.to_string(value)}",
+      file: caller.file,
+      line: caller.line
   end
 end

lib/coloured_flow/dsl/builder.ex

@@ -10,6 +10,7 @@ defmodule ColouredFlow.DSL.Builder do
   alias ColouredFlow.Definition.ColouredPetriNet
   alias ColouredFlow.Definition.Place
   alias ColouredFlow.Definition.Procedure
+  alias ColouredFlow.Enactment.Marking
 
   @doc false
   defmacro __before_compile__(env) do
@@ -20,6 +21,7 @@ defmodule ColouredFlow.DSL.Builder do
     # and lets the arc validator allow free vars on outgoing arcs that are
     # produced by the action.
     cpnet = ColouredFlow.Builder.build(cpnet)
+    initial_markings = build_initial_markings(env.module)
 
     case ColouredFlow.Validators.run(cpnet) do
       {:ok, validated} ->
@@ -31,6 +33,14 @@ defmodule ColouredFlow.DSL.Builder do
           @spec cpnet() :: ColouredPetriNet.t()
           def cpnet, do: unquote(Macro.escape(validated))
 
+          @doc """
+          The list of `%ColouredFlow.Enactment.Marking{}` structs declared via
+          `initial_marking/2`. Used by the Runner to seed an enactment; this is *not* part
+          of the static CPN definition (see `cpnet/0`).
+          """
+          @spec initial_markings() :: [Marking.t()]
+          def initial_markings, do: unquote(Macro.escape(initial_markings))
+
           @doc """
           The human-readable name of this workflow, or `nil` if unset.
           """
@@ -56,6 +66,13 @@ defmodule ColouredFlow.DSL.Builder do
     end
   end
 
+  @spec build_initial_markings(module()) :: [Marking.t()]
+  defp build_initial_markings(module) do
+    module
+    |> pull(:cf_initial_markings)
+    |> Enum.map(fn {place, tokens} -> %Marking{place: place, tokens: tokens} end)
+  end
+
   @spec build_cpnet(module()) :: ColouredPetriNet.t()
   defp build_cpnet(module) do
     %ColouredPetriNet{

lib/coloured_flow/dsl/function.ex

@@ -21,7 +21,9 @@ defmodule ColouredFlow.DSL.Function do
       end
   """
   defmacro function(head_with_type, body \\ nil) do
-    {name, args, result} = decompose_head(head_with_type)
+    caller_file = __CALLER__.file
+    caller_line = __CALLER__.line
+    {name, args, result} = decompose_head(head_with_type, __CALLER__)
     expr_ast = ExpressionHelper.block_to_ast(body)
     expression = ExpressionHelper.build_from_ast!(expr_ast)
 
@@ -39,7 +41,9 @@ defmodule ColouredFlow.DSL.Function do
         unquote(name_ast),
         unquote(args_ast),
         unquote(missing_ast),
-        unquote(extra_ast)
+        unquote(extra_ast),
+        unquote(caller_file),
+        unquote(caller_line)
       )
 
       @cf_functions %Procedure{
@@ -51,79 +55,59 @@ defmodule ColouredFlow.DSL.Function do
   end
 
   @doc false
-  @spec __validate_args__!(atom(), [atom()], [atom()], [atom()]) :: :ok
-  def __validate_args__!(name, args, missing, _extra) do
+  @spec __validate_args__!(atom(), [atom()], [atom()], [atom()], String.t(), non_neg_integer()) ::
+          :ok
+  def __validate_args__!(name, args, missing, _extra, file, line) do
     if missing != [] do
       raise CompileError,
         description: """
         Function `#{name}/#{length(args)}` declares argument(s) \
         #{inspect(missing)}, but they are not referenced in the body.
-        """
+        """,
+        file: file,
+        line: line
     end
 
     # Extra free variables are allowed (other vars/constants resolved at the
     # workflow level), so we don't reject them here.
     :ok
   end
 
-  @spec decompose_head(Macro.t()) :: {atom(), [atom()], ColouredFlow.Definition.ColourSet.descr()}
-  defp decompose_head({:"::", _meta, [head, type_ast]}) do
-    {name, args} = decompose_call(head)
-    type_descr = decompose_type(type_ast)
+  @spec decompose_head(Macro.t(), Macro.Env.t()) ::
+          {atom(), [atom()], ColouredFlow.Definition.ColourSet.descr()}
+  defp decompose_head({:"::", _meta, [head, type_ast]}, caller) do
+    {name, args} = decompose_call(head, caller)
+    type_descr = ColouredFlow.Notation.Colset.__decompose_type__(type_ast)
     {name, args, type_descr}
   end
 
-  defp decompose_head(other) do
-    raise ArgumentError, """
-    Invalid function head, expected `name(arg1, arg2) :: type()`,
-    got: #{Macro.to_string(other)}
-    """
+  defp decompose_head(other, caller) do
+    raise CompileError,
+      description: """
+      Invalid function head, expected `name(arg1, arg2) :: type()`,
+      got: #{Macro.to_string(other)}
+      """,
+      file: caller.file,
+      line: caller.line
   end
 
-  defp decompose_call({name, _meta, args}) when is_atom(name) and is_list(args) do
+  defp decompose_call({name, _meta, args}, caller) when is_atom(name) and is_list(args) do
     arg_names =
       Enum.map(args, fn
         {arg, _meta, ctx} when is_atom(arg) and is_atom(ctx) ->
           arg
 
         other ->
-          raise ArgumentError,
-                "function argument must be a variable, got: #{Macro.to_string(other)}"
+          raise CompileError,
+            description: "function argument must be a variable, got: #{Macro.to_string(other)}",
+            file: caller.file,
+            line: caller.line
       end)
 
     {name, arg_names}
   end
 
-  defp decompose_call({name, _meta, ctx}) when is_atom(name) and is_atom(ctx) do
+  defp decompose_call({name, _meta, ctx}, _caller) when is_atom(name) and is_atom(ctx) do
     {name, []}
   end
-
-  # Reuse Notation.Colset's type decomposer through a public-ish path. Falls
-  # back to a small local impl for the cases we need.
-  @spec decompose_type(Macro.t()) :: ColouredFlow.Definition.ColourSet.descr()
-  defp decompose_type({:{}, _meta, []}), do: {:unit, []}
-
-  defp decompose_type({type1, type2}) do
-    {:tuple, [decompose_type(type1), decompose_type(type2)]}
-  end
-
-  defp decompose_type({:{}, _meta, types}) do
-    {:tuple, Enum.map(types, &decompose_type/1)}
-  end
-
-  defp decompose_type({:%{}, _meta, fields}) do
-    map = Map.new(fields, fn {key, type} -> {key, decompose_type(type)} end)
-    {:map, map}
-  end
-
-  defp decompose_type({:list, _meta, [type]}) do
-    {:list, decompose_type(type)}
-  end
-
-  defp decompose_type(type) do
-    case Macro.decompose_call(type) do
-      {name, []} when is_atom(name) -> {name, []}
-      _other -> raise ArgumentError, "Invalid function return type: #{Macro.to_string(type)}"
-    end
-  end
 end

lib/coloured_flow/dsl/place.ex

@@ -15,8 +15,8 @@ defmodule ColouredFlow.DSL.Place do
       place :output, :int
   """
   defmacro place(name, colour_set) do
-    name_value = unquote_atom!(name, "place name")
-    colour_set_value = unquote_atom!(colour_set, "place colour set")
+    name_value = unquote_atom!(name, "place name", __CALLER__)
+    colour_set_value = unquote_atom!(colour_set, "place colour set", __CALLER__)
 
     quote do
       @cf_places %Place{
@@ -32,20 +32,23 @@ defmodule ColouredFlow.DSL.Place do
 
   ## Examples
 
-      initial_marking :input, ~MS[1, 2, 3]
+      initial_marking :input, ~MS[1 2 3]
   """
   defmacro initial_marking(name, marking) do
-    name_value = unquote_atom!(name, "initial_marking place name")
+    name_value = unquote_atom!(name, "initial_marking place name", __CALLER__)
 
     quote do
       @cf_initial_markings {unquote(Atom.to_string(name_value)), unquote(marking)}
     end
   end
 
-  @spec unquote_atom!(Macro.t(), String.t()) :: atom()
-  defp unquote_atom!(value, _label) when is_atom(value), do: value
+  @spec unquote_atom!(Macro.t(), String.t(), Macro.Env.t()) :: atom()
+  defp unquote_atom!(value, _label, _caller) when is_atom(value), do: value
 
-  defp unquote_atom!(value, label) do
-    raise ArgumentError, "Expected #{label} to be an atom, got: #{Macro.to_string(value)}"
+  defp unquote_atom!(value, label, caller) do
+    raise CompileError,
+      description: "Expected #{label} to be an atom, got: #{Macro.to_string(value)}",
+      file: caller.file,
+      line: caller.line
   end
 end

lib/coloured_flow/dsl/spec.md

@@ -32,7 +32,7 @@ time.
       place :input, :int
       place :output, :int
 
-      initial_marking :input, ~MS[1, 2, 3]
+      initial_marking :input, ~MS[1 2 3]
 
       transition :pass_through do
         guard x > 0
@@ -70,9 +70,14 @@ declarations and runs `ColouredFlow.Validators.run/1` against it. Any
 validator failure raises at compile time so misconfigured workflows never
 reach runtime.
 
-Compiled modules expose a single zero-arity helper:
+Compiled modules expose two zero-arity helpers:
 
-    MyWorkflow.cpnet() :: %ColouredFlow.Definition.ColouredPetriNet{}
+    MyWorkflow.cpnet()             :: %ColouredFlow.Definition.ColouredPetriNet{}
+    MyWorkflow.initial_markings()  :: [%ColouredFlow.Enactment.Marking{}]
+
+`cpnet/0` returns the static CPN definition. `initial_markings/0` returns
+the list of `%Marking{}` structs declared via `initial_marking/2` — Runner
+seed data, deliberately *not* part of `cpnet/0`.
 
 Higher-level integration (running an enactment, persisting it, etc.) is
 intentionally left to the existing `ColouredFlow.Runner.*` API. The DSL
@@ -162,7 +167,7 @@ Declare the initial marking for a place. Multiple `initial_marking/2`
 calls may target different places; they are scattered freely between
 other declarations.
 
-    initial_marking :input, ~MS[1, 2, 3]
+    initial_marking :input, ~MS[1 2 3]
 
 ### `function/2` and `function/3`