feat(asm): implement macro @ret wiring, parameterized qualifiers, and ${param} substitution

Enhancement 2: Parameterized placement, port, and context slot qualifiers
- Grammar: placement, port, ctx_slot accept param_ref
- IR: PlacementRef, PortRef, CtxSlotRef, CtxSlotRange wrapper types
- Lower: qualified_ref extracts typed qualifier refs; _normalize_port passes PortRef through
- Lower: _process_statements uses replace() instead of manual IRNode reconstruction
- Expand: resolves PlacementRef/PortRef/CtxSlotRef during substitution

Enhancement 3: @ret wiring for macros
- Grammar: macro_call_stmt accepts optional |> call_output_list
- IR: IRMacroCall gains output_dests field
- Lower: macro_call_stmt handler extracts output destinations
- Expand: rewrites @ret/@ret_name edges to concrete destinations after body expansion
- Expand: reports MACRO error for unmatched @ret or missing output wiring

asm/expand.py

···
 from asm.errors import AssemblyError, ErrorCategory
 from asm.ir import (
     IRGraph, IRNode, IREdge, IRRegion, RegionKind, ParamRef, ConstExpr,
-    MacroDef, IRMacroCall, CallSiteResult, CallSite, IRRepetitionBlock, SourceLoc
+    MacroDef, IRMacroCall, CallSiteResult, CallSite, IRRepetitionBlock, SourceLoc,
+    PlacementRef, PortRef, CtxSlotRef, CtxSlotRange,
 )
 from asm.opcodes import MNEMONIC_TO_OP
 from cm_inst import Port, RoutingOp
···
             ))
             new_opcode = node.opcode
 
+    # Resolve placement if it's a PlacementRef
+    new_pe = node.pe
+    if isinstance(new_pe, PlacementRef):
+        resolved = _substitute_param(new_pe.param, subst_map)
+        if isinstance(resolved, str) and resolved.startswith("pe"):
+            try:
+                new_pe = int(resolved[2:])
+            except ValueError:
+                errors.append(AssemblyError(
+                    loc=node.loc,
+                    category=ErrorCategory.MACRO,
+                    message=f"placement parameter must resolve to 'peN', got '{resolved}'",
+                ))
+                new_pe = None
+        elif isinstance(resolved, int):
+            new_pe = resolved
+        else:
+            errors.append(AssemblyError(
+                loc=node.loc,
+                category=ErrorCategory.MACRO,
+                message=f"placement parameter must resolve to 'peN', got {type(resolved).__name__}",
+            ))
+            new_pe = None
+
+    # Resolve ctx_slot if it's a CtxSlotRef
+    new_ctx_slot = node.ctx_slot
+    if isinstance(new_ctx_slot, CtxSlotRef):
+        resolved = _substitute_param(new_ctx_slot.param, subst_map)
+        if isinstance(resolved, int):
+            new_ctx_slot = CtxSlotRange(start=resolved, end=resolved)
+        else:
+            errors.append(AssemblyError(
+                loc=node.loc,
+                category=ErrorCategory.MACRO,
+                message=f"ctx_slot parameter must resolve to an integer, got {type(resolved).__name__}",
+            ))
+            new_ctx_slot = None
+
     # Substitute the node name (may be a ParamRef with token pasting)
     substituted_name = _substitute_param(node.name, subst_map)
 
···
     # Qualify the node name
     new_name = _qualify_expanded_name(substituted_name, macro_scope, parent_scope, func_scope)
 
