updating docs

.gitignore

···
 # ExoMonad - track config, ignore runtime artifacts
 .exo/*
 !.exo/config.toml
+.deciduous

asm/builtins.py

···
 These macros are automatically available in all dfasm programs.
 The BUILTIN_MACROS string is prepended to user source before parsing.
 
-Note: The current grammar does not support referencing macro parameters
-in edge endpoints (bare identifiers aren't valid qualified_ref). Therefore
-all built-in macros are self-contained: they define their own internal
-topology and expose well-known internal node names for the user to wire to.
+Macro parameters can appear in edge endpoints via ${param} syntax.
+The expand pass handles parameter refs in source/dest positions,
+correctly skipping scope qualification for external references.
 
-For example, #loop_counted expands to nodes named &counter (add), &compare
-(brgt), and &inc (inc) with the internal feedback loop pre-wired. The user
-wires init/limit/body/exit externally after invoking the macro.
+The opcode position cannot be parameterized (grammar constraint:
+opcode is a keyword terminal). Per-opcode variants are provided
+where needed (e.g., reduce_add_N).
 """
 
 BUILTIN_MACROS = """\
···
 }
 
 ; --- Binary reduction trees (per-arity, per-opcode variants) ---
-; Note: The macro expansion system's ParamRef only handles const fields and
-; edge endpoints, not opcode positions. Generic opcode parameterization
-; (e.g., passing 'add' as a macro argument) is a future enhancement.
-; For now, per-opcode variants are provided.
+; Note: The opcode position cannot be parameterized (grammar constraint).
+; Per-opcode variants are provided instead.
 #reduce_add_2 |> {
     &r <| add
 }

design-notes/alu-and-output-design.md

···
 ```
 EQ       A == B. Result: 0x01 if true, 0x00 if false.
 LT       A < B (signed). Result: 0x01 / 0x00.
+LTE      A ≤ B (signed). Result: 0x01 / 0x00.
 GT       A > B (signed). Result: 0x01 / 0x00.
-ULT      A < B (unsigned). Result: 0x01 / 0x00.
-UGT      A > B (unsigned). Result: 0x01 / 0x00.
+GTE      A ≥ B (signed). Result: 0x01 / 0x00.
 ```
 
-All comparisons produce an 8-bit result token with value 0x00 or 0x01.
+All comparisons produce a result token with value 0x0000 or 0x0001.
 This token is data — it enters the network and arrives at a downstream
 SWITCH or GATE instruction as a normal operand. The bool_out signal
 (internal to the PE, derived from the comparator output) is also available
 to the output formatter for same-instruction conditional routing, but the
 primary mechanism is to emit the boolean as a data token.
 
-Signed vs unsigned distinction: the comparator hardware (74LS85) natively
-does unsigned magnitude comparison. Signed comparison can be derived by
-XORing the sign bits of both inputs before feeding the comparator, or by
-using a dedicated signed-compare path. The opcode decoder selects which
-path via control lines.
+> **⚠ Note:** The emulator operates with 16-bit data throughout, so
+> comparison results are 16-bit values (0x0000 or 0x0001). The 8-bit
+> hardware datapath sketch below produces 8-bit results (0x00 or 0x01).
+> Both representations are semantically identical — only bit 0 carries
+> information.
+
+All comparisons interpret operands as signed 2's complement. The
+comparator hardware (74LS85) natively does unsigned magnitude comparison.
+Signed comparison is derived by XORing the sign bits of both inputs
+before feeding the comparator. LTE and GTE are synthesised from the
+existing comparator outputs (LTE = LT OR EQ, GTE = GT OR EQ) via
+the decoder EEPROM's control signal selection.
 
 ### Routing (dyadic)
 
+**Branch operations** (BREQ, BRGT, BRGE, BROF): compare L and R
+operands, then route the data to the taken or not-taken destination.
+Both destinations receive the data value; the branch condition selects
+which destination gets it first (taken) vs second (not-taken).
+
+**Switch operations** (SWEQ, SWGT, SWGE, SWOF): compare L and R
+operands, then route data to the taken side and a trigger token
+(value 0) to the not-taken side. See the Output Formatter section
+for the not-taken trigger semantics (FREE vs NOOP).
+
 ```
-SWITCH   Conditional route. Takes data (port L) and boolean (port R).
-         If bool == true:  emit data to dest1, emit trigger to dest2.
-         If bool == false: emit data to dest2, emit trigger to dest1.
-         See Output Formatter section for trigger token semantics.
-
 GATE     Conditional pass/suppress. Takes data (port L) and boolean (port R).
          If bool == true:  emit data to dest1 (and optionally dest2).
          If bool == false: emit nothing. Both tokens consumed silently.
+SEL      Select between inputs based on a condition.
+MRGE     Merge two token streams (non-deterministic).
 ```
 
-SWITCH always emits exactly 2 tokens: one data token to the taken side,
-one inline monadic trigger to the not-taken side. See the Output Formatter
-section for the not-taken trigger semantics (FREE vs NOOP).
+Branch and switch ops always emit exactly 2 tokens: one data token to
+the taken side, one token to the not-taken side (data for branch, inline
+monadic trigger for switch). See the Output Formatter section for details.
 
 GATE emits 0 or 1-2 tokens depending on the boolean. When suppressed
 (bool false), both input operands are consumed with no output — the
···
 | ----------- | -------- | ------- | -------------- | ------------------------ |
 | 00000       | ADD      | dyadic  | DUAL or SINGLE | A + B                    |
 | 00001       | SUB      | dyadic  | DUAL or SINGLE | A - B                    |
-| 00000       | INC      | monadic | DUAL or SINGLE | A + 1 (imm const)        |
-| 00001       | DEC      | monadic | DUAL or SINGLE | A - 1  (imm const)       |
+| 00010       | INC      | monadic | DUAL or SINGLE | A + 1 (imm const)        |
+| 00011       | DEC      | monadic | DUAL or SINGLE | A - 1  (imm const)       |
 | 00100       | AND      | dyadic  | DUAL or SINGLE | A & B                    |
 | 00101       | OR       | dyadic  | DUAL or SINGLE | A \| B                   |
 | 00110       | XOR      | dyadic  | DUAL or SINGLE | A ^ B                    |
···
 | 01010       | ASR      | monadic | DUAL or SINGLE | A >> N (imm, arithmetic) |
 | 01011       | EQ       | dyadic  | DUAL or SINGLE | A == B → bool            |
 | 01100       | LT       | dyadic  | DUAL or SINGLE | A < B signed → bool      |
-| 01101       | GT       | dyadic  | DUAL or SINGLE | A > B signed → bool      |
-| 01110       | ULT      | dyadic  | DUAL or SINGLE | A < B unsigned → bool    |
-| 01111       | UGT      | dyadic  | DUAL or SINGLE | A > B unsigned → bool    |
-| 10000       | SWITCH   | dyadic  | SWITCH         | route data by bool       |
-| 10001       | GATE     | dyadic  | GATE           | pass or suppress by bool |
-| 10010       | PASS     | monadic | DUAL or SINGLE | identity                 |
-| 10011       | CONST    | monadic | DUAL or SINGLE | output = immediate       |
-| 10100       | FREE_CTX | monadic | SUPPRESS       | deallocate slot          |
-| 10101-11111 | —        | —       | —              | reserved for expansion   |
+| 01101       | LTE      | dyadic  | DUAL or SINGLE | A ≤ B signed → bool      |
+| 01110       | GT       | dyadic  | DUAL or SINGLE | A > B signed → bool      |
+| 01111       | GTE      | dyadic  | DUAL or SINGLE | A ≥ B signed → bool      |
+| 10000       | BREQ     | dyadic  | SWITCH         | branch if L == R         |
+| 10001       | BRGT     | dyadic  | SWITCH         | branch if L > R          |
+| 10010       | BRGE     | dyadic  | SWITCH         | branch if L ≥ R          |
+| 10011       | BROF     | dyadic  | SWITCH         | branch on overflow       |
+| 10100       | SWEQ     | dyadic  | SWITCH         | switch if L == R         |
+| 10101       | SWGT     | dyadic  | SWITCH         | switch if L > R          |
+| 10110       | SWGE     | dyadic  | SWITCH         | switch if L ≥ R          |
+| 10111       | SWOF     | dyadic  | SWITCH         | switch on overflow       |
+| 11000       | GATE     | dyadic  | GATE           | pass or suppress by bool |
+| 11001       | SEL      | dyadic  | DUAL or SINGLE | select between inputs    |
+| 11010       | MRGE     | dyadic  | DUAL or SINGLE | merge two token streams  |
+| 11011       | PASS     | monadic | DUAL or SINGLE | identity                 |
+| 11100       | CONST    | monadic | DUAL or SINGLE | output = immediate       |
+| 11101       | FREE_CTX | monadic | SUPPRESS       | deallocate slot          |
+| 11110-11111 | —        | —       | —              | reserved for expansion   |
+
+> **⚠ Preliminary:** The binary opcode encodings above are a draft layout,
+> not a committed hardware encoding. The Python emulator and assembler use
+> IntEnum ordinal values that do NOT correspond to these bit patterns.
+> Final hardware encoding will be determined during physical build.
 
 The output mode column indicates the default. DUAL vs SINGLE is
 controlled by a flag in the IRAM instruction word (has_dest2), not by
 the opcode — any arithmetic/logic/compare instruction can fan out to
 two destinations or one.
 
-**Reserved opcode space (11 slots):** future candidates include hardware
-multiply, predicate store read/write, triadic operations, SM-directed
-operations, debug/trace instructions, and CALL/RETURN linkage primitives.
+**Branch vs Switch:** Branch operations (BR*) compare their two operands
+and route the data value to the taken or not-taken destination. Switch
+operations (SW*) are similar but emit a trigger token (value 0) to the
+not-taken side instead of the data value. See the Output Formatter section
+for the not-taken trigger semantics.
+
+**Reserved opcode space (2 slots):** future candidates include hardware
+multiply, predicate store read/write, and debug/trace instructions.
+
+### SM Instruction Dispatch
+
+The operation set above covers CM compute instructions (IRAM half 0,
+bit 15 = 0). When IRAM half 0 bit 15 = 1, the PE dispatches an SM
+operation instead of an ALU computation. In this mode:
+
+- The ALU is bypassed entirely
+- Stage 4 constructs an `SMToken` from the SM opcode, operand data,
+  and IRAM fields (SM_id, const address, return routing)
+- Stage 5 emits the SMToken to the target SM via the SM bus
+
+The SM instruction encoding uses the same IRAM word width but with a
+different field layout. See `iram-and-function-calls.md` for the SM
+IRAM word format and operation table.
 
 ---
 
···
 ```
 result:8          computed data value (or passthrough for SWITCH/PASS)
 bool_out:1        boolean/comparison result:
-                    - from comparator for EQ/LT/GT/ULT/UGT
-                    - from data_R bit 0 for SWITCH/GATE (boolean input)
+                    - from comparator for EQ/LT/LTE/GT/GTE
+                    - from comparator for BR*/SW* (inline comparison)
+                    - from data_R bit 0 for GATE (boolean input)
                     - undefined for arithmetic/logic ops
 ```
 

design-notes/architecture-overview.md

···
    much of SM00's address space is mapped to IO vs general-purpose storage?
    SM00 is special only at boot for now; further specialisation deferred
    until profiling shows the standard opcodes are insufficient.
-5. ~~**Compiler / assembler**~~ — **Partially Resolved.** The `asm/` package
-   implements a 6-stage assembler pipeline (parse → lower → resolve →
-   place → allocate → codegen). Produces PEConfig/SMConfig + seed tokens
-   or a bootstrap token stream. See `assembler-architecture.md` for architecture.
-   Grammar is `dfasm.lark` (Lark/Earley parser). Auto-placement via
-   greedy bin-packing with locality heuristic. Remaining work: further
-   optimisation passes, macro expansion, binary output.
+5. ~~**Compiler / assembler**~~ — **Resolved.** The `asm/` package
+   implements a 7-stage assembler pipeline (parse → lower → expand →
+   resolve → place → allocate → codegen). Produces PEConfig/SMConfig +
+   seed tokens or a bootstrap token stream. The expand pass handles
+   macro expansion (`#macro` definitions with `${param}` substitution,
+   variadic repetition, constant arithmetic) and function call wiring
+   (cross-context edges, trampoline nodes, context teardown). Built-in
+   macros for common patterns (counted loops, permit injection, reduction
+   trees) are automatically available. See `assembler-architecture.md`
+   for architecture. Grammar is `dfasm.lark` (Lark/Earley parser).
+   Auto-placement via greedy bin-packing with locality heuristic.
+   Remaining work: optimisation passes, binary output.
 7. **Mode B clock ratio** — exactly 2x, or design for arbitrary integer
    ratios? See `bus-architecture-and-width-decoupling.md`.
 8. **Instruction residency** — small IRAM per PE means programs larger

