docs(dsl): polish spec.md and drop macro-call parens in tests

- Restructure spec.md as a user-facing reference: removed the internal
  "File layout" section, tightened "Generated module surface" to
  document `cpnet/0` and the new `initial_markings/0` accessor as a
  pair, clarified what each generates and when.
- Strip optional parens from DSL macro invocations in test fixtures
  (`name/1`, `place/2`, `input/{2,3}`, `output/{2,3}`, etc.) so the
  test sources mirror the canonical paren-less style established in
  `.formatter.exs#locals_without_parens`.

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

Author: fahchen

lib/coloured_flow/dsl/spec.md

@@ -1,10 +1,11 @@
 A declarative Elixir DSL for defining Coloured Petri Nets.
 
-This is the high-level workflow-assembly layer. The low-level building
-blocks (`colset/1`, `var/1`, `val/1`) live in `ColouredFlow.Notation.*` and
-are reused here. The DSL composes them into a complete
-`ColouredFlow.Definition.ColouredPetriNet` and validates it at compile
-time.
+This is the high-level workflow-assembly layer on top of
+`ColouredFlow.Notation.*`. The DSL composes colour sets, variables,
+constants, places, transitions, arcs, functions, and termination criteria
+into a complete `ColouredFlow.Definition.ColouredPetriNet` and validates
+it at compile time. Any issue raises during `mix compile`, never at
+runtime.
 
 ## Synopsis
 
@@ -14,21 +15,16 @@ time.
       name "My Workflow"
       version "1.0.0"
 
-      # types
       colset int() :: integer()
       colset bool() :: boolean()
 
-      # bindings
       var x :: int()
-      var y :: int()
       val pi :: float() = 3.14
 
-      # functions
       function is_even(x) :: bool() do
         Integer.mod(x, 2) === 0
       end
 
-      # graph
       place :input, :int
       place :output, :int
 
@@ -42,13 +38,8 @@ time.
         output :output do
           if is_even(x), do: {1, x}, else: {1, x + 1}
         end
-
-        action do
-          log("fired with x=\#{x}")
-        end
       end
 