-    return replace(node, name=new_name, const=new_const, opcode=new_opcode), errors
+    return replace(node, name=new_name, const=new_const, opcode=new_opcode,
+                   pe=new_pe, ctx_slot=new_ctx_slot), errors
 
 
 def _clone_and_substitute_edge(
···
     if not dest_was_param:
         dest = _qualify_expanded_name(dest, macro_scope, parent_scope, func_scope)
 
-    return replace(edge, source=source, dest=dest)
+    # Resolve PortRef on dest port
+    new_port = edge.port
+    if isinstance(new_port, PortRef):
+        resolved = _substitute_param(new_port.param, subst_map)
+        if isinstance(resolved, str):
+            if resolved == "L":
+                new_port = Port.L
+            elif resolved == "R":
+                new_port = Port.R
+            else:
+                new_port = Port.L  # fallback, error reported elsewhere
+        elif isinstance(resolved, Port):
+            new_port = resolved
+        else:
+            new_port = Port.L
+
+    # Resolve PortRef on source port
+    new_source_port = edge.source_port
+    if isinstance(new_source_port, PortRef):
+        resolved = _substitute_param(new_source_port.param, subst_map)
+        if isinstance(resolved, str):
+            if resolved == "L":
+                new_source_port = Port.L
+            elif resolved == "R":
+                new_source_port = Port.R
+            else:
+                new_source_port = None
+        elif isinstance(resolved, Port):
+            new_source_port = resolved
+        else:
+            new_source_port = None
+
+    return replace(edge, source=source, dest=dest, port=new_port, source_port=new_source_port)
 
 
 def _add_expansion_context(
···
         depth,
     )
     errors.extend(nested_errors)
+
+    # Rewrite @ret edges: either substitute with output destinations, or
+    # report an error if the macro body uses @ret but the call site doesn't
+    # provide output wiring.
+    has_ret_edges = any(
+        isinstance(e.dest, str) and e.dest.startswith("@ret")
+        for e in expanded_edges
+    )
+
+    if has_ret_edges and not call.output_dests:
+        # Collect the @ret markers for the error message
+        ret_markers = sorted({
+            e.dest for e in expanded_edges
+            if isinstance(e.dest, str) and e.dest.startswith("@ret")
+        })
+        errors.append(AssemblyError(
+            loc=call.loc,
+            category=ErrorCategory.MACRO,
+            message=f"macro '#{call.name}' defines output(s) {', '.join(ret_markers)} but call site has no '|>' output wiring",
+        ))
+
+    if call.output_dests:
+        rewritten_edges = []
+        all_outputs = list(call.output_dests)
+
+        for edge in expanded_edges:
+            if not (isinstance(edge.dest, str) and edge.dest.startswith("@ret")):
+                rewritten_edges.append(edge)
+                continue
+
+            # This edge targets an @ret marker — resolve it
+            ret_dest = edge.dest  # e.g. "@ret" or "@ret_body"
+            dest_name = None
+
+            # Try named match: @ret_body -> output with name="body"
+            if ret_dest.startswith("@ret_"):
+                expected_suffix = ret_dest[5:]  # "body" from "@ret_body"
+                for output in all_outputs:
+                    if isinstance(output, dict) and "name" in output and "ref" in output:
+                        if output["name"] == expected_suffix:
+                            ref = output["ref"]
+                            dest_name = ref.get("name", ref) if isinstance(ref, dict) else str(ref)
+                            break
+
+            # Bare @ret -> first positional output
+            if dest_name is None and ret_dest == "@ret":
+                for output in all_outputs:
+                    if isinstance(output, dict):
+                        if "name" in output and "ref" in output:
+                            # Named output — skip for bare @ret
+                            continue
+                        # Positional output (just a ref dict)
+                        dest_name = output.get("name", None)
+                    else:
+                        dest_name = str(output)
+                    if dest_name is not None:
+                        break
+
+            if dest_name is None:
+                errors.append(AssemblyError(
+                    loc=call.loc,
+                    category=ErrorCategory.MACRO,
+                    message=f"macro '#{call.name}' has output marker '{ret_dest}' but no matching output destination in call site",
+                ))
+                rewritten_edges.append(edge)
+                continue
+
+            # Replace the @ret destination with the concrete node reference
+            rewritten_edges.append(replace(edge, dest=dest_name))
+
+        expanded_edges = rewritten_edges
 
     # Propagate errors from macro body template
     for body_error in macro_def.body.errors:

asm/ir.py

···
     dest_l: Optional[Union[NameRef, ResolvedDest]] = None
     dest_r: Optional[Union[NameRef, ResolvedDest]] = None
     const: Optional[Union[int, ParamRef, ConstExpr]] = None
-    pe: Optional[int] = None
+    pe: Optional[Union[int, PlacementRef]] = None
+    ctx_slot: Optional[Union[int, CtxSlotRef, CtxSlotRange]] = None
     iram_offset: Optional[int] = None
     ctx: Optional[int] = None
     loc: SourceLoc = SourceLoc(0, 0)
···
     """
     source: Union[str, ParamRef]
     dest: Union[str, ParamRef]
-    port: Port
-    source_port: Optional[Port] = None
+    port: Union[Port, PortRef]
+    source_port: Optional[Union[Port, PortRef]] = None
     port_explicit: bool = False
     ctx_override: bool = False
     loc: SourceLoc = SourceLoc(0, 0)
···
 
 
 @dataclass(frozen=True)
+class PlacementRef:
+    """Deferred placement from macro parameter."""
+    param: ParamRef
+
+
+@dataclass(frozen=True)
+class PortRef:
+    """Deferred port from macro parameter."""
+    param: ParamRef
+
+
+@dataclass(frozen=True)
+class CtxSlotRef:
+    """Deferred context slot from macro parameter."""
+    param: ParamRef
+
+
+@dataclass(frozen=True)
+class CtxSlotRange:
+    """Explicit context slot range reservation."""
+    start: int
+    end: int
+
+
+@dataclass(frozen=True)
 class IRRepetitionBlock:
     """A repetition block within a macro body template.
 
···
     name: str
     positional_args: tuple = ()
     named_args: tuple[tuple[str, object], ...] = ()
+    output_dests: tuple = ()
     loc: SourceLoc = SourceLoc(0, 0)
 
 

asm/lower.py

···
 from asm.ir import (
     IRGraph, IRNode, IREdge, IRRegion, RegionKind, IRDataDef, SystemConfig,
     SourceLoc, NameRef, ResolvedDest, MacroParam, ParamRef, MacroDef, IRMacroCall,
-    CallSiteResult, IRRepetitionBlock
+    CallSiteResult, IRRepetitionBlock,
+    PlacementRef, PortRef, CtxSlotRef, CtxSlotRange,
 )
 from asm.errors import AssemblyError, ErrorCategory
 from asm.opcodes import MNEMONIC_TO_OP
···
     return [arg for arg in args if not isinstance(arg, LarkToken)]
 
 
-def _normalize_port(value: Union[int, Port]) -> Port:
-    """Normalize a port value to Port enum.
-
-    Handles conversion from raw integers (0 for L, 1 for R) to Port enum.
-    If already a Port, returns as-is. Defaults to Port.L for invalid values.
+def _normalize_port(value: Union[int, Port, PortRef]) -> Union[Port, PortRef]:
+    """Normalize a port value to Port enum, preserving PortRef for macro templates.
 
     Args:
-        value: An int (0/1) or Port enum value
+        value: An int (0/1), Port enum, or PortRef (macro parameter)
 
     Returns:
-        Normalized Port enum value
+        Port enum value, or PortRef passed through for later expansion
     """
+    if isinstance(value, PortRef):
+        return value
     if isinstance(value, Port):
         return value
     if isinstance(value, int):
···
                     qualified_name = self._qualify_name(node_name, func_scope)
                     if not self._check_duplicate_name(qualified_name, node.loc):
                         # Update node with qualified name
-                        qualified_node = IRNode(
-                            name=qualified_name,
-                            opcode=node.opcode,
-                            dest_l=node.dest_l,
-                            dest_r=node.dest_r,
-                            const=node.const,
-                            pe=node.pe,
-                            iram_offset=node.iram_offset,
-                            ctx=node.ctx,
-                            loc=node.loc,
-                            args=node.args,
-                            sm_id=node.sm_id,
-                            seed=node.seed,
-                        )
+                        qualified_node = replace(node, name=qualified_name)
                         nodes[qualified_name] = qualified_node
 
             elif isinstance(stmt, EdgeResult):
···
                 for node_name, node in stmt.nodes.items():
                     qualified_name = self._qualify_name(node_name, func_scope)
                     if not self._check_duplicate_name(qualified_name, node.loc):
-                        qualified_node = IRNode(
-                            name=qualified_name,
-                            opcode=node.opcode,
-                            dest_l=node.dest_l,
-                            dest_r=node.dest_r,
-                            const=node.const,
-                            pe=node.pe,
-                            iram_offset=node.iram_offset,
-                            ctx=node.ctx,
-                            loc=node.loc,
-                            args=node.args,
-                            sm_id=node.sm_id,
-                            seed=node.seed,
-                        )
+                        qualified_node = replace(node, name=qualified_name)
                         nodes[qualified_name] = qualified_node
                 for edge in stmt.edges:
                     qualified_edge = IREdge(
···
         # Extract placement (PE qualifier)
         pe = None
         if "placement" in qualified_ref_dict and qualified_ref_dict["placement"]:
-            placement_str = qualified_ref_dict["placement"]
-            # Parse placement like "pe0" → extract 0
-            if placement_str.startswith("pe"):
+            placement_val = qualified_ref_dict["placement"]
+            if isinstance(placement_val, PlacementRef):
+                pe = placement_val
+            elif isinstance(placement_val, str) and placement_val.startswith("pe"):
                 try:
-                    pe = int(placement_str[2:])
+                    pe = int(placement_val[2:])
                 except ValueError:
                     pass
+
+        # Extract context slot qualifier
+        ctx_slot = qualified_ref_dict.get("ctx_slot")
 
         # Extract const and named args from arguments
         # Check if first remaining arg is an inline_const (int directly after opcode)
···
             dest_r=None,
             const=const,
             pe=pe,
+            ctx_slot=ctx_slot,
             loc=loc,
             args=args_dict if args_dict else None,
         )
-
         return NodeResult({name: node})
 
     @v_args(inline=True, meta=True)
···
 
         positional_args = []
         named_args: dict[str, object] = {}
+        output_dests = ()
         found_name = False
         for item in args:
             if isinstance(item, LarkToken):
···
                     # First LarkToken is the macro name
                     found_name = True
                     continue
-                if item.type == "OPCODE":
-                    # Bare opcode token as macro argument — wrap as string
+                if item.type in ("OPCODE", "IDENT"):
+                    # Bare opcode or identifier as macro argument — wrap as string
                     positional_args.append(str(item))
                     continue
                 # Skip other tokens (FLOW_OUT, commas, etc.)
                 continue
+            elif isinstance(item, list) and all(isinstance(x, dict) for x in item):
+                # call_output_list result — list of output dest dicts
+                output_dests = tuple(item)
             elif isinstance(item, tuple) and len(item) == 2 and isinstance(item[0], str):
                 # Named argument from named_arg rule (name, value)
                 named_args[item[0]] = item[1]
···
             name=macro_name,
             positional_args=tuple(positional_args),
             named_args=tuple(named_args.items()),
+            output_dests=output_dests,
             loc=loc,
         )
 
···
         # Extract SM ID from placement
         sm_id = None
         if "placement" in qualified_ref_dict and qualified_ref_dict["placement"]:
-            placement_str = qualified_ref_dict["placement"]
-            if placement_str.startswith("sm"):
+            placement_val = qualified_ref_dict["placement"]
+            if isinstance(placement_val, str) and placement_val.startswith("sm"):
                 try:
-                    sm_id = int(placement_str[2:])
+                    sm_id = int(placement_val[2:])
                 except ValueError:
                     pass
 
···
         """Collect qualified reference components into a dict."""
         ref_type = None
         placement = None
+        ctx_slot = None
         port = None
 
         for arg in args:
-            if isinstance(arg, ParamRef):
+            if isinstance(arg, PlacementRef):
+                placement = arg
+            elif isinstance(arg, PortRef):
+                port = arg
+            elif isinstance(arg, (CtxSlotRef, CtxSlotRange)):
+                ctx_slot = arg
+            elif isinstance(arg, (Port, int)):
+                port = arg
+            elif isinstance(arg, ParamRef):
                 ref_type = {"name": arg}
             elif isinstance(arg, dict):
                 ref_type = arg
             elif isinstance(arg, str) and (arg.startswith("pe") or arg.startswith("sm")):
                 placement = arg
-            elif isinstance(arg, (Port, int)):
-                port = arg
 
         result = ref_type.copy() if ref_type else {}
-        if placement:
+        if placement is not None:
             result["placement"] = placement
+        if ctx_slot is not None:
+            result["ctx_slot"] = ctx_slot
         if port is not None:
             result["port"] = port
 
···
         return ParamRef(param=name)
 
     @v_args(inline=True)
-    def placement(self, token: LarkToken) -> str:
+    def placement(self, token) -> Union[str, PlacementRef]:
         """Extract placement specifier."""
+        if isinstance(token, ParamRef):
+            return PlacementRef(param=token)
         return str(token)
 
+    def ctx_slot(self, args: list):
+        """Extract context slot specifier.
+
+        Always returns a typed wrapper (CtxSlotRef, CtxSlotRange) so
+        qualified_ref can distinguish ctx_slot ints from port ints.
+        """
+        if len(args) == 1:
+            arg = args[0]
+            if isinstance(arg, ParamRef):
+                return CtxSlotRef(param=arg)
+            if isinstance(arg, CtxSlotRange):
+                return arg
+            n = int(str(arg))
+            return CtxSlotRange(start=n, end=n)
+        return args[0]
+
+    def ctx_range(self, args: list) -> CtxSlotRange:
+        """Extract context slot range (start..end)."""
+        return CtxSlotRange(start=int(str(args[0])), end=int(str(args[1])))
+
     @v_args(inline=True)
-    def port(self, token: LarkToken) -> Union[Port, int]:
-        """Convert port specifier to Port enum or raw int.
+    def port(self, token) -> Union[Port, int, PortRef]:
+        """Convert port specifier to Port enum, raw int, or PortRef.
 
         Returns:
-            Port.L for "L" or "0"
-            Port.R for "R" or "1"
-            Raw int for other numeric values (e.g., cell address)
+            Port.L for "L"
+            Port.R for "R"
+            Raw int for numeric values (e.g., cell address in data_def)
+            PortRef for param_ref
         """
+        if isinstance(token, ParamRef):
+            return PortRef(param=token)
         spec = str(token)
-        if spec in ("L", "0"):
+        if spec == "L":
             return Port.L
-        elif spec in ("R", "1"):
+        elif spec == "R":
             return Port.R
         else:
-            # Try to parse as integer (for cell addresses in data_def)
             try:
                 return int(spec)
             except ValueError:
-                # Fall back to Port.L for unparseable values
                 return Port.L
 
     @v_args(inline=True)

dfasm.lark

···
 // #name  — macro reference
 // Chaining: @sum|pe0:L  (placement + port)
 
-qualified_ref: (node_ref | label_ref | func_ref | macro_ref | scoped_ref | param_ref) placement? port?
+qualified_ref: (node_ref | label_ref | func_ref | macro_ref | scoped_ref | param_ref) placement? ctx_slot? port?
 
 node_ref:  "@" IDENT
 label_ref: "&" IDENT
···
 param_ref: PARAM_REF_START IDENT "}"
 PARAM_REF_START.3: "${"
 
-placement: "|" IDENT
-port:      ":" PORT_SPEC
+placement: "|" (IDENT | param_ref)
+ctx_slot:  "[" (DEC_LIT | ctx_range | param_ref) "]"
+ctx_range: DEC_LIT ".." DEC_LIT
+port:      ":" (PORT_SPEC | param_ref)
 
 PORT_SPEC: IDENT | HEX_LIT | DEC_LIT
 
···
 
 ?argument: named_arg | positional_arg
 named_arg: IDENT "=" positional_arg
-?positional_arg: value | qualified_ref | OPCODE
+?positional_arg: value | qualified_ref | OPCODE | IDENT
 
 // === Values (literals) ===
 
···
 
 macro_call: "#" IDENT (value | qualified_ref)*
 
-// #name arg [, arg ...] — standalone macro invocation (as statement)
-macro_call_stmt: "#" IDENT (argument ("," argument)*)?
+// #name arg [, arg ...] [|> output, ...] — standalone macro invocation (as statement)
+macro_call_stmt: "#" IDENT (argument ("," argument)*)? (FLOW_OUT call_output_list)?
 
 // --- Function call ---
 // $func a=&x, b=&y |> @output [, name=@output2]

tests/test_macro_ret_wiring.py

···
+"""Tests for Enhancement 3: @ret wiring for macros (macro-enh.E3.*).
+
+Tests verify:
+- E3.1: Grammar accepts |> output list on macro_call_stmt
+- E3.2: Lower stores output_dests on IRMacroCall
+- E3.3: Expand rewrites @ret edges to concrete destinations (positional)
+- E3.4: Expand rewrites @ret_name edges to concrete destinations (named)
+- E3.5: Unmatched @ret marker produces MACRO error
+- E3.6: Macro with @ret but no |> at call site produces MACRO error
+- E3.7: Multiple @ret markers with mixed positional/named outputs
+- E3.8: @ret in nested macro invocation
+"""
+
+from pathlib import Path
+
+from lark import Lark
+
+from asm.expand import expand
+from asm.lower import lower
+from asm.errors import ErrorCategory
+from asm.ir import IRMacroCall
+
+
+def _get_parser():
+    grammar_path = Path(__file__).parent.parent / "dfasm.lark"
+    return Lark(
+        grammar_path.read_text(),
+        parser="earley",
+        propagate_positions=True,
+    )
+
+
+def parse_and_lower(source: str):
+    parser = _get_parser()
+    tree = parser.parse(source)
+    return lower(tree)
+
+
+def parse_lower_expand(source: str):
+    graph = parse_and_lower(source)
+    return expand(graph)
+
+
+class TestE31_GrammarAcceptsOutputList:
+    """E3.1: Grammar accepts |> output list on macro_call_stmt.
+
+    Note: #macro |> &dest (no args, single positional output) is ambiguous
+    with plain_edge syntax and parses as plain_edge. Disambiguation requires
+    either named outputs (name=&dest) or at least one argument before |>.
+    """
+
+    def test_macro_call_with_named_output_no_args(self):
+        """#macro |> name=&dest parses as macro_call_stmt (named output disambiguates)."""
+        source = """
+        @system pe=1, sm=1
+        #simple |> {
+            &g <| pass
+            &g |> @ret_out
+        }
+        &sink <| add
+        #simple |> out=&sink
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+        assert len(graph.macro_calls) == 1
+
+    def test_macro_call_with_named_outputs(self):
+        """#macro |> name=&dest, name2=&dest2 parses without error."""
+        source = """
+        @system pe=1, sm=1
+        #dual |> {
+            &g <| pass
+            &g |> @ret_body
+            &g |> @ret_exit:R
+        }
+        &body_sink <| add
+        &exit_sink <| add
+        #dual |> body=&body_sink, exit=&exit_sink
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+
+    def test_macro_call_with_args_and_positional_output(self):
+        """#macro arg |> &dest parses as macro_call_stmt (args disambiguate)."""
+        source = """
+        @system pe=1, sm=1
+        #with_arg val |> {
+            &g <| const, ${val}
+            &g |> @ret
+        }
+        &sink <| add
+        #with_arg 42 |> &sink
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+        assert len(graph.macro_calls) == 1
+
+
+class TestE32_LowerStoresOutputDests:
+    """E3.2: Lower stores output_dests on IRMacroCall."""
+
+    def test_output_dests_populated_with_arg(self):
+        """IRMacroCall.output_dests contains output destinations (arg disambiguates)."""
+        source = """
+        @system pe=1, sm=1
+        #simple val |> {
+            &g <| const, ${val}
+            &g |> @ret
+        }
+        &sink <| add
+        #simple 1 |> &sink
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+        assert len(graph.macro_calls) == 1
+        call = graph.macro_calls[0]
+        assert len(call.output_dests) >= 1
+
+    def test_named_output_dests(self):
+        """Named outputs stored as {"name": ..., "ref": ...} dicts."""
+        source = """
+        @system pe=1, sm=1
+        #dual |> {
+            &g <| pass
+        }
+        &sink <| add
+        #dual |> body=&sink
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+        call = graph.macro_calls[0]
+        assert len(call.output_dests) >= 1
+        output = call.output_dests[0]
+        assert isinstance(output, dict)
+        assert output.get("name") == "body"
+
+
+class TestE33_ExpandRewritesPositionalRet:
+    """E3.3: Expand rewrites @ret edges to concrete destinations (positional)."""
+
+    def test_bare_ret_rewritten(self):
+        """@ret in macro body becomes concrete &sink after expansion."""
+        source = """
+        @system pe=1, sm=1
+        #simple val |> {
+            &g <| const, ${val}
+            &g |> @ret
+        }
+        &sink <| add
+        #simple 1 |> &sink
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        # Find the edge from the expanded &g to &sink
+        ret_edges = [
+            e for e in graph.edges
+            if e.dest == "&sink" and "#simple_0.&g" in e.source
+        ]
+        assert len(ret_edges) == 1
+
+    def test_bare_ret_with_named_output(self):
+        """@ret in macro body resolved via named output (no args needed)."""
+        source = """
+        @system pe=1, sm=1
+        #simple |> {
+            &g <| pass
+            &g |> @ret_out
+        }
+        &sink <| add
+        #simple |> out=&sink
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        ret_edges = [
+            e for e in graph.edges
+            if e.dest == "&sink" and "#simple_0.&g" in e.source
+        ]
+        assert len(ret_edges) == 1
+
+
+class TestE34_ExpandRewritesNamedRet:
+    """E3.4: Expand rewrites @ret_name edges to concrete destinations (named)."""
+
+    def test_named_ret_body(self):
+        """@ret_body in macro resolves to body=&body_sink output."""
+        source = """
+        @system pe=1, sm=1
+        #dual |> {
+            &g <| pass
+            &g |> @ret_body
+            &g |> @ret_exit:R
+        }
+        &body_sink <| add
+        &exit_sink <| add
+        #dual |> body=&body_sink, exit=&exit_sink
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        # Find edges from expanded #dual_0.&g
+        g_edges = [e for e in graph.edges if "#dual_0.&g" in e.source]
+        dests = {e.dest for e in g_edges}
+        assert "&body_sink" in dests
+        assert "&exit_sink" in dests
+
+    def test_mixed_named_outputs(self):
+        """Multiple @ret_name markers all resolve correctly."""
+        source = """
+        @system pe=1, sm=1
+        #triple |> {
+            &a <| pass
+            &b <| pass
+            &c <| pass
+            &a |> @ret_x
+            &b |> @ret_y
+            &c |> @ret_z
+        }
+        &x_sink <| add
+        &y_sink <| add
+        &z_sink <| add
+        #triple |> x=&x_sink, y=&y_sink, z=&z_sink
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        all_dests = {e.dest for e in graph.edges}
+        assert "&x_sink" in all_dests
+        assert "&y_sink" in all_dests
+        assert "&z_sink" in all_dests
+
+
+class TestE35_UnmatchedRetError:
+    """E3.5: Unmatched @ret marker produces MACRO error."""
+
+    def test_unmatched_named_ret(self):
+        """@ret_missing has no matching named output -> MACRO error."""
+        source = """
+        @system pe=1, sm=1
+        #bad |> {
+            &g <| pass
+            &g |> @ret_missing
+        }
+        &sink <| add
+        #bad |> wrong_name=&sink
+        """
+        graph = parse_lower_expand(source)
+        macro_errors = [e for e in graph.errors if e.category == ErrorCategory.MACRO]
+        assert len(macro_errors) >= 1
+        assert "@ret_missing" in macro_errors[0].message
+
+    def test_extra_ret_marker(self):
+        """Macro has @ret_body and @ret_exit but call only provides body output."""
+        source = """
+        @system pe=1, sm=1
+        #dual |> {
+            &a <| pass
+            &b <| pass
+            &a |> @ret_body
+            &b |> @ret_exit
+        }
+        &sink <| add
+        #dual |> body=&sink
+        """
+        graph = parse_lower_expand(source)
+        macro_errors = [e for e in graph.errors if e.category == ErrorCategory.MACRO]
+        assert len(macro_errors) >= 1
+        assert "@ret_exit" in macro_errors[0].message
+
+
+class TestE36_NoOutputWiringError:
+    """E3.6: Macro with @ret but no |> at call site produces MACRO error."""
+
+    def test_ret_without_output_wiring(self):
+        """Macro body uses @ret but call has no |> -> error."""
+        source = """
+        @system pe=1, sm=1
+        #needs_output |> {
+            &g <| pass
+            &g |> @ret
+        }
+        #needs_output
+        """
+        graph = parse_lower_expand(source)
+        macro_errors = [e for e in graph.errors if e.category == ErrorCategory.MACRO]
+        assert len(macro_errors) >= 1
+        assert "output" in macro_errors[0].message.lower() or "@ret" in macro_errors[0].message
+
+
+class TestE37_MultipleRetMarkers:
+    """E3.7: Multiple @ret markers with mixed positional/named outputs."""
+
+    def test_named_and_positional_ret(self):
+        """Macro with @ret_main and @ret_extra resolves to named outputs."""
+        source = """
+        @system pe=1, sm=1
+        #mixed |> {
+            &a <| pass
+            &b <| pass
+            &a |> @ret_main
+            &b |> @ret_extra
+        }
+        &main_sink <| add
+        &extra_sink <| add
+        #mixed |> main=&main_sink, extra=&extra_sink
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        all_dests = {e.dest for e in graph.edges}
+        assert "&main_sink" in all_dests
+        assert "&extra_sink" in all_dests
+
+
+class TestE38_NestedMacroRet:
+    """E3.8: @ret in nested macro invocation."""
+
+    def test_nested_macro_ret_resolves(self):
+        """Inner macro's @ret resolves independently from outer macro's @ret."""
+        source = """
+        @system pe=1, sm=1
+        #inner val |> {
+            &i <| const, ${val}
+            &i |> @ret
+        }
+        #outer val |> {
+            &o <| pass
+            #inner ${val} |> &o
+            &o |> @ret_out
+        }
+        &final_sink <| add
+        #outer 1 |> out=&final_sink
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        # The outer @ret_out should resolve to &final_sink
+        # The inner @ret should resolve to #outer_0.&o
+        outer_ret_edges = [
+            e for e in graph.edges
+            if e.dest == "&final_sink"
+        ]
+        assert len(outer_ret_edges) >= 1

tests/test_qualified_ref_params.py

···
+"""Tests for Enhancement 2: Parameterized placement and port qualifiers (macro-enh.E2.*).
+
+Tests verify:
+- macro-enh.E2.1: Grammar accepts param_ref in placement position
+- macro-enh.E2.2: Grammar accepts param_ref in port position
+- macro-enh.E2.3: Context slot bracket syntax parses
+- macro-enh.E2.4: Expand pass resolves placement ParamRef
+- macro-enh.E2.5: Expand pass resolves port ParamRef
+- macro-enh.E2.6: Expand pass resolves context slot ParamRef
+- macro-enh.E2.7: Full pipeline with placement/port params
+
+Note: Placement qualifiers attach to the LHS qualified_ref in inst_def,
+not to the opcode. So `&n|${pe} <| add` is the correct syntax, not
+`&n <| add|${pe}`.
+"""
+
+from pathlib import Path
+
+from lark import Lark
+
+from asm import assemble, run_pipeline
+from asm.expand import expand
+from asm.lower import lower
+from asm.errors import ErrorCategory
+from asm.ir import (
+    IRNode, ParamRef, PlacementRef, PortRef, CtxSlotRef, CtxSlotRange,
+)
+from cm_inst import ArithOp, Port
+
+
+def _get_parser():
+    grammar_path = Path(__file__).parent.parent / "dfasm.lark"
+    return Lark(
+        grammar_path.read_text(),
+        parser="earley",
+        propagate_positions=True,
+    )
+
+
+def parse_and_lower(source: str):
+    parser = _get_parser()
+    tree = parser.parse(source)
+    return lower(tree)
+
+
+def parse_lower_expand(source: str):
+    graph = parse_and_lower(source)
+    return expand(graph)
+
+
+class TestE21_PlacementParamRef:
+    """E2.1: Grammar accepts param_ref in placement position."""
+
+    def test_placement_param_ref_in_macro_body(self):
+        """&n|${pe} <| add parses and lowers to PlacementRef."""
+        source = """
+        @system pe=1, sm=1
+        #place pe |> {
+            &n|${pe} <| add
+        }
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+        body_nodes = graph.macro_defs[0].body.nodes
+        node = list(body_nodes.values())[0]
+        assert isinstance(node.pe, PlacementRef)
+        assert node.pe.param.param == "pe"
+
+
+class TestE22_PortParamRef:
+    """E2.2: Grammar accepts param_ref in port position."""
+
+    def test_port_param_ref_in_edge(self):
+        """&src |> &dst:${port} parses and lowers to PortRef."""
+        source = """
+        @system pe=1, sm=1
+        #wire port |> {
+            &src <| pass
+            &dst <| add
+            &src |> &dst:${port}
+        }
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+        body_edges = graph.macro_defs[0].body.edges
+        port_ref_edges = [e for e in body_edges if isinstance(e.port, PortRef)]
+        assert len(port_ref_edges) == 1
+        assert port_ref_edges[0].port.param.param == "port"
+
+
+class TestE23_CtxSlotSyntax:
+    """E2.3: Context slot bracket syntax parses."""
+
+    def test_literal_ctx_slot(self):
+        """&node[2] parses — literal context slot in bracket syntax."""
+        source = """
+        @system pe=1, sm=1
+        #slot_macro |> {
+            &n[2] <| add
+        }
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+        body_nodes = graph.macro_defs[0].body.nodes
+        node = list(body_nodes.values())[0]
+        assert isinstance(node.ctx_slot, CtxSlotRange)
+        assert node.ctx_slot.start == 2
+        assert node.ctx_slot.end == 2
+
+    def test_full_qualifier_chain(self):
+        """&node|pe0[2]:L parses — placement + ctx_slot + port."""
+        source = """
+        @system pe=1, sm=1
+        &n|pe0[2]:L <| add
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+        node = list(graph.nodes.values())[0]
+        assert node.pe == 0
+        assert isinstance(node.ctx_slot, CtxSlotRange)
+        assert node.ctx_slot.start == 2
+        assert node.ctx_slot.end == 2
+
+    def test_parameterized_ctx_slot(self):
+        """&node[${ctx}] parses — parameterized context slot."""
+        source = """
+        @system pe=1, sm=1
+        #ctx_macro ctx |> {
+            &n[${ctx}] <| add
+        }
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+        body_nodes = graph.macro_defs[0].body.nodes
+        node = list(body_nodes.values())[0]
+        assert isinstance(node.ctx_slot, CtxSlotRef)
+        assert node.ctx_slot.param.param == "ctx"
+
+    def test_ctx_slot_range(self):
+        """&node[0..4] parses — range reservation."""
+        source = """
+        @system pe=1, sm=1
+        &n[0..4] <| add
+        """
+        graph = parse_and_lower(source)
+        assert not graph.errors
+        node = list(graph.nodes.values())[0]
+        assert isinstance(node.ctx_slot, CtxSlotRange)
+        assert node.ctx_slot.start == 0
+        assert node.ctx_slot.end == 4
+
+
+class TestE24_ExpandResolvesPlacement:
+    """E2.4: Expand pass resolves placement ParamRef."""
+
+    def test_resolve_pe0(self):
+        """Placement param 'pe0' resolves to PE 0."""
+        source = """
+        @system pe=2, sm=1
+        #place pe |> {
+            &n|${pe} <| add
+        }
+        #place pe0
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        node = list(graph.nodes.values())[0]
+        assert node.pe == 0
+
+    def test_resolve_pe1(self):
+        """Placement param 'pe1' resolves to PE 1."""
+        source = """
+        @system pe=2, sm=1
+        #place pe |> {
+            &n|${pe} <| add
+        }
+        #place pe1
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        node = list(graph.nodes.values())[0]
+        assert node.pe == 1
+
+    def test_invalid_placement_error(self):
+        """Invalid placement value produces MACRO error."""
+        source = """
+        @system pe=1, sm=1
+        #place pe |> {
+            &n|${pe} <| add
+        }
+        #place &banana
+        """
+        graph = parse_lower_expand(source)
+        macro_errors = [e for e in graph.errors if e.category == ErrorCategory.MACRO]
+        assert len(macro_errors) >= 1
+        assert "placement" in macro_errors[0].message.lower()
+
+
+class TestE25_ExpandResolvesPort:
+    """E2.5: Expand pass resolves port ParamRef."""
+
+    def test_resolve_port_L(self):
+        """Port param 'L' resolves to Port.L."""
+        source = """
+        @system pe=1, sm=1
+        #wire port |> {
+            &src <| pass
+            &dst <| add
+            &src |> &dst:${port}
+        }
+        #wire L
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        edges = [e for e in graph.edges if e.dest.endswith("&dst")]
+        assert len(edges) >= 1
+        assert edges[0].port == Port.L
+
+    def test_resolve_port_R(self):
+        """Port param 'R' resolves to Port.R."""
+        source = """
+        @system pe=1, sm=1
+        #wire port |> {
+            &src <| pass
+            &dst <| add
+            &src |> &dst:${port}
+        }
+        #wire R
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        edges = [e for e in graph.edges if e.dest.endswith("&dst")]
+        assert len(edges) >= 1
+        assert edges[0].port == Port.R
+
+
+class TestE26_ExpandResolvesCtxSlot:
+    """E2.6: Expand pass resolves context slot ParamRef."""
+
+    def test_resolve_ctx_slot_int(self):
+        """Ctx slot param resolves to CtxSlotRange."""
+        source = """
+        @system pe=1, sm=1
+        #ctx_macro ctx |> {
+            &n[${ctx}] <| add
+        }
+        #ctx_macro 2
+        """
+        graph = parse_lower_expand(source)
+        assert not graph.errors
+        node = list(graph.nodes.values())[0]
+        assert isinstance(node.ctx_slot, CtxSlotRange)
+        assert node.ctx_slot.start == 2
+        assert node.ctx_slot.end == 2
+
+    def test_non_numeric_ctx_slot_error(self):
+        """Non-numeric ctx slot value produces MACRO error."""
+        source = """
+        @system pe=1, sm=1
+        #ctx_macro ctx |> {
+            &n[${ctx}] <| add
+        }
+        #ctx_macro &banana
+        """
+        graph = parse_lower_expand(source)
+        macro_errors = [e for e in graph.errors if e.category == ErrorCategory.MACRO]
+        assert len(macro_errors) >= 1
+        assert "ctx_slot" in macro_errors[0].message.lower()
+
+
+class TestE27_FullPipeline:
+    """E2.7: Full pipeline with placement/port params."""
+
+    def test_full_pipeline_placement_param(self):
+        """Placement-parameterized macro assembles; node on correct PE."""
+        source = """
+        @system pe=2, sm=1
+        #place pe |> {
+            &n|${pe} <| add
+        }
+        &seed <| const, 5
+        #place pe1
+        &seed |> #place_0.&n:L
+        &seed |> #place_0.&n:R
+        """
+        graph = run_pipeline(source)
+        assert not graph.errors
+        placed_node = graph.nodes["#place_0.&n"]
+        assert placed_node.pe == 1
+
+    def test_full_pipeline_port_param(self):
+        """Port-parameterized macro assembles; edge targets correct port."""
+        source = """
+        @system pe=1, sm=1
+        #wire port |> {
+            &src <| pass
+            &dst <| add
+            &src |> &dst:${port}
+        }
+        &seed <| const, 5
+        #wire L
+        &seed |> #wire_0.&src
+        &seed |> #wire_0.&dst:R
+        """
+        result = assemble(source)
+        assert result is not None