design-notes/assembler-architecture.md

···
 
 ## Pipeline Overview
 
-Six stages, each a pure function from `IRGraph → IRGraph` (or `IRGraph → output`). 
+Seven stages, each a pure function from `IRGraph → IRGraph` (or `IRGraph → output`).
 
 The pipeline is:
 
···
   Parse       Lark/Earley parser, dfasm.lark grammar
     │          → concrete syntax tree (CST)
     ▼
-  Lower       CST → IRGraph (nodes, edges, regions, data defs)
+  Lower       CST → IRGraph (nodes, edges, regions, data defs,
+    │            macro defs, macro calls, call sites)
     │          → name qualification, scope creation
+    ▼
+  Expand      macro expansion + function call wiring
+    │          → clone macro bodies, substitute params, evaluate
+    │            const expressions, wire cross-context call edges
     ▼
   Resolve     validate edge endpoints, detect scope violations
     │          → "did you mean" suggestions via Levenshtein distance
···
     │          → dyadic-first layout, per-PE context scoping
     ▼
   Codegen     emit PEConfig/SMConfig + seeds (direct mode)
-              or SM init → ROUTE_SET → LOAD_INST → seeds (token mode)
+              or SM init → IRAM writes → seeds (token mode)
 ```
 
 Each pass returns a new `IRGraph`. Graphs are never mutated after construction, each pass produces a fresh copy with the new information filled in. Errors accumulate in `IRGraph.errors` rather than failing fast, so the assembler reports all problems in a single pass rather than forcing the programmer to fix them one at a time.
···
 
 | Type | Fields | Purpose |
 |------|--------|---------|
-| `IRNode` | name, opcode, dest_l, dest_r, const, pe, iram_offset, ctx, loc, args, sm_id | Single instruction in the dataflow graph |
-| `IREdge` | source, dest, port, source_port, loc | Connection between two nodes |
-| `IRGraph` | nodes, edges, regions, data_defs, system, errors | Complete program representation |
-| `IRRegion` | tag, kind, body (IRGraph), loc | Nested scope (FUNCTION or LOCATION) |
+| `IRNode` | name, opcode, dest_l, dest_r, const, pe, iram_offset, ctx, loc, args, sm_id, seed | Single instruction in the dataflow graph. `name` and `const` can be `ParamRef` or `ConstExpr` in macro templates. |
+| `IREdge` | source, dest, port, source_port, port_explicit, ctx_override, loc | Connection between two nodes. `ctx_override` marks cross-context call edges (ctx_mode=01). `port_explicit` tracks whether port was user-specified. |
+| `IRGraph` | nodes, edges, regions, data_defs, system, errors, macro_defs, macro_calls, raw_call_sites, call_sites, builtin_line_offset | Complete program representation. Macro-related fields are populated by lower and consumed by expand. |
+| `IRRegion` | tag, kind, body (IRGraph), loc | Nested scope (FUNCTION, LOCATION, or MACRO) |
 | `IRDataDef` | name, sm_id, cell_addr, value, loc | SM cell initialisation |
-| `SystemConfig` | pe_count, sm_count, iram_capacity, ctx_slots, loc | Hardware configuration from `@system` pragma |
+| `SystemConfig` | pe_count, sm_count, iram_capacity, ctx_slots, loc | Hardware configuration from `@system` pragma (defaults: iram=128, ctx=16) |
+| `MacroDef` | name, params, body (IRGraph), repetition_blocks, loc | Macro definition: formal parameters + template body with `ParamRef` placeholders |
+| `MacroParam` | name, variadic | Formal macro parameter. `variadic=True` collects remaining args. |
+| `ParamRef` | param, prefix, suffix | Placeholder for a macro parameter. Supports token pasting via prefix/suffix. |
+| `ConstExpr` | expression, params, loc | Compile-time arithmetic expression (e.g., `base + _idx + 1`) |
+| `IRRepetitionBlock` | body (IRGraph), variadic_param, loc | Repetition block (`@each`) expanded once per variadic argument |
+| `IRMacroCall` | name, positional_args, named_args, loc | Macro invocation, consumed by expand pass |
+| `CallSiteResult` | func_name, input_args, output_dests, loc | Intermediate call data from lower, consumed by expand |
+| `CallSite` | func_name, call_id, input_edges, trampoline_nodes, free_ctx_nodes, loc | Processed call site metadata for per-call-site context allocation |
 
 ### Destination Representation
 
···
 - `strong_edge` / `weak_edge` -> anonymous `IRNode` + input/output
   `IREdge` set (creates a `CompositeResult`)
 - `func_def` → `IRRegion(kind=FUNCTION)` with a nested `IRGraph` body
+- `macro_def` → `MacroDef` with `ParamRef` placeholders in body template
+- `macro_call` → `IRMacroCall` with positional/named arguments
+- `call_stmt` → `CallSiteResult` with function name, input args, output dests
 - `location_dir` -> `IRRegion(kind=LOCATION)`: subsequent statements
   are collected into its body during post-processing
 - `data_def` -> `IRDataDef` with SM placement and cell address
···
 
 **Opcode mapping (`opcodes.py`):**
 
-Mnemonic strings from the grammar are mapped to `ALUOp`, `MemOp`, or `CfgOp` enum values via `MNEMONIC_TO_OP`. A complication: Python `IntEnum` sub-classes can share numeric values across types (`ArithOp.ADD == 0 == MemOp.READ`), so the reverse mapping and set membership tests use type-aware collections (`TypeAwareOpToMnemonicDict`, `TypeAwareMonadicOpsSet`) that key on `(type, value)` tuples internally.
+Mnemonic strings from the grammar are mapped to `ALUOp` or `MemOp` enum values via `MNEMONIC_TO_OP`. A complication: Python `IntEnum` sub-classes can share numeric values across types (`ArithOp.ADD == 0 == MemOp.READ`), so the reverse mapping and set membership tests use type-aware collections (`TypeAwareOpToMnemonicDict`, `TypeAwareMonadicOpsSet`) that key on `(type, value)` tuples internally.
+
+### Expand (`expand.py`)
+
+Processes macro definitions, macro invocations, and function call sites. This pass bridges the gap between the template-based IR from lowering and the concrete IR that resolve expects.
+
+**Macro expansion:**
+
+1. Collect all `MacroDef` entries from the graph (including built-in macros prepended to every program)
+2. For each `IRMacroCall`, clone the macro's body template
+3. Substitute `ParamRef` placeholders with actual argument values
+4. Evaluate `ConstExpr` arithmetic expressions (supports `+`, `-`, `*` on integers and `_idx`)
+5. Expand `IRRepetitionBlock` entries once per variadic argument, binding `_idx` to the iteration index
+6. Qualify expanded names with scope prefixes: `#macroname_N.&label` for top-level, `$func.#macro_N.&label` inside functions
+
+**Function call wiring:**
+
+1. For each `CallSiteResult` from lowering, create a `CallSite` with a unique `call_id`
+2. Generate trampoline `PASS` nodes for return routing
+3. Create `IREdge` entries with `ctx_override=True` for cross-context argument passing (becomes `ctx_mode=01` in codegen)
+4. Generate `FREE_CTX` nodes for context teardown on call completion
+5. Wire `@ret` / `@ret_name` synthetic nodes for return paths
+
+**Post-conditions:**
+
+After expansion, the IR contains only concrete `IRNode`/`IREdge` entries. No `ParamRef` placeholders, no `MacroDef` regions, no `IRMacroCall` entries remain.
 
 ### Resolve (`resolve.py`)
 
···
 
 **System config inference:**
 
-If no `@system` pragma is provided, the placer infers `pe_count` from the highest explicit PE ID and uses defaults for IRAM capacity (64) and context slots (4).
+If no `@system` pragma is provided, the placer infers `pe_count` from the highest explicit PE ID and uses defaults for IRAM capacity (128) and context slots (16).
 
 ### Allocate (`allocate.py`)
 
···
 | RESOURCE | allocate | IRAM overflow, context slot overflow, missing SM target |
 | ARITY | lower | wrong operand count |
 | PORT | allocate | port conflicts, missing destinations |
+| MACRO | expand | undefined macro, wrong argument count, expansion failure |
+| CALL | expand | undefined function, missing return path, call wiring error |
 | UNREACHABLE | (future) | unused nodes |
 | VALUE | lower | out-of-range literals |
 
···
 ## Future Work
 
 - **Optimization passes** between resolve and place: dead node elimination, constant folding, sub-graph deduplication
-- **Macro expansion**: the grammar already supports `#macro` syntax; the expansion pass is not yet implemented
 - **Wider placement heuristics**: graph partitioning, min-cut algorithms, or profile-guided placement for larger programs
 - **Incremental reassembly**: modify part of the graph and re-run only affected passes
 - **Hardware encoding pass**: translate ALUInst/SMInst to bit-level instruction words for actual IRAM loading
+- **Conditional macro expansion**: the current macro system supports variadic repetition, constant arithmetic, and nested macro invocation (depth limit 32), but not conditionals within macros

design-notes/dfasm-primer.md

···
 
 ### Names and Sigils
 
-dfasm uses three sigil-prefixed naming conventions:
+dfasm uses four sigil-prefixed naming conventions:
+
+| Sigil    | Scope                             | Use                               |
+| -------- | --------------------------------- | --------------------------------- |
+| `@name`  | Global (top-level)                | Node references, data definitions |
+| `&name`  | Local (within enclosing function) | Labels for instructions           |
+| `$name`  | Global                            | Function / subgraph definitions   |
+| `#name`  | Global                            | Macro definitions and invocations |
 
-| Sigil   | Scope                             | Use                               |
-| ------- | --------------------------------- | --------------------------------- |
-| `@name` | Global (top-level)                | Node references, data definitions |
-| `&name` | Local (within enclosing function) | Labels for instructions           |
-| `$name` | Global                            | Function / subgraph definitions   |
+Additionally, `${name}` is used within macro bodies for parameter substitution (see Macros section).
 
 Names are composed of `[a-zA-Z_][a-zA-Z0-9_]*`.
 
···
 | --------- | -------- | ------- | ---------------------------------------- |
 | `pe`      | yes      | —       | Number of processing elements            |
 | `sm`      | yes      | —       | Number of structure memory modules       |
-| `iram`    | no       | 64      | IRAM capacity per PE (instruction slots) |
-| `ctx`     | no       | 4       | Context slots per PE                     |
+| `iram`    | no       | 128     | IRAM capacity per PE (instruction slots) |
+| `ctx`     | no       | 16      | Context slots per PE                     |
 
 At most one `@system` pragma per program.
 
···
 
 These operations route tokens based on a comparison result. They are all dyadic — they compare L and R, then route accordingly.
 
-**Branch operations** (`br*`): emit data to `dest_l` (taken) or `dest_r` (not taken) based on comparison:
+**Branch operations** (`br*`): compare L and R, then emit data to `dest_l` (taken) or `dest_r` (not taken). Both outputs carry the data value; the branch condition selects the destination:
 
 | Mnemonic | Condition  |
 | -------- | ---------- |
···
 | `brgt`   | L > R      |
 | `brge`   | L ≥ R      |
 | `brof`   | overflow   |
-| `brty`   | type match |
 
-> NOTE: 
->`br*` ops use predicate register and internal-to-PE loopback route if supported by hardware.
+> NOTE:
+> `br*` ops use predicate register and internal-to-PE loopback route if supported by hardware. Future strongly-connected block execution will change the behaviour of `br*` ops to support pseudo-sequential execution within a PE.
 
-**Switch operations** (`sw*`): like branch, but when the condition is true, data goes to `dest_l` and a trigger token (value 0) goes to `dest_r`. 
+**Switch operations** (`sw*`): like branch, but when the condition is true, data goes to `dest_l` and a trigger token (value 0) goes to `dest_r`.
 When false, trigger goes to `dest_l` and data goes to `dest_r`:
 
 | Mnemonic | Condition |
 |----------|-----------|
-| `sweq` | L == R |
-| `swgt` | L > R |
-| `swge` | L ≥ R |
-| `swof` | overflow |
-| `swty` | type match |
+| `sweq`   | L == R    |
+| `swgt`   | L > R     |
+| `swge`   | L ≥ R     |
+| `swof`   | overflow  |
 
 **Other routing:**
 
-| Mnemonic | Arity  | Description                                              |
-| -------- | ------ | -------------------------------------------------------- |
-| `gate`   | dyadic | pass data through if bool_out is true, suppress if false |
-| `sel`    | dyadic | select between inputs                                    |
-| `merge`  | dyadic | merge two inputs                                         |
+| Mnemonic | Arity  | Description                                                         |
+| -------- | ------ | ------------------------------------------------------------------- |
+| `gate`   | dyadic | pass data through if bool_out is true, suppress if false            |
+| `sel`    | dyadic | select between L and R based on a condition                         |
+| `merge`  | dyadic | merge two token streams (non-deterministic: fires on either input)  |
 
 ### Data
 
···
 | `pass`     | monadic | pass data through unchanged             |
 | `const`    | monadic | emit constant value (from const field)  |
 | `free_ctx` | monadic | deallocate context slot, no data output |
-| `call`     | dyadic  |                                         |
 
-- `free_ctx` in particular is a special token used to handle function body and loop exits.
+- `free_ctx` is a special instruction used to handle function body and loop exits. It frees the context slot so it can be reused.
 
 ### Structure Memory
 
-| Mnemonic | Arity             | Description                                                                                                           |
-| -------- | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `read`   | monadic           | read from SM cell (const = cell address)                                                                              |
-| `write`  | context-dependent | write to SM cell — monadic if const is set (cell addr from const), dyadic if const is None (cell addr from L operand) |
-| `clear`  | monadic           | clear SM cell                                                                                                         |
-| `alloc`  | monadic           | allocate SM cell                                                                                                      |
-| `free`   | monadic           | free SM cell                                                                                                          |
-| `rd_inc` | monadic           | atomic read-and-increment                                                                                             |
-| `rd_dec` | monadic           | atomic read-and-decrement                                                                                             |
-| `cmp_sw` | monadic           | compare-and-swap                                                                                                      |
-### Configuration / System
+| Mnemonic    | Arity             | Description                                                                                                           |
+| ----------- | ----------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `read`      | monadic           | read from SM cell (const = cell address)                                                                              |
+| `write`     | context-dependent | write to SM cell — monadic if const is set (cell addr from const), dyadic if const is None (cell addr from L operand) |
+| `clear`     | monadic           | clear SM cell (reset to EMPTY state)                                                                                  |
+| `alloc`     | monadic           | allocate SM cell                                                                                                      |
+| `free`      | monadic           | free SM cell                                                                                                          |
+| `rd_inc`    | monadic           | atomic read-and-increment                                                                                             |
+| `rd_dec`    | monadic           | atomic read-and-decrement                                                                                             |
+| `cmp_sw`    | dyadic            | compare-and-swap (L = expected, R = new value)                                                                        |
+| `exec`      | monadic           | trigger EXEC on SM (inject tokens from T0 storage into network)                                                       |
+| `raw_read`  | monadic           | raw read from T0 storage (no I-structure semantics)                                                                   |
+| `set_page`  | monadic           | set SM page register (T0 operation)                                                                                   |
+| `write_imm` | monadic           | immediate write to SM cell (T0 operation)                                                                             |
+| `ext`       | monadic           | extended SM operation                                                                                                 |
 
-| Mnemonic | Description |
-|----------|-------------|
-| `load_inst` | load instruction into PE IRAM |
-| `route_set` | configure PE routing table |
-| `ior` | I/O read |
-| `iow` | I/O write |
-| `iorw` | I/O read-write |
+Note: `free` (SM cell deallocation) and `free_ctx` (PE context slot deallocation) are distinct operations targeting different resources.
 
-These are rarely written by hand — `load_inst` and `route_set` are generated by the assembler's token stream mode during bootstrap.
+SM opcodes use a variable-width bus encoding. See `sm-design.md` for the full opcode table and encoding tiers.
 
 ## Literals
 
···
 
 **Direct mode** produces `PEConfig` objects (IRAM contents, route restrictions, context slot count) and `SMConfig` objects (initial cell values), plus seed tokens. This is the fast path for the emulator. Configuration is applied directly.
 
-**Token stream mode** produces a bootstrap sequence: SM initialization writes, route configuration tokens, instruction load tokens, then seed tokens. This mirrors the bootstrap process, loading the code stored at the reset vector.
+**Token stream mode** produces a bootstrap sequence: SM initialization writes, IRAM write tokens, then seed tokens. This mirrors the bootstrap process, loading the code stored at the reset vector.
+
+## Macros
+
+Macros define reusable template subgraphs that are expanded inline at their call sites. The macro system supports parameterisation, variadic arguments, repetition blocks, constant arithmetic, and token pasting.
+
+### Macro Definition
+
+```dfasm
+#macro_name param1, param2, *variadic_param |> {
+    ; body — instructions and edges using ${param} substitution
+    &node <| add ${param1}
+    ${param1} |> &node:L
+    ${param2} |> &node:R
+}
+```
+
+- Macro names use the `#` sigil
+- Parameters are declared before `|>`
+- Variadic parameters are prefixed with `*` and collect remaining arguments
+- The body contains standard dfasm statements with `${param}` placeholders
+
+### Parameter Substitution
+
+Within a macro body, `${name}` references are replaced with the actual argument values during expansion:
+
+```dfasm
+#add_const val |> {
+    &adder <| add
+    &c <| const, ${val}
+    &c |> &adder:R
+}
+```
+
+**Token pasting:** Parameters can be combined with literal text to synthesise unique names. The `${param}` reference within a label name produces a label that incorporates the argument value:
+
+```dfasm
+#make_pair name |> {
+    &${name}_left <| pass
+    &${name}_right <| pass
+}
+```
+
+### Repetition Blocks
+
+The `$(  ),*` syntax expands its body once per element of a variadic parameter. Within a repetition block, `${_idx}` provides the current iteration index (0-based):
+
+```dfasm
+#fan_out *targets |> {
+    &src <| pass
+    $(
+        &src |> ${targets}
+    ),*
+}
+```
+
+### Constant Arithmetic
+
+Macro const fields support compile-time arithmetic with `+`, `-`, `*` on integer values and parameters:
+
+```dfasm
+#indexed_read base, *cells |> {
+    $(
+        &r${_idx} <| read, ${base} + ${_idx}
+    ),*
+}
+```
+
+### Macro Invocation
+
+Macros are invoked as standalone statements:
+
+```dfasm
+#loop_counted
+#fan_out &a:L, &b:R, &c:L
+#indexed_read 10, &dest1, &dest2, &dest3
+```
+
+Arguments can be positional or named:
+
+```dfasm
+#make_pair name=foo
+```
+
+### Scoping
+
+Expanded macro names are automatically qualified to prevent collisions between multiple invocations of the same macro:
+
+- Top-level invocation: `#macro_N.&label` (N is the invocation counter)
+- Inside a function: `$func.#macro_N.&label`
+
+### Built-in Macros
+
+The following macros are automatically available in all programs:
+
+| Macro | Purpose |
+|-------|---------|
+| `#loop_counted` | Counted loop: counter + compare + increment feedback loop |
+| `#loop_while` | Condition-tested loop: gate node for predicate-driven iteration |
+| `#permit_inject_N` | Inject N const(1) seed tokens (variants for N=1..4) |
+| `#reduce_add_N` | Binary reduction tree for addition (variants for N=2..4) |
+
+Built-in macros expose well-known internal node names (e.g., `&counter`, `&compare`, `&gate`) that the user wires externally after invocation.
+
+## Function Calls
+
+Function calls wire argument values across context boundaries using the expand pass. The call syntax declares which arguments feed into the callee and where results flow back.
+
+### Call Syntax
+
+```dfasm
+$func_name arg1=&source1, arg2=&source2 |> @result
+```
+
+The function must be defined as a `$name |> { ... }` region. Arguments are named (matching the function's parameter labels) or positional. Outputs after `|>` specify where results are routed.
+
+Multiple outputs can be named:
+
+```dfasm
+$divmod a=&dividend, b=&divisor |> @quotient, remainder=@remainder
+```
+
+### What the Expand Pass Does
+
+When processing a function call:
+
+1. Allocates a fresh context slot for the callee activation
+2. Generates cross-context edges with `ctx_override=True` (becomes `ctx_mode=01` / CTX_OVRD in hardware)
+3. Creates trampoline `PASS` nodes for return routing
+4. Generates `FREE_CTX` nodes to clean up the callee's context on completion
+5. Synthesises `@ret` marker nodes for return paths
+
+### Return Convention
+
+The expand pass creates synthetic `@ret` (or `@ret_name` for named outputs) nodes as return markers. The callee's result edges are wired to these markers, which trampoline the results back to the caller's context.
+
+### Example
+
+```dfasm
+@system pe=2, sm=0
+
+; Define a function that adds two values
+$add_pair |> {
+    &sum <| add
+}
+
+; Call it
+&a <| const, 3
+&b <| const, 7
+$add_pair a=&a, b=&b |> @result
+@result <| pass
+```
+
+After expansion, the assembler generates the cross-context wiring, trampoline nodes, and context cleanup automatically. The programmer does not need to manage context slots or return routing manually.

design-notes/io-and-bootstrap.md

···
 mapping is configured at bootstrap (or hardwired for v0):
 
 ```
-Example SM00 address map:
-  0x000 - 0x0FF:  IO devices (tier 0, raw memory semantics)
-  0x100 - 0x1FF:  Bootstrap ROM (tier 0, read-only)
-  0x200 - 0x3FF:  General-purpose I-structure cells (tier 1)
+Example SM00 address map (indicative, not final):
+  0x000 - 0x0FF:  I-structure cells (tier 1, presence-tracked)
+  0x100 - 0x1FF:  IO devices (tier 0, raw memory semantics)
+  0x200 - 0x3FF:  Bootstrap ROM (tier 0, read-only)
 ```
+
+**Tier boundary direction** is a hardware design decision, not yet
+finalised. The current design intent places I-structure cells at low
+addresses (below the boundary) where they are directly addressable by
+2-flit SM tokens and reachable by atomic operations (RD_INC, RD_DEC,
+CMP_SW — 5-bit opcode tier, 8-bit payload, 256-cell range). T0 raw
+storage sits above the boundary; it does not need atomics and can use
+extended addressing when necessary.
+
+The emulator currently uses `tier_boundary=256` with T1 below and T0
+at/above, but the exact mapping may change during physical build.
+See `sm-design.md` for the full tier model and encoding details.
 
 Within the IO range, specific addresses map to device registers:
 
···
        |
   [Address Decoder]
        |
-       +---> addr < 0x100? --> [IO Device Registers]
-       |                           |
-       |                           +---> [UART chip (6850/16550/etc.)]
-       |                           +---> [future: SPI, GPIO, timer]
+       +---> addr < tier_boundary? --> [SRAM Banks] (I-structure cells)
        |
-       +---> addr >= 0x100? --> [SRAM Banks] (normal SM operation)
+       +---> addr >= tier_boundary?
+               |
+               +---> IO range? --> [IO Device Registers]
+               |                       |
+               |                       +---> [UART chip (6850/16550/etc.)]
+               |                       +---> [future: SPI, GPIO, timer]
+               |
+               +---> ROM range? --> [Bootstrap ROM]
+               |
+               +---> else --> [T0 raw SRAM]
 ```
 
 The IO device registers behave like SM cells from the SM controller's

design-notes/loop-patterns-and-flow-control.md

···
 or a purpose-built assembler template system. No conditionals, no
 recursion in the macro evaluator, no type system.
 
+> **Implementation status:** All five requirements below are now
+> implemented in the `asm/expand.py` pass. The implemented syntax
+> differs from the Rust-style examples in this section — see
+> `dfasm-primer.md` for the canonical syntax reference.
+
 #### 1. Named Variadic Repetition
 
-```
-$($arg = $src),*
-```
-
-A comma-separated list of named pairs, expanded once per entry.
-Rust `macro_rules!` provides this directly.
+**Implemented.** Variadic parameters use `*name` in the macro
+definition. Repetition blocks use `$( ... ),*` syntax
+(`IRRepetitionBlock` in the IR). Each iteration binds the variadic
+parameter to the current element.
 
 #### 2. Token Pasting (Label Synthesis)
 
-```
-&__${arg}_tag
-```
-
-Concatenate a macro parameter into a label name. Produces unique
-labels per repetition entry. C has `##`, rust proc macros have
-`Ident::new()`, but `macro_rules!` does NOT have this natively —
-would need an assembler-specific extension or a `paste!`-style
-helper.
-
-This is the single most important extension beyond stock
-`macro_rules!`. Without it, macros can't generate unique labels
-for per-arg instructions.
+**Implemented.** `ParamRef` supports `prefix` and `suffix` fields
+for token pasting. Within a macro body, `&${name}_tag` produces
+labels incorporating the parameter value. Unique labels per
+repetition entry are generated automatically.
 
 #### 3. Implicit Repetition Index
 
-```
-${_idx}
-```
-
-An auto-incrementing counter within a `$(...),*` expansion.
-Used for descriptor table offset arithmetic (`$desc + ${_idx} + 1`).
-Not available in rust `macro_rules!` — another assembler-specific
-extension. Alternative: require the programmer to pass explicit
-indices, which is ugly but functional.
+**Implemented.** `${_idx}` is bound to the current iteration index
+(0-based) within `$(...),*` expansion blocks. Used for descriptor
+table offset arithmetic and generating unique per-iteration names.
 
 #### 4. Constant Arithmetic in Expressions
 
-```
-$desc + ${_idx} + 1
-```
-
-Compile-time addition on constant/label expressions. The assembler
-already evaluates constant expressions for instruction operands, so
-the macro expander just needs to emit the expression text and let the
-normal evaluator handle it. No new evaluation capability needed.
+**Implemented.** `ConstExpr` in `ir.py` supports compile-time `+`,
+`-`, `*` on integer values and parameter references. Expressions like
+`${base} + ${_idx} + 1` are evaluated during macro expansion.
 
 #### 5. Label Reference Across Macro Boundaries
 
-```
-&__alloc |> $func.__stub.ctx_in
-```
+**Implemented via scoped naming.** Expanded macro names are
+automatically qualified with scope prefixes (`#macroname_N.&label`
+for top-level, `$func.#macro_N.&label` inside functions). Cross-macro
+references use these qualified names. The expand pass also handles
+function call wiring via `CallSite` metadata, which generates
+cross-context edges and trampoline nodes automatically.
 
-The per-call-site macro needs to reference labels inside the
-per-function stub macro's expansion. This requires either:
-
-- A naming convention that both macros agree on (fragile but simple)
-- The stub macro "exporting" label names via a known pattern
-  (`$func.__stub.*`)
-- The assembler resolving qualified names across scopes
-
-The naming convention approach is the most macro-friendly: the
-`call_stub` macro always emits labels named
-`&__${func}_ctx_fan`, `&__${func}_or_ret`, etc., and the
-`call_dyn` macro references them by constructing the same names.
-Both macros must agree. This is a social contract, not a type system.
-
-#### What's NOT Needed
+#### What's NOT Needed (still true)
 
 - **Conditional expansion** — different call shapes get different
   macros, not `if` inside a macro.
-- **Recursive macro expansion** — the fan-out PASS chain has a fixed
-  structure per argument count. For N=1 it's one PASS with dual dest.
-  For N=2 it's two PASSes. Rather than recursing, provide
-  `call_stub_1`, `call_stub_2`, `call_stub_3` for common arities.
-  Ugly, pragmatic, correct.
+- **Recursive macro expansion** — macros CAN invoke other macros
+  (nested expansion with depth limit of 32). Per-arity variants are
+  provided for the built-ins for simplicity, not due to a limitation.
 - **Type checking** — the assembler validates after expansion (wrong
   arity, missing labels, offset overflow). The macro doesn't check.
-- **Hygiene** — label collisions between macro expansions ARE a risk.
-  Mitigated by the `&__${func}_` prefix convention. If two functions
-  have the same name, you have bigger problems.
+- **Hygiene** — scoped naming (`#macroname_N.&label`) prevents
+  collisions between multiple invocations of the same macro.
+
+#### Built-in Macros
+
+The assembler ships built-in macros (prepended to every program) that
+implement common patterns from this document:
+
+| Macro | Pattern |
+|-------|---------|
+| `#loop_counted` | Counted loop (counter + compare + increment feedback) |
+| `#loop_while` | Condition-tested loop (gate node) |
+| `#permit_inject_N` | Permit injection (N=1..4 const seed tokens) |
+| `#reduce_add_N` | Binary reduction tree for addition (N=2..4) |
+
+See `asm/builtins.py` for definitions.
 
 #### Example Macro Definitions
 
 ```dfasm
 ; ── call stub for a 1-argument function ──
 ; emitted once per function, provides shared call infrastructure
-.macro call_stub_1 $func, $desc {
+#call_stub_1 func, desc |> {
   ; ctx fan-out (1 arg + 1 return = 2 consumers, one PASS suffices)
   &__${func}_ctx_fan <| pass
   &__${func}_ctx_fan |> &__${func}_or_ret:R, &__${func}_or_arg0:R
···
 }
 
 ; ── call stub for a 2-argument function ──
-.macro call_stub_2 $func, $desc {
+#call_stub_2 func, desc |> {
   ; ctx fan-out chain (3 consumers)
   &__${func}_ctx_fan0 <| pass
   &__${func}_ctx_fan1 <| pass
···
 }
 
 ; ── per-call-site (works for any arity) ──
-.macro call_dyn $func, $alloc, $call_seq, $ret_offset, $($arg = $src),* {
+#call_dyn func, alloc, call_seq, ret_offset, *args |> {
   ; allocate + trigger + return continuation
-  &__call_alloc_${func}  <| rd_inc, $alloc
-  &__call_exec_${func}   <| exec, $call_seq
-  &__call_extag_${func}  <| extract_tag, $ret_offset
+  &__call_alloc_${func}  <| rd_inc, ${alloc}
+  &__call_exec_${func}   <| exec, ${call_seq}
+  &__call_extag_${func}  <| extract_tag, ${ret_offset}
 
   ; wire into stub
   &__call_alloc_${func} |> &__${func}_ctx_fan
   &__call_extag_${func} |> &__${func}_ct_ret:R
   $(
-    $src |> &__${func}_ct_${arg}:R
+    ${args} |> &__${func}_ct_${args}:R
   ),*
 }
 ```
···
 #call_stub_1 fib, @fib_desc
 
 ; at each call site
-#call_dyn fib, @ctx_alloc, @fib_call_seq, 20, n = &my_arg
+#call_dyn fib, @ctx_alloc, @fib_call_seq, 20, &my_arg
 ```
 
-The `call_stub_N` per-arity approach is admittedly clunky. A future
-macro system with proper counted repetition could unify them. For
-now, N=1 through N=3 covers the vast majority of functions, and
-anything beyond N=3 can be hand-written — it's the same pattern,
-just more of it.
+The `call_stub_N` per-arity approach is admittedly clunky. Macros can
+invoke other macros (nested expansion up to depth 32), so a unified
+variadic call_stub using a helper macro is possible. Per-arity variants
+are used here for clarity. N=1 through N=3 covers the vast majority
+of functions, and anything beyond N=3 can be hand-written — it's the
+same pattern, just more of it.
 
-### Permit Injection — Two Macros
+### Permit Injection — Two Approaches
 
-For small K (roughly K <= 4), inline CONST injection:
+For small K (roughly K <= 4), inline CONST injection. The built-in
+macros `#permit_inject_1` through `#permit_inject_4` provide this:
 
 ```dfasm
-; Macro definition:
-$permit_inject_inline K, &gate |> {
-  ; expands to K const instructions, each targeting &gate:L
-  ; each const needs its own trigger to fire
+; Built-in definition (from asm/builtins.py):
+#permit_inject_2 |> {
+    &p0 <| const, 1
+    &p1 <| const, 1
 }
 
-; Usage: inject 3 permits into the gate
-#permit_inject_inline 3, &dispatch_gate
+; Usage: invoke the built-in, then wire outputs to the gate
+#permit_inject_2
+#permit_inject_2.&p0 |> &dispatch_gate:L
+#permit_inject_2.&p1 |> &dispatch_gate:L
 ```
 
 For large K, use SM EXEC to batch-emit permits:
 
 ```dfasm
-; Macro definition:
-$permit_inject_exec K, &gate, @sm_base |> {
-  ; expands to a single SM_EXEC reading K pre-formed permit
-  ; tokens from SM starting at @sm_base, each addressed to &gate:L
+; Custom macro for EXEC-based injection:
+#permit_inject_exec count, sm_base |> {
+  ; a single SM EXEC reading ${count} pre-formed permit
+  ; tokens from SM starting at ${sm_base}
+  &exec <| exec, ${sm_base}
 }
 
 ; Usage: inject 8 permits via EXEC
-#permit_inject_exec 8, &dispatch_gate, @permit_store
+#permit_inject_exec 8, @permit_store
 ```
 
 Programmer chooses based on K. No magic.
 
 ### Loop Control Macro
 
+The built-in `#loop_counted` provides the core loop infrastructure:
+
 ```dfasm
-$loop_counted &limit, &body, &exit |> {
-  &counter <| const, 0
-  &step    <| inc
-  &test    <| lt
-  &route   <| sweq
-
-  &counter |> &step
-  &step    |> &test:L, &route:L   ; fan-out: counter to both LT and SWITCH
-  &limit   |> &test:R
-  &test    |> &route:R            ; bool from comparison → SWITCH control
-  &route:L |> &body               ; taken → body dispatch
-  &route:R |> &exit               ; not-taken → done
-  &route:L |> &step               ; feedback arc: counter recirculates
+; Built-in definition (from asm/builtins.py):
+#loop_counted |> {
+    &counter <| add
+    &compare <| brgt
+    &counter |> &compare:L
+    &inc <| inc
+    &compare |> &inc:L
+    &inc |> &counter:R
 }
 
-; Usage:
-#loop_counted 64, &body_entry, &done
+; Usage: wire init, limit, body, and exit externally
+#loop_counted
+&c_init <| const, 0
+&c_limit <| const, 64
+&c_init |> #loop_counted.&counter:L        ; initial counter value
+&c_limit |> #loop_counted.&compare:R       ; loop bound
+#loop_counted.&compare:L |> &body_entry    ; taken → body
+#loop_counted.&compare:R |> &done          ; not-taken → exit
 ```
 
 ### Reduction Tree Macro

design-notes/pe-design.md

···
     - First operand: store in slot, advance to wait state
     - Second operand: read partner from slot, both proceed
   - Monadic (prefix 010 or 011+10): bypass matching, proceed directly
+  - **DyadToken at monadic instruction**: if a dyadic-format token
+    arrives at an instruction that is monadic (determined after IRAM
+    fetch), the matching store is bypassed and the token fires
+    immediately as a monadic operand (data from token, no partner).
+    This allows the compiler to send dyadic-format tokens to monadic
+    instructions without deadlocking the matching store.
   - Single cycle for all cases (no hash path, no CAM search —
     direct indexing only, see matching store section below)
   - Estimated: ~200-300 transistors + SRAM
···
     network config writes — see "Instruction Memory" section below
 
 Stage 4: EXECUTE
-  - 16-bit ALU
-  - ~1500-2000 transistors
+  - IRAM half 0 bit 15 selects CM compute (0) or SM operation (1)
+  - CM path: 16-bit ALU executes arithmetic/logic/comparison/routing
+  - SM path: ALU is bypassed; PE constructs an SMToken from the SM
+    opcode, operand data, and IRAM fields (SM_id, const address,
+    return routing). See `iram-and-function-calls.md` for SM IRAM
+    word format.
+  - ~1500-2000 transistors (ALU) + SM flit assembly mux (~2 chips)
 
 Stage 5: TOKEN OUTPUT
-  - Form result token with routing prefix (type, destination PE/SM,
-    offset, context, etc.) using destination fields from IRAM
+  - CM path: form result CM token with routing prefix (type,
+    destination PE, offset, context, etc.) using destination fields
+    from IRAM. ctx_mode selects context source:
+      00 = INHERIT (pipeline latches)
+      01 = CTX_OVRD (const field overrides ctx/gen)
+      10 = CHANGE_TAG (left operand becomes flit 1 verbatim)
+    See `iram-and-function-calls.md` for ctx_mode details.
+  - SM path: emit SMToken to target SM via SM bus routes
   - Pass to output serialiser for flit encoding and bus injection
-  - ~300 transistors
+  - ~300 transistors + ctx/gen mux (~3 chips)
 ```
+
+### Concurrency Model
+
+The pipeline is pipelined: multiple tokens can be in-flight
+simultaneously at different stages. In the emulator, each token spawns
+a separate SimPy process that progresses through the pipeline
+independently. This models the hardware reality where Stage 2 can be
+matching a new token while Stage 4 is executing a previous one.
+
+Cycle counts per token type:
+- **Dyadic**: 5 cycles (dequeue + match + fetch + execute + emit)
+- **Monadic**: 4 cycles (dequeue + fetch + execute + emit; match bypassed)
+- **IRAMWriteToken**: 2 cycles (dequeue + write; no match/fetch/execute/emit)
+- **Network delivery**: +1 cycle latency between emit and arrival at destination
 
 ### Pipeline Register Widths
 
···
 just 32 bytes.
 
 > **⚠ Preliminary:** These configurations are candidates, not commitments.
-> The emulator defaults to 16 context slots and 128 IRAM entries (matching
-> Config B sizing). Final sizing depends on compiling real programs and
-> measuring actual concurrent activation counts and dyadic instruction
-> density per PE.
+> The emulator defaults to 16 context slots and 128 IRAM entries. Note
+> that IRAM entries (128) and matching store entries per context (32 in
+> Config B) are distinct: the matching store only holds dyadic
+> instructions at offsets 0-31, while IRAM holds all instructions
+> (dyadic + monadic) across the full 128-slot range. Final sizing
+> depends on compiling real programs and measuring actual concurrent
+> activation counts and dyadic instruction density per PE.
 
 **Recommendation for v0**: Config B (16 slots x 32 entries = 1KB). This
 matches the token format directly: 4-bit ctx from flit 1, 5-bit offset

design-notes/sm-design.md

···
 
 'aa' = address bits (part of 10-bit address).
 
-**Tier 1 ops (3-bit, full address range):** READ, WRITE, ALLOC, FREE,
+**Tier 1 ops (3-bit, full address range):** READ, WRITE, ALLOC, EXEC,
 CLEAR reach the full 1024-cell address space. EXT signals a 3-flit
 token for extended addressing (external RAM, wide addresses).
 
 **Tier 2 ops (5-bit, restricted address/payload):** atomic operations
-(READ_INC, READ_DEC, CAS) are restricted to 256 cells — the compiler
-places atomic-access cells in the lower range. EXEC, SET_PAGE, and
+(READ_INC, READ_DEC, CAS) as well as CLEAR are restricted to 256 cells — the compiler
+places atomic-access cells in the lower range. SET_PAGE and
 WRITE_IMM use the 8-bit payload field for non-address data (length,
 page register value, small immediate).
 
···
 operand. The 8-bit payload in the restricted tier can be inline data,
 config values, or range counts depending on the opcode:
 
-- EXEC: payload = length/count (base addr in config register)
 - SET_PAGE: payload = page register value
 - WRITE_IMM: 8-bit addr, flit 2 carries immediate data
 - RAW_READ: non-blocking read, returns data or empty indicator without

docs/macro-enhancements.md

···
+# Macro Enhancements: Opcode Parameters, Qualified Ref Parameters, and @ret Wiring
+
+Extends the dfasm macro system with three capabilities that reduce the need for per-variant macro definitions and make macros composable in the same way as functions.
+
+## Current State
+
+The macro system (implemented in `asm/expand.py`, grammar in `dfasm.lark`) supports:
+
+- Parameter substitution in node names via `${param}` (token pasting with prefix/suffix)
+- Parameter substitution in edge endpoints via `${param}` in `qualified_ref`
+- Parameter substitution in const fields
+- Compile-time arithmetic via `ConstExpr` (`${base} + ${_idx} + 1`)
+- Variadic parameters with `@each` repetition blocks
+- Nested macro invocation (depth limit 32)
+
+Three gaps remain:
+
+1. **Opcode position is not parameterizable.** The grammar defines `opcode: OPCODE` as a keyword terminal. You cannot pass an opcode as a macro argument. This forces per-opcode variants: `#reduce_add_2`, `#reduce_add_3`, etc.
+
+2. **Placement and port qualifiers are not parameterizable.** The grammar defines `placement: "|" IDENT` and `port: ":" PORT_SPEC` — neither accepts `param_ref`. You cannot write `&ref:${port}` or `&ref|${pe}` in a macro body to parameterize which port or PE a reference targets.
+
+3. **Macros have no output wiring convention.** Functions use `@ret` / `@ret_name` markers in their body, and the call syntax `$func args |> outputs` auto-wires return paths. Macros have no equivalent — the user must manually wire to expanded internal node names after invocation.
+
+## Enhancement 1: Opcode Parameters
+
+### Goal
+
+Allow macro parameters to appear in the opcode position of `inst_def`, `strong_edge`, and `weak_edge` rules.
+
+### Grammar Change
+
+```lark
+// Current:
+opcode: OPCODE
+
+// Proposed:
+opcode: OPCODE | param_ref
+```
+
+This is the only grammar change needed. `param_ref` (`${name}`) is already a valid production. Earley parsing handles the ambiguity.
+
+### Lower Pass
+
+The `inst_def` handler in `lower.py` currently calls `self._resolve_opcode()` which maps mnemonic strings to `ALUOp`/`MemOp` values. When the opcode is a `ParamRef`, lowering must defer resolution — store the `ParamRef` on the `IRNode` in a new field (or overload the `opcode` field's type to `Union[ALUOp, MemOp, ParamRef]`).
+
+The `strong_edge` and `weak_edge` handlers need the same treatment: if the opcode token is a `ParamRef`, create the anonymous node with a deferred opcode.
+
+### Expand Pass
+
+During `_clone_and_substitute_node`, if `node.opcode` is a `ParamRef`:
+
+1. Look up the parameter in the substitution map
+2. The argument value must be a string matching a known opcode mnemonic
+3. Resolve via `MNEMONIC_TO_OP` to get the concrete `ALUOp`/`MemOp`
+4. Replace the node's opcode with the resolved value
+5. Error if the argument is not a valid opcode mnemonic
+
+### Validation
+
+Opcode validation (monadic/dyadic arity, valid argument combinations) already happens after expansion in the resolve and allocate passes. No additional validation needed at expansion time beyond confirming the mnemonic exists.
+
+### Example
+
+Before (current — per-opcode variants):
+
+```
+#reduce_add_2 |> { &r <| add }
+#reduce_add_3 |> { &r0 <| add; &r1 <| add; &r0 |> &r1:L }
+#reduce_sub_2 |> { &r <| sub }
+; ... N variants per opcode
+```
+
+After (parameterized):
+
+```
+#reduce_2 op |> {
+    &r <| ${op}
+}
+
+#reduce_3 op |> {
+    &r0 <| ${op}
+    &r1 <| ${op}
+    &r0 |> &r1:L
+}
+
+; Usage:
+#reduce_2 add
+#reduce_3 sub
+```
+
+### Argument Syntax
+
+Opcode arguments are passed as bare identifiers in the macro call. The grammar for `macro_call_stmt` already accepts `argument` which includes `qualified_ref`, and a bare `IDENT` would normally parse as... hmm, actually it won't. An unqualified `add` in argument position parses as the `OPCODE` terminal (priority 2), not as `IDENT`. And `OPCODE` is not a valid `argument`.
+
+Two options:
+
+**Option A: Quote opcode arguments.** Pass as string literals: `#reduce_2 "add"`. Simple, unambiguous. Expand pass strips quotes and resolves. Slightly ugly.
+
+**Option B: Accept OPCODE as a macro argument.** Add `OPCODE` as an alternative in `positional_arg`:
+
+```lark
+// Current:
+?positional_arg: value | qualified_ref
+
+// Proposed:
+?positional_arg: value | qualified_ref | OPCODE
+```
+
+The lower pass wraps the bare opcode token as a string argument in the `IRMacroCall`. Expand resolves it against `MNEMONIC_TO_OP`. This reads naturally: `#reduce_2 add`.
+
+Option B is cleaner. The only risk is if someone has an `IDENT` that collides with an opcode name as a label/node, but the priority system already handles that (opcodes win at lexer level), and this collision already exists in the language.
+
+**Recommendation: Option B.**
+
+
+## Enhancement 2: Parameterized Placement and Port Qualifiers
+
+### Goal
+
+Allow `${param}` in the placement (`|pe0`) and port (`:L`) positions of a `qualified_ref`, so macros can parameterize which PE a node targets, which port an edge uses, and (when exposed) which context slot to use.
+
+### Current State
+
+`qualified_ref` is built from three parts:
+
+```lark
+qualified_ref: (node_ref | label_ref | ... | param_ref) placement? port?
+placement: "|" IDENT
+port:      ":" PORT_SPEC
+PORT_SPEC: IDENT | HEX_LIT | DEC_LIT
+```
+
+`${param}` can already stand in for the entire ref part (the first element). But the `placement` and `port` suffixes only accept literal tokens. So `&node:${port}` and `&node|${pe}` don't parse.
+
+In the lower pass, `qualified_ref` collects its children into a dict:
+- The ref part becomes `{"name": ...}`
+- `placement` returns a string (e.g., `"pe0"`)
+- `port` returns a `Port` enum (`Port.L`, `Port.R`) or raw `int`
+
+In the IR, `IRNode.pe` stores placement as `Optional[int]`, and `IREdge.port`/`IREdge.source_port` store port as `Port`. Neither field currently accepts `ParamRef`.
+
+The expand pass (`_clone_and_substitute_node`, `_clone_and_substitute_edge`) only substitutes `name`, `const`, `source`, and `dest`. It does not touch `pe`, `port`, or `source_port`.
+
+### Grammar Changes
+
+```lark
+// Current:
+placement: "|" IDENT
+port:      ":" PORT_SPEC
+
+// Proposed:
+placement: "|" (IDENT | param_ref)
+port:      ":" (PORT_SPEC | param_ref)
+```
+
+### Lower Pass
+
+The `placement` handler currently does `return str(token)`. It needs to handle receiving a `ParamRef` from the parser and return it as-is:
+
+```python
+def placement(self, *args):
+    for arg in args:
+        if isinstance(arg, ParamRef):
+            return arg
+    return str(args[-1])
+```
+
+Similarly, the `port` handler needs to pass through `ParamRef` instead of resolving to `Port`:
+
+```python
+def port(self, *args):
+    for arg in args:
+        if isinstance(arg, ParamRef):
+            return arg
+    # ... existing Port.L / Port.R / int resolution
+```
+
+The `qualified_ref` handler already iterates over args by type. It needs a new branch to detect `ParamRef` in placement/port positions (currently it only detects `ParamRef` in the ref-name position). The disambiguation is based on ordering: the ref-name comes first, placement second (prefixed with `|`), port third (prefixed with `:`). Since Lark processes them through their respective rules before `qualified_ref` sees them, the parser distinguishes them. The `qualified_ref` handler just needs to accept `ParamRef` for placement and port:
+
+```python
+def qualified_ref(self, *args):
+    ref_type = None
+    placement = None
+    port = None
+    for arg in args:
+        if isinstance(arg, ParamRef) and ref_type is None:
+            ref_type = {"name": arg}
+        elif isinstance(arg, ParamRef) and ref_type is not None:
+            # Second or third ParamRef — depends on position
+            # But Lark gives us placement/port through their handlers,
+            # so we get ParamRef from the placement() or port() handler.
+            # Need to distinguish: placement handler adds a marker or
+            # we rely on Lark's rule names.
+            ...
+```
+
+Actually, this is simpler than it looks. Lark calls `placement()` and `port()` before `qualified_ref()`. So `qualified_ref` receives:
+- A dict or `ParamRef` (from the ref-name rules)
+- A string or `ParamRef` (from the `placement` handler)
+- A `Port`/`int` or `ParamRef` (from the `port` handler)
+
+The existing type-based dispatch in `qualified_ref` needs one addition: if an arg is `ParamRef` and `ref_type` is already set, it's either placement or port. We can distinguish by wrapping them — the placement handler returns `("placement", ParamRef(...))` and port returns `("port", ParamRef(...))` when deferring. Or simpler: use a thin wrapper type.
+
+Alternatively, Lark's `@v_args(inline=True)` on placement/port means the handler already knows which rule matched. The cleanest approach: return a `ParamRef` tagged with its role:
+
+```python
+@dataclass(frozen=True)
+class PlacementRef:
+    """Deferred placement from macro parameter."""
+    param: ParamRef
+
+@dataclass(frozen=True)
+class PortRef:
+    """Deferred port from macro parameter."""
+    param: ParamRef
+```
+
+Then `qualified_ref` type-dispatches on `PlacementRef`/`PortRef` alongside `str`/`Port`/`int`.
+
+### IR Changes
+
+`IRNode.pe` type becomes `Optional[Union[int, ParamRef]]`.
+
+`IREdge.port` type becomes `Union[Port, ParamRef]`.
+
+`IREdge.source_port` type becomes `Optional[Union[Port, ParamRef]]`.
+
+These wider types only appear in macro template bodies. After expansion, all `ParamRef` values are resolved to concrete types. The resolve, place, and allocate passes never see `ParamRef` — if one leaks through, it's a bug in expand.
+
+### Expand Pass
+
+`_clone_and_substitute_node` gains:
+
+```python
+# Substitute PE placement if it's a ParamRef
+new_pe = node.pe
+if isinstance(new_pe, ParamRef):
+    resolved = _substitute_param(new_pe, subst_map)
+    # Must resolve to a PE identifier string like "pe0" or an int
+    new_pe = _resolve_pe_placement(resolved)  # parse "pe0" -> 0, or int -> int
+```
+
+`_clone_and_substitute_edge` gains:
+
+```python
+# Substitute port if it's a ParamRef
+new_port = edge.port
+if isinstance(new_port, ParamRef):
+    resolved = _substitute_param(new_port, subst_map)
+    new_port = _resolve_port(resolved)  # "L" -> Port.L, "R" -> Port.R, int -> int
+
+new_source_port = edge.source_port
+if isinstance(new_source_port, ParamRef):
+    resolved = _substitute_param(new_source_port, subst_map)
+    new_source_port = _resolve_port(resolved)
+```
+
+### Validation
+
+Invalid port/placement values (e.g., passing `"banana"` as a port) produce a MACRO error during expansion. Post-expansion, the existing place and allocate passes validate that PE IDs are in range and ports are valid.
+
+### Examples
+
+Parameterized port selection:
+
+```
+; Macro that wires to a caller-selected port
+#wire_to_port target, port |> {
+    &src <| pass
+    &src |> ${target}:${port}
+}
+
+; Usage: wire to left port
+#wire_to_port &dest, L
+
+; Usage: wire to right port
+#wire_to_port &dest, R
+```
+
+Parameterized PE placement:
+
+```
+; Macro that places its node on a specific PE
+#placed_const val, pe |> {
+    &c <| const, ${val} |${pe}
+    &c |> @ret
+}
+
+; Usage: place on pe0
+#placed_const 42, pe0 |> &target
+
+; Usage: place on pe1
+#placed_const 42, pe1 |> &target
+```
+
+Combined — a macro that builds a cross-PE relay:
+
+```
+; Route a value from one PE to another
+#cross_pe_relay src_pe, dst_pe |> {
+    &hop <| pass |${src_pe}
+    &hop |> @ret
+}
+
+; Usage:
+#cross_pe_relay pe0, pe1 |> &destination
+```
+
+### Context Slot Syntax
+
+Context slots use bracket syntax `[N]`, distinct from all other qualifiers:
+
+```
+&node|pe0[2]       ; place on pe0, context slot 2
+&node[0]           ; context slot 0, auto-placed PE
+&node|pe1[0..4]    ; reserve context slots 0-4 for this instruction
+```
+
+The bracket syntax avoids overloading `:` (which already carries port, cell address, and potentially IRAM address semantics). `[N]` is exclusively context slots.
+
+#### Grammar
+
+```lark
+// New production:
+ctx_slot: "[" (DEC_LIT | ctx_range | param_ref) "]"
+ctx_range: DEC_LIT ".." DEC_LIT
+
+// Updated qualified_ref:
+qualified_ref: (node_ref | label_ref | ... | param_ref) placement? ctx_slot? port?
+```
+
+`ctx_slot` appears between placement and port in the qualifier chain: `&node|pe0[2]:L`.
+
+#### Use Cases
+
+- **Explicit context partitioning**: place parallel computations in distinct context slots to avoid matching store collisions
+- **Debugging**: force a known context layout for inspection
+- **Range reservation** (`[0..4]`): reserve a contiguous block of slots for an instruction that will be targeted by multiple parallel sources wired identically — not essential but a natural extension
+
+#### Parameterization
+
+Same mechanism as placement/port. `[${ctx}]` in a macro body, substituted to an integer during expansion:
+
+```
+#placed_op op, pe, ctx |> {
+    &n <| ${op} |${pe}[${ctx}]
+    &n |> @ret
+}
+
+; Usage:
+#placed_op add, pe0, 2 |> &target
+```
+
+
+## Enhancement 3: @ret Wiring for Macros
+
+### Goal
+
+Allow macros to define output points using `@ret` / `@ret_name` markers, and wire them to destinations at the call site using the `|>` syntax.
+
+### Grammar Change
+
+Add optional output list to `macro_call_stmt`:
+
+```lark
+// Current:
+macro_call_stmt: "#" IDENT (argument ("," argument)*)?
+
+// Proposed:
+macro_call_stmt: "#" IDENT (argument ("," argument)*)? (FLOW_OUT call_output_list)?
+```
+
+This reuses the existing `call_output_list` and `call_output` productions from `call_stmt`. Same syntax: `#macro args |> &dest` or `#macro args |> name=&dest`.
+
+### Macro Body Convention
+
+Macro bodies use `@ret` and `@ret_name` in edge destinations, same as function bodies:
+
+```
+#loop op, init_val |> {
+    &counter <| add
+    &compare <| ${op}
+    &counter |> &compare:L
+    &inc <| inc
+    &compare |> &inc:L
+    &inc |> &counter:R
+    ; Output edges use @ret convention
+    &compare |> @ret_body
+    &compare |> @ret_exit:R
+}
+```
+
+### Lower Pass
+
+When lowering `macro_call_stmt` with a `FLOW_OUT` and `call_output_list`:
+
+1. Parse the output list the same way `call_stmt` does (named/positional outputs)
+2. Store output destinations on the `IRMacroCall` in a new field: `output_dests: tuple`
+
+The `IRMacroCall` dataclass gains:
+
+```python
+@dataclass(frozen=True)
+class IRMacroCall:
+    name: str
+    positional_args: tuple
+    named_args: tuple
+    output_dests: tuple = ()   # New: output wiring destinations
+    loc: Optional[SourceLoc] = None
+```
+
+### Expand Pass
+
+After cloning and substituting the macro body, process `@ret` markers:
+
+1. Scan expanded edges for destinations starting with `@ret`
+2. For each `@ret` / `@ret_name` destination, look up the corresponding output from `IRMacroCall.output_dests`
+3. Replace the `@ret*` destination with the actual target node name
+4. If a `@ret*` marker has no matching output dest, report a MACRO error
+
+This is simpler than function call wiring because macros don't need:
+- Trampoline nodes (no cross-context routing)
+- `ctx_override` edges (macros inline into the caller's context)
+- `FREE_CTX` nodes (no context allocation)
+- Synthetic PASS nodes (direct edge replacement suffices)
+
+The `@ret` substitution in macros is purely edge rewriting — replace the symbolic `@ret_name` destination with the concrete node reference from the call site.
+
+### Positional @ret Mapping
+
+Same convention as function calls:
+
+- Bare `@ret` maps to the first (or only) positional output
+- `@ret_name` maps to the named output `name=&dest`
+- Multiple bare `@ret` edges to different ports on the same output are valid
+
+### Example
+
+```
+; Define macro with outputs
+#loop_counted |> {
+    &counter <| add
+    &compare <| brgt
+    &counter |> &compare:L
+    &inc <| inc
+    &compare |> &inc:L
+    &inc |> &counter:R
+    &compare |> @ret_body
+    &compare |> @ret_exit:R
+}
+
+; Invoke with output wiring
+#loop_counted |> body=&process, exit=&done
+&init |> #loop_counted_0.&counter:L
+&limit |> #loop_counted_0.&compare:R
+```
+
+Or positionally:
+
+```
+#simple_gate |> {
+    &g <| gate
+    &g |> @ret
+    &g |> @ret:R   ; second output port
+}
+
+; Invoke — positional @ret maps to first output
+#simple_gate |> &body, &exit
+```
+
+
+## Impact on Built-in Macros
+
+With both enhancements, the built-in library collapses significantly:
+
+### Current (11 macros)
+
+```
+#loop_counted, #loop_while
+#permit_inject_1, #permit_inject_2, #permit_inject_3, #permit_inject_4
+#reduce_add_2, #reduce_add_3, #reduce_add_4
+```
+
+### Proposed (4-5 macros, more capable)
+
+```
+; Counted loop with output wiring
+#loop_counted |> {
+    &counter <| add
+    &compare <| brgt
+    &counter |> &compare:L
+    &inc <| inc
+    &compare |> &inc:L
+    &inc |> &counter:R
+    &compare |> @ret_body
+    &compare |> @ret_exit:R
+}
+
+; Condition-tested loop
+#loop_while |> {
+    &gate <| gate
+    &gate |> @ret_body
+    &gate |> @ret_exit:R
+}
+
+; Permit injection — variadic, outputs via @ret
+#permit_inject *nodes |> {
+    $(
+        &p_${_idx} <| const, 1
+        &p_${_idx} |> @ret
+    ),*
+}
+
+; Binary reduction tree — parameterized opcode + arity
+#reduce_2 op |> {
+    &r <| ${op}
+}
+
+#reduce_3 op |> {
+    &r0 <| ${op}
+    &r1 <| ${op}
+    &r0 |> &r1:L
+}
+
+#reduce_4 op |> {
+    &r0 <| ${op}
+    &r1 <| ${op}
+    &r2 <| ${op}
+    &r0 |> &r2:L
+    &r1 |> &r2:R
+}
+```
+
+Usage:
+
+```
+; Old:
+!#loop_counted
+&init |> #loop_counted_0.&counter:L
+&limit |> #loop_counted_0.&compare:R
+#loop_counted_0.&compare |> &body:L
+#loop_counted_0.&compare |> &exit:R
+
+; New:
+#loop_counted |> body=&process, exit=&done
+&init |> #loop_counted_0.&counter:L
+&limit |> #loop_counted_0.&compare:R
+
+; Old:
+!#reduce_add_4
+
+; New:
+#reduce_4 add
+```
+
+Note: the `#permit_inject` example with variadic `@ret` is aspirational — it requires `@ret` to work inside repetition blocks, which means the `@ret` substitution must happen after repetition expansion. This ordering is already correct since repetition expansion happens before edge rewriting in the expand pass.
+
+
+## Implementation Order
+
+1. **Opcode parameters** — grammar change (`opcode: OPCODE | param_ref`), argument syntax (`positional_arg: ... | OPCODE`), expand pass substitution. Smallest diff, immediately useful.
+
+2. **Qualified ref parameters** — grammar changes to `placement` and `port`, `PlacementRef`/`PortRef` wrapper types, IR type widening, expand pass substitution. Mechanically similar to opcode params, builds on the same `_substitute_param` infrastructure.
+
+3. **@ret wiring for macros** — grammar change (output list on `macro_call_stmt`), `IRMacroCall.output_dests`, expand pass edge rewriting. Builds on existing `@ret` patterns from function calls.
+
+4. **Built-in macro rewrite** — collapse per-variant macros using the new features. Backwards-incompatible (old macro names removed), but since the built-ins are bundled and the system is pre-1.0, this is acceptable.
+
+## Open Questions
+
+1. **Should macros with `@ret` also support `|>` on inputs?** Function calls use `$func a=&x |> @output`. Currently macro calls use `#macro arg1, arg2` for inputs. Adding `|>` for outputs is proposed above. Should inputs also support named wiring? Probably not needed — macros already have `${param}` for inputs, and the input wiring is fundamentally different (parameter substitution vs edge creation).
+
+2. **Error messages for mismatched @ret counts.** If a macro body has `@ret_body` and `@ret_exit` but the call site only provides one output, what error? Probably MACRO category: "macro '#loop_counted' defines outputs @ret_body, @ret_exit but call provides 1 output".
+
+3. **Interaction with nested macros.** If macro A calls macro B which has `@ret`, and A also has `@ret`, the scoping should work naturally — B's `@ret` resolves at B's call site (inside A's body), A's `@ret` resolves at A's call site. The existing scope qualification prevents name collisions.