-      # termination
       termination do
         on_markings do
           match?(
@@ -59,73 +50,58 @@ time.
       end
     end
 
-    MyWorkflow.cpnet() #=> %ColouredFlow.Definition.ColouredPetriNet{...}
-
-## Module surface
-
-`use ColouredFlow.DSL` injects the macros listed below and registers an
-`@before_compile` hook that assembles a
-`%ColouredFlow.Definition.ColouredPetriNet{}` from the accumulated
-declarations and runs `ColouredFlow.Validators.run/1` against it. Any
-validator failure raises at compile time so misconfigured workflows never
-reach runtime.
+## Generated module surface
 
-Compiled modules expose two zero-arity helpers:
+A module that uses `ColouredFlow.DSL` exposes two zero-arity helpers:
 
     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`.
+`cpnet/0` returns the static CPN — colour sets, variables, places,
+transitions, arcs, and termination criteria. It is the input the runner
+reuses across every enactment of the workflow.
 
-Higher-level integration (running an enactment, persisting it, etc.) is
-intentionally left to the existing `ColouredFlow.Runner.*` API. The DSL
-produces only the static definition.
+`initial_markings/0` returns the list of `%Marking{}` declared via
+`initial_marking/2`. This is enactment-seed data, deliberately *not*
+folded into `cpnet/0`. Pass it to `Storage.insert_enactment/1` (or your
+own runner glue) when starting an enactment.
+
+Higher-level integration — spawning enactments, persisting flows,
+visualisation — is left to the existing `ColouredFlow.Runner.*` API.
 
 ## Universal expression rule
 
-Every macro that accepts an expression follows the same rule:
+Every macro that accepts an expression follows the same shape:
 
-- **Single-line**: the expression is the last positional argument.
-- **Multi-line**: pass a `do ... end` block; the block body **is** the
-  expression. There is no `expr do ... end` wrapper anywhere.
-- **Options** (e.g., `label:`): keyword arguments only, placed before the
-  `do` block.
+  - **Single-line**: the expression is the last positional argument.
+  - **Multi-line**: pass a `do ... end` block; the block body **is** the
+    expression. There is no `expr do ... end` wrapper.
+  - **Options** (e.g., `label:`): keyword arguments only, before the `do`
+    block.
 
 ```elixir
-guard x > 0                                  # single-line
-guard do x > 0 and y > 0 end                 # multi-line
+guard x > 0                                 # single-line
+guard do x > 0 and y > 0 end                # multi-line
 
-input :p, bind({1, x})                       # single-line, no label
-input :p, bind({1, x}), label: "in"          # single-line, with label
+input :p, bind({1, x})                      # single-line, no label
+input :p, bind({1, x}), label: "in"         # single-line, with label
 
-input :p, label: "in" do                     # multi-line, with label
+input :p, label: "in" do                    # multi-line, with label
   if x > 0, do: bind({1, x}), else: bind({2, x})
 end
 ```
 
-## Reuse
-
-`colset/1`, `var/1`, and `val/1` are re-exported from
-`ColouredFlow.Notation.*` so existing notation users have one mental model.
-Everything else (`name`, `version`, `place`, `initial_marking`,
-`transition`, `input`, `output`, `guard`, `action`, `function`,
-`termination`, `on_markings`) is new and lives under
-`ColouredFlow.DSL.*`.
-
 ## Top-level macros
 
 ### `name/1`
 
-Set the human-readable workflow name. Compile-time only.
+Set the human-readable workflow name.
 
     name "Traffic Light"
 
 ### `version/1`
 
-Set the workflow version (any string the caller chooses; semver is
-conventional).
+Set the workflow version (free-form string; semver is conventional).
 
     version "1.0.0"
 
@@ -140,41 +116,42 @@ Re-exported from `ColouredFlow.Notation.Colset`. Declares a colour set.
 
 ### `var/1`
 
-Re-exported from `ColouredFlow.Notation.Var`. Declares a variable bound to
-a colour set.
+Re-exported from `ColouredFlow.Notation.Var`. Declares a variable bound
+to a colour set.
 
     var x :: int()
 
 ### `val/1`
 
-Re-exported from `ColouredFlow.Notation.Val`. Declares a constant bound to
-a colour set.
+Re-exported from `ColouredFlow.Notation.Val`. Declares a constant bound
+to a colour set.
 
     val pi :: float() = 3.14
 
 ### `place/2`
 
-Declare a place. The first argument is the place name (atom; converted to a
-string for the underlying `%Place{}`); the second is the colour set name
-(atom).
+Declare a place. Place names are atoms; the underlying `%Place{}` stores
+them as strings. The colour set name is also an atom and must be a
+declared `colset`.
 
     place :input, :int
     place :output, :int
 
 ### `initial_marking/2`
 
-Declare the initial marking for a place. Multiple `initial_marking/2`
-calls may target different places; they are scattered freely between
-other declarations.
+Declare an initial marking for a place. Multiple `initial_marking/2`
+calls accumulate in declaration order and are exposed via
+`initial_markings/0` on the host module. The cpnet definition itself is
+not affected.
 
     initial_marking :input, ~MS[1 2 3]
 
 ### `function/2` and `function/3`
 
 Declare a user-defined function (CPN procedure) usable in arc, guard,
-action, and termination expressions. The arguments listed in the head
-must appear as free variables in the body. The return type after `::` is
-the result colour set.
+action, and termination expressions. Arguments listed in the head must
+appear as free variables in the body; the result type after `::` is the
+result colour set.
 
     function is_even(x) :: bool(), do: Integer.mod(x, 2) === 0
 
@@ -184,8 +161,8 @@ the result colour set.
 
 ### `transition/2`
 
-Declare a transition. The block accepts `guard/1`, `action/1`, `input/2,3`
-and `output/2,3`.
+Declare a transition. The block accepts `guard/1`, `action/1`,
+`input/2,3`, and `output/2,3`.
 
     transition :pass_through do
       guard x > 0
@@ -201,9 +178,9 @@ and `output/2,3`.
 ### `termination/1`
 
 Declare termination criteria. The block accepts criterion-specific
-sub-macros. Currently only `on_markings/1` is supported. Future criterion
-kinds (`on_time`, `on_workitem_count`, etc.) plug in here without
-changing call sites.
+sub-macros. Currently `on_markings/1` is the only kind. Future kinds
+(`on_time`, `on_workitem_count`, …) plug in here without changing call
+sites.
 
     termination do
       on_markings do
@@ -218,8 +195,9 @@ changing call sites.
 
 ### `guard/1`
 
-Boolean expression over bound variables. Optional. Returning a falsy
-value disables the transition for the current binding.
+A boolean expression over bound variables. Optional. A falsy result
+disables the transition for the current binding. Declaring `guard` more
+than once in a transition is a compile-time error.
 
     guard x > 0
     guard do
@@ -228,9 +206,10 @@ value disables the transition for the current binding.
 
 ### `action/1`
 
-Expression evaluated when the transition fires. Optional. Use for output
-bindings (when an outgoing arc references an unbound variable) and for
-side effects.
+Expression evaluated when the transition fires. Optional. Use it to
+provide bindings for outgoing arcs that reference variables not bound by
+any incoming arc. Declaring `action` more than once in a transition is a
+compile-time error.
 
     action :ok
     action do
@@ -240,8 +219,8 @@ side effects.
 
 ### `input/2` and `input/3`
 
-Declare an incoming arc (place → transition). The expression must use the
-`bind/1` keyword to consume tokens. Options: `:label`.
+Declare an incoming arc (place → transition). The expression must use
+`bind/1` to consume tokens. Options: `:label`.
 
     input :input, bind({1, x})
     input :input, bind({1, x}), label: "in"
@@ -251,8 +230,8 @@ Declare an incoming arc (place → transition). The expression must use the
 
 ### `output/2` and `output/3`
 
-Declare an outgoing arc (transition → place). The expression evaluates to
-the multiset of tokens produced. Options: `:label`.
+Declare an outgoing arc (transition → place). The expression evaluates
+to the multiset of tokens produced. Options: `:label`.
 
     output :output, {1, x}
     output :output, {1, x}, label: "out"
@@ -264,9 +243,10 @@ the multiset of tokens produced. Options: `:label`.
 
 ### `on_markings/1`
 
-Boolean expression over the special variable `markings` (a map of place
-name → token multiset). Returning a truthy value terminates the enactment
-with reason `:explicit`.
+Boolean expression over the special variable `markings` — a map of place
+name (string) to token multiset. A truthy result terminates the
+enactment with reason `:explicit`. Declaring `on_markings` more than
+once is a compile-time error.
 
     on_markings do
       match?(
@@ -278,39 +258,18 @@ with reason `:explicit`.
 ## Compile-time validation
 
 The `@before_compile` hook builds a `%ColouredPetriNet{}` from the
-accumulated declarations and runs the existing
-`ColouredFlow.Validators.run/1` pipeline:
-
-- colour-set declarations are well-formed,
-- place colour-set references resolve,
-- arc endpoints exist,
-- incoming arcs use `bind/1`,
-- free variables in expressions resolve to declared `var/1` (or function
-  arguments),
-- structural sanity (no orphan places, no duplicate names, etc.).
-
-Any failure raises a clear compile-time error pointing to the offending
-line.
-
-## File layout
-
-Macros are partitioned by concern; the entry module re-exports them via
-`__using__/1`.
-
-- `ColouredFlow.DSL`                       — entry, `__using__/1`, top-level macros
-- `ColouredFlow.DSL.Builder`               — `@before_compile` hook
-- `ColouredFlow.DSL.Place`                 — `place/2`, `initial_marking/2`
-- `ColouredFlow.DSL.Transition`            — `transition/2`, `guard/1`, `action/1`
-- `ColouredFlow.DSL.Arc`                   — `input/{2,3}`, `output/{2,3}`
-- `ColouredFlow.DSL.Function`              — `function/{2,3}`
-- `ColouredFlow.DSL.Termination`           — `termination/1`, `on_markings/1`
-- `ColouredFlow.DSL.ExpressionHelper`      — AST → `%Expression{}` conversion
-
-## Out of scope
-
-- Runner integration: spawning enactments, persisting flows. The DSL
-  produces a definition; how it is run is the caller's choice.
-- Visualisation / diagram generation. Could be layered on top of
-  `cpnet/0`.
-- Live editing / hot reload. Workflows are expected to be defined in
-  source and recompiled.
+accumulated declarations, runs `ColouredFlow.Builder.build/1` (which
+populates `action.outputs` from arc/guard analysis), and runs
+`ColouredFlow.Validators.run/1`:
+
+  - colour set declarations are well-formed,
+  - place / variable / constant colour-set references resolve,
+  - arc endpoints exist,
+  - incoming arcs use `bind/1`,
+  - free variables in expressions resolve to `var/1` (or function args),
+  - guard variables are bound by the same transition's incoming arcs,
+  - 